| 1 |
NAME |
| 2 |
XML::FeedPP -- Parse/write/merge/edit RSS/RDF/Atom syndication feeds |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
Get an RSS file and parse it: |
| 6 |
|
| 7 |
my $source = 'http://use.perl.org/index.rss'; |
| 8 |
my $feed = XML::FeedPP->new( $source ); |
| 9 |
print "Title: ", $feed->title(), "\n"; |
| 10 |
print "Date: ", $feed->pubDate(), "\n"; |
| 11 |
foreach my $item ( $feed->get_item() ) { |
| 12 |
print "URL: ", $item->link(), "\n"; |
| 13 |
print "Title: ", $item->title(), "\n"; |
| 14 |
} |
| 15 |
|
| 16 |
Generate an RDF file and save it: |
| 17 |
|
| 18 |
my $feed = XML::FeedPP::RDF->new(); |
| 19 |
$feed->title( "use Perl" ); |
| 20 |
$feed->link( "http://use.perl.org/" ); |
| 21 |
$feed->pubDate( "Thu, 23 Feb 2006 14:43:43 +0900" ); |
| 22 |
my $item = $feed->add_item( "http://search.cpan.org/~kawasaki/XML-TreePP-0.02" ); |
| 23 |
$item->title( "Pure Perl implementation for parsing/writing xml file" ); |
| 24 |
$item->pubDate( "2006-02-23T14:43:43+09:00" ); |
| 25 |
$feed->to_file( "index.rdf" ); |
| 26 |
|
| 27 |
Convert some RSS/RDF files to Atom format: |
| 28 |
|
| 29 |
my $feed = XML::FeedPP::Atom::Atom10->new(); # create empty atom file |
| 30 |
$feed->merge( "rss.xml" ); # load local RSS file |
| 31 |
$feed->merge( "http://www.kawa.net/index.rdf" ); # load remote RDF file |
| 32 |
my $now = time(); |
| 33 |
$feed->pubDate( $now ); # touch date |
| 34 |
my $atom = $feed->to_string(); # get Atom source code |
| 35 |
|
| 36 |
DESCRIPTION |
| 37 |
"XML::FeedPP" is an all-purpose syndication utility that parses and |
| 38 |
publishes RSS 2.0, RSS 1.0 (RDF), Atom 0.3 and 1.0 feeds. It allows you |
| 39 |
to add new content, merge feeds, and convert among these various |
| 40 |
formats. It is a pure Perl implementation and does not require any other |
| 41 |
module except for XML::TreePP. |
| 42 |
|
| 43 |
METHODS FOR FEED |
| 44 |
$feed = XML::FeedPP->new( "index.rss" ); |
| 45 |
This constructor method creates an "XML::FeedPP" feed instance. The only |
| 46 |
argument is the local filename. The format of $source must be one of the |
| 47 |
supported feed formats -- RSS, RDF or Atom -- or execution is halted. |
| 48 |
|
| 49 |
$feed = XML::FeedPP->new( "http://use.perl.org/index.rss" ); |
| 50 |
The URL on the remote web server is also available as the first |
| 51 |
argument. LWP::UserAgent is required to download it. |
| 52 |
|
| 53 |
$feed = XML::FeedPP->new( '<rss version="2.0">...' ); |
| 54 |
The XML source code is also available as the first argument. |
| 55 |
|
| 56 |
$feed = XML::FeedPP->new( $source, -type => $type ); |
| 57 |
The "-type" argument allows you to specify type of $source from choice |
| 58 |
of 'file', 'url' or 'string'. |
| 59 |
|
| 60 |
$feed = XML::FeedPP->new( $source, utf8_flag => 1 ); |
| 61 |
This makes utf8 flag on for every feed elements. Perl 5.8.1 or later is |
| 62 |
required to use this. |
| 63 |
|
| 64 |
Note that any other options for "XML::TreePP" constructor are also |
| 65 |
allowed like this. See more detail on XML::TreePP. |
| 66 |
|
| 67 |
$feed = XML::FeedPP::RSS->new( $source ); |
| 68 |
This constructor method creates an instance for an RSS 2.0 feed. The |
| 69 |
first argument is optional, but must be valid an RSS source if |
| 70 |
specified. This method returns an empty instance when $source is |
| 71 |
undefined. |
| 72 |
|
| 73 |
$feed = XML::FeedPP::RDF->new( $source ); |
| 74 |
This constructor method creates an instance for RSS 1.0 (RDF) feed. The |
| 75 |
first argument is optional, but must be an RDF source if specified. This |
| 76 |
method returns an empty instance when $source is undefined. |
| 77 |
|
| 78 |
$feed = XML::FeedPP::Atom->new( $source ); |
| 79 |
This constructor method creates an instance for an Atom 0.3/1.0 feed. |
| 80 |
The first argument is optional, but must be an Atom source if specified. |
| 81 |
This method returns an empty instance when $source is undefined. |
| 82 |
|
| 83 |
Atom 1.0 feed is also supported since "XML::FeedPP" version 0.30. Atom |
| 84 |
0.3 is still default, however, future version of this module would |
| 85 |
create Atom 1.0 as default. |
| 86 |
|
| 87 |
$feed = XML::FeedPP::Atom::Atom03->new(); |
| 88 |
This creates an empty Atom 0.3 instance obviously. |
| 89 |
|
| 90 |
$feed = XML::FeedPP::Atom::Atom10->new(); |
| 91 |
This creates an empty Atom 1.0 instance intended. |
| 92 |
|
| 93 |
$feed = XML::FeedPP::RSS->new( link => $link, title => $tile, ... ); |
| 94 |
This creates a RSS instance which has "link", "title" elements etc. |
| 95 |
|
| 96 |
$feed->load( $source ); |
| 97 |
This method loads an RSS/RDF/Atom file, much like "new()" method does. |
| 98 |
|
| 99 |
$feed->merge( $source ); |
| 100 |
This method merges an RSS/RDF/Atom file into the existing $feed |
| 101 |
instance. Top-level metadata from the imported feed is incorporated only |
| 102 |
if missing from the present feed. |
| 103 |
|
| 104 |
$string = $feed->to_string( $encoding ); |
| 105 |
This method generates XML source as string and returns it. The output |
| 106 |
$encoding is optional, and the default encoding is 'UTF-8'. On Perl 5.8 |
| 107 |
and later, any encodings supported by the Encode module are available. |
| 108 |
On Perl 5.005 and 5.6.1, only four encodings supported by the Jcode |
| 109 |
module are available: 'UTF-8', 'Shift_JIS', 'EUC-JP' and 'ISO-2022-JP'. |
| 110 |
'UTF-8' is recommended for overall compatibility. |
| 111 |
|
| 112 |
$string = $feed->to_string( indent => 4 ); |
| 113 |
This makes the output more human readable by indenting appropriately. |
| 114 |
This does not strictly follow the XML specification but does looks nice. |
| 115 |
|
| 116 |
Note that any other options for "XML::TreePP" constructor are also |
| 117 |
allowed like this. See more detail on XML::TreePP. |
| 118 |
|
| 119 |
$feed->to_file( $filename, $encoding ); |
| 120 |
This method generate an XML file. The output $encoding is optional, and |
| 121 |
the default is 'UTF-8'. |
| 122 |
|
| 123 |
$item = $feed->add_item( $link ); |
| 124 |
This method creates a new item/entry and returns its instance. A |
| 125 |
mandatory $link argument is the URL of the new item/entry. |
| 126 |
|
| 127 |
$item = $feed->add_item( $srcitem ); |
| 128 |
This method duplicates an item/entry and adds it to $feed. $srcitem is a |
| 129 |
"XML::FeedPP::*::Item" class's instance which is returned by |
| 130 |
"get_item()" method, as described above. |
| 131 |
|
| 132 |
$item = $feed->add_item( link => $link, title => $tile, ... ); |
| 133 |
This method creates an new item/entry which has "link", "title" elements |
| 134 |
etc. |
| 135 |
|
| 136 |
$item = $feed->get_item( $index ); |
| 137 |
This method returns item(s) in a $feed. A valid zero-based array $index |
| 138 |
returns the corresponding item in the feed. An invalid $index yields |
| 139 |
undef. If $index is undefined in array context, it returns an array of |
| 140 |
all items. If $index is undefined in scalar context, it returns the |
| 141 |
number of items. |
| 142 |
|
| 143 |
@items = $feed->match_item( link => qr/.../, title => qr/.../, ... ); |
| 144 |
This method finds item(s) which match all regular expressions given. |
| 145 |
This method returns an array of all matched items in array context. This |
| 146 |
method returns the first matched item in scalar context. |
| 147 |
|
| 148 |
$feed->remove_item( $index or $link ); |
| 149 |
This method removes an item/entry specified by zero-based array index or |
| 150 |
link URL. |
| 151 |
|
| 152 |
$feed->clear_item(); |
| 153 |
This method removes all items/entries from the $feed. |
| 154 |
|
| 155 |
$feed->sort_item(); |
| 156 |
This method sorts the order of items in $feed by "pubDate". |
| 157 |
|
| 158 |
$feed->uniq_item(); |
| 159 |
This method makes items unique. The second and succeeding items that |
| 160 |
have the same link URL are removed. |
| 161 |
|
| 162 |
$feed->normalize(); |
| 163 |
This method calls both the "sort_item()" and "uniq_item()" methods. |
| 164 |
|
| 165 |
$feed->limit_item( $num ); |
| 166 |
Removes items in excess of the specified numeric limit. Items at the end |
| 167 |
of the list are removed. When preceded by "sort_item()" or |
| 168 |
"normalize()", this deletes more recent items. |
| 169 |
|
| 170 |
$feed->xmlns( "xmlns:media" => "http://search.yahoo.com/mrss" ); |
| 171 |
Adds an XML namespace at the document root of the feed. |
| 172 |
|
| 173 |
$url = $feed->xmlns( "xmlns:media" ); |
| 174 |
Returns the URL of the specified XML namespace. |
| 175 |
|
| 176 |
@list = $feed->xmlns(); |
| 177 |
Returns the list of all XML namespaces used in $feed. |
| 178 |
|
| 179 |
METHODS FOR CHANNEL |
| 180 |
$feed->title( $text ); |
| 181 |
This method sets/gets the feed's "title" element, returning its current |
| 182 |
value when $title is undefined. |
| 183 |
|
| 184 |
$feed->description( $html ); |
| 185 |
This method sets/gets the feed's "description" element in plain text or |
| 186 |
HTML, returning its current value when $html is undefined. It is mapped |
| 187 |
to "content" element for Atom 0.3/1.0. |
| 188 |
|
| 189 |
$feed->pubDate( $date ); |
| 190 |
This method sets/gets the feed's "pubDate" element for RSS, returning |
| 191 |
its current value when $date is undefined. It is mapped to "dc:date" |
| 192 |
element for RDF, "modified" for Atom 0.3, and "updated" for Atom 1.0. |
| 193 |
See also "DATE AND TIME FORMATS" section below. |
| 194 |
|
| 195 |
$feed->copyright( $text ); |
| 196 |
This method sets/gets the feed's "copyright" element for RSS, returning |
| 197 |
its current value when $text is undefined. It is mapped to "dc:rights" |
| 198 |
element for RDF, "copyright" for Atom 0.3, and "rights" for Atom 1.0. |
| 199 |
|
| 200 |
$feed->link( $url ); |
| 201 |
This method sets/gets the URL of the web site as the feed's "link" |
| 202 |
element, returning its current value when the $url is undefined. |
| 203 |
|
| 204 |
$feed->language( $lang ); |
| 205 |
This method sets/gets the feed's "language" element for RSS, returning |
| 206 |
its current value when the $lang is undefined. It is mapped to |
| 207 |
"dc:language" element for RDF, "feed xml:lang=""" for Atom 0.3/1.0. |
| 208 |
|
| 209 |
$feed->image( $url, $title, $link, $description, $width, $height ) |
| 210 |
This method sets/gets the feed's "image" element and its child nodes, |
| 211 |
returning a list of current values when any arguments are undefined. |
| 212 |
|
| 213 |
METHODS FOR ITEM |
| 214 |
$item->title( $text ); |
| 215 |
This method sets/gets the item's "title" element, returning its current |
| 216 |
value when the $text is undefined. |
| 217 |
|
| 218 |
$item->description( $html ); |
| 219 |
This method sets/gets the item's "description" element in HTML or plain |
| 220 |
text, returning its current value when $text is undefined. It is mapped |
| 221 |
to "content" element for Atom 0.3/1.0. |
| 222 |
|
| 223 |
$item->pubDate( $date ); |
| 224 |
This method sets/gets the item's "pubDate" element, returning its |
| 225 |
current value when $date is undefined. It is mapped to "dc:date" element |
| 226 |
for RDF, "modified" for Atom 0.3, and "updated" for Atom 1.0. See also |
| 227 |
"DATE AND TIME FORMATS" section below. |
| 228 |
|
| 229 |
$item->category( $text ); |
| 230 |
This method sets/gets the item's "category" element. returning its |
| 231 |
current value when $text is undefined. It is mapped to "dc:subject" |
| 232 |
element for RDF, and ignored for Atom 0.3. |
| 233 |
|
| 234 |
$item->author( $name ); |
| 235 |
This method sets/gets the item's "author" element, returning its current |
| 236 |
value when $name is undefined. It is mapped to "dc:creator" element for |
| 237 |
RDF, "author" for Atom 0.3/1.0. |
| 238 |
|
| 239 |
$item->guid( $guid, isPermaLink => $bool ); |
| 240 |
This method sets/gets the item's "guid" element, returning its current |
| 241 |
value when $guid is undefined. It is mapped to "id" element for Atom, |
| 242 |
and ignored for RDF. The second argument is optional. |
| 243 |
|
| 244 |
$item->set( $key => $value, ... ); |
| 245 |
This method sets customized node values or attributes. See also |
| 246 |
"ACCESSOR AND MUTATORS" section below. |
| 247 |
|
| 248 |
$value = $item->get( $key ); |
| 249 |
This method returns the node value or attribute. See also "ACCESSOR AND |
| 250 |
MUTATORS" section below. |
| 251 |
|
| 252 |
$link = $item->link(); |
| 253 |
This method returns the item's "link" element. |
| 254 |
|
| 255 |
ACCESSOR AND MUTATORS |
| 256 |
This module understands only subset of "rdf:*", "dc:*" modules and |
| 257 |
RSS/RDF/Atom's default namespaces by itself. There are NO native methods |
| 258 |
for any other external modules, such as "media:*". But "set()" and |
| 259 |
"get()" methods are available to get/set the value of any elements or |
| 260 |
attributes for these modules. |
| 261 |
|
| 262 |
$item->set( "module:name" => $value ); |
| 263 |
This sets the value of the child node: |
| 264 |
|
| 265 |
<item><module:name>$value</module:name>...</item> |
| 266 |
|
| 267 |
$item->set( "module:name@attr" => $value ); |
| 268 |
This sets the value of the child node's attribute: |
| 269 |
|
| 270 |
<item><module:name attr="$value" />...</item> |
| 271 |
|
| 272 |
$item->set( "@attr" => $value ); |
| 273 |
This sets the value of the item's attribute: |
| 274 |
|
| 275 |
<item attr="$value">...</item> |
| 276 |
|
| 277 |
$item->set( "hoge/pomu@hare" => $value ); |
| 278 |
This code sets the value of the child node's child node's attribute: |
| 279 |
|
| 280 |
<item><hoge><pomu attr="$value" /></hoge>...</item> |
| 281 |
|
| 282 |
DATE AND TIME FORMATS |
| 283 |
"XML::FeedPP" allows you to describe date/time using any of the three |
| 284 |
following formats: |
| 285 |
|
| 286 |
$date = "Thu, 23 Feb 2006 14:43:43 +0900"; |
| 287 |
This is the HTTP protocol's preferred format and RSS 2.0's native |
| 288 |
format, as defined by RFC 1123. |
| 289 |
|
| 290 |
$date = "2006-02-23T14:43:43+09:00"; |
| 291 |
W3CDTF is the native format of RDF, as defined by ISO 8601. |
| 292 |
|
| 293 |
$date = 1140705823; |
| 294 |
The last format is the number of seconds since the epoch, |
| 295 |
"1970-01-01T00:00:00Z". You know, this is the native format of Perl's |
| 296 |
"time()" function. |
| 297 |
|
| 298 |
USING MEDIA RSS |
| 299 |
To publish Media RSS, add the "media" namespace then use "set()" setter |
| 300 |
method to manipulate "media:content" element, etc. |
| 301 |
|
| 302 |
my $feed = XML::FeedPP::RSS->new(); |
| 303 |
$feed->xmlns('xmlns:media' => 'http://search.yahoo.com/mrss/'); |
| 304 |
my $item = $feed->add_item('http://www.example.com/index.html'); |
| 305 |
$item->set('media:content@url' => 'http://www.example.com/image.jpg'); |
| 306 |
$item->set('media:content@type' => 'image/jpeg'); |
| 307 |
$item->set('media:content@width' => 640); |
| 308 |
$item->set('media:content@height' => 480); |
| 309 |
|
| 310 |
MODULE DEPENDENCIES |
| 311 |
"XML::FeedPP" requires only XML::TreePP which likewise is a pure Perl |
| 312 |
implementation. The standard LWP::UserAgent is required to download |
| 313 |
feeds from remote web servers. "Jcode.pm" is required to convert |
| 314 |
Japanese encodings on Perl 5.005 and 5.6.1, but is NOT required on Perl |
| 315 |
5.8.x and later. |
| 316 |
|
| 317 |
AUTHOR |
| 318 |
Yusuke Kawasaki, http://www.kawa.net/ |
| 319 |
|
| 320 |
COPYRIGHT |
| 321 |
The following copyright notice applies to all the files provided in this |
| 322 |
distribution, including binary files, unless explicitly noted otherwise. |
| 323 |
|
| 324 |
Copyright 2006-2011 Yusuke Kawasaki |
| 325 |
|
| 326 |
LICENSE |
| 327 |
This library is free software; you can redistribute it and/or modify it |
| 328 |
under the same terms as Perl itself. |
| 329 |
|