.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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::TreePP 3pm"
.TH XML::TreePP 3pm "2009-06-30" "perl v5.10.0" "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::TreePP \-\- Pure Perl implementation for parsing/writing XML documents
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
parse an \s-1XML\s0 document from file into hash tree:
.PP
.Vb 5
\&    use XML::TreePP;
\&    my $tpp = XML::TreePP\->new();
\&    my $tree = $tpp\->parsefile( "index.rdf" );
\&    print "Title: ", $tree\->{"rdf:RDF"}\->{item}\->[0]\->{title}, "\en";
\&    print "URL:   ", $tree\->{"rdf:RDF"}\->{item}\->[0]\->{link}, "\en";
.Ve
.PP
write an \s-1XML\s0 document as string from hash tree:
.PP
.Vb 11
\&    use XML::TreePP;
\&    my $tpp = XML::TreePP\->new();
\&    my $tree = { rss => { channel => { item => [ {
\&        title   => "The Perl Directory",
\&        link    => "http://www.perl.org/",
\&    }, {
\&        title   => "The Comprehensive Perl Archive Network",
\&        link    => "http://cpan.perl.org/",
\&    } ] } } };
\&    my $xml = $tpp\->write( $tree );
\&    print $xml;
.Ve
.PP
get a remote \s-1XML\s0 document by HTTP-GET and parse it into hash tree:
.PP
.Vb 5
\&    use XML::TreePP;
\&    my $tpp = XML::TreePP\->new();
\&    my $tree = $tpp\->parsehttp( GET => "http://use.perl.org/index.rss" );
\&    print "Title: ", $tree\->{"rdf:RDF"}\->{channel}\->{title}, "\en";
\&    print "URL:   ", $tree\->{"rdf:RDF"}\->{channel}\->{link}, "\en";
.Ve
.PP
get a remote \s-1XML\s0 document by HTTP-POST and parse it into hash tree:
.PP
.Vb 8
\&    use XML::TreePP;
\&    my $tpp = XML::TreePP\->new( force_array => [qw( item )] );
\&    my $cgiurl = "http://search.hatena.ne.jp/keyword";
\&    my $keyword = "ajax";
\&    my $cgiquery = "mode=rss2&word=".$keyword;
\&    my $tree = $tpp\->parsehttp( POST => $cgiurl, $cgiquery );
\&    print "Link: ", $tree\->{rss}\->{channel}\->{item}\->[0]\->{link}, "\en";
\&    print "Desc: ", $tree\->{rss}\->{channel}\->{item}\->[0]\->{description}, "\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
XML::TreePP module parses an \s-1XML\s0 document and expands it for a hash tree.
This generates an \s-1XML\s0 document from a hash tree as the opposite way around.
This is a pure Perl implementation and requires no modules depended.
This can also fetch and parse an \s-1XML\s0 document from remote web server
like the XMLHttpRequest object does at JavaScript language.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Parse \s-1XML\s0 file"
.IX Subsection "Parse XML file"
Sample \s-1XML\s0 document:
.PP
.Vb 10
\&    <?xml version="1.0" encoding="UTF\-8"?>
\&    <family name="Kawasaki">
\&        <father>Yasuhisa</father>
\&        <mother>Chizuko</mother>
\&        <children>
\&            <girl>Shiori</girl>
\&            <boy>Yusuke</boy>
\&            <boy>Kairi</boy>
\&        </children>
\&    </family>
.Ve
.PP
Sample program to read a xml file and dump it:
.PP
.Vb 6
\&    use XML::TreePP;
\&    use Data::Dumper;
\&    my $tpp = XML::TreePP\->new();
\&    my $tree = $tpp\->parsefile( "family.xml" );
\&    my $text = Dumper( $tree );
\&    print $text;
.Ve
.PP
Result dumped:
.PP
.Vb 10
\&    $VAR1 = {
\&        \*(Aqfamily\*(Aq => {
\&            \*(Aq\-name\*(Aq => \*(AqKawasaki\*(Aq,
\&            \*(Aqfather\*(Aq => \*(AqYasuhisa\*(Aq,
\&            \*(Aqmother\*(Aq => \*(AqChizuko\*(Aq,
\&            \*(Aqchildren\*(Aq => {
\&                \*(Aqgirl\*(Aq => \*(AqShiori\*(Aq
\&                \*(Aqboy\*(Aq => [
\&                    \*(AqYusuke\*(Aq,
\&                    \*(AqKairi\*(Aq
\&                ],
\&            }
\&        }
\&    };
.Ve
.PP
Details:
.PP
.Vb 1
\&    print $tree\->{family}\->{father};        # the father\*(Aqs given name.
.Ve
.PP
The prefix '\-' is added on every attribute's name.
.PP
.Vb 1
\&    print $tree\->{family}\->{"\-name"};       # the family name of the family
.Ve
.PP
The array is used because the family has two boys.
.PP
.Vb 2
\&    print $tree\->{family}\->{children}\->{boy}\->[1];  # The second boy\*(Aqs name
\&    print $tree\->{family}\->{children}\->{girl};      # The girl\*(Aqs name
.Ve
.SS "Text node and attributes:"
.IX Subsection "Text node and attributes:"
If a element has both of a text node and attributes
or both of a text node and other child nodes,
value of a text node is moved to \f(CW\*(C`#text\*(C'\fR like child nodes.
.PP
.Vb 7
\&    use XML::TreePP;
\&    use Data::Dumper;
\&    my $tpp = XML::TreePP\->new();
\&    my $source = \*(Aq<span class="author">Kawasaki Yusuke</span>\*(Aq;
\&    my $tree = $tpp\->parse( $source );
\&    my $text = Dumper( $tree );
\&    print $text;
.Ve
.PP
The result dumped is following:
.PP
.Vb 6
\&    $VAR1 = {
\&        \*(Aqspan\*(Aq => {
\&            \*(Aq\-class\*(Aq => \*(Aqauthor\*(Aq,
\&            \*(Aq#text\*(Aq  => \*(AqKawasaki Yusuke\*(Aq
\&        }
\&    };
.Ve
.PP
The special node name of \f(CW\*(C`#text\*(C'\fR is used because this elements
has attribute(s) in addition to the text node.
See also \*(L"text_node_key\*(R" option.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
This constructor method returns a new XML::TreePP object with \f(CW%options\fR.
.PP
.Vb 1
\&    $tpp = XML::TreePP\->new( %options );
.Ve
.SS "set"
.IX Subsection "set"
This method sets a option value for \f(CW\*(C`option_name\*(C'\fR.
If \f(CW$option_value\fR is not defined, its option is deleted.
.PP
.Vb 1
\&    $tpp\->set( option_name => $option_value );
.Ve
.PP
See \s-1OPTIONS\s0 section below for details.
.SS "get"
.IX Subsection "get"
This method returns a current option value for \f(CW\*(C`option_name\*(C'\fR.
.PP
.Vb 1
\&    $tpp\->get( \*(Aqoption_name\*(Aq );
.Ve
.SS "parse"
.IX Subsection "parse"
This method reads an \s-1XML\s0 document by string and returns a hash tree converted.
The first argument is a scalar or a reference to a scalar.
.PP
.Vb 1
\&        $tree = $tpp\->parse( $source );
.Ve
.SS "parsefile"
.IX Subsection "parsefile"
This method reads an \s-1XML\s0 document by file and returns a hash tree converted.
The first argument is a filename.
.PP
.Vb 1
\&    $tree = $tpp\->parsefile( $file );
.Ve
.SS "parsehttp"
.IX Subsection "parsehttp"
This method receives an \s-1XML\s0 document from a remote server via \s-1HTTP\s0 and
returns a hash tree converted.
.PP
.Vb 1
\&    $tree = $tpp\->parsehttp( $method, $url, $body, $head );
.Ve
.PP
\&\f(CW$method\fR is a method of \s-1HTTP\s0 connection: \s-1GET/POST/PUT/DELETE\s0
\&\f(CW$url\fR is an \s-1URI\s0 of an \s-1XML\s0 file.
\&\f(CW$body\fR is a request body when you use \s-1POST\s0 method.
\&\f(CW$head\fR is a request headers as a hash ref.
LWP::UserAgent module or HTTP::Lite module is required to fetch a file.
.PP
.Vb 1
\&    ( $tree, $xml, $code ) = $tpp\->parsehttp( $method, $url, $body, $head );
.Ve
.PP
In array context, This method returns also raw \s-1XML\s0 document received
and \s-1HTTP\s0 response's status code.
.SS "write"
.IX Subsection "write"
This method parses a hash tree and returns an \s-1XML\s0 document as a string.
.PP
.Vb 1
\&    $source = $tpp\->write( $tree, $encode );
.Ve
.PP
\&\f(CW$tree\fR is a reference to a hash tree.
.SS "writefile"
.IX Subsection "writefile"
This method parses a hash tree and writes an \s-1XML\s0 document into a file.
.PP
.Vb 1
\&    $tpp\->writefile( $file, $tree, $encode );
.Ve
.PP
\&\f(CW$file\fR is a filename to create.
\&\f(CW$tree\fR is a reference to a hash tree.
.SH "OPTIONS FOR PARSING XML"
.IX Header "OPTIONS FOR PARSING XML"
This module accepts option parameters following:
.SS "force_array"
.IX Subsection "force_array"
This option allows you to specify a list of element names which
should always be forced into an array representation.
.PP
.Vb 1
\&    $tpp\->set( force_array => [ \*(Aqrdf:li\*(Aq, \*(Aqitem\*(Aq, \*(Aq\-xmlns\*(Aq ] );
.Ve
.PP
The default value is null, it means that context of the elements
will determine to make array or to keep it scalar or hash.
Note that the special wildcard name \f(CW\*(Aq*\*(Aq\fR means all elements.
.SS "force_hash"
.IX Subsection "force_hash"
This option allows you to specify a list of element names which
should always be forced into an hash representation.
.PP
.Vb 1
\&    $tpp\->set( force_hash => [ \*(Aqitem\*(Aq, \*(Aqimage\*(Aq ] );
.Ve
.PP
The default value is null, it means that context of the elements
will determine to make hash or to keep it scalar as a text node.
See also \*(L"text_node_key\*(R" option below.
Note that the special wildcard name \f(CW\*(Aq*\*(Aq\fR means all elements.
.SS "cdata_scalar_ref"
.IX Subsection "cdata_scalar_ref"
This option allows you to convert a cdata section into a reference
for scalar on parsing an \s-1XML\s0 document.
.PP
.Vb 1
\&    $tpp\->set( cdata_scalar_ref => 1 );
.Ve
.PP
The default value is false, it means that each cdata section is converted into a scalar.
.SS "user_agent"
.IX Subsection "user_agent"
This option allows you to specify a \s-1HTTP_USER_AGENT\s0 string which
is used by \fIparsehttp()\fR method.
.PP
.Vb 1
\&    $tpp\->set( user_agent => \*(AqMozilla/4.0 (compatible; ...)\*(Aq );
.Ve
.PP
The default string is \f(CW\*(AqXML\-TreePP/#.##\*(Aq\fR, where \f(CW\*(Aq#.##\*(Aq\fR is
substituted with the version number of this library.
.SS "http_lite"
.IX Subsection "http_lite"
This option forces \fIpasrsehttp()\fR method to use a HTTP::Lite instance.
.PP
.Vb 2
\&    my $http = HTTP::Lite\->new();
\&    $tpp\->set( http_lite => $http );
.Ve
.SS "lwp_useragent"
.IX Subsection "lwp_useragent"
This option forces \fIpasrsehttp()\fR method to use a LWP::UserAgent instance.
.PP
.Vb 4
\&    my $ua = LWP::UserAgent\->new();
\&    $ua\->timeout( 60 );
\&    $ua\->env_proxy;
\&    $tpp\->set( lwp_useragent => $ua );
.Ve
.PP
You may use this with LWP::UserAgent::WithCache.
.SS "base_class"
.IX Subsection "base_class"
This blesses class name for each element's hashref.
Each class is named straight as a child class of it parent class.
.PP
.Vb 4
\&    $tpp\->set( base_class => \*(AqMyElement\*(Aq );
\&    my $xml  = \*(Aq<root><parent><child key="val">text</child></parent></root>\*(Aq;
\&    my $tree = $tpp\->parse( $xml );
\&    print ref $tree\->{root}\->{parent}\->{child}, "\en";
.Ve
.PP
A hash for <child> element above is blessed to \f(CW\*(C`MyElement::root::parent::child\*(C'\fR
class. You may use this with Class::Accessor.
.SS "elem_class"
.IX Subsection "elem_class"
This blesses class name for each element's hashref.
Each class is named horizontally under the direct child of \f(CW\*(C`MyElement\*(C'\fR.
.PP
.Vb 4
\&    $tpp\->set( base_class => \*(AqMyElement\*(Aq );
\&    my $xml  = \*(Aq<root><parent><child key="val">text</child></parent></root>\*(Aq;
\&    my $tree = $tpp\->parse( $xml );
\&    print ref $tree\->{root}\->{parent}\->{child}, "\en";
.Ve
.PP
A hash for <child> element above is blessed to \f(CW\*(C`MyElement::child\*(C'\fR class.
.SS "xml_deref"
.IX Subsection "xml_deref"
This option dereferences the numeric character references, like &#xEB;,
&#28450;, etc., in an \s-1XML\s0 document when this value is true.
.PP
.Vb 1
\&    $tpp\->set( xml_deref => 1 );
.Ve
.PP
Note that, for security reasons and your convenient,
this module dereferences the predefined character entity references,
&amp;, &lt;, &gt;, &apos; and &quot;, and the numeric character
references up to U+007F without xml_deref per default.
.SH "OPTIONS FOR WRITING XML"
.IX Header "OPTIONS FOR WRITING XML"
.SS "first_out"
.IX Subsection "first_out"
This option allows you to specify a list of element/attribute
names which should always appears at first on output \s-1XML\s0 document.
.PP
.Vb 1
\&    $tpp\->set( first_out => [ \*(Aqlink\*(Aq, \*(Aqtitle\*(Aq, \*(Aq\-type\*(Aq ] );
.Ve
.PP
The default value is null, it means alphabetical order is used.
.SS "last_out"
.IX Subsection "last_out"
This option allows you to specify a list of element/attribute
names which should always appears at last on output \s-1XML\s0 document.
.PP
.Vb 1
\&    $tpp\->set( last_out => [ \*(Aqitems\*(Aq, \*(Aqitem\*(Aq, \*(Aqentry\*(Aq ] );
.Ve
.SS "indent"
.IX Subsection "indent"
This makes the output more human readable by indenting appropriately.
.PP
.Vb 1
\&    $tpp\->set( indent => 2 );
.Ve
.PP
This doesn't strictly follow the \s-1XML\s0 specification but does looks nice.
.SS "xml_decl"
.IX Subsection "xml_decl"
This module inserts an \s-1XML\s0 declaration on top of the \s-1XML\s0 document generated
per default. This option forces to change it to another or just remove it.
.PP
.Vb 1
\&    $tpp\->set( xml_decl => \*(Aq\*(Aq );
.Ve
.SS "output_encoding"
.IX Subsection "output_encoding"
This option allows you to specify a encoding of the \s-1XML\s0 document generated
by write/writefile methods.
.PP
.Vb 1
\&    $tpp\->set( output_encoding => \*(AqUTF\-8\*(Aq );
.Ve
.PP
On Perl 5.8.0 and later, you can select it from every
encodings supported by Encode.pm. On Perl 5.6.x and before with
Jcode.pm, you can use \f(CW\*(C`Shift_JIS\*(C'\fR, \f(CW\*(C`EUC\-JP\*(C'\fR, \f(CW\*(C`ISO\-2022\-JP\*(C'\fR and
\&\f(CW\*(C`UTF\-8\*(C'\fR. The default value is \f(CW\*(C`UTF\-8\*(C'\fR which is recommended encoding.
.SH "OPTIONS FOR BOTH"
.IX Header "OPTIONS FOR BOTH"
.SS "utf8_flag"
.IX Subsection "utf8_flag"
This makes utf8 flag on for every element's value parsed
and makes it on for the \s-1XML\s0 document generated as well.
.PP
.Vb 1
\&    $tpp\->set( utf8_flag => 1 );
.Ve
.PP
Perl 5.8.1 or later is required to use this.
.SS "attr_prefix"
.IX Subsection "attr_prefix"
This option allows you to specify a prefix character(s) which
is inserted before each attribute names.
.PP
.Vb 1
\&    $tpp\->set( attr_prefix => \*(Aq@\*(Aq );
.Ve
.PP
The default character is \f(CW\*(Aq\-\*(Aq\fR.
Or set \f(CW\*(Aq@\*(Aq\fR to access attribute values like E4X, ECMAScript for \s-1XML\s0.
Zero-length prefix \f(CW\*(Aq\*(Aq\fR is available as well, it means no prefix is added.
.SS "text_node_key"
.IX Subsection "text_node_key"
This option allows you to specify a hash key for text nodes.
.PP
.Vb 1
\&    $tpp\->set( text_node_key => \*(Aq#text\*(Aq );
.Ve
.PP
The default key is \f(CW\*(C`#text\*(C'\fR.
.SS "ignore_error"
.IX Subsection "ignore_error"
This module calls Carp::croak function on an error per default.
This option makes all errors ignored and just returns.
.PP
.Vb 1
\&    $tpp\->set( ignore_error => 1 );
.Ve
.SS "use_ixhash"
.IX Subsection "use_ixhash"
This option keeps the order for each element appeared in \s-1XML\s0.
Tie::IxHash module is required.
.PP
.Vb 1
\&    $tpp\->set( use_ixhash => 1 );
.Ve
.PP
This makes parsing performance slow.
(about 100% slower than default)
.SH "AUTHOR"
.IX Header "AUTHOR"
Yusuke Kawasaki, http://www.kawa.net/
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (c) 2006\-2009 Yusuke Kawasaki. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.