1XML::Atom::SimpleFeed(3U)ser Contributed Perl DocumentatiXoMnL::Atom::SimpleFeed(3)
2
6 XML::Atom::SimpleFeed - No-fuss generation of Atom syndication feeds
7
9 This document describes XML::Atom::SimpleFeed version 0.84
10
12 use XML::Atom::SimpleFeed;
13 my $feed = XML::Atom::SimpleFeed->new(
15 title => 'Example Feed',
16 link => 'http://example.org/',
17 link => { rel => 'self', href => 'http://example.org/atom', },
18 updated => '2003-12-13T18:30:02Z',
19 author => 'John Doe',
20 id => 'urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6',
21 );
22 $feed->add_entry(
24 title => 'Atom-Powered Robots Run Amok',
25 link => 'http://example.org/2003/12/13/atom03',
26 id => 'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
27 summary => 'Some text.',
28 updated => '2003-12-13T18:30:02Z',
29 category => 'Atom',
30 category => 'Miscellaneous',
31 );
32 $feed->print;
34
36 This module provides a minimal API for generating Atom syndication
37 feeds quickly and easily. It supports all aspects of the Atom format,
38 but has no provisions for generating feeds with extension elements.
39 You can supply strings for most things, and the module will provide
41 useful defaults. When you want more control, you can provide data
42 structures, as documented, to specify more particulars.
43
45 "new"
46 XML::Atom::SimpleFeed instances are created by the "new" constructor,
47 which takes a list of key-value pairs as parameters. The keys are used
48 to create the corresponding "Atom elements". The following elements are
49 available:
50 · ""id"" (omissible)
52 · ""link"" (omissible, multiple)
54 · ""title"" (required)
56 · ""author"" (optional, multiple)
58 · ""category"" (optional, multiple)
60 · ""contributor"" (optional, multiple)
62 · ""generator"" (optional)
64 · ""icon"" (optional)
66 · ""logo"" (optional)
68 · ""rights"" (optional)
70 · ""subtitle"" (optional)
72 · ""updated"" (optional)
74 To specify multiple instances of an element that may be given multiple
76 times, simply list multiple key-value pairs with the same key.
77 "add_entry"
79 This method adds an entry into the Atom feed. It takes a list of key-
80 value pairs as parameters. The keys are used to create the
81 corresponding "Atom Elements". The following elements are available:
82 · ""author"" (required unless there is a feed-level author, multiple)
84 · ""id"" (omissible)
86 · ""link"" (required, multiple)
88 · ""title"" (required)
90 · ""category"" (optional, multiple)
92 · ""content"" (optional)
94 · ""contributor"" (optional, multiple)
96 · ""published"" (optional)
98 · ""rights"" (optional)
100 · ""summary"" (optional)
102 · ""updated"" (optional)
104 To specify multiple instances of an element that may be given multiple
106 times, simply list multiple key-value pairs with the same key.
107 "no_generator"
109 Suppresses the output of a default "generator" element. It is not
110 necessary to call this method if you supply a custom "generator"
111 element.
112 "as_string"
114 Returns the XML representation of the feed as a string.
115 "print"
117 Outputs the XML representation of the feed to a handle which should be
118 passed as a parameter. Defaults to "STDOUT" if you do not pass a
119 handle.
120
122 "author"
123 A "Person Construct" denoting the author of the feed or entry.
124 If you supply at least one author for the feed, you can omit this
126 information from entries; the feed's author(s) will be assumed as the
127 author(s) for those entries. If you do not supply any author for the
128 feed, you must supply one for each entry.
129 "category"
131 One or more categories that apply to the feed or entry. You can supply
132 a string which will be used as the category term. The full range of
133 details that can be provided by passing a hash instead of a string is
134 as follows:
135 "term" (required)
137 The category term.
138 "scheme" (optional)
140 A URI that identifies a categorization scheme.
141 It is common to provide the base of some kind of by-category URL
143 here. F.ex., if the weblog "http://www.example.com/blog/" can be
144 browsed by category using URLs such as
145 "http://www.example.com/blog/category/personal", you would supply
146 "http://www.example.com/blog/category/" as the scheme and, in that
147 case, "personal" as the term.
148 "label" (optional)
150 A human-readable version of the term.
151 "content"
153 The actual, honest-to-goodness, body of the entry. This is like a "Text
154 Construct", with a couple of extras.
155 In addition to the "type" values of a "Text Construct", you can also
157 supply any MIME Type (except multipart types, which the Atom format
158 specification forbids). If you specify a "text/*" type, the same rules
159 apply as for "text". If you pass a "*/xml" or "*/*+xml" type, the same
160 rules apply as for "xhtml" (except in that case there is no wrapper
161 "<div>" element). Any other type will be transported as Base64-encoded
162 binary.
163 XXX Furthermore, you can supply a "src" key in place of the "content"
165 key. In that case, the value of the "src" key should be a URL denoting
166 the actual location of the content. FIXME This is not currently
167 supported. XXX
168 "contributor"
170 A "Person Construct" denoting a contributor to the feed or entry.
171 "generator"
173 The software used to generate the feed. Can be supplied as a string, or
174 a hash with "uri", "version" and "name" keys. Defaults to reporting
175 XML::Atom::SimpleFeed as the generator, which can be calling
176 "no_generator".
177 "icon"
179 The URI of a small image that should have the same height and width.
180 "id"
182 A URI that is a permanent, globally unique identifier for the feed or
183 entry that MUST NEVER CHANGE.
184 You are encouraged to generate a UUID using Data::UUID for the purpose
186 of identifying entries/feeds. It should be stored alongside the
187 resource corresponding to the entry/feed, f.ex. in a column of the
188 article table of your weblog database. To use it as an identifier in
189 the entry/feed, use the "urn:uuid:########-####-####-####-############"
190 URI form.
191 If you do not specify an ID, the permalink will be used instead. This
193 is unwise, as permalinks do unfortunately occasionally change. It is
194 your responsibility to ensure that the permalink NEVER CHANGES.
195 "link"
197 A link element. You can either supply a bare string as the parameter,
198 which will be used as the permalink URI, or a hash. The permalink for a
199 feed is generally a browser-viewable weblog, upload browser, search
200 engine results page or similar web page; for an entry, it is generally
201 a browser-viewable article, upload details page, search result or
202 similar web page. This URI should be unique. If you supply a hash, you
203 can provide the following range of details in the given hash keys:
204 "rel" (optional)
206 The link relationship. If omitted, defaults to "alternate" (note
207 that you can only have one alternate link per feed/entry). Other
208 permissible values are "related", "self", "enclosure" and "via", as
209 well as any URI.
210 "href" (required URL)
212 Where the link points to.
213 "type" (optional)
215 An advisory media type that provides a hint about the type of the
216 resource pointed to by the link.
217 "hreflang" (optional)
219 The language of the resource pointed to by the link, an an RFC3066
220 language tag.
221 "title" (optional)
223 Human-readable information about the link.
224 "length" (optional)
226 A hint about the content length in bytes of the resource pointed to
227 by the link.
228 "logo"
230 The URI of an image that should be twice as wide as it is high.
231 "published"
233 A "Date Construct" denoting the moment in time when the entry was first
234 published. This should never change.
235 "rights"
237 A "Text Construct" containing a human-readable statement of legal
238 rights for the content of the feed or entry. This is not intended for
239 machine processing.
240 "subtitle"
242 A "Text Construct" containing an optional additional description of the
243 feed.
244 "summary"
246 A "Text Construct" giving a short summary of the entry.
247 "title"
249 A "Text Construct" containing the title of the feed or entry.
250 "updated"
252 A "Date Construct" denoting the moment in time when the feed or entry
253 was last updated. Defaults to the current date and time if omitted.
254 In entries, you can use this element to signal significant changes at
256 your discretion.
257
259 A number of Atom elements share a common structure. The following
260 sections outline the data you can (or must) pass in each case.
261 Date Construct
263 A string denoting a date and time in W3CDTF format. You can generate
264 those using something like
265 use POSIX qw( strftime );
267 my $now = strftime '%Y-%m-%dT%H:%M:%SZ', gmtime;
268 Person Construct
270 You can supply a string to Person Construct parameters, which will be
271 used as the name of the person. The full range of details that can be
272 provided by passing a hash instead of a string is as follows:
273 "name" (required)
275 The name of the person.
276 "email" (optional)
278 The person's email address.
279 "uri" (optional)
281 A URI to distinguish this person. This would usually be a homepage,
282 but need not actually be a dereferencable URL.
283 Text Construct
285 You can supply a string to Text Construct parameters, which will be
286 used as the HTML content of the element.
287 FIXME details, text/html/xhtml
289
291 · Atom Enabled (<http://www.atomenabled.org/>)
292 · W3CDTF Spec (http://www.w3.org/TR/NOTE-datetime
294 <http://www.w3.org/TR/NOTE-datetime>)
295 · RFC 3066 (<http://rfc.net/rfc3066.html>)
297 · XML::Atom::Syndication
299 · XML::Feed
301 · http://groups.yahoo.com/group/atomic-perl/
303
305 In "content" elements, the "src" attribute cannot be used, and non-XML
306 or -text media types do not get Base64-encoded automatically. This is a
307 bug.
308 There are practically no tests. This is a bug.
310 Support for "xml:lang" and "xml:base" is completely absent. This is a
312 bug and should be partially addressed in a future version. There are
313 however no plans to allow these attributes on arbitrary elements.
314 There are no plans to ever support generating feeds with arbitrary
316 extensions, although support for specific extensions may or may not be
317 added in the future.
318 The "source" element is not and may never be supported.
320 Nothing is done to ensure that text constructs with type "xhtml" and
322 entry contents using either that or an XML media type are well-formed.
323 So far, this is by design. You should strongly consider using an XML
324 writer if you want to include content with such types in your feed.
325 If you find bugs or you have feature requests, please report them to
327 mailto:bug-xml-atom-simplefeed@rt.cpan.org <mailto:bug-xml-atom-
328 simplefeed@rt.cpan.org>, or through the web interface at
329 <http://rt.cpan.org>.
330
332 Aristotle Pagaltzis, <mailto:pagaltzis@gmx.de>
333 API designed largely by H. Wade Minter.
335
337 Copyright (c) 2005-2006, Aristotle Pagaltzis. All rights reserved.
338 This module is free software; you can redistribute it and/or modify it
340 under the same terms as Perl itself. See perlartistic.
341
343 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
344 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
345 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
346 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
347 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
348 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
349 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
350 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
351 NECESSARY SERVICING, REPAIR, OR CORRECTION.
352 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
354 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
355 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
356 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
357 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
358 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
359 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
360 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
361 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
362 DAMAGES.
363perl v5.12.0 2010-05-07 XML::Atom::SimpleFeed(3)