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 version 0.902
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 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 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 Takes a list of key-value pairs.
47 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 Keys that start with a dash specify how the XML document will be
53 generated.
54 The following keys are supported:
56 · "-encoding" (omissible, default "us-ascii")
58 · ""id"" (omissible)
60 · ""link"" (omissible, multiple)
62 · ""title"" (required)
64 · ""author"" (optional, multiple)
66 · ""category"" (optional, multiple)
68 · ""contributor"" (optional, multiple)
70 · ""generator"" (optional)
72 · ""icon"" (optional)
74 · ""logo"" (optional)
76 · ""rights"" (optional)
78 · ""subtitle"" (optional)
80 · ""updated"" (optional)
82 "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 The following keys are supported:
89 · ""author"" (required unless there is a feed-level author, multiple)
91 · ""id"" (omissible)
93 · ""link"" (required, multiple)
95 · ""title"" (required)
97 · ""category"" (optional, multiple)
99 · ""content"" (optional)
101 · ""contributor"" (optional, multiple)
103 · ""published"" (optional)
105 · ""rights"" (optional)
107 · ""summary"" (optional)
109 · ""updated"" (optional)
111 "as_string"
113 Returns the XML representation of the feed as a string.
114 "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
121 "author"
122 A "Person Construct" denoting the author of the feed or entry.
123 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 "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 "term" (required)
136 The category term.
137 "scheme" (optional)
139 A URI that identifies a categorization scheme.
140 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 "label" (optional)
149 A human-readable version of the term.
150 "content"
152 The actual, honest-to-goodness, body of the entry. This is like a "Text
153 Construct", with a couple of extras.
154 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 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 "contributor"
169 A "Person Construct" denoting a contributor to the feed or entry.
170 "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 "icon"
178 The URI of a small image whose width and height should be identical.
179 "id"
181 A URI that is a permanent, globally unique identifier for the feed or
182 entry that MUST NEVER CHANGE.
183 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 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 "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 "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 "href" (required URL)
211 Where the link points to.
212 "type" (optional)
214 An advisory media type that provides a hint about the type of the
215 resource pointed to by the link.
216 "hreflang" (optional)
218 The language of the resource pointed to by the link, an an RFC3066
219 language tag.
220 "title" (optional)
222 Human-readable information about the link.
223 "length" (optional)
225 A hint about the content length in bytes of the resource pointed to
226 by the link.
227 "logo"
229 The URI of an image that should be twice as wide as it is high.
230 "published"
232 A "Date Construct" denoting the moment in time when the entry was first
233 published. This should never change.
234 "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 "subtitle"
241 A "Text Construct" containing an optional additional description of the
242 feed.
243 "summary"
245 A "Text Construct" giving a short summary of the entry.
246 "title"
248 A "Text Construct" containing the title of the feed or entry.
249 "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 In entries, you can use this element to signal significant changes at
255 your discretion.
256
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 Date Construct
262 A string denoting a date and time in W3CDTF format. You can generate
263 those using something like
264 use POSIX 'strftime';
266 my $now = strftime '%Y-%m-%dT%H:%M:%SZ', gmtime;
267 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 The following datetime classes from CPAN are compatible with this
273 interface:
274 · Time::Piece
276 · DateTime
278 · Time::Moment
280 · Panda::Date
282 · Class::Date
284 · Time::Object (an obsolete precursor to Time::Piece)
286 · Time::Date (version 0.05 or newer)
288 The following are not:
290 · DateTime::Tiny
292 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 · Date::Handler
299 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 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 "name" (required)
309 The name of the person.
310 "email" (optional)
312 The person's email address.
313 "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 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 FIXME details, text/html/xhtml
323
325 · Atom Enabled (<http://www.atomenabled.org/>)
326 · W3CDTF Spec (<http://www.w3.org/TR/NOTE-datetime>)
328 · RFC 3066 (<http://rfc.net/rfc3066.html>)
330 · XML::Atom::Syndication
332 · XML::Feed
334
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 There are practically no tests. This is a bug.
341 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 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 The "source" element is not and may never be supported.
351 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
358 Aristotle Pagaltzis <pagaltzis@gmx.de>
359
361 This software is copyright (c) 2017 by Aristotle Pagaltzis.
362 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.
365perl v5.28.0 2017-11-01 XML::Atom::SimpleFeed(3)