The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
XML-Loy-0.04
River stage one • 4 direct dependents • 4 total dependents
7 ++
/ XML::Loy::Atom

NAME

XML::Loy::Atom - Atom Syndication Format Extension

SYNOPSIS

  # Create new Atom feed
  my $feed = XML::Loy::Atom->new('feed');

  # Add new author
  $feed->author(
    name => 'Sheldon Cooper',
    uri => 'https://en.wikipedia.org/wiki/Sheldon_Cooper'
  );

  # Set title
  $feed->title('Bazinga!');

  # Set current time for publishing
  $feed->published(time);

  # Add new entry
  my $entry = $feed->entry(id => 'first');

  for ($entry) {
    $_->title('Welcome');
    $_->summary('My first post');

    # Add content
    my $content = $_->content(
      xhtml => '<p>First para</p>'
    );

    # Use XML::Loy methods
    $content->add(p => 'Second para')
            ->comment('My second paragraph');
  };

  # Get summary of first entry
  print $feed->entry('first')->summary->all_text;
  # My first post

  # Pretty print
  print $feed->to_pretty_xml;

  # <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  # <feed xmlns="http://www.w3.org/2005/Atom">
  #   <author>
  #     <name>Sheldon Cooper</name>
  #     <uri>https://en.wikipedia.org/wiki/Sheldon_Cooper</uri>
  #   </author>
  #   <title xml:space="preserve">Bazinga!</title>
  #   <published>2013-03-07T17:51:25Z</published>
  #   <entry xml:id="first">
  #     <id>first</id>
  #     <title xml:space="preserve">Welcome</title>
  #     <summary xml:space="preserve">My first post</summary>
  #     <div xmlns="http://www.w3.org/1999/xhtml">
  #       <p>First para</p>
  #
  #       <!-- My second paragraph -->
  #       <p>Second para</p>
  #     </div>
  #   </entry>
  # </feed>

DESCRIPTION

XML::Loy::Atom is a base class or extension for XML::Loy and provides several functions for the work with the Atom Syndication Format as described in RFC4287.

This code may help you to create your own XML::Loy extensions.

This module is an early release! There may be significant changes in the future.

METHODS

XML::Loy::Atom inherits all methods from XML::Loy and implements the following new ones.

new_person

  my $person = $atom->new_person(
    name => 'Bender',
    uri  => 'acct:bender@example.org'
  );

Returns a new person construction. Accepts a hash with element descriptions.

new_text

  my $text = $atom->new_text('This is a test');
  my $text = $atom->new_text( xhtml => 'This is a <strong>test</strong>!');
  my $text = $atom->new_text(
    type    => 'xhtml',
    content => 'This is a <strong>test</strong>!'
  );

Creates a new text construct. Accepts either a simple string (of type text), a tupel with the first argument being the media type and the second argument being the content, or a hash with the parameters type, content or src (and others). There are three predefined type values:

  • text for textual data

  • html for HTML data

  • xhtml for XHTML data

xhtml data is automatically wrapped in a namespaced div element (see RFC4287, Section 3.1 for further details).

author

  my $person = $atom->new_person(
    name => 'Bender',
    uri  => 'acct:bender@example.org'
  );
  my $author = $atom->author($person);

  print $atom->author->[0]->at('name')->text;

Adds author information to the Atom object or returns it. Accepts a person construct (see new_person) or the parameters accepted by new_person.

Returns a collection of author nodes.

category

  $atom->category('world');

  print $atom->category->[0];

Adds category information to the Atom object or returns it. Accepts either a hash for attributes (with, e.g., term and label) or one string representing the category's term.

Returns a collection of category terms.

content

  my $text = $atom->new_text(
    type    => 'xhtml',
    content => '<p>This is a <strong>test</strong>!</p>'
  );

  my $entry = $atom->entry(id => 'entry_1');

  $entry->content($text);
  $entry->content('This is a test!');

  print $atom->content->all_text;

Sets content information to the Atom object or returns it. Accepts a text construct (see new_text) or the parameters accepted by new_text. Returns the content node or, on construction of an xhtml object, the wrapped div node.

contributor

  my $person = $atom->new_person(
    name => 'Bender',
    uri  => 'acct:bender@example.org'
  );
  my $contributor = $atom->contributor($person);

  print $atom->contributor->[0]->at('name')->text;

Adds contributor information to the Atom object or returns it. Accepts a person construct (see new_person) or the parameters accepted by new_person.

Returns a collection of contributor nodes.

entry

  # Add entry as a hash of attributes
  my $entry = $atom->entry(
    id      => 'entry_id_1',
    summary => 'My first entry'
  );

  # Get entry by id
  my $entry = $atom->entry('entry_id_1');

Adds an entry to the Atom feed or returns one. Accepts a hash of simple entry information for adding or an id for retrieval.

generator

  $atom->generator('XML-Loy-Atom');
  print $atom->generator;

Sets generator information of the feed or returns it as a text string.

icon

  $atom->icon('http://sojolicio.us/favicon.ico');
  print $atom->icon;

Sets icon url of the feed or returns it as a text string. The image should be suitable for a small representation size and have an aspect ratio of 1:1.

id

  $atom->id('http://sojolicio.us/#12345');
  print $atom->id;

Sets or returns the unique identifier of the Atom object.

  $atom->link(related => 'http://sojolicio.us/#12345');
  $atom->link(
    rel  => 'self',
    href => 'http://sojolicio.us/#12345'
  );

  # Get link elements
  $atom->link('related');

Adds link information to the Atom object. Accepts either one scalar as a reference of a related link, a pair of scalars for the relational type and the reference, or multiple hashes for the attributes of the link. If no relation attribute is given, the default relation is 'related'.

  $atom->logo('http://sojolicio.us/sojolicious.png');
  print $atom->logo;

Sets logo url of the feed or returns it as a text string. The image should have an aspect ratio of 2:1.

published

  $atom->published('1312311456');
  $atom->published('2011-08-30T16:16:40Z');

  # Set current time
  $atom->published(time);

  print $atom->published->to_string;

Sets the publishing date of the Atom object or returns the publishing date as a XML::Loy::Date::RFC3339 object. Accepts all valid parameters of XML::Loy::Date::RFC3339::new.

This method is experimental and may return another object with a different API!

rights

  $atom->rights('Public Domain');
  print $atom->rights->all_text;

Sets legal information of the Atom object or returns it. Accepts a text construct (see new_text) or the parameters accepted by new_text. Returns the rights node or, on construction of an xhtml object, the wrapped div node.

source

  my $source = $atom->entry('my_id')->source({
    'xml:base' => 'http://source.sojolicio.us/'
  });
  $source->author(name => 'Zoidberg');

  print $atom->entry('my_id')
        ->source
        ->author->[0]->at('name')->all_text;

Sets or returns the source information of an atom entry. Expects for setting a hash reference (at least empty) of the attributes of the source. Returns the source node.

subtitle

  my $text = $atom->new_text(
    type => 'text',
    content => 'This is a subtitle!'
  );

  $atom->subtitle($text);
  $atom->subtitle('This is a subtitle!');

  print $atom->subtitle->all_text;

Sets subtitle information to the Atom feed or returns it. Accepts a text construct (see new_text) or the parameters accepted by new_text. Returns the subtitle node or, on construction of an xhtml object, the wrapped div node.

summary

  my $text = $atom->new_text(
    type => 'text',
    content => 'This is a summary!'
  );

  $atom->summary($text);
  $atom->summary('This is a summary!');

  print $atom->summary->all_text;

Sets summary information to the Atom entry or returns it. Accepts a text construct (see new_text) or the parameters accepted by new_text. Returns the summary node or, on construction of an xhtml object, the wrapped div node.

title

  my $text = $atom->new_text(
    type => 'text',
    content => 'This is a title!'
  );

  $atom->title($text);
  $atom->title('This is a title!');

  print $atom->title->all_text;

Sets title information to the Atom object or returns it. Accepts a text construct (see new_text) or the parameters accepted by new_text. Returns the title node or, on construction of an xhtml object, the wrapped div node.

updated

  $atom->updated('1312311456');
  $atom->updated('2011-08-30T16:16:40Z');

  # Set current time
  $atom->updated(time);

  print $atom->updated->to_string;

Sets the date of the last update of the Atom object or returns it as a XML::Loy::Date::RFC3339 object. Accepts all valid parameters of XML::Loy::Date::RFC3339's new.

This method is experimental and may return another object with a different API!

MIME-TYPES

When loaded as a base class, XML::Loy::Atom makes the mime-type application/atom+xml available.

DEPENDENCIES

Mojolicious.

AVAILABILITY

  https://github.com/Akron/XML-Loy

COPYRIGHT AND LICENSE

Copyright (C) 2011-2013, Nils Diewald.

This program is free software, you can redistribute it and/or modify it under the same terms as Perl.