Provided by: libxml-feedpp-perl_0.95-1_all bug

NAME

       XML::FeedPP -- Parse/write/merge/edit RSS/RDF/Atom syndication feeds

SYNOPSIS

       Get an RSS file and parse it:

           use XML::FeedPP ();
           my $source = 'http://use.perl.org/index.rss';
           my $feed = XML::FeedPP->new( $source );
           print "Title: ", $feed->title(), "\n";
           print "Date: ", $feed->pubDate(), "\n";
           foreach my $item ( $feed->get_item() ) {
               print "URL: ", $item->link(), "\n";
               print "Title: ", $item->title(), "\n";
           }

       Generate an RDF file and save it:

           use XML::FeedPP ();
           my $feed = XML::FeedPP::RDF->new();
           $feed->title( "use Perl" );
           $feed->link( "http://use.perl.org/" );
           $feed->pubDate( "Thu, 23 Feb 2006 14:43:43 +0900" );
           my $item = $feed->add_item( "http://search.cpan.org/~kawasaki/XML-TreePP-0.02" );
           $item->title( "Pure Perl implementation for parsing/writing xml file" );
           $item->pubDate( "2006-02-23T14:43:43+09:00" );
           $feed->to_file( "index.rdf" );

       Convert some RSS/RDF files to Atom format:

           use XML::FeedPP ();
           my $feed = XML::FeedPP::Atom::Atom10->new();        # create empty atom file
           $feed->merge( "rss.xml" );                          # load local RSS file
           $feed->merge( "http://www.kawa.net/index.rdf" );    # load remote RDF file
           my $now = time();
           $feed->pubDate( $now );                             # touch date
           my $atom = $feed->to_string();                      # get Atom source code

DESCRIPTION

       "XML::FeedPP" is an all-purpose syndication utility that parses and publishes RSS 2.0, RSS
       1.0 (RDF), Atom 0.3 and 1.0 feeds.  It allows you to add new content, merge feeds, and
       convert among these various formats.  It is a pure Perl implementation and does not
       require any other module except for XML::TreePP.

METHODS FOR FEED

   $feed = XML::FeedPP->new( "index.rss" );
       This constructor method creates an "XML::FeedPP" feed instance. The only argument is the
       local filename.  The format of $source must be one of the supported feed formats -- RSS,
       RDF or Atom -- or execution is halted.

   $feed = XML::FeedPP->new( "http://use.perl.org/index.rss" );
       The URL on the remote web server is also available as the first argument.  LWP::UserAgent
       is required to download it.

   $feed = XML::FeedPP->new( '<rss version="2.0">...' );
       The XML source code is also available as the first argument.

   $feed = XML::FeedPP->new( $source, -type => $type );
       The "-type" argument allows you to specify type of $source from choice of 'file', 'url' or
       'string'.

   $feed = XML::FeedPP->new( $source, utf8_flag => 1 );
       This makes utf8 flag on for all feed elements.  Perl 5.8.1 or later is required to use
       this.

       Note that any other options for "XML::TreePP" constructor are also allowed like this. See
       more detail on XML::TreePP.

   $feed = XML::FeedPP::RSS->new( $source );
       This constructor method creates an instance for an RSS 2.0 feed.  The first argument is
       optional, but must be valid an RSS source if specified.  This method returns an empty
       instance when $source is undefined.

   $feed = XML::FeedPP::RDF->new( $source );
       This constructor method creates an instance for RSS 1.0 (RDF) feed.  The first argument is
       optional, but must be an RDF source if specified.  This method returns an empty instance
       when $source is undefined.

   $feed = XML::FeedPP::Atom->new( $source );
       This constructor method creates an instance for an Atom 0.3/1.0 feed.  The first argument
       is optional, but must be an Atom source if specified.  This method returns an empty
       instance when $source is undefined.

       Atom 1.0 feed is also supported since "XML::FeedPP" version 0.30.  Atom 0.3 is still
       default, however, future version of this module would create Atom 1.0 as default.

   $feed = XML::FeedPP::Atom::Atom03->new();
       This creates an empty Atom 0.3 instance obviously.

   $feed = XML::FeedPP::Atom::Atom10->new();
       This creates an empty Atom 1.0 instance intended.

   $feed = XML::FeedPP::RSS->new( link => $link, title => $tile, ... );
       This creates a RSS instance which has "link", "title" elements etc.

   $feed->load( $source );
       This method loads an RSS/RDF/Atom file, much like "new()" method does.

   $feed->merge( $source );
       This method merges an RSS/RDF/Atom file into the existing $feed instance. Top-level
       metadata from the imported feed is incorporated only if missing from the present feed.

   $string = $feed->to_string( $encoding );
       This method generates XML source as string and returns it.  The output $encoding is
       optional, and the default encoding is 'UTF-8'.  On Perl 5.8 and later, any encodings
       supported by the Encode module are available.  On Perl 5.005 and 5.6.1, only four
       encodings supported by the Jcode module are available: 'UTF-8', 'Shift_JIS', 'EUC-JP' and
       'ISO-2022-JP'.  'UTF-8' is recommended for overall compatibility.

   $string = $feed->to_string( indent => 4 );
       This makes the output more human readable by indenting appropriately.  This does not
       strictly follow the XML specification but does looks nice.

       Note that any other options for "XML::TreePP" constructor are also allowed like this. See
       more detail on XML::TreePP.

   $feed->to_file( $filename, $encoding );
       This method generate an XML file.  The output $encoding is optional, and the default is
       'UTF-8'.

   $item = $feed->add_item( $link );
       This method creates a new item/entry and returns its instance.  A mandatory $link argument
       is the URL of the new item/entry.

   $item = $feed->add_item( $srcitem );
       This method duplicates an item/entry and adds it to $feed.  $srcitem is a
       "XML::FeedPP::*::Item" class's instance which is returned by "get_item()" method, as
       described above.

   $item = $feed->add_item( link => $link, title => $tile, ... );
       This method creates an new item/entry which has "link", "title" elements etc.

   $item = $feed->get_item( $index );
       This method returns item(s) in a $feed.  A valid zero-based array $index returns the
       corresponding item in the feed.  An invalid $index yields undef.  If $index is undefined
       in array context, it returns an array of all items.  If $index is undefined in scalar
       context, it returns the number of items.

   @items = $feed->match_item( link => qr/.../, title => qr/.../, ... );
       This method finds item(s) which match all regular expressions given.  This method returns
       an array of all matched items in array context.  This method returns the first matched
       item in scalar context.

   $feed->remove_item( $index or $link );
       This method removes an item/entry specified by zero-based array index or link URL.

   $feed->clear_item();
       This method removes all items/entries from the $feed.

   $feed->sort_item();
       This method sorts the order of items in $feed by "pubDate".

   $feed->uniq_item();
       Reduces the list of items, not to include duplicates.  RDF and Atoms have a guid attribute
       to defined uniqueness, for RSS we use the link.

   $feed->normalize();
       This method calls both the "sort_item()" and "uniq_item()" methods.

   $feed->limit_item( $num );
       Removes items in excess of the specified numeric limit. Items at the end of the list are
       removed. When preceded by "sort_item()" or "normalize()", this deletes more recent items.

   $feed->xmlns( "xmlns:media" => "http://search.yahoo.com/mrss" );
       Adds an XML namespace at the document root of the feed.

   $url = $feed->xmlns( "xmlns:media" );
       Returns the URL of the specified XML namespace.

   @list = $feed->xmlns();
       Returns the list of all XML namespaces used in $feed.

METHODS FOR CHANNEL

   $feed->title( $text );
       This method sets/gets the feed's "title" element, returning its current value when $title
       is undefined.

   $feed->description( $html );
       This method sets/gets the feed's "description" element in plain text or HTML, returning
       its current value when $html is undefined.  It is mapped to "content" element for Atom
       0.3/1.0.

   $feed->pubDate( $date );
       This method sets/gets the feed's "pubDate" element for RSS, returning its current value
       when $date is undefined.  It is mapped to "dc:date" element for RDF, "modified" for Atom
       0.3, and "updated" for Atom 1.0.  See also "DATE AND TIME FORMATS" section below.

   $feed->copyright( $text );
       This method sets/gets the feed's "copyright" element for RSS, returning its current value
       when $text is undefined.  It is mapped to "dc:rights" element for RDF, "copyright" for
       Atom 0.3, and "rights" for Atom 1.0.

   $feed->link( $url );
       This method sets/gets the URL of the web site as the feed's "link" element, returning its
       current value when the $url is undefined.

   $feed->language( $lang );
       This method sets/gets the feed's "language" element for RSS, returning its current value
       when the $lang is undefined.  It is mapped to "dc:language" element for RDF, "feed
       xml:lang=""" for Atom 0.3/1.0.

   $feed->image( $url, $title, $link, $description, $width, $height )
       This method sets/gets the feed's "image" element and its child nodes, returning a list of
       current values when any arguments are undefined.

METHODS FOR ITEM

   $item->title( $text );
       This method sets/gets the item's "title" element, returning its current value when the
       $text is undefined.

   $item->description( $html );
       This method sets/gets the item's "description" element in HTML or plain text, returning
       its current value when $text is undefined.  It is mapped to "content" element for Atom
       0.3/1.0.

   $item->pubDate( $date );
       This method sets/gets the item's "pubDate" element, returning its current value when $date
       is undefined.  It is mapped to "dc:date" element for RDF, "modified" for Atom 0.3, and
       "updated" for Atom 1.0.  See also "DATE AND TIME FORMATS" section below.

   $item->category( $text );
       This method sets/gets the item's "category" element.  returning its current value when
       $text is undefined.  It is mapped to "dc:subject" element for RDF, and ignored for Atom
       0.3.

   $item->author( $name );
       This method sets/gets the item's "author" element, returning its current value when $name
       is undefined.  It is mapped to "dc:creator" element for RDF, "author" for Atom 0.3/1.0.

   $item->guid( $guid, isPermaLink => $bool );
       This method sets/gets the item's "guid" element, returning its current value when $guid is
       undefined.

       It is mapped to "id" element for Atom, and ignored for RDF.  In case of RSS, it will
       return a HASH.  The "isParmaLink" is supported by RSS only, and optional.

   $item->set( $key => $value, ... );
       This method sets customized node values or attributes.  See also "ACCESSOR AND MUTATORS"
       section below.

   $value = $item->get( $key );
       This method returns the node value or attribute.  See also "ACCESSOR AND MUTATORS" section
       below.

   $link = $item->link();
       This method returns the item's "link" element.

ACCESSOR AND MUTATORS

       This module understands only subset of "rdf:*", "dc:*" modules and RSS/RDF/Atom's default
       namespaces by itself.  There are NO native methods for any other external modules, such as
       "media:*".  But "set()" and "get()" methods are available to get/set the value of any
       elements or attributes for these modules.

   $item->set( "module:name" => $value );
       This sets the value of the child node:

           <item><module:name>$value</module:name>...</item>

   $item->set( "module:name@attr" => $value );
       This sets the value of the child node's attribute:

           <item><module:name attr="$value" />...</item>

   $item->set( "@attr" => $value );
       This sets the value of the item's attribute:

           <item attr="$value">...</item>

   $item->set( "hoge/pomu@hare" => $value );
       This code sets the value of the child node's child node's attribute:

           <item><hoge><pomu attr="$value" /></hoge>...</item>

DATE AND TIME FORMATS

       "XML::FeedPP" allows you to describe date/time using any of the three following formats:

   $date = "Thu, 23 Feb 2006 14:43:43 +0900";
       This is the HTTP protocol's preferred format and RSS 2.0's native format, as defined by
       RFC 1123.

   $date = "2006-02-23T14:43:43+09:00";
       W3CDTF is the native format of RDF, as defined by ISO 8601.

   $date = 1140705823;
       The last format is the number of seconds since the epoch, "1970-01-01T00:00:00Z".  You
       know, this is the native format of Perl's "time()" function.

USING MEDIA RSS

       To publish Media RSS, add the "media" namespace then use "set()" setter method to
       manipulate "media:content" element, etc.

           my $feed = XML::FeedPP::RSS->new();
           $feed->xmlns('xmlns:media' => 'http://search.yahoo.com/mrss/');
           my $item = $feed->add_item('http://www.example.com/index.html');
           $item->set('media:content@url' => 'http://www.example.com/image.jpg');
           $item->set('media:content@type' => 'image/jpeg');
           $item->set('media:content@width' => 640);
           $item->set('media:content@height' => 480);

MODULE DEPENDENCIES

       "XML::FeedPP" requires only XML::TreePP which likewise is a pure Perl implementation.  The
       standard LWP::UserAgent is required to download feeds from remote web servers.  "Jcode.pm"
       is required to convert Japanese encodings on Perl 5.005 and 5.6.1, but is NOT required on
       Perl 5.8.x and later.

AUTHOR

       Yusuke Kawasaki, http://www.kawa.net/

COPYRIGHT

       The following copyright notice applies to all the files provided in this distribution,
       including binary files, unless explicitly noted otherwise.

       Copyright 2006-2011 Yusuke Kawasaki

LICENSE

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.