1XML::Atom::SimpleFeed(3U)ser Contributed Perl DocumentatiXoMnL::Atom::SimpleFeed(3)
2
3
4

NAME

6       XML::Atom::SimpleFeed - No-fuss generation of Atom syndication feeds
7

VERSION

9       version 0.902
10

SYNOPSIS

12        use XML::Atom::SimpleFeed;
13
14        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
23        $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
33        $feed->print;
34

DESCRIPTION

36       This is a minimal API for generating Atom syndication feeds quickly and
37       easily.  It supports all aspects of the Atom format itself but has no
38       mechanism for the inclusion of extension elements.
39
40       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

INTERFACE

45   "new"
46       Takes a list of key-value pairs.
47
48       Most keys are used to create corresponding "Atom elements".  To specify
49       multiple instances of an element that may be given multiple times, pass
50       multiple key-value pairs with the same key.
51
52       Keys that start with a dash specify how the XML document will be
53       generated.
54
55       The following keys are supported:
56
57       ·   "-encoding" (omissible, default "us-ascii")
58
59       ·   ""id"" (omissible)
60
61       ·   ""link"" (omissible, multiple)
62
63       ·   ""title"" (required)
64
65       ·   ""author"" (optional, multiple)
66
67       ·   ""category"" (optional, multiple)
68
69       ·   ""contributor"" (optional, multiple)
70
71       ·   ""generator"" (optional)
72
73       ·   ""icon"" (optional)
74
75       ·   ""logo"" (optional)
76
77       ·   ""rights"" (optional)
78
79       ·   ""subtitle"" (optional)
80
81       ·   ""updated"" (optional)
82
83   "add_entry"
84       Takes a list of key-value pairs, used to create corresponding "Atom
85       elements".  To specify multiple instances of an element that may be
86       given multiple times, pass multiple key-value pairs with the same key.
87
88       The following keys are supported:
89
90       ·   ""author"" (required unless there is a feed-level author, multiple)
91
92       ·   ""id"" (omissible)
93
94       ·   ""link"" (required, multiple)
95
96       ·   ""title"" (required)
97
98       ·   ""category"" (optional, multiple)
99
100       ·   ""content"" (optional)
101
102       ·   ""contributor"" (optional, multiple)
103
104       ·   ""published"" (optional)
105
106       ·   ""rights"" (optional)
107
108       ·   ""summary"" (optional)
109
110       ·   ""updated"" (optional)
111
112   "as_string"
113       Returns the XML representation of the feed as a string.
114
115   "print"
116       Outputs the XML representation of the feed to a handle which should be
117       passed as a parameter. Defaults to "STDOUT" if you do not pass a
118       handle.
119

ATOM ELEMENTS

121   "author"
122       A "Person Construct" denoting the author of the feed or entry.
123
124       If you supply at least one author for the feed, you can omit this
125       information from entries; the feed's author(s) will be assumed as the
126       author(s) for those entries. If you do not supply any author for the
127       feed, you must supply one for each entry.
128
129   "category"
130       One or more categories that apply to the feed or entry. You can supply
131       a string which will be used as the category term. The full range of
132       details that can be provided by passing a hash instead of a string is
133       as follows:
134
135       "term" (required)
136           The category term.
137
138       "scheme" (optional)
139           A URI that identifies a categorization scheme.
140
141           It is common to provide the base of some kind of by-category URL
142           here. F.ex., if the weblog "http://www.example.com/blog/" can be
143           browsed by category using URLs such as
144           "http://www.example.com/blog/category/personal", you would supply
145           "http://www.example.com/blog/category/" as the scheme and, in that
146           case, "personal" as the term.
147
148       "label" (optional)
149           A human-readable version of the term.
150
151   "content"
152       The actual, honest-to-goodness, body of the entry. This is like a "Text
153       Construct", with a couple of extras.
154
155       In addition to the "type" values of a "Text Construct", you can also
156       supply any MIME Type (except multipart types, which the Atom format
157       specification forbids). If you specify a "text/*" type, the same rules
158       apply as for "text".  If you pass a "*/xml" or "*/*+xml" type, the same
159       rules apply as for "xhtml" (except in that case there is no wrapper
160       "<div>" element). Any other type will be transported as Base64-encoded
161       binary.
162
163       XXX Furthermore, you can supply a "src" key in place of the "content"
164       key. In that case, the value of the "src" key should be a URL denoting
165       the actual location of the content. FIXME This is not currently
166       supported. XXX
167
168   "contributor"
169       A "Person Construct" denoting a contributor to the feed or entry.
170
171   "generator"
172       The software used to generate the feed. Can be supplied as a string or
173       as a hash with "uri", "version" and "name" keys. Can also be undef to
174       suppress the element entirely. If nothing is passed, defaults to
175       reporting XML::Atom::SimpleFeed as the generator.
176
177   "icon"
178       The URI of a small image whose width and height should be identical.
179
180   "id"
181       A URI that is a permanent, globally unique identifier for the feed or
182       entry that MUST NEVER CHANGE.
183
184       You are encouraged to generate a UUID using Data::UUID for the purpose
185       of identifying entries/feeds. It should be stored alongside the
186       resource corresponding to the entry/feed, f.ex. in a column of the
187       article table of your weblog database. To use it as an identifier in
188       the entry/feed, use the "urn:uuid:########-####-####-####-############"
189       URI form.
190
191       If you do not specify an ID, the permalink will be used instead. This
192       is unwise, as permalinks do unfortunately occasionally change.  It is
193       your responsibility to ensure that the permalink NEVER CHANGES.
194
195   "link"
196       A link element. You can either supply a bare string as the parameter,
197       which will be used as the permalink URI, or a hash. The permalink for a
198       feed is generally a browser-viewable weblog, upload browser, search
199       engine results page or similar web page; for an entry, it is generally
200       a browser-viewable article, upload details page, search result or
201       similar web page. This URI should be unique. If you supply a hash, you
202       can provide the following range of details in the given hash keys:
203
204       "rel" (optional)
205           The link relationship. If omitted, defaults to "alternate" (note
206           that you can only have one alternate link per feed/entry). Other
207           permissible values are "related", "self", "enclosure" and "via", as
208           well as any URI.
209
210       "href" (required URL)
211           Where the link points to.
212
213       "type" (optional)
214           An advisory media type that provides a hint about the type of the
215           resource pointed to by the link.
216
217       "hreflang" (optional)
218           The language of the resource pointed to by the link, an an RFC3066
219           language tag.
220
221       "title" (optional)
222           Human-readable information about the link.
223
224       "length" (optional)
225           A hint about the content length in bytes of the resource pointed to
226           by the link.
227
228   "logo"
229       The URI of an image that should be twice as wide as it is high.
230
231   "published"
232       A "Date Construct" denoting the moment in time when the entry was first
233       published. This should never change.
234
235   "rights"
236       A "Text Construct" containing a human-readable statement of legal
237       rights for the content of the feed or entry. This is not intended for
238       machine processing.
239
240   "subtitle"
241       A "Text Construct" containing an optional additional description of the
242       feed.
243
244   "summary"
245       A "Text Construct" giving a short summary of the entry.
246
247   "title"
248       A "Text Construct" containing the title of the feed or entry.
249
250   "updated"
251       A "Date Construct" denoting the moment in time when the feed or entry
252       was last updated. Defaults to the current date and time if omitted.
253
254       In entries, you can use this element to signal significant changes at
255       your discretion.
256

COMMON ATOM CONSTRUCTS

258       A number of Atom elements share a common structure. The following
259       sections outline the data you can (or must) pass in each case.
260
261   Date Construct
262       A string denoting a date and time in W3CDTF format. You can generate
263       those using something like
264
265        use POSIX 'strftime';
266        my $now = strftime '%Y-%m-%dT%H:%M:%SZ', gmtime;
267
268       However, you can also simply pass a Unix timestamp (a positive integer)
269       or an object that responds to an "epoch" method call. (Make sure that
270       the timezone reported by such objects is correct!)
271
272       The following datetime classes from CPAN are compatible with this
273       interface:
274
275       ·   Time::Piece
276
277       ·   DateTime
278
279       ·   Time::Moment
280
281       ·   Panda::Date
282
283       ·   Class::Date
284
285       ·   Time::Object (an obsolete precursor to Time::Piece)
286
287       ·   Time::Date (version 0.05 or newer)
288
289       The following are not:
290
291       ·   DateTime::Tiny
292
293           This class lacks both an "epoch" method or any way to emulate one –
294           as well as any timezone support in the first place.  That makes it
295           unsuitable in principle for use in Atom feeds – unless you have
296           separate information about the timezone.
297
298       ·   Date::Handler
299
300           This class has a suitable method… but sadly, calls it "Epoch".  So
301           it is left up to you to call "$dh->Epoch" to pass such values.
302
303   Person Construct
304       You can supply a string to Person Construct parameters, which will be
305       used as the name of the person. The full range of details that can be
306       provided by passing a hash instead of a string is as follows:
307
308       "name" (required)
309           The name of the person.
310
311       "email" (optional)
312           The person's email address.
313
314       "uri" (optional)
315           A URI to distinguish this person. This would usually be a homepage,
316           but need not actually be a dereferencable URL.
317
318   Text Construct
319       You can supply a string to Text Construct parameters, which will be
320       used as the HTML content of the element.
321
322       FIXME details, text/html/xhtml
323

SEE ALSO

325       ·   Atom Enabled (<http://www.atomenabled.org/>)
326
327       ·   W3CDTF Spec (<http://www.w3.org/TR/NOTE-datetime>)
328
329       ·   RFC 3066 (<http://rfc.net/rfc3066.html>)
330
331       ·   XML::Atom::Syndication
332
333       ·   XML::Feed
334

BUGS AND LIMITATIONS

336       In "content" elements, the "src" attribute cannot be used, and non-XML
337       or non-text media types do not get Base64-encoded automatically. This
338       is a bug.
339
340       There are practically no tests. This is a bug.
341
342       Support for "xml:lang" and "xml:base" is completely absent. This is a
343       bug and should be partially addressed in a future version. There are
344       however no plans to allow these attributes on arbitrary elements.
345
346       There are no plans to ever support generating feeds with arbitrary
347       extensions, although support for specific extensions may or may not be
348       added in the future.
349
350       The "source" element is not and may never be supported.
351
352       Nothing is done to ensure that text constructs with type "xhtml" and
353       entry contents using either that or an XML media type are well-formed.
354       So far, this is by design. You should strongly consider using an XML
355       writer if you want to include content with such types in your feed.
356

AUTHOR

358       Aristotle Pagaltzis <pagaltzis@gmx.de>
359
361       This software is copyright (c) 2017 by Aristotle Pagaltzis.
362
363       This is free software; you can redistribute it and/or modify it under
364       the same terms as the Perl 5 programming language system itself.
365
366
367
368perl v5.28.0                      2017-11-01          XML::Atom::SimpleFeed(3)
Impressum