NAME

XML::Atom::SimpleFeed - Generate simple Atom syndication feeds

SYNOPSIS

  use XML::Atom::SimpleFeed;

  # Create the feed object
  my $atom = XML::Atom::SimpleFeed->new(
      title    => "My Atom Feed",
      link     => "http://www.example.com/blog/",
      modified => "2005-02-18T15:00:00Z",
      tagline  => "This is an example feed.  Nothing to see here.  Move along."
    )
    or die;

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

  # Print out the feed
  $atom->print;

DESCRIPTION

This module exists to generate basic Atom syndication feeds. While it does not provide a full, object-oriented interface into all the nooks and crannies of Atom feeds, an Atom parser, or an Atom client API, it should be useful for people who want to generate valid Atom feeds of their content quickly and easily.

METHODS

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

This creates a new XML::Atom::SimpleFeed objects with the supplied parameters. The parameters are supplied as a hash. Some parameters are required, some are optional. They are:

• title

  REQUIRED (string). The title of the Atom feed.

• link

  REQUIRED (string). The URL link of the Atom feed. Normally points to the home page of the resource you are syndicating.

• modified

  OPTIONAL (string). The date the feed was last modified in W3CDTF format. This is a REQUIRED element in the Atom spec, but if you do not supply it, the current date and time will be used.

• tagline

  OPTIONAL (string). A description or tagline for the feed.

• generator

  OPTIONAL (string). The software agent used to generate the feed. If not supplied, will be set to "XML::Atom::SimpleFeed"

• copyright

  OPTIONAL (string). The copyright string for the feed.

• info

  OPTIONAL (string). A human-readable explanation of the feed format itself.

• id

  OPTIONAL (string). A permanent, globally unique identifier for the feed.

• author

  OPTIONAL (hash). A hash of information about the author of the feed. If this element exists, it will be used to provide author information for a feed entry, if no author information was provided for the entry. The author hash contains the following information:

  • name

    REQUIRED (string). The name of the author ("J. Random Hacker")

  • email

    OPTIONAL (string). The email address of the author ("jrh@example.com")

  • url

    OPTIONAL (string). The URL of the author ("http://www.example.com/jrh/")

$atom->add_entry(%args);

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

• title

  REQUIRED (string). The title of the entry.

• link

  REQUIRED (string). The URL to the entry itself. Should be unique to assure valid feeds.

• author

  OPTIONAL (hash). Optional with a caveat. A hash of information about the author of the entry. If this element is left blank, the author information for the feed will be used. If that information was not provided, the method will return undef, since the author is required.

  • name

    REQUIRED (string). The name of the author ("J. Random Hacker")

  • email

    OPTIONAL (string). The email address of the author ("jrh@example.com")

  • url

    OPTIONAL (string). The URL of the author ("http://www.example.com/jrh/")

• id

  OPTIONAL (string). Optional with a caveat. This is the globally unique identifier for the feed. It should be a string that does not change. If the id is not provided, the module will attempt to construct one via the link parameter, based on the Mark Pilgrim method. For more information about generating unique ids in Atom, see http://diveintomark.org/archives/2004/05/28/howto-atom-id

• issued

  OPTIONAL (string). The date and time the entry was first published, in W3CDTF format. A REQUIRED part of the Atom spec. Should be set once and not changed (if the feed changes, use the modified parameter below). If this parameter is not provided, the current date and time will be used.

• modified

  OPTIONAL (string). The date and time the entry was last modified, in W3CDTF format. A REQUIRED part of the Atom spec. This is the date you will change if the contents of the feed are modified. If this parameter is not provided, the current date and time will be used.

• created

  OPTIONAL (string). The date and time the entry was created (differs from "issued" and "modified"), in W3CDTF format. May often be, but is not necessarily, the same time the entry was issued.

• summary

  OPTIONAL (string). A short summary of the entry.

• subject

  OPTIONAL (string). The subject of the entry.

• content

  OPTIONAL (string). The actual, honest-to-goodness, body of the entry.

$atom->print();

Outputs the full atom feed as a string, suitable for printing or framing.

$atom->save_file($filename);

Saves the full atom feed into the file referenced by $filename. If the file cannot be opened for writing, returns undef.

BUGS

Most likely does not implement all the useful features of an Atom feed. Comments and patches welcome!

Language is hardcoded as "en"

SEE ALSO

XML::Atom http://search.cpan.org/dist/XML-Atom/

Atom Enabled http://www.atomenabled.org/

W3CDTF Spec http://www.w3.org/TR/NOTE-datetime

AUTHOR

H. Wade Minter, <minter@lunenburg.org> http://www.lunenburg.org/

COPYRIGHT AND LICENSE

Copyright 2005 by H. Wade Minter

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