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)

Register one of more callbacks for your RSS document.

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.

SEE ALSO

XML::Filter::XML_Directory::Pruner

XML::Directory::SAX

http://groups.yahoo.com/group/rss-dev/files/specification.html

LICENSE

Copyright (c) 2002, Aaron Straup Cope. All Rights Reserved.

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

cpanm XML::Filter::XML_Directory_2RSS

perl -MCPAN -e shell
install XML::Filter::XML_Directory_2RSS