


XML::Atom::SimpUsereContributed Perl DocuXML::Atom::SimpleFeed(3)


NAME
       XML::Atom::SimpleFeed - No-fuss generation of Atom syndication feeds

VERSION
       This document describes XML::Atom::SimpleFeed version 0.84

SYNOPSIS
        use XML::Atom::SimpleFeed;

        my $feed = XML::Atom::SimpleFeed->new(
            title   => 'Example Feed',
            link    => 'http://example.org/',
            link    => { rel => 'self', href => 'http://example.org/atom', },
            updated => '2003-12-13T18:30:02Z',
            author  => 'John Doe',
            id      => 'urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6',
        );

        $feed->add_entry(
            title     => 'Atom-Powered Robots Run Amok',
            link      => 'http://example.org/2003/12/13/atom03',
            id        => 'urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a',
            summary   => 'Some text.',
            updated   => '2003-12-13T18:30:02Z',
            category  => 'Atom',
            category  => 'Miscellaneous',
        );

        $feed->print;

DESCRIPTION
       This module provides a minimal API for generating Atom syndication
       feeds quickly and easily. It supports all aspects of the Atom format,
       but has no provisions for generating feeds with extension elements.

       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.

INTERFACE
   "new"
       XML::Atom::SimpleFeed instances are created by the "new" constructor,
       which takes a list of key-value pairs as parameters. The keys are used
       to create the corresponding "Atom elements". The following elements are
       available:

       o   ""id"" (omissible)

       o   ""link"" (omissible, multiple)

       o   ""title"" (required)

       o   ""author"" (optional, multiple)




perl v5.12.2                2011-02-22                          1





XML::Atom::SimpUsereContributed Perl DocuXML::Atom::SimpleFeed(3)


       o   ""category"" (optional, multiple)

       o   ""contributor"" (optional, multiple)

       o   ""generator"" (optional)

       o   ""icon"" (optional)

       o   ""logo"" (optional)

       o   ""rights"" (optional)

       o   ""subtitle"" (optional)

       o   ""updated"" (optional)

       To specify multiple instances of an element that may be given multiple
       times, simply list multiple key-value pairs with the same key.

   "add_entry"
       This method adds an entry into the Atom feed. It takes a list of key-
       value pairs as parameters. The keys are used to create the
       corresponding "Atom Elements". The following elements are available:

       o   ""author"" (required unless there is a feed-level author, multiple)

       o   ""id"" (omissible)

       o   ""link"" (required, multiple)

       o   ""title"" (required)

       o   ""category"" (optional, multiple)

       o   ""content"" (optional)

       o   ""contributor"" (optional, multiple)

       o   ""published"" (optional)

       o   ""rights"" (optional)

       o   ""summary"" (optional)

       o   ""updated"" (optional)

       To specify multiple instances of an element that may be given multiple
       times, simply list multiple key-value pairs with the same key.

   "no_generator"
       Suppresses the output of a default "generator" element. It is not
       necessary to call this method if you supply a custom "generator"
       element.




perl v5.12.2                2011-02-22                          2





XML::Atom::SimpUsereContributed Perl DocuXML::Atom::SimpleFeed(3)


   "as_string"
       Returns the XML representation of the feed as a string.

   "print"
       Outputs the XML representation of the feed to a handle which should be
       passed as a parameter. Defaults to "STDOUT" if you do not pass a
       handle.

ATOM ELEMENTS
   "author"
       A "Person Construct" denoting the author of the feed or entry.

       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 must supply one for each entry.

   "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:

       "term" (required)
           The category term.

       "scheme" (optional)
           A URI that identifies a categorization scheme.

           It is common to provide the base of some kind of by-category URL
           here. F.ex., if the weblog "http://www.example.com/blog/" can be
           browsed by category using URLs such as
           "http://www.example.com/blog/category/personal", you would supply
           "http://www.example.com/blog/category/" as the scheme and, in that
           case, "personal" as the term.

       "label" (optional)
           A human-readable version of the term.

   "content"
       The actual, honest-to-goodness, body of the entry. This is like a "Text
       Construct", with a couple of extras.

       In addition to the "type" values of a "Text Construct", you can also
       supply any MIME Type (except multipart types, which the Atom format
       specification forbids). If you specify a "text/*" type, the same rules
       apply as for "text". If you pass a "*/xml" or "*/*+xml" type, the same
       rules apply as for "xhtml" (except in that case there is no wrapper
       "<div>" element). Any other type will be transported as Base64-encoded
       binary.

       XXX Furthermore, you can supply a "src" key in place of the "content"
       key. In that case, the value of the "src" key should be a URL denoting
       the actual location of the content. FIXME This is not currently



perl v5.12.2                2011-02-22                          3





XML::Atom::SimpUsereContributed Perl DocuXML::Atom::SimpleFeed(3)


       supported. XXX

   "contributor"
       A "Person Construct" denoting a contributor to the feed or entry.

   "generator"
       The software used to generate the feed. Can be supplied as a string, or
       a hash with "uri", "version" and "name" keys. Defaults to reporting
       XML::Atom::SimpleFeed as the generator, which can be calling
       "no_generator".

   "icon"
       The URI of a small image that should have the same height and width.

   "id"
       A URI that is a permanent, globally unique identifier for the feed or
       entry that MUST NEVER CHANGE.

       You are encouraged to generate a UUID 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 "urn:uuid:########-####-####-####-############"
       URI form.

       If you do not specify an ID, the permalink will be used instead. This
       is unwise, as permalinks do unfortunately occasionally change. It is
       your responsibility to ensure that the permalink NEVER CHANGES.

   "link"
       A link element. You can either supply a bare string as the parameter,
       which will be used as the permalink URI, 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 URI should be unique. If you supply a hash, you
       can provide the following range of details in the given hash keys:

       "rel" (optional)
           The link relationship. If omitted, defaults to "alternate" (note
           that you can only have one alternate link per feed/entry). Other
           permissible values are "related", "self", "enclosure" and "via", as
           well as any URI.

       "href" (required URL)
           Where the link points to.

       "type" (optional)
           An advisory media type that provides a hint about the type of the
           resource pointed to by the link.

       "hreflang" (optional)
           The language of the resource pointed to by the link, an an RFC3066
           language tag.



perl v5.12.2                2011-02-22                          4





XML::Atom::SimpUsereContributed Perl DocuXML::Atom::SimpleFeed(3)


       "title" (optional)
           Human-readable information about the link.

       "length" (optional)
           A hint about the content length in bytes of the resource pointed to
           by the link.

   "logo"
       The URI of an image that should be twice as wide as it is high.

   "published"
       A "Date Construct" denoting the moment in time when the entry was first
       published. This should never change.

   "rights"
       A "Text Construct" containing a human-readable statement of legal
       rights for the content of the feed or entry. This is not intended for
       machine processing.

   "subtitle"
       A "Text Construct" containing an optional additional description of the
       feed.

   "summary"
       A "Text Construct" giving a short summary of the entry.

   "title"
       A "Text Construct" containing the title of the feed or entry.

   "updated"
       A "Date Construct" denoting the moment in time when the feed or entry
       was last updated. Defaults to the current date and time if omitted.

       In entries, you can use this element to signal significant changes at
       your discretion.

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.

   Date Construct
       A string denoting a date and time in W3CDTF format. You can generate
       those using something like

        use POSIX qw( strftime );
        my $now = strftime '%Y-%m-%dT%H:%M:%SZ', gmtime;

   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:

       "name" (required)
           The name of the person.



perl v5.12.2                2011-02-22                          5





XML::Atom::SimpUsereContributed Perl DocuXML::Atom::SimpleFeed(3)


       "email" (optional)
           The person's email address.

       "uri" (optional)
           A URI to distinguish this person. This would usually be a homepage,
           but need not actually be a dereferencable URL.

   Text Construct
       You can supply a string to Text Construct parameters, which will be
       used as the HTML content of the element.

       FIXME details, text/html/xhtml

SEE ALSO
       o   Atom Enabled (<http://www.atomenabled.org/>)

       o   W3CDTF Spec (http://www.w3.org/TR/NOTE-datetime
           <http://www.w3.org/TR/NOTE-datetime>)

       o   RFC 3066 (<http://rfc.net/rfc3066.html>)

       o   XML::Atom::Syndication

       o   XML::Feed

       o   http://groups.yahoo.com/group/atomic-perl/

BUGS AND LIMITATIONS
       In "content" elements, the "src" attribute cannot be used, and non-XML
       or -text media types do not get Base64-encoded automatically. This is a
       bug.

       There are practically no tests. This is a bug.

       Support for "xml:lang" and "xml:base" 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.

       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.

       The "source" element is not and may never be supported.

       Nothing is done to ensure that text constructs with type "xhtml" and
       entry contents using either that or an XML media type are well-formed.
       So far, this is by design. You should strongly consider using an XML
       writer if you want to include content with such types in your feed.

       If you find bugs or you have feature requests, please report them to
       mailto:bug-xml-atom-simplefeed@rt.cpan.org <mailto:bug-xml-atom-
       simplefeed@rt.cpan.org>, or through the web interface at
       <http://rt.cpan.org>.




perl v5.12.2                2011-02-22                          6





XML::Atom::SimpUsereContributed Perl DocuXML::Atom::SimpleFeed(3)


AUTHOR
       Aristotle Pagaltzis, <mailto:pagaltzis@gmx.de>

       API designed largely by H. Wade Minter.

LICENCE AND COPYRIGHT
       Copyright (c) 2005-2006, Aristotle Pagaltzis. All rights reserved.

       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY
       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
       PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
       NECESSARY SERVICING, REPAIR, OR CORRECTION.

       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
       RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
       DAMAGES.

























perl v5.12.2                2011-02-22                          7


