--- /dev/null
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "XML::Atom::Feed 3"
+.TH XML::Atom::Feed 3 "2009-04-24" "perl v5.8.7" "User Contributed Perl Documentation"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+XML::Atom::Feed \- Atom feed
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 11
+\& use XML::Atom::Feed;
+\& use XML::Atom::Entry;
+\& my $feed = XML::Atom::Feed\->new;
+\& $feed\->title(\*(AqMy Weblog\*(Aq);
+\& $feed\->id(\*(Aqtag:example.com,2006:feed\-id\*(Aq);
+\& my $entry = XML::Atom::Entry\->new;
+\& $entry\->title(\*(AqFirst Post\*(Aq);
+\& $entry\->id(\*(Aqtag:example.com,2006:entry\-id\*(Aq);
+\& $entry\->content(\*(AqPost Body\*(Aq);
+\& $feed\->add_entry($entry);
+\& $feed\->add_entry($entry, { mode => \*(Aqinsert\*(Aq });
+\&
+\& my @entries = $feed\->entries;
+\& my $xml = $feed\->as_xml;
+\&
+\& ## Get a list of the <link rel="..." /> tags in the feed.
+\& my $links = $feed\->link;
+\&
+\& ## Find all of the Atom feeds on a given page, using auto\-discovery.
+\& my @uris = XML::Atom::Feed\->find_feeds(\*(Aqhttp://www.example.com/\*(Aq);
+\&
+\& ## Use auto\-discovery to load the first Atom feed on a given page.
+\& my $feed = XML::Atom::Feed\->new(URI\->new(\*(Aqhttp://www.example.com/\*(Aq));
+.Ve
+.SH "USAGE"
+.IX Header "USAGE"
+.ie n .SS "XML::Atom::Feed\->new([ $stream ])"
+.el .SS "XML::Atom::Feed\->new([ \f(CW$stream\fP ])"
+.IX Subsection "XML::Atom::Feed->new([ $stream ])"
+Creates a new feed object, and if \fI\f(CI$stream\fI\fR is supplied, fills it with the
+data specified by \fI\f(CI$stream\fI\fR.
+.PP
+Automatically handles autodiscovery if \fI\f(CI$stream\fI\fR is a \s-1URI\s0 (see below).
+.PP
+Returns the new \fIXML::Atom::Feed\fR object. On failure, returns \f(CW\*(C`undef\*(C'\fR.
+.PP
+\&\fI\f(CI$stream\fI\fR can be any one of the following:
+.IP "\(bu" 4
+Reference to a scalar
+.Sp
+This is treated as the \s-1XML\s0 body of the feed.
+.IP "\(bu" 4
+Scalar
+.Sp
+This is treated as the name of a file containing the feed \s-1XML\s0.
+.IP "\(bu" 4
+Filehandle
+.Sp
+This is treated as an open filehandle from which the feed \s-1XML\s0 can be read.
+.IP "\(bu" 4
+\&\s-1URI\s0 object
+.Sp
+This is treated as a \s-1URI\s0, and the feed \s-1XML\s0 will be retrieved from the \s-1URI\s0.
+.Sp
+If the content type returned from fetching the content at \s-1URI\s0 is
+\&\fItext/html\fR, this method will automatically try to perform auto-discovery
+by looking for a \fI<link>\fR tag describing the feed \s-1URL\s0. If such
+a \s-1URL\s0 is found, the feed \s-1XML\s0 will be automatically retrieved.
+.Sp
+If the \s-1URI\s0 is already of a feed, no auto-discovery is necessary, and the
+feed \s-1XML\s0 will be retrieved and parsed as normal.
+.SS "XML::Atom::Feed\->find_feeds($uri)"
+.IX Subsection "XML::Atom::Feed->find_feeds($uri)"
+Given a \s-1URI\s0 \fI\f(CI$uri\fI\fR, use auto-discovery to find all of the Atom feeds linked
+from that page (using \fI<link>\fR tags).
+.PP
+Returns a list of feed URIs.
+.ie n .SS "$feed\->link"
+.el .SS "\f(CW$feed\fP\->link"
+.IX Subsection "$feed->link"
+If called in scalar context, returns an \fIXML::Atom::Link\fR object
+corresponding to the first \fI<link>\fR tag found in the feed.
+.PP
+If called in list context, returns a list of \fIXML::Atom::Link\fR objects
+corresponding to all of the \fI<link>\fR tags found in the feed.
+.ie n .SS "$feed\->add_link($link)"
+.el .SS "\f(CW$feed\fP\->add_link($link)"
+.IX Subsection "$feed->add_link($link)"
+Adds the link \fI\f(CI$link\fI\fR, which must be an \fIXML::Atom::Link\fR object, to
+the feed as a new \fI<link>\fR tag. For example:
+.PP
+.Vb 5
+\& my $link = XML::Atom::Link\->new;
+\& $link\->type(\*(Aqtext/html\*(Aq);
+\& $link\->rel(\*(Aqalternate\*(Aq);
+\& $link\->href(\*(Aqhttp://www.example.com/\*(Aq);
+\& $feed\->add_link($link);
+.Ve
+.ie n .SS "$feed\->add_entry($entry)"
+.el .SS "\f(CW$feed\fP\->add_entry($entry)"
+.IX Subsection "$feed->add_entry($entry)"
+Adds the entry \fI\f(CI$entry\fI\fR, which must be an \fIXML::Atom::Entry\fR object,
+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.
+.PP
+.Vb 1
+\& $feed\->add_entry($entry, { mode => \*(Aqinsert\*(Aq });
+.Ve
+.ie n .SS "$feed\->entries"
+.el .SS "\f(CW$feed\fP\->entries"
+.IX Subsection "$feed->entries"
+Returns list of XML::Atom::Entry objects contained in the feed.
+.ie n .SS "$feed\->language"
+.el .SS "\f(CW$feed\fP\->language"
+.IX Subsection "$feed->language"
+Returns the language of the feed, from \fIxml:lang\fR.
+.ie n .SS "$feed\->author([ $author ])"
+.el .SS "\f(CW$feed\fP\->author([ \f(CW$author\fP ])"
+.IX Subsection "$feed->author([ $author ])"
+Returns an \fIXML::Atom::Person\fR object representing the author of the entry,
+or \f(CW\*(C`undef\*(C'\fR if there is no author information present.
+.PP
+If \fI\f(CI$author\fI\fR is supplied, it should be an \fIXML::Atom::Person\fR object
+representing the author. For example:
+.PP
+.Vb 4
+\& my $author = XML::Atom::Person\->new;
+\& $author\->name(\*(AqFoo Bar\*(Aq);
+\& $author\->email(\*(Aqfoo@bar.com\*(Aq);
+\& $feed\->author($author);
+.Ve
+.ie n .SS "$feed\->id([ $id ])"
+.el .SS "\f(CW$feed\fP\->id([ \f(CW$id\fP ])"
+.IX Subsection "$feed->id([ $id ])"
+Returns an id for the feed. If \fI\f(CI$id\fI\fR is supplied, set the id. When
+generating the new feed, it is your responsibility to generate unique
+\&\s-1ID\s0 for the feed and set to XML::Atom::Feed object. You can use \fIhttp\fR
+permalink, \fItag\fR \s-1URI\s0 scheme or \fIurn:uuid\fR for handy.
+.SH "UNICODE FLAGS"
+.IX Header "UNICODE FLAGS"
+By default, XML::Atom takes off all the Unicode flag fro mthe feed content. For example,
+.PP
+.Vb 1
+\& my $title = $feed\->title;
+.Ve
+.PP
+the variable \f(CW$title\fR contains \s-1UTF\-8\s0 bytes without Unicode flag set,
+even if the feed title contains some multibyte chracters.
+.PP
+If you don't like this behaviour and wants to andle everything as
+Unicode characters (rather than \s-1UTF\-8\s0 bytes), set
+\&\f(CW$XML::Atom::ForceUnicode\fR flag to 1.
+.PP
+.Vb 1
+\& $XML::Atom::ForceUnicode = 1;
+.Ve
+.PP
+then all the data returned from XML::Atom::Feed object and
+XML::Atom::Entry object etc., will have Unicode flag set.
+.PP
+The only exception will be \f(CW\*(C`$entry\->content\->body\*(C'\fR, if content
+type is not text/* (e.g. image/gif). In that case, the content body is
+still binary data, without Unicode flag set.
+.SH "CREATING ATOM 1.0 FEEDS"
+.IX Header "CREATING ATOM 1.0 FEEDS"
+By default, XML::Atom::Feed and other classes (Entry, Link and
+Content) will create entities using Atom 0.3 namespaces. In order to
+create 1.0 feed and entry elements, you can set \fIVersion\fR as a
+parameter, like:
+.PP
+.Vb 2
+\& $feed = XML::Atom::Feed\->new(Version => 1.0);
+\& $entry = XML::Atom::Entry\->new(Version => 1.0);
+.Ve
+.PP
+Setting those Version to every element would be sometimes painful. In
+that case, you can override the default version number by setting
+\&\f(CW$XML::Atom::DefaultVersion\fR global variable to \*(L"1.0\*(R".
+.PP
+.Vb 1
+\& use XML::Atom;
+\&
+\& $XML::Atom::DefaultVersion = "1.0";
+\&
+\& my $feed = XML::Atom::Feed\->new;
+\& $feed\->title("blah");
+\&
+\& my $entry = XML::Atom::Entry\->new;
+\& $feed\->add_entry($entry);
+\&
+\& $feed\->version; # 1.0
+.Ve
+.SH "AUTHOR & COPYRIGHT"
+.IX Header "AUTHOR & COPYRIGHT"
+Please see the \fIXML::Atom\fR manpage for author, copyright, and license
+information.
projects / catagits/Gitalist.git / blobdiff