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

SYNOPSIS

9        use XML::Atom::SimpleFeed;
10
11        my $feed = XML::Atom::SimpleFeed->new(
12            title   => 'Example Feed',
13            link    => 'http://example.org/',
14            link    => { rel => 'self', href => 'http://example.org/atom', },
15            updated => '2003-12-13T18:30:02Z',
16            author  => 'John Doe',
17            id      => 'urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6',
18        );
19
20        $feed->add_entry(
21            title     => 'Atom-Powered Robots Run Amok',
22            link      => 'http://example.org/2003/12/13/atom03',
23            id        => 'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
24            summary   => 'Some text.',
25            updated   => '2003-12-13T18:30:02Z',
26            category  => 'Atom',
27            category  => 'Miscellaneous',
28        );
29
30        $feed->print;
31

DESCRIPTION

33       This is a minimal API for generating Atom syndication feeds quickly and
34       easily.  It supports all aspects of the Atom format itself but has no
35       mechanism for the inclusion of extension elements.
36
37       You can supply strings for most things, and the module will provide
38       useful defaults. When you want more control, you can provide data
39       structures, as documented, to specify more particulars.
40

INTERFACE

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

ATOM ELEMENTS

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

COMMON ATOM CONSTRUCTS

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

SEE ALSO

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

BUGS AND LIMITATIONS

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

AUTHOR

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