/ 
XML-Atom-SimpleFeed-0.8_001
River stage two • 10 direct dependents • 13 total dependents
/ XML::Atom::SimpleFeed

NAME

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

VERSION

This document describes XML::Atom::SimpleFeed version 0.8_001

SYNOPSIS

use XML::Atom::SimpleFeed;

# Create the feed object
my $atom = XML::Atom::SimpleFeed->new(
    title     => "My Atom Feed",
    subtitle  => "This is an example feed.  Nothing to see here.  Move along."
    link      => "http://www.example.com/blogs/",
    generator => 'Elite Blogs LLP',
    updated   => "2005-02-18T15:00:00Z",
);

# Add an entry to the feed
$atom->add_entry(
    title     => "A Sample Entry",
    link      => "http://www.example.com/blogs/joe/entries/1234",
    content   => "This is the body of the entry"
    author    => { name => "J. Random Hacker", email => 'jrh@example.com' },
    published => "2005-02-18T15:30:00Z",
    updated   => "2005-02-18T16:45:00Z",
);

# Add a more complicated entry
$atom->add_entry(
    title => 'A more complicated example.',
    link  => [
        href => 'http://www.example.com/blogs/quux/entries/1337',
        {
            rel  => 'via',
            href => 'http://www.example.com/blogs/foo/entries/1',
        }
    ],
    author => {
        name  => 'Foo Bar',
        uri   => 'http://www.example.com/blogs/foo/',
        email => 'foo@example.com'
    },
    rights    => 'Copyright 2005 by Foo Bar Inc.',
    category  => 'Technology',
    content   => 'I have nothing to say now.'
);

# Print out the feed
$atom->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 it 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

Constructor

XML::Atom::SimpleFeed instances are created by the new constructor:

my $atom = XML::Atom::SimpleFeed->new( %arguments );

Parameters are supplied as key-value pairs, as follows:

id (omissible URI)

A URI that is a permanent, globally unique identifier for the entry. This should never change.

title (required "Text Construct")

The title of the feed.

subtitle (optional "Text Construct")

An optional additional description of the feed.

category (optional "Category Construct")

One or more categories that apply to the entry.

The permalink for the syndicated resource. This is generally a browser-viewable weblog, upload browser, search engine results page or similar web page.

author (optional "Person Construct")

The author of the feed.

rights (optional "Text Construct")

The legal rights for the content of the feed.

generator (optional string/hash)

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 suppressed by explicitly passing an undef value.

updated (optional "Date Construct")

The date and time at which the feed was last updated. If omitted, the current date and time will be used.

Methods

add_entry

This method adds an entry into the atom feed. Its arguments are supplied as a hash, with the following keys:

id (omissible URI)

A URI that is a permanent, globally unique identifier for the entry. This should never change.

You are encouraged to generate a UUID using Data::UUID for the purpose. It should be stored alongside the resource corresponding to this entry, f.ex. in a column of the article table of your weblog database. To use it as an identifier in the feed, use the urn:uuid:########-####-####-####-############ URI form.

If you do not specify an ID, the permalink will be used instead. It is your responsibility to ensure that the permalink never changes.

title (required "Text Construct")

The title of the entry.

The permalink for the entry. This is generally a browser-viewable article, upload details page, search result or similar web page. It should be unique.

summary (optional "Text Construct")

A short summary of the entry.

content (optional Content Construct)

The actual, honest-to-goodness, body of the entry. This is 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.

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.

category (optional "Category Construct")

One or more categories that apply to the entry.

author (possibly required "Person Construct")

The author of the entry. If no author was given for the feed as a whole, this is required.

rights (optional "Text Construct")

The legal rights for the content of this entry.

published (optional "Date Construct")

The date and time the entry was first published. This should never change.

updated (optional "Date Construct")

The date and time the entry was last updated. You can use this to signal changes to the entry at your discretion. Defaults to the current date and time.

generate( [$handler] )

Serialises the feed using a SAX2 handler. If you don't pass a handler to be used, a default XML::SAX::Writer or XML::Genx::SAXWriter handler will be instantiated, which results in the feed being printed to STDOUT.

as_string

Returns the text of the feed as a string. This is a convenience wrapper around generate.

print

Outputs the feed to STDOUT. This is just an alias to generate.

save_file( $file )

Saves the feed into $file, which can be a filename or filehandle. This is a convenience wrapper that passes a SAX handler instantiated with ->new( Output => $file ) to generate.

ATOM CONSTRUCTS

Many of the parameters accepted by the new constructor and the add_entry method are identified as a particular construct. These are pieces of information with a common structure. The following sections outline the data you can (or must) pass in each case.

Text Construct

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

FIXME text/html/xhtml

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.

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.

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;

You can supply a string to Link Construct parameters, which will be used as the href value of the link. The full range of details that can be provided by passing a hash instead of a string is as follows:

FIXME mention multiplicity

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.

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.

Category Construct

FIXME mention multiplicity

You can supply a string to Category Construct parameters, 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.

DIAGNOSTICS

Warnings

Missing entry ID, falling back to the alternate link

You did not supply an identifier for the feed or entry. In this case, the module uses the permalink as the feed's/entry's identifier. It is your responsibility to ensure that the permalink NEVER CHANGES.

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 feed, use the urn:uuid:########-####-####-####-############ URI form.

Outputting deprecated Atom 0.3 element '%s' as '%s' according to Atom 1.0

This module used to generate Atom 0.3 feeds. Atom 0.3 is now deprecated, since Atom 1.0 has been standardised by the IETF, and this module now generates Atom 1.0 feeds. A number of elements from the 0.3 (non)standard have changed names in 1.0.

This module's old interface, which follows Atom 0.3 conventions, will continue to be supported for some time, but you should change your code to use the 1.0 conventions.

Dropping deprecated Atom 0.3 element '%s' without equivalent in Atom 1.0

This module used to generate Atom 0.3 feeds. Atom 0.3 is now deprecated, since Atom 1.0 has been standardised by the IETF, and this module now generates Atom 1.0. A small number of features from the 0.3 (non)standard have been removed from Atom 1.0.

Since there is no way to express these concepts in Atom 1.0, this module no longer supports these old features. Please remove their use from your code.

Errors

Category without term

You used a hash without a term key to specify a category. term is a required attribute of a category in Atom.

You used a hash without a href key to specify a link. href is a required attribute of a link in Atom.

You used a hash or an array of hashes to define an entry's or feed's links, but more than one of them is an alternate link. (Alternate links are those whose rel attribute is either unspecified or equal to alternate.)

Missing entry author (required in feeds without author)

If you did not specify a author for the feed, then every entry in the feed must have an author.

Missing entry title, Missing feed title

Titles are required for feeds and entries.

Missing generator name

You used a hash without a name key to specify the feed generator. Atom requires that a human-readable name be given for the generator, if the generator is specified.

Missing person name

You used a hash without a name key to specify a person. Atom requires a name for every author or contributor mentioned.

Must pass a filename or filehandle

You passed something to save_file that's neither a string nor a filehandle.

No 'src' key allowed in text construct, Type '%s' not allowed in text construct

You used a hash to specify a text construct, such as a title or entry summary, but specified a type other than text, html or xhtml or specified a src attribute to refer to remote content. Atom only specifies this extended use only for the content of an entry.

Missing content

You used a hash without a content key to specify a text construct, such as a title, summary or entry content. Atom requires that such elements have content.

Internal fatal errors

Couldn't load default SAX handler

You did not pass a SAX handler object to generate, but you do not have XML::SAX::Writer or XML::Genx::SAXWriter installed either.

Install one of these modules or make sure your code passes some SAX handler object to generate.

SEE ALSO

DEPENDENCIES

You will need some kind of SAX handler to use this module.

If all you want is to output XML, that would be one of the SAX serialiser modules. XML::SAX::Writer is recommended.

BUGS AND LIMITATIONS

Feeds with extension elements cannot be generated using this module.

Only one author per feed and entry is currently supported and no contributors can be mentioned.

More Atom format features might be missing.

There is currently no support for xml:lang and xml:base. This should be addressed in a future version.

No bugs have been reported.

Please report any bugs or feature requests to bug-xml-atom-simplefeed@rt.cpan.org, or through the web interface at http://rt.cpan.org.

DEVELOPMENT NOTES

  • Fill in the FIXME POD bits

  • Write reams of unit tests

  • Add some knobs so users can twiddle which warnings are emitted

  • Find a way to stream output

    This is difficult with the current interface, since print, as_string etc. only get called at the very end of the object's lifecycle. To stream the output, the SAX handler used would have to be supplied at the very beginning instead. How to reconcile the two?

  • Possibly switch to Class::Std

    But that may not be necessary if I find a good solution for streaming output, since that would obviate the need for keeping any internal state. That would also make the module more parsimonious with memory; not that that seems likely to be a great concern for a module generating Atom feeds.

AUTHOR

Aristotle Pagaltzis, mailto:pagaltzis@gmx.de

Original version by H. Wade Minter.

LICENCE AND COPYRIGHT

Copyright (c) 2005, 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.