local-lib5/man/man3/XML::Atom::Entry.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "XML::Atom::Entry 3"
 127 .TH XML::Atom::Entry 3 "2009-04-24" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 XML::Atom::Entry \- Atom entry
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 7
 137 \&    use XML::Atom::Entry;
 138 \&    my $entry = XML::Atom::Entry\->new;
 139 \&    $entry\->title(\*(AqMy Post\*(Aq);
 140 \&    $entry\->content(\*(AqThe content of my post.\*(Aq);
 141 \&    my $xml = $entry\->as_xml;
 142 \&    my $dc = XML::Atom::Namespace\->new(dc => \*(Aqhttp://purl.org/dc/elements/1.1/\*(Aq);
 143 \&    $entry\->set($dc, \*(Aqsubject\*(Aq, \*(AqFood & Drink\*(Aq);
 144 .Ve
 145 .SH "USAGE"
 146 .IX Header "USAGE"
 147 .ie n .SS "XML::Atom::Entry\->new([ $stream ])"
 148 .el .SS "XML::Atom::Entry\->new([ \f(CW$stream\fP ])"
 149 .IX Subsection "XML::Atom::Entry->new([ $stream ])"
 150 Creates a new entry object, and if \fI\f(CI$stream\fI\fR is supplied, fills it with the
 151 data specified by \fI\f(CI$stream\fI\fR.
 152 .PP
 153 Automatically handles autodiscovery if \fI\f(CI$stream\fI\fR is a \s-1URI\s0 (see below).
 154 .PP
 155 Returns the new \fIXML::Atom::Entry\fR object. On failure, returns \f(CW\*(C`undef\*(C'\fR.
 156 .PP
 157 \&\fI\f(CI$stream\fI\fR can be any one of the following:
 158 .IP "\(bu" 4
 159 Reference to a scalar
 160 .Sp
 161 This is treated as the \s-1XML\s0 body of the entry.
 162 .IP "\(bu" 4
 163 Scalar
 164 .Sp
 165 This is treated as the name of a file containing the entry \s-1XML\s0.
 166 .IP "\(bu" 4
 167 Filehandle
 168 .Sp
 169 This is treated as an open filehandle from which the entry \s-1XML\s0 can be read.
 170 .ie n .SS "$entry\->content([ $content ])"
 171 .el .SS "\f(CW$entry\fP\->content([ \f(CW$content\fP ])"
 172 .IX Subsection "$entry->content([ $content ])"
 173 Returns the content of the entry. If \fI\f(CI$content\fI\fR is given, sets the content
 174 of the entry. Automatically handles all necessary escaping.
 175 .ie n .SS "$entry\->author([ $author ])"
 176 .el .SS "\f(CW$entry\fP\->author([ \f(CW$author\fP ])"
 177 .IX Subsection "$entry->author([ $author ])"
 178 Returns an \fIXML::Atom::Person\fR object representing the author of the entry,
 179 or \f(CW\*(C`undef\*(C'\fR if there is no author information present.
 180 .PP
 181 If \fI\f(CI$author\fI\fR is supplied, it should be an \fIXML::Atom::Person\fR object
 182 representing the author. For example:
 183 .PP
 184 .Vb 4
 185 \&    my $author = XML::Atom::Person\->new;
 186 \&    $author\->name(\*(AqFoo Bar\*(Aq);
 187 \&    $author\->email(\*(Aqfoo@bar.com\*(Aq);
 188 \&    $entry\->author($author);
 189 .Ve
 190 .ie n .SS "$entry\->link"
 191 .el .SS "\f(CW$entry\fP\->link"
 192 .IX Subsection "$entry->link"
 193 If called in scalar context, returns an \fIXML::Atom::Link\fR object
 194 corresponding to the first \fI<link>\fR tag found in the entry.
 195 .PP
 196 If called in list context, returns a list of \fIXML::Atom::Link\fR objects
 197 corresponding to all of the \fI<link>\fR tags found in the entry.
 198 .ie n .SS "$entry\->add_link($link)"
 199 .el .SS "\f(CW$entry\fP\->add_link($link)"
 200 .IX Subsection "$entry->add_link($link)"
 201 Adds the link \fI\f(CI$link\fI\fR, which must be an \fIXML::Atom::Link\fR object, to
 202 the entry as a new \fI<link>\fR tag. For example:
 203 .PP
 204 .Vb 5
 205 \&    my $link = XML::Atom::Link\->new;
 206 \&    $link\->type(\*(Aqtext/html\*(Aq);
 207 \&    $link\->rel(\*(Aqalternate\*(Aq);
 208 \&    $link\->href(\*(Aqhttp://www.example.com/2003/12/post.html\*(Aq);
 209 \&    $entry\->add_link($link);
 210 .Ve
 211 .ie n .SS "$entry\->get($ns, $element)"
 212 .el .SS "\f(CW$entry\fP\->get($ns, \f(CW$element\fP)"
 213 .IX Subsection "$entry->get($ns, $element)"
 214 Given an \fIXML::Atom::Namespace\fR element \fI\f(CI$ns\fI\fR and an element name
 215 \&\fI\f(CI$element\fI\fR, retrieves the value for the element in that namespace.
 216 .PP
 217 This is useful for retrieving the value of elements not in the main Atom
 218 namespace, like categories. For example:
 219 .PP
 220 .Vb 2
 221 \&    my $dc = XML::Atom::Namespace\->new(dc => \*(Aqhttp://purl.org/dc/elements/1.1/\*(Aq);
 222 \&    my $subj = $entry\->get($dc, \*(Aqsubject\*(Aq);
 223 .Ve
 224 .ie n .SS "$entry\->getlist($ns, $element)"
 225 .el .SS "\f(CW$entry\fP\->getlist($ns, \f(CW$element\fP)"
 226 .IX Subsection "$entry->getlist($ns, $element)"
 227 Just like \fI\f(CI$entry\fI\->get\fR, but if there are multiple instances of the
 228 element \fI\f(CI$element\fI\fR in the namespace \fI\f(CI$ns\fI\fR, returns all of them. \fIget\fR
 229 will return only the first.
 230 .SH "AUTHOR & COPYRIGHT"
 231 .IX Header "AUTHOR & COPYRIGHT"
 232 Please see the \fIXML::Atom\fR manpage for author, copyright, and license
 233 information.