.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" 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 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "XML::TreePuller::CookBook::Intro 3pm"
.TH XML::TreePuller::CookBook::Intro 3pm "2016-06-27" "perl v5.22.2" "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::TreePuller::CookBook::Intro \- Various ways to work with an Atom feed
.SH "ABOUT"
.IX Header "ABOUT"
Atom documents are simple and small \- they fit into \s-1RAM\s0 and don't have many
nested elements. Processing them is straight forward and a good place to
start learning.
.SS "Atom Format"
.IX Subsection "Atom Format"
An Atom feed looks like this:
.PP
.Vb 1
\&  <?xml version="1.0" encoding="utf\-8"?>
\& 
\&  <feed xmlns="http://www.w3.org/2005/Atom">
\& 
\&        <title>Example Feed</title>
\&        <subtitle>A subtitle.</subtitle>
\&        <link href="http://example.org/feed/" rel="self" />
\&        <link href="http://example.org/" />
\&        <id>urn:uuid:60a76c80\-d399\-11d9\-b91C\-0003939e0af6</id>
\&        <updated>2003\-12\-13T18:30:02Z</updated>
\&        <author>
\&                <name>John Doe</name>
\&                <email>johndoe@example.com</email>
\&        </author>
\& 
\&        <entry>
\&                <title>Atom\-Powered Robots Run Amok</title>
\&                <link href="http://example.org/2003/12/13/atom03" />
\&                <link rel="alternate" type="text/html" href="http://example.org/2003/12/13/atom03.html"/>
\&                <link rel="edit" href="http://example.org/2003/12/13/atom03/edit"/>
\&                <id>urn:uuid:1225c695\-cfb8\-4ebb\-aaaa\-80da344efa6a</id>
\&                <updated>2003\-12\-13T18:30:02Z</updated>
\&                <summary>Some text.</summary>
\&        </entry>
\& 
\&  </feed>
.Ve
.SH "PROGRAMS"
.IX Header "PROGRAMS"
.SS "Feed summaries"
.IX Subsection "Feed summaries"
Lets say you have 10 Atom feeds you are interested in subscribing to but
you want to see what they have to offer as a summary; Perl to the rescue!
The following script generates a report of an arbitrary number of Atom feeds 
off the Internet fetching them directly from a \s-1URL\s0 or a file. The format 
of the report is like this:
.PP
.Vb 2
\&  Feed: Example Feed
\&    * Atom\-Powered Robots Run Amok
.Ve
.PP
(that sure does sound like an interesting feed)
.PP
.Vb 1
\&  #!/usr/bin/env perl
\&  
\&  use strict;
\&  use warnings;
\&  
\&  use XML::TreePuller;
\&  
\&  foreach (@ARGV) {
\&        my $root = XML::TreePuller\->parse(location => $_);
\&        my $title = $root\->xpath(\*(Aq/feed/title\*(Aq)\->text;
\&        
\&        print "Feed: $title\en";
\&
\&        foreach ($root\->xpath(\*(Aq/feed/entry/title\*(Aq)) {   
\&                print "  * ", $_\->text, "\en";
\&        }
\&        
\&        print "\en\en\en";
\&  }
.Ve
.SS "Linking to entries"
.IX Subsection "Linking to entries"
Given an Atom feed what is the easiest way to build an \s-1HTML\s0 list of hyperlinks to the entries that
are specified in it? We need to get the title which is stored in a single element and the hyperlink
to the entry; there are multiple link elements and we only want one \- the one with \*(L"rel\*(R" attribute
value of \*(L"alternate\*(R". XPath makes quick work of this.
.PP
.Vb 1
\&  #!/usr/bin/env perl
\&
\&  use strict;
\&  use warnings;
\&  
\&  use XML::TreePuller;
\&  
\&  my $root = XML::TreePuller\->parse(location => shift(@ARGV));
\&  
\&  print "<ul>\en";
\&  
\&  foreach($root\->xpath(\*(Aq/feed/entry\*(Aq)) {
\&        my $title = $_\->xpath(\*(Aq//title\*(Aq)\->text;
\&        #there are many link elements but we only want one of them
\&        my $to = $_\->xpath("//link[\e@rel=\*(Aqalternate\*(Aq]")\->attribute(\*(Aqhref\*(Aq);
\&  
\&        print "  <li><a href=\e"$to\e">$title</a></li>\en";
\&  }
\&  
\&  print "</ul>\en";
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
The \s-1ATOM\s0 example \s-1XML\s0 document was taken from Wikipedia at the
following \s-1URL:\s0 http://en.wikipedia.org/w/index.php?title=Atom_(standard)&oldid=353180236
and is available under the Creative Commons Attribution ShareAlike license
.PP
All other content is copyright Tyler Riddle; see the \s-1README\s0 for licensing terms.