GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  XML::ATOM::SIMPLEFEED (3)

.ds Aq ’

NAME

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

CONTENTS

VERSION

version 0.862

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

CWnew

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" (<B>requiredB>)
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)
To specify multiple instances of an element that may be given multiple times, simply list multiple key-value pairs with the same key.

CWadd_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" (<B>requiredB> unless there is a feed-level author, multiple)
o "id" (omissible)
o "link" (<B>requiredB>, multiple)
o "title" (<B>requiredB>)
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.

CWno_generator

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

CWas_string

Returns the XML representation of the feed as a string.

CWprint

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

CWauthor

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

CWcategory

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 (<B>requiredB>) 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.

CWcontent

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

CWcontributor

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

CWgenerator

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.

CWicon

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

CWid

A URI that is a permanent, globally unique identifier for the feed or entry that <B>MUST NEVER CHANGEB>.

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. <B>It is your responsibility to ensure that the permalink NEVER CHANGES.B>

CWlink

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 (<B>requiredB> 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.

CWlogo

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

CWpublished

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

CWrights

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.

CWsubtitle

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

CWsummary

A Text Construct giving a short summary of the entry.

CWtitle

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

CWupdated

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 a strftime method call (such as a Time::Piece or DateTime instance). Make sure that the timezone reported by such objects is correct!

    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 (<B>requiredB>) 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) 2015 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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 XML::ATOM::SIMPLEFEED (3) 2015-09-08

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.