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 use XML::Atom::SimpleFeed;
10 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 $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 $feed->print;
31
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 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
42 "new"
43 Takes a list of key-value pairs.
44 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 Keys that start with a dash specify how the XML document will be
50 generated.
51 The following keys are supported:
53 • "-encoding" (omissible, default "us-ascii")
55 • ""id"" (omissible)
57 • ""link"" (omissible, multiple)
59 • ""title"" (required)
61 • ""author"" (optional, multiple)
63 • ""category"" (optional, multiple)
65 • ""contributor"" (optional, multiple)
67 • ""generator"" (optional)
69 • ""icon"" (optional)
71 • ""logo"" (optional)
73 • ""rights"" (optional)
75 • ""subtitle"" (optional)
77 • ""updated"" (optional)
79 "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 The following keys are supported:
86 • ""author"" (required unless there is a feed-level author, multiple)
88 • ""id"" (omissible)
90 • ""link"" (required, multiple)
92 • ""title"" (required)
94 • ""category"" (optional, multiple)
96 • ""content"" (optional)
98 • ""contributor"" (optional, multiple)
100 • ""published"" (optional)
102 • ""rights"" (optional)
104 • ""summary"" (optional)
106 • ""updated"" (optional)
108 "as_string"
110 Returns the XML representation of the feed as a string.
111 "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
118 "author"
119 A "Person Construct" denoting the author of the feed or entry.
120 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 "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 "term" (required)
133 The category term.
134 "scheme" (optional)
136 A URI that identifies a categorization scheme.
137 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 "label" (optional)
146 A human-readable version of the term.
147 "content"
149 The actual, honest-to-goodness, body of the entry. This is like a "Text
150 Construct", with a couple of extras.
151 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 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 "contributor"
166 A "Person Construct" denoting a contributor to the feed or entry.
167 "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 "icon"
175 The URI of a small image whose width and height should be identical.
176 "id"
178 A URI that is a permanent, globally unique identifier for the feed or
179 entry that MUST NEVER CHANGE.
180 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 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 "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 "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 "href" (required URL)
208 Where the link points to.
209 "type" (optional)
211 An advisory media type that provides a hint about the type of the
212 resource pointed to by the link.
213 "hreflang" (optional)
215 The language of the resource pointed to by the link, an an RFC3066
216 language tag.
217 "title" (optional)
219 Human-readable information about the link.
220 "length" (optional)
222 A hint about the content length in bytes of the resource pointed to
223 by the link.
224 "logo"
226 The URI of an image that should be twice as wide as it is high.
227 "published"
229 A "Date Construct" denoting the moment in time when the entry was first
230 published. This should never change.
231 "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 "subtitle"
238 A "Text Construct" containing an optional additional description of the
239 feed.
240 "summary"
242 A "Text Construct" giving a short summary of the entry.
243 "title"
245 A "Text Construct" containing the title of the feed or entry.
246 "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 In entries, you can use this element to signal significant changes at
252 your discretion.
253
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 Date Construct
259 A string denoting a date and time in W3CDTF format. You can generate
260 those using something like
261 use POSIX 'strftime';
263 my $now = strftime '%Y-%m-%dT%H:%M:%SZ', gmtime;
264 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 The following datetime classes from CPAN are compatible with this
270 interface:
271 • Time::Piece
273 • DateTime
275 • Time::Moment
277 • Panda::Date
279 • Class::Date
281 • Time::Object (an obsolete precursor to Time::Piece)
283 • Time::Date (version 0.05 or newer)
285 The following are not:
287 • DateTime::Tiny
289 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 • Date::Handler
296 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 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 "name" (required)
306 The name of the person.
307 "email" (optional)
309 The person's email address.
310 "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 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 FIXME details, text/html/xhtml
320
322 • Atom Enabled (<http://www.atomenabled.org/>)
323 • W3CDTF Spec (<http://www.w3.org/TR/NOTE-datetime>)
325 • RFC 3066 (<http://rfc.net/rfc3066.html>)
327 • XML::Atom::Syndication
329 • XML::Feed
331
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 There are practically no tests. This is a bug.
338 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 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 The "source" element is not and may never be supported.
348 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
355 Aristotle Pagaltzis <pagaltzis@gmx.de>
356
358 This software is copyright (c) 2020 by Aristotle Pagaltzis.
359 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.
362perl v5.36.0 2023-01-20 XML::Atom::SimpleFeed(3)