.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" 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 3pm"
.TH XML::Atom::Feed 3pm "2018-01-02" "perl v5.26.1" "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 from the 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 characters.
.PP
If you don't like this behaviour and wants to handle 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.