NAME
    XML::TreePP -- Pure Perl implementation for parsing/writing xml file

SYNOPSIS
    parse xml file into hash tree

        use XML::TreePP;
        my $tpp = XML::TreePP->new();
        my $tree = $tpp->parsefile( "index.rdf" );
        print "Title: ", $tree->{"rdf:RDF"}->{item}->[0]->{title}, "\n";
        print "URL:   ", $tree->{"rdf:RDF"}->{item}->[0]->{link}, "\n";

    write xml as string from hash tree

        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;

    get remote xml file with HTTP-GET and parse it into hash tree

        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}, "\n";
        print "URL:   ", $tree->{"rdf:RDF"}->{channel}->{link}, "\n";

    get remote xml file with HTTP-POST and parse it into hash tree

        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}, "\n";
        print "Desc: ", $tree->{rss}->{channel}->{item}->[0]->{description}, "\n";

DESCRIPTION
    XML::TreePP module parses XML file and expand it for a hash tree. And
    also generate XML file from a hash tree. This is a pure Perl
    implementation. You can also download XML from remote web server like
    XMLHttpRequest object at JavaScript language.

EXAMPLES
  Parse XML file
    Sample XML source:

        <?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>

    Sample program to read a xml file and dump it:

        use XML::TreePP;
        use Data::Dumper;
        my $tpp = XML::TreePP->new();
        my $tree = $tpp->parsefile( "family.xml" );
        my $text = Dumper( $tree );
        print $text;

    Result dumped:

        $VAR1 = {
            'family' => {
                '-name' => 'Kawasaki',
                'father' => 'Yasuhisa',
                'mother' => 'Chizuko',
                'children' => {
                    'girl' => 'Shiori'
                    'boy' => [
                        'Yusuke',
                        'Kairi'
                    ],
                }
            }
        };

    Explain:

        print $tree->{family}->{father};        # the father's given name.

    The prefix '-' is added on every attributes' name.

        print $tree->{family}->{"-name"};       # the family name of the family

    The array is used because the family has two boys.

        print $tree->{family}->{children}->{boy}->[1];  # The second boy's name
        print $tree->{family}->{children}->{girl};      # The girl's name

  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 "#text"
    like child nodes.

        use XML::TreePP;
        use Data::Dumper;
        my $tpp = XML::TreePP->new();
        my $source = '<span class="author">Kawasaki Yusuke</span>';
        my $tree = $tpp->parse( $source );
        my $text = Dumper( $tree );
        print $text;

    The result dumped is following:

        $VAR1 = {
            'span' => {
                '-class' => 'author',
                '#text' => 'Kawasaki Yusuke'
            }
        };

    The special node name of "#text" is used because this elements has
    attribute(s) in addition to the text node.

METHODS
  $tpp = XML::TreePP->new( %attributes )
    This method constructs a new "XML::TreePP" object. Optional attributes
    are following:

  output_encoding => "UTF-8",
    You can define a encoding of xml file generated by write/writefile
    methods. On Perl 5.8.x and later, you can select it from every encodings
    supported by Encode.pm. On Perl 5.6.x or before with Jcode.pm, you can
    use "Shift_JIS", "EUC-JP", "ISO-2022-JP" and "UTF-8". The default value
    is "UTF-8".

  force_array => [ "rdf:li", "item", "-xmlns" ],
    This option allows you to specify a list of element names which should
    always be forced into an array representation The default value is null,
    it means that context of the elements will determine to make array or to
    keep it scalar.

  first_out => [ "link", "title", "-type" ],
    This option allows you to specify a list of element/attribute names
    which should always appears at first on output XML code. The default
    value is null, it means alphabetical order is used.

  last_out => [ "items", "item", "entry" ],
    This option allows you to specify a list of element/attribute names
    which should always appears at last on output XML code.

  $tree = $tpp->parse( $source );
    This method reads XML source and returns a hash tree converted. The
    first argument is a scalar or a reference to a scalar.

  $tree = $tpp->parsefile( $file );
    This method reads a XML file and returns a hash tree converted. The
    first argument is a filename.

  $tree = $tpp->parsefile( $method, $url, $body );
    This method receive a XML file from a remote server via HTTP and returns
    a hash tree converted. This medhot requires LWP::UserAgent module.
    $method is a method of HTTP connection: GET/POST/PUT/DELETE $url is URI
    of a XML file. $body is request body when you use POST method.

  $source = $tpp->write( $tree, $encode );
    This method parse a hash tree and returns a XML source generated. $tree
    is a referecen to a hash tree.

  $tpp->writefile( $file, $tree, $encode );
    This method parse a hash tree and writes a XML source into a file. $file
    is a filename to create. $tree is a referecen to a hash tree.

AUTHOR
    Yusuke Kawasaki, <u-suke [at] kawa.net>
    http://www.kawa.net/works/perl/treepp/treepp-e.html

COPYRIGHT AND LICENSE
    Copyright (c) 2006 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.

