local-lib5/lib/perl5/XML/Atom/Entry.pm

   1 # $Id$
   2
   3 package XML::Atom::Entry;
   4 use strict;
   5
   6 use XML::Atom;
   7 use base qw( XML::Atom::Thing );
   8 use MIME::Base64 qw( encode_base64 decode_base64 );
   9 use XML::Atom::Person;
  10 use XML::Atom::Content;
  11 use XML::Atom::Util qw( first );
  12
  13 sub element_name { 'entry' }
  14
  15 sub content {
  16     my $entry = shift;
  17     if (my @arg = @_) {
  18         if (ref($arg[0]) ne 'XML::Atom::Content') {
  19             $arg[0] = XML::Atom::Content->new(Body => $arg[0], Version => $entry->version);
  20         }
  21         $entry->set($entry->ns, 'content', @arg);
  22     } else {
  23         return $entry->get_object($entry->ns, 'content', 'XML::Atom::Content');
  24     }
  25 }
  26
  27 __PACKAGE__->mk_elem_accessors(qw( summary ));
  28 __PACKAGE__->mk_xml_attr_accessors(qw( lang base ));
  29
  30 __PACKAGE__->_rename_elements('issued' => 'published');
  31 __PACKAGE__->_rename_elements('modified' => 'updated');
  32
  33 # OMG 0.3 elements ... to be backward compatible
  34 __PACKAGE__->mk_elem_accessors(qw( created ));
  35
  36 __PACKAGE__->mk_object_accessor( source => 'XML::Atom::Feed' );
  37
  38 1;
  39 __END__
  40
  41 =head1 NAME
  42
  43 XML::Atom::Entry - Atom entry
  44
  45 =head1 SYNOPSIS
  46
  47     use XML::Atom::Entry;
  48     my $entry = XML::Atom::Entry->new;
  49     $entry->title('My Post');
  50     $entry->content('The content of my post.');
  51     my $xml = $entry->as_xml;
  52     my $dc = XML::Atom::Namespace->new(dc => 'http://purl.org/dc/elements/1.1/');
  53     $entry->set($dc, 'subject', 'Food & Drink');
  54
  55 =head1 USAGE
  56
  57 =head2 XML::Atom::Entry->new([ $stream ])
  58
  59 Creates a new entry object, and if I<$stream> is supplied, fills it with the
  60 data specified by I<$stream>.
  61
  62 Automatically handles autodiscovery if I<$stream> is a URI (see below).
  63
  64 Returns the new I<XML::Atom::Entry> object. On failure, returns C<undef>.
  65
  66 I<$stream> can be any one of the following:
  67
  68 =over 4
  69
  70 =item * Reference to a scalar
  71
  72 This is treated as the XML body of the entry.
  73
  74 =item * Scalar
  75
  76 This is treated as the name of a file containing the entry XML.
  77
  78 =item * Filehandle
  79
  80 This is treated as an open filehandle from which the entry XML can be read.
  81
  82 =back
  83
  84 =head2 $entry->content([ $content ])
  85
  86 Returns the content of the entry. If I<$content> is given, sets the content
  87 of the entry. Automatically handles all necessary escaping.
  88
  89 =head2 $entry->author([ $author ])
  90
  91 Returns an I<XML::Atom::Person> object representing the author of the entry,
  92 or C<undef> if there is no author information present.
  93
  94 If I<$author> is supplied, it should be an I<XML::Atom::Person> object
  95 representing the author. For example:
  96
  97     my $author = XML::Atom::Person->new;
  98     $author->name('Foo Bar');
  99     $author->email('foo@bar.com');
 100     $entry->author($author);
 101
 102 =head2 $entry->link
 103
 104 If called in scalar context, returns an I<XML::Atom::Link> object
 105 corresponding to the first I<E<lt>linkE<gt>> tag found in the entry.
 106
 107 If called in list context, returns a list of I<XML::Atom::Link> objects
 108 corresponding to all of the I<E<lt>linkE<gt>> tags found in the entry.
 109
 110 =head2 $entry->add_link($link)
 111
 112 Adds the link I<$link>, which must be an I<XML::Atom::Link> object, to
 113 the entry as a new I<E<lt>linkE<gt>> tag. For example:
 114
 115     my $link = XML::Atom::Link->new;
 116     $link->type('text/html');
 117     $link->rel('alternate');
 118     $link->href('http://www.example.com/2003/12/post.html');
 119     $entry->add_link($link);
 120
 121 =head2 $entry->get($ns, $element)
 122
 123 Given an I<XML::Atom::Namespace> element I<$ns> and an element name
 124 I<$element>, retrieves the value for the element in that namespace.
 125
 126 This is useful for retrieving the value of elements not in the main Atom
 127 namespace, like categories. For example:
 128
 129     my $dc = XML::Atom::Namespace->new(dc => 'http://purl.org/dc/elements/1.1/');
 130     my $subj = $entry->get($dc, 'subject');
 131
 132 =head2 $entry->getlist($ns, $element)
 133
 134 Just like I<$entry-E<gt>get>, but if there are multiple instances of the
 135 element I<$element> in the namespace I<$ns>, returns all of them. I<get>
 136 will return only the first.
 137
 138 =head1 AUTHOR & COPYRIGHT
 139
 140 Please see the I<XML::Atom> manpage for author, copyright, and license
 141 information.
 142
 143 =cut