Debian Codegraph @

README

raw
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