local-lib5/man/man3/XML::Atom::Feed.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::Feed 3"
 127 .TH XML::Atom::Feed 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::Feed \- Atom feed
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 11
 137 \&    use XML::Atom::Feed;
 138 \&    use XML::Atom::Entry;
 139 \&    my $feed = XML::Atom::Feed\->new;
 140 \&    $feed\->title(\*(AqMy Weblog\*(Aq);
 141 \&    $feed\->id(\*(Aqtag:example.com,2006:feed\-id\*(Aq);
 142 \&    my $entry = XML::Atom::Entry\->new;
 143 \&    $entry\->title(\*(AqFirst Post\*(Aq);
 144 \&    $entry\->id(\*(Aqtag:example.com,2006:entry\-id\*(Aq);
 145 \&    $entry\->content(\*(AqPost Body\*(Aq);
 146 \&    $feed\->add_entry($entry);
 147 \&    $feed\->add_entry($entry, { mode => \*(Aqinsert\*(Aq });
 148 \&
 149 \&    my @entries = $feed\->entries;
 150 \&    my $xml = $feed\->as_xml;
 151 \&
 152 \&    ## Get a list of the <link rel="..." /> tags in the feed.
 153 \&    my $links = $feed\->link;
 154 \&
 155 \&    ## Find all of the Atom feeds on a given page, using auto\-discovery.
 156 \&    my @uris = XML::Atom::Feed\->find_feeds(\*(Aqhttp://www.example.com/\*(Aq);
 157 \&
 158 \&    ## Use auto\-discovery to load the first Atom feed on a given page.
 159 \&    my $feed = XML::Atom::Feed\->new(URI\->new(\*(Aqhttp://www.example.com/\*(Aq));
 160 .Ve
 161 .SH "USAGE"
 162 .IX Header "USAGE"
 163 .ie n .SS "XML::Atom::Feed\->new([ $stream ])"
 164 .el .SS "XML::Atom::Feed\->new([ \f(CW$stream\fP ])"
 165 .IX Subsection "XML::Atom::Feed->new([ $stream ])"
 166 Creates a new feed object, and if \fI\f(CI$stream\fI\fR is supplied, fills it with the
 167 data specified by \fI\f(CI$stream\fI\fR.
 168 .PP
 169 Automatically handles autodiscovery if \fI\f(CI$stream\fI\fR is a \s-1URI\s0 (see below).
 170 .PP
 171 Returns the new \fIXML::Atom::Feed\fR object. On failure, returns \f(CW\*(C`undef\*(C'\fR.
 172 .PP
 173 \&\fI\f(CI$stream\fI\fR can be any one of the following:
 174 .IP "\(bu" 4
 175 Reference to a scalar
 176 .Sp
 177 This is treated as the \s-1XML\s0 body of the feed.
 178 .IP "\(bu" 4
 179 Scalar
 180 .Sp
 181 This is treated as the name of a file containing the feed \s-1XML\s0.
 182 .IP "\(bu" 4
 183 Filehandle
 184 .Sp
 185 This is treated as an open filehandle from which the feed \s-1XML\s0 can be read.
 186 .IP "\(bu" 4
 187 \&\s-1URI\s0 object
 188 .Sp
 189 This is treated as a \s-1URI\s0, and the feed \s-1XML\s0 will be retrieved from the \s-1URI\s0.
 190 .Sp
 191 If the content type returned from fetching the content at \s-1URI\s0 is
 192 \&\fItext/html\fR, this method will automatically try to perform auto-discovery
 193 by looking for a \fI<link>\fR tag describing the feed \s-1URL\s0. If such
 194 a \s-1URL\s0 is found, the feed \s-1XML\s0 will be automatically retrieved.
 195 .Sp
 196 If the \s-1URI\s0 is already of a feed, no auto-discovery is necessary, and the
 197 feed \s-1XML\s0 will be retrieved and parsed as normal.
 198 .SS "XML::Atom::Feed\->find_feeds($uri)"
 199 .IX Subsection "XML::Atom::Feed->find_feeds($uri)"
 200 Given a \s-1URI\s0 \fI\f(CI$uri\fI\fR, use auto-discovery to find all of the Atom feeds linked
 201 from that page (using \fI<link>\fR tags).
 202 .PP
 203 Returns a list of feed URIs.
 204 .ie n .SS "$feed\->link"
 205 .el .SS "\f(CW$feed\fP\->link"
 206 .IX Subsection "$feed->link"
 207 If called in scalar context, returns an \fIXML::Atom::Link\fR object
 208 corresponding to the first \fI<link>\fR tag found in the feed.
 209 .PP
 210 If called in list context, returns a list of \fIXML::Atom::Link\fR objects
 211 corresponding to all of the \fI<link>\fR tags found in the feed.
 212 .ie n .SS "$feed\->add_link($link)"
 213 .el .SS "\f(CW$feed\fP\->add_link($link)"
 214 .IX Subsection "$feed->add_link($link)"
 215 Adds the link \fI\f(CI$link\fI\fR, which must be an \fIXML::Atom::Link\fR object, to
 216 the feed as a new \fI<link>\fR tag. For example:
 217 .PP
 218 .Vb 5
 219 \&    my $link = XML::Atom::Link\->new;
 220 \&    $link\->type(\*(Aqtext/html\*(Aq);
 221 \&    $link\->rel(\*(Aqalternate\*(Aq);
 222 \&    $link\->href(\*(Aqhttp://www.example.com/\*(Aq);
 223 \&    $feed\->add_link($link);
 224 .Ve
 225 .ie n .SS "$feed\->add_entry($entry)"
 226 .el .SS "\f(CW$feed\fP\->add_entry($entry)"
 227 .IX Subsection "$feed->add_entry($entry)"
 228 Adds the entry \fI\f(CI$entry\fI\fR, which must be an \fIXML::Atom::Entry\fR object,
 229 to the feed. If you want to add an entry before existent entries, you can pass optional hash reference containing \f(CW\*(C`mode\*(C'\fR value set to \f(CW\*(C`insert\*(C'\fR.
 230 .PP
 231 .Vb 1
 232 \&  $feed\->add_entry($entry, { mode => \*(Aqinsert\*(Aq });
 233 .Ve
 234 .ie n .SS "$feed\->entries"
 235 .el .SS "\f(CW$feed\fP\->entries"
 236 .IX Subsection "$feed->entries"
 237 Returns list of XML::Atom::Entry objects contained in the feed.
 238 .ie n .SS "$feed\->language"
 239 .el .SS "\f(CW$feed\fP\->language"
 240 .IX Subsection "$feed->language"
 241 Returns the language of the feed, from \fIxml:lang\fR.
 242 .ie n .SS "$feed\->author([ $author ])"
 243 .el .SS "\f(CW$feed\fP\->author([ \f(CW$author\fP ])"
 244 .IX Subsection "$feed->author([ $author ])"
 245 Returns an \fIXML::Atom::Person\fR object representing the author of the entry,
 246 or \f(CW\*(C`undef\*(C'\fR if there is no author information present.
 247 .PP
 248 If \fI\f(CI$author\fI\fR is supplied, it should be an \fIXML::Atom::Person\fR object
 249 representing the author. For example:
 250 .PP
 251 .Vb 4
 252 \&    my $author = XML::Atom::Person\->new;
 253 \&    $author\->name(\*(AqFoo Bar\*(Aq);
 254 \&    $author\->email(\*(Aqfoo@bar.com\*(Aq);
 255 \&    $feed\->author($author);
 256 .Ve
 257 .ie n .SS "$feed\->id([ $id ])"
 258 .el .SS "\f(CW$feed\fP\->id([ \f(CW$id\fP ])"
 259 .IX Subsection "$feed->id([ $id ])"
 260 Returns an id for the feed. If \fI\f(CI$id\fI\fR is supplied, set the id. When
 261 generating the new feed, it is your responsibility to generate unique
 262 \&\s-1ID\s0 for the feed and set to XML::Atom::Feed object. You can use \fIhttp\fR
 263 permalink, \fItag\fR \s-1URI\s0 scheme or \fIurn:uuid\fR for handy.
 264 .SH "UNICODE FLAGS"
 265 .IX Header "UNICODE FLAGS"
 266 By default, XML::Atom takes off all the Unicode flag fro mthe feed content. For example,
 267 .PP
 268 .Vb 1
 269 \&  my $title = $feed\->title;
 270 .Ve
 271 .PP
 272 the variable \f(CW$title\fR contains \s-1UTF\-8\s0 bytes without Unicode flag set,
 273 even if the feed title contains some multibyte chracters.
 274 .PP
 275 If you don't like this behaviour and wants to andle everything as
 276 Unicode characters (rather than \s-1UTF\-8\s0 bytes), set
 277 \&\f(CW$XML::Atom::ForceUnicode\fR flag to 1.
 278 .PP
 279 .Vb 1
 280 \&  $XML::Atom::ForceUnicode = 1;
 281 .Ve
 282 .PP
 283 then all the data returned from XML::Atom::Feed object and
 284 XML::Atom::Entry object etc., will have Unicode flag set.
 285 .PP
 286 The only exception will be \f(CW\*(C`$entry\->content\->body\*(C'\fR, if content
 287 type is not text/* (e.g. image/gif). In that case, the content body is
 288 still binary data, without Unicode flag set.
 289 .SH "CREATING ATOM 1.0 FEEDS"
 290 .IX Header "CREATING ATOM 1.0 FEEDS"
 291 By default, XML::Atom::Feed and other classes (Entry, Link and
 292 Content) will create entities using Atom 0.3 namespaces. In order to
 293 create 1.0 feed and entry elements, you can set \fIVersion\fR as a
 294 parameter, like:
 295 .PP
 296 .Vb 2
 297 \&  $feed = XML::Atom::Feed\->new(Version => 1.0);
 298 \&  $entry = XML::Atom::Entry\->new(Version => 1.0);
 299 .Ve
 300 .PP
 301 Setting those Version to every element would be sometimes painful. In
 302 that case, you can override the default version number by setting
 303 \&\f(CW$XML::Atom::DefaultVersion\fR global variable to \*(L"1.0\*(R".
 304 .PP
 305 .Vb 1
 306 \&  use XML::Atom;
 307 \&
 308 \&  $XML::Atom::DefaultVersion = "1.0";
 309 \&
 310 \&  my $feed = XML::Atom::Feed\->new;
 311 \&  $feed\->title("blah");
 312 \&
 313 \&  my $entry = XML::Atom::Entry\->new;
 314 \&  $feed\->add_entry($entry);
 315 \&
 316 \&  $feed\->version; # 1.0
 317 .Ve
 318 .SH "AUTHOR & COPYRIGHT"
 319 .IX Header "AUTHOR & COPYRIGHT"
 320 Please see the \fIXML::Atom\fR manpage for author, copyright, and license
 321 information.