NAME

XML::Filter::XML_Directory_2RSS - SAX2 filter for generating RSS from the output of XML::Directory::SAX

SYNOPSIS

  use IO::File;
  use XML::SAX::Writer;

  use XML::Directory::SAX;
  use XML::Filter::XML_Directory_2RSS;

  my $rss       = "/path/to/rss.xml";
  my $directory = "/path/to/some/directory";

 #

  my $output = IO::File->new(">$rss");
  my $writer = XML::SAX::Writer->new(Output=>$output);
  my $filter = XML::Filter::XML_Directory_2RSS->new(Handler=>$writer);

 # Various RSS meta data methods
  
  $rss->uri("http://www.foo.com/rss.xml");

  $rss->channel_data({title      => "foo",
                      link       => "http://foo.com",
                      subject    => "bar",
                      descripion => "foo is to bar as bar is to foo"});

  $rss->generator($0);

 # Set up one or more events for affecting the 
 # data describe in your RSS document

  $rss->callbacks({link => \&do_link});
  $rss->handlers({title=>MySax::Title->new(Handler=>$writer)});

 # Describe items to be explicily excluded (or included)
 # in your RSS document.

  $rss->exclude(exclude=>["RCS","CVS"],ending=>["~"]);

 # Parse parse parse

  my $directory = XML::Directory::SAX->new(Handler => $filter,
                                           detail  => 2,
                                           depth   => 1);

  $directory->order_by("a");
  $directory->parse_dir($directory);

 # 

  sub do_link { 
    my $link = shift; 
    $link =~ s!$directory!http://www.foo.com!s; 
    return $link; 
  }

DESCRIPTION

SAX2 filter for generating RSS from the output of XML::Directory::SAX.

NOTES

This package has very limited support for RSS modules. I'm workin' on it.

OBJECT METHODS

$pkg->encoding($enc)

Set the encoding type for your RSS document. Default is UTF-8

$pkg->uri($uri)

Set the URI for your RSS document. This is the value of the channel@rdf:about attribute.

$pkg->channel_data(\%args)

Set channel data for your RSS document.

Valid arguments are :

title
String.
link
String.
subject
String.
description
String.
dc:rights
String.
dc:publisher
String.
dc:creator
String.
dc:language
Array reference.

Proper support for RSS 1.0 modules is in the works.

$pkg->image(\%args)

Set image data for your RSS document.

Valid arguments are :

title
String.
url
String.
link
String.

$pkg->textinput(\%args)

Set textinput data for your RSS document.

Valid arguments are :

title
String.
description
String.
name
String.
link
String.

$pkg->generator($agent)

Set generator agent data for your RSS document.

Currently this is really only used by the Syndic8 project, but it's a good idea so we'll add hooks it for.

$pkg->exclude(%args)

This method is inherited from XML::Filter::XML_Directory_Pruner. See docs for details.

$pkg->include(%args);

This method is inherited from XML::Filter::XML_Directory_Pruner. See docs for details.

$pkg->handlers(\%args)

A is a valid SAX2 thingy for assigning the title or description element of an RSS item. Thingies are like any other SAX2 thingy with a few requirements :

Must inherit from XML::SAX::Base.
It's handler must be the same one passed to the XML_Directory_2RSS filter.
It must define a parse_uri method.

 # If this...

 my $writer = XML::SAX::Writer->new();
 my $rss = XML::Filter::XML_Directory_2RSS->new(Handler=>$writer);
 $rss->handler({title=>MySAX::TitleHandler->new(Handler=>$writer)});

 # Called this...

 package MySAX::TitleHandler;
 use base qw (XML::SAX::Base);
 
 sub parse_uri {
    my ($pkg,$path,$title) = @_;

    $pkg->SUPER::start_prefix_mapping({Prefix=>"me",NamespaceURI=>"..."});
    $pkg->SUPER::start_element({Name=>"me:woot"});
    $pkg->SUPER::characters({Data=>&get_title_from_file($path)});
    $pkg->SUPER::end_element({Name=>"me:woot"});
    $pkg->SUPER::end_prefix_mapping({Prefix=>"me"});
 }

 # Then the output would look like this...

 <item>
  <title>
   <me:woot xmlns:me="...">I Got My Title From the File</me:woot>
  </title>
  <link>...</link>
  <description />
 </item>

Valid arguments are :

title
Object.

The handler's parse_uri method is passed the absolute path of the file and the filename itself.

If no handler, or callback, is defined then the filename will be assigned to the title element.
description
Object.

The handler's parse_uri method is passed the absolute path of the file.

If no handler, or callback, is defined then the description element will be left empty.

Handlers have a higher precedence than callbacks.

$pkg->callbacks(\%args)

Callbacks are like handlers except that they are code references instead of SAX2 thingies.

A code reference might be used to munge the link value of an item into a URI suitable for viewing in a web browser.

Valid arguments are

title
Code reference.

Code references will be passed the absolute path of the file and the filename itself.

If no callback, or handler, is defined then the filename will be assigned to the title element.
link
Code reference.

Code references will be passed the absolute path of the file.

If no callback is defined then the absolute path of the file will be assigned to the link element.
description
Code reference.

Code references will be passed the absolute path of the file.

If no callback, or handler, the descripion element will be left empty.

Callbacks have a lower precedence than handlers.

VERSION

0.9.1

DATE

May 24, 2002

AUTHOR

Aaron Straup Cope

TO DO

Proper support for RSS modules.

LICENSE

This is free software, you may use it and distribute it under the same terms as Perl itself.