.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "XML::Atom::SimpleFeed 3pm" .TH XML::Atom::SimpleFeed 3pm "2022-11-27" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" XML::Atom::SimpleFeed \- No\-fuss generation of Atom syndication feeds .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use XML::Atom::SimpleFeed; \& \& my $feed = XML::Atom::SimpleFeed\->new( \& title => \*(AqExample Feed\*(Aq, \& link => \*(Aqhttp://example.org/\*(Aq, \& link => { rel => \*(Aqself\*(Aq, href => \*(Aqhttp://example.org/atom\*(Aq, }, \& updated => \*(Aq2003\-12\-13T18:30:02Z\*(Aq, \& author => \*(AqJohn Doe\*(Aq, \& id => \*(Aqurn:uuid:60a76c80\-d399\-11d9\-b93C\-0003939e0af6\*(Aq, \& ); \& \& $feed\->add_entry( \& title => \*(AqAtom\-Powered Robots Run Amok\*(Aq, \& link => \*(Aqhttp://example.org/2003/12/13/atom03\*(Aq, \& id => \*(Aqurn:uuid:1225c695\-cfb8\-4ebb\-aaaa\-80da344efa6a\*(Aq, \& summary => \*(AqSome text.\*(Aq, \& updated => \*(Aq2003\-12\-13T18:30:02Z\*(Aq, \& category => \*(AqAtom\*(Aq, \& category => \*(AqMiscellaneous\*(Aq, \& ); \& \& $feed\->print; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is a minimal \s-1API\s0 for generating Atom syndication feeds quickly and easily. It supports all aspects of the Atom format itself but has no mechanism for the inclusion of extension elements. .PP You can supply strings for most things, and the module will provide useful defaults. When you want more control, you can provide data structures, as documented, to specify more particulars. .SH "INTERFACE" .IX Header "INTERFACE" .ie n .SS """new""" .el .SS "\f(CWnew\fP" .IX Subsection "new" Takes a list of key-value pairs. .PP Most keys are used to create corresponding \*(L"Atom elements\*(R". To specify multiple instances of an element that may be given multiple times, pass multiple key-value pairs with the same key. .PP Keys that start with a dash specify how the \s-1XML\s0 document will be generated. .PP The following keys are supported: .IP "\(bu" 4 \&\f(CW\*(C`\-encoding\*(C'\fR (\fIomissible\fR, default \f(CW\*(C`us\-ascii\*(C'\fR) .IP "\(bu" 4 "\f(CW\*(C`id\*(C'\fR" (\fIomissible\fR) .IP "\(bu" 4 "\f(CW\*(C`link\*(C'\fR" (\fIomissible\fR, multiple) .IP "\(bu" 4 "\f(CW\*(C`title\*(C'\fR" (\fBrequired\fR) .IP "\(bu" 4 "\f(CW\*(C`author\*(C'\fR" (optional, multiple) .IP "\(bu" 4 "\f(CW\*(C`category\*(C'\fR" (optional, multiple) .IP "\(bu" 4 "\f(CW\*(C`contributor\*(C'\fR" (optional, multiple) .IP "\(bu" 4 "\f(CW\*(C`generator\*(C'\fR" (optional) .IP "\(bu" 4 "\f(CW\*(C`icon\*(C'\fR" (optional) .IP "\(bu" 4 "\f(CW\*(C`logo\*(C'\fR" (optional) .IP "\(bu" 4 "\f(CW\*(C`rights\*(C'\fR" (optional) .IP "\(bu" 4 "\f(CW\*(C`subtitle\*(C'\fR" (optional) .IP "\(bu" 4 "\f(CW\*(C`updated\*(C'\fR" (optional) .ie n .SS """add_entry""" .el .SS "\f(CWadd_entry\fP" .IX Subsection "add_entry" Takes a list of key-value pairs, used to create corresponding \*(L"Atom elements\*(R". To specify multiple instances of an element that may be given multiple times, pass multiple key-value pairs with the same key. .PP The following keys are supported: .IP "\(bu" 4 "\f(CW\*(C`author\*(C'\fR" (\fBrequired\fR unless there is a feed-level author, multiple) .IP "\(bu" 4 "\f(CW\*(C`id\*(C'\fR" (\fIomissible\fR) .IP "\(bu" 4 "\f(CW\*(C`link\*(C'\fR" (\fBrequired\fR, multiple) .IP "\(bu" 4 "\f(CW\*(C`title\*(C'\fR" (\fBrequired\fR) .IP "\(bu" 4 "\f(CW\*(C`category\*(C'\fR" (optional, multiple) .IP "\(bu" 4 "\f(CW\*(C`content\*(C'\fR" (optional) .IP "\(bu" 4 "\f(CW\*(C`contributor\*(C'\fR" (optional, multiple) .IP "\(bu" 4 "\f(CW\*(C`published\*(C'\fR" (optional) .IP "\(bu" 4 "\f(CW\*(C`rights\*(C'\fR" (optional) .IP "\(bu" 4 "\f(CW\*(C`summary\*(C'\fR" (optional) .IP "\(bu" 4 "\f(CW\*(C`updated\*(C'\fR" (optional) .ie n .SS """as_string""" .el .SS "\f(CWas_string\fP" .IX Subsection "as_string" Returns the \s-1XML\s0 representation of the feed as a string. .ie n .SS """print""" .el .SS "\f(CWprint\fP" .IX Subsection "print" Outputs the \s-1XML\s0 representation of the feed to a handle which should be passed as a parameter. Defaults to \f(CW\*(C`STDOUT\*(C'\fR if you do not pass a handle. .SH "ATOM ELEMENTS" .IX Header "ATOM ELEMENTS" .ie n .SS """author""" .el .SS "\f(CWauthor\fP" .IX Subsection "author" A \*(L"Person Construct\*(R" denoting the author of the feed or entry. .PP If you supply at least one author for the feed, you can omit this information from entries; the feed's author(s) will be assumed as the author(s) for those entries. If you do not supply any author for the feed, you \fBmust\fR supply one for each entry. .ie n .SS """category""" .el .SS "\f(CWcategory\fP" .IX Subsection "category" One or more categories that apply to the feed or entry. You can supply a string which will be used as the category term. The full range of details that can be provided by passing a hash instead of a string is as follows: .ie n .IP """term"" (\fBrequired\fR)" 4 .el .IP "\f(CWterm\fR (\fBrequired\fR)" 4 .IX Item "term (required)" The category term. .ie n .IP """scheme"" (optional)" 4 .el .IP "\f(CWscheme\fR (optional)" 4 .IX Item "scheme (optional)" A \s-1URI\s0 that identifies a categorization scheme. .Sp It is common to provide the base of some kind of by-category \s-1URL\s0 here. F.ex., if the weblog \f(CW\*(C`http://www.example.com/blog/\*(C'\fR can be browsed by category using URLs such as \f(CW\*(C`http://www.example.com/blog/category/personal\*(C'\fR, you would supply \&\f(CW\*(C`http://www.example.com/blog/category/\*(C'\fR as the scheme and, in that case, \&\f(CW\*(C`personal\*(C'\fR as the term. .ie n .IP """label"" (optional)" 4 .el .IP "\f(CWlabel\fR (optional)" 4 .IX Item "label (optional)" A human-readable version of the term. .ie n .SS """content""" .el .SS "\f(CWcontent\fP" .IX Subsection "content" The actual, honest-to-goodness, body of the entry. This is like a \&\*(L"Text Construct\*(R", with a couple of extras. .PP In addition to the \f(CW\*(C`type\*(C'\fR values of a \*(L"Text Construct\*(R", you can also supply any \s-1MIME\s0 Type (except multipart types, which the Atom format specification forbids). If you specify a \f(CW\*(C`text/*\*(C'\fR type, the same rules apply as for \f(CW\*(C`text\*(C'\fR. If you pass a \f(CW\*(C`*/xml\*(C'\fR or \f(CW\*(C`*/*+xml\*(C'\fR type, the same rules apply as for \f(CW\*(C`xhtml\*(C'\fR (except in that case there is no wrapper \f(CW\*(C`
\*(C'\fR element). Any other type will be transported as Base64\-encoded binary. .PP \&\s-1XXX\s0 Furthermore, you can supply a \f(CW\*(C`src\*(C'\fR key in place of the \f(CW\*(C`content\*(C'\fR key. In that case, the value of the \f(CW\*(C`src\*(C'\fR key should be a \s-1URL\s0 denoting the actual location of the content. \s-1FIXME\s0 This is not currently supported. \s-1XXX\s0 .ie n .SS """contributor""" .el .SS "\f(CWcontributor\fP" .IX Subsection "contributor" A \*(L"Person Construct\*(R" denoting a contributor to the feed or entry. .ie n .SS """generator""" .el .SS "\f(CWgenerator\fP" .IX Subsection "generator" The software used to generate the feed. Can be supplied as a string or as a hash with \f(CW\*(C`uri\*(C'\fR, \f(CW\*(C`version\*(C'\fR and \f(CW\*(C`name\*(C'\fR keys. Can also be undef to suppress the element entirely. If nothing is passed, defaults to reporting XML::Atom::SimpleFeed as the generator. .ie n .SS """icon""" .el .SS "\f(CWicon\fP" .IX Subsection "icon" The \s-1URI\s0 of a small image whose width and height should be identical. .ie n .SS """id""" .el .SS "\f(CWid\fP" .IX Subsection "id" A \s-1URI\s0 that is a permanent, globally unique identifier for the feed or entry that \fB\s-1MUST NEVER CHANGE\s0\fR. .PP You are encouraged to generate a \s-1UUID\s0 using Data::UUID for the purpose of identifying entries/feeds. It should be stored alongside the resource corresponding to the entry/feed, f.ex. in a column of the article table of your weblog database. To use it as an identifier in the entry/feed, use the \&\f(CW\*(C`urn:uuid:########\-####\-####\-####\-############\*(C'\fR \s-1URI\s0 form. .PP If you do not specify an \s-1ID,\s0 the permalink will be used instead. This is unwise, as permalinks do unfortunately occasionally change. \&\fBIt is your responsibility to ensure that the permalink \s-1NEVER CHANGES.\s0\fR .ie n .SS """link""" .el .SS "\f(CWlink\fP" .IX Subsection "link" A link element. You can either supply a bare string as the parameter, which will be used as the permalink \s-1URI,\s0 or a hash. The permalink for a feed is generally a browser-viewable weblog, upload browser, search engine results page or similar web page; for an entry, it is generally a browser-viewable article, upload details page, search result or similar web page. This \s-1URI\s0 \fIshould\fR be unique. If you supply a hash, you can provide the following range of details in the given hash keys: .ie n .IP """rel"" (optional)" 4 .el .IP "\f(CWrel\fR (optional)" 4 .IX Item "rel (optional)" The link relationship. If omitted, defaults to \f(CW\*(C`alternate\*(C'\fR (note that you can only have one alternate link per feed/entry). Other permissible values are \&\f(CW\*(C`related\*(C'\fR, \f(CW\*(C`self\*(C'\fR, \f(CW\*(C`enclosure\*(C'\fR and \f(CW\*(C`via\*(C'\fR, as well as any \s-1URI.\s0 .ie n .IP """href"" (\fBrequired\fR \s-1URL\s0)" 4 .el .IP "\f(CWhref\fR (\fBrequired\fR \s-1URL\s0)" 4 .IX Item "href (required URL)" Where the link points to. .ie n .IP """type"" (optional)" 4 .el .IP "\f(CWtype\fR (optional)" 4 .IX Item "type (optional)" An advisory media type that provides a hint about the type of the resource pointed to by the link. .ie n .IP """hreflang"" (optional)" 4 .el .IP "\f(CWhreflang\fR (optional)" 4 .IX Item "hreflang (optional)" The language of the resource pointed to by the link, an an \s-1RFC3066\s0 language tag. .ie n .IP """title"" (optional)" 4 .el .IP "\f(CWtitle\fR (optional)" 4 .IX Item "title (optional)" Human-readable information about the link. .ie n .IP """length"" (optional)" 4 .el .IP "\f(CWlength\fR (optional)" 4 .IX Item "length (optional)" A hint about the content length in bytes of the resource pointed to by the link. .ie n .SS """logo""" .el .SS "\f(CWlogo\fP" .IX Subsection "logo" The \s-1URI\s0 of an image that should be twice as wide as it is high. .ie n .SS """published""" .el .SS "\f(CWpublished\fP" .IX Subsection "published" A \*(L"Date Construct\*(R" denoting the moment in time when the entry was first published. This should never change. .ie n .SS """rights""" .el .SS "\f(CWrights\fP" .IX Subsection "rights" A \*(L"Text Construct\*(R" containing a human-readable statement of legal rights for the content of the feed or entry. This is not intended for machine processing. .ie n .SS """subtitle""" .el .SS "\f(CWsubtitle\fP" .IX Subsection "subtitle" A \*(L"Text Construct\*(R" containing an optional additional description of the feed. .ie n .SS """summary""" .el .SS "\f(CWsummary\fP" .IX Subsection "summary" A \*(L"Text Construct\*(R" giving a short summary of the entry. .ie n .SS """title""" .el .SS "\f(CWtitle\fP" .IX Subsection "title" A \*(L"Text Construct\*(R" containing the title of the feed or entry. .ie n .SS """updated""" .el .SS "\f(CWupdated\fP" .IX Subsection "updated" A \*(L"Date Construct\*(R" denoting the moment in time when the feed or entry was last updated. Defaults to the current date and time if omitted. .PP In entries, you can use this element to signal \fIsignificant\fR changes at your discretion. .SH "COMMON ATOM CONSTRUCTS" .IX Header "COMMON ATOM CONSTRUCTS" A number of Atom elements share a common structure. The following sections outline the data you can (or must) pass in each case. .SS "Date Construct" .IX Subsection "Date Construct" A string denoting a date and time in W3CDTF format. You can generate those using something like .PP .Vb 2 \& use POSIX \*(Aqstrftime\*(Aq; \& my $now = strftime \*(Aq%Y\-%m\-%dT%H:%M:%SZ\*(Aq, gmtime; .Ve .PP However, you can also simply pass a Unix timestamp (a positive integer) or an object that responds to an \f(CW\*(C`epoch\*(C'\fR method call. (Make sure that the timezone reported by such objects is correct!) .PP The following datetime classes from \s-1CPAN\s0 are compatible with this interface: .IP "\(bu" 4 Time::Piece .IP "\(bu" 4 DateTime .IP "\(bu" 4 Time::Moment .IP "\(bu" 4 Panda::Date .IP "\(bu" 4 Class::Date .IP "\(bu" 4 Time::Object (an obsolete precursor to Time::Piece) .IP "\(bu" 4 Time::Date (version 0.05 or newer) .PP The following are not: .IP "\(bu" 4 DateTime::Tiny .Sp This class lacks both an \f(CW\*(C`epoch\*(C'\fR method or any way to emulate one – as well as any timezone support in the first place. That makes it unsuitable in principle for use in Atom feeds – unless you have separate information about the timezone. .IP "\(bu" 4 Date::Handler .Sp This class has a suitable method… but sadly, calls it \f(CW\*(C`Epoch\*(C'\fR. So it is left up to you to call \f(CW\*(C`$dh\->Epoch\*(C'\fR to pass such values. .SS "Person Construct" .IX Subsection "Person Construct" You can supply a string to Person Construct parameters, which will be used as the name of the person. The full range of details that can be provided by passing a hash instead of a string is as follows: .ie n .IP """name"" (\fBrequired\fR)" 4 .el .IP "\f(CWname\fR (\fBrequired\fR)" 4 .IX Item "name (required)" The name of the person. .ie n .IP """email"" (optional)" 4 .el .IP "\f(CWemail\fR (optional)" 4 .IX Item "email (optional)" The person's email address. .ie n .IP """uri"" (optional)" 4 .el .IP "\f(CWuri\fR (optional)" 4 .IX Item "uri (optional)" A \s-1URI\s0 to distinguish this person. This would usually be a homepage, but need not actually be a dereferencable \s-1URL.\s0 .SS "Text Construct" .IX Subsection "Text Construct" You can supply a string to Text Construct parameters, which will be used as the \&\s-1HTML\s0 content of the element. .PP \&\s-1FIXME\s0 details, text/html/xhtml .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 Atom Enabled () .IP "\(bu" 4 W3CDTF Spec () .IP "\(bu" 4 \&\s-1RFC 3066\s0 () .IP "\(bu" 4 XML::Atom::Syndication .IP "\(bu" 4 XML::Feed .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" In \f(CW\*(C`content\*(C'\fR elements, the \f(CW\*(C`src\*(C'\fR attribute cannot be used, and non-XML or non-text media types do not get Base64\-encoded automatically. This is a bug. .PP There are practically no tests. This is a bug. .PP Support for \f(CW\*(C`xml:lang\*(C'\fR and \f(CW\*(C`xml:base\*(C'\fR is completely absent. This is a bug and should be partially addressed in a future version. There are however no plans to allow these attributes on arbitrary elements. .PP There are no plans to ever support generating feeds with arbitrary extensions, although support for specific extensions may or may not be added in the future. .PP The \f(CW\*(C`source\*(C'\fR element is not and may never be supported. .PP Nothing is done to ensure that text constructs with type \f(CW\*(C`xhtml\*(C'\fR and entry contents using either that or an \s-1XML\s0 media type are well-formed. So far, this is by design. You should strongly consider using an \s-1XML\s0 writer if you want to include content with such types in your feed. .SH "AUTHOR" .IX Header "AUTHOR" Aristotle Pagaltzis .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2020 by Aristotle Pagaltzis. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.