Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XML::Atom::SimpleFeed(User Contributed Perl DocumentatXML::Atom::SimpleFeed(3)

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

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 is a minimal API 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.

       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"
       Takes a list of key-value pairs.

       Most keys are used to create corresponding "Atom	elements".  To specify
       multiple	instances of an	element	that may be given multiple times, pass
       multiple	key-value pairs	with the same key.

       Keys that start with a dash specify how the XML document	will be
       generated.

       The following keys are supported:

       o   "-encoding" (omissible, default "us-ascii")

       o   ""id"" (omissible)

       o   ""link"" (omissible,	multiple)

       o   ""title"" (required)

       o   ""author"" (optional, multiple)

       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)

   "add_entry"
       Takes a list of key-value pairs,	used to	create corresponding "Atom
       elements".  To specify multiple instances of an element that may	be
       given multiple times, pass multiple key-value pairs with	the same key.

       The following keys are supported:

       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)

   "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
       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
       as a hash with "uri", "version" and "name" keys.	Can also be undef to
       suppress	the element entirely. If nothing is passed, defaults to
       reporting XML::Atom::SimpleFeed as the generator.

   "icon"
       The URI of a small image	whose width and	height should be identical.

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

       "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 'strftime';
	my $now	= strftime '%Y-%m-%dT%H:%M:%SZ', gmtime;

       However,	you can	also simply pass a Unix	timestamp (a positive integer)
       or an object that responds to an	"epoch"	method call. (Make sure	that
       the timezone reported by	such objects is	correct!)

       The following datetime classes from CPAN	are compatible with this
       interface:

       o   Time::Piece

       o   DateTime

       o   Time::Moment

       o   Panda::Date

       o   Class::Date

       o   Time::Object	(an obsolete precursor to Time::Piece)

       o   Time::Date (version 0.05 or newer)

       The following are not:

       o   DateTime::Tiny

	   This	class lacks both an "epoch" method or any way to emulate one a
	   as well as any timezone support in the first	place.	That makes it
	   unsuitable in principle for use in Atom feeds a unless you have
	   separate information	about the timezone.

       o   Date::Handler

	   This	class has a suitable methoda| but sadly, calls it "Epoch".  So
	   it is left up to you	to call	"$dh->Epoch" to	pass such values.

   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.

   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>)

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

       o   XML::Atom::Syndication

       o   XML::Feed

BUGS AND LIMITATIONS
       In "content" elements, the "src"	attribute cannot be used, and non-XML
       or non-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.

AUTHOR
       Aristotle Pagaltzis <pagaltzis@gmx.de>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2020 by Aristotle	Pagaltzis.

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

perl v5.32.0			  2020-06-03	      XML::Atom::SimpleFeed(3)

NAME | SYNOPSIS | DESCRIPTION | INTERFACE | ATOM ELEMENTS | COMMON ATOM CONSTRUCTS | SEE ALSO | BUGS AND LIMITATIONS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XML::Atom::SimpleFeed&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help