========================================================================
* README
========================================================================

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

SYNOPSIS
    parse an XML document from 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 an XML document 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 a remote XML document by 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 a remote XML document by 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 an XML document and expands it for a hash
    tree. This generates an XML 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 XML document from remote web
    server like the XMLHttpRequest object does at JavaScript language.

EXAMPLES
  Parse XML file
    Sample XML document:

        <?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'
                    ],
                }
            }
        };

    Details:

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

    The prefix '-' is added on every attribute's 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. See also "text_node_key"
    option.

METHODS
  new
    This constructor method returns a new XML::TreePP object with %options.

        $tpp = XML::TreePP->new( %options );

  set
    This method sets a option value for "option_name". If $option_value is
    not defined, its option is deleted.

        $tpp->set( option_name => $option_value );

    See OPTIONS section below for details.

  get
    This method returns a current option value for "option_name".

        $tpp->get( 'option_name' );

  parse
    This method reads an XML document by string and returns a hash tree
    converted. The first argument is a scalar or a reference to a scalar.

            $tree = $tpp->parse( $source );

  parsefile
    This method reads an XML document by file and returns a hash tree
    converted. The first argument is a filename.

        $tree = $tpp->parsefile( $file );

  parsehttp
    This method receives an XML document from a remote server via HTTP and
    returns a hash tree converted.

        $tree = $tpp->parsehttp( $method, $url, $body, $head );

    $method is a method of HTTP connection: GET/POST/PUT/DELETE $url is an
    URI of an XML file. $body is a request body when you use POST method.
    $head is a request headers as a hash ref. LWP::UserAgent module or
    HTTP::Lite module is required to fetch a file.

        ( $tree, $xml, $code ) = $tpp->parsehttp( $method, $url, $body, $head );

    In array context, This method returns also raw XML document received and
    HTTP response's status code.

  write
    This method parses a hash tree and returns an XML document as a string.

        $source = $tpp->write( $tree, $encode );

    $tree is a reference to a hash tree.

  writefile
    This method parses a hash tree and writes an XML document into a file.

        $tpp->writefile( $file, $tree, $encode );

    $file is a filename to create. $tree is a reference to a hash tree.

OPTIONS FOR PARSING XML
    This module accepts option parameters following:

  force_array
    This option allows you to specify a list of element names which should
    always be forced into an array representation.

        $tpp->set( force_array => [ 'rdf:li', 'item', '-xmlns' ] );

    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 '*' means all elements.

  force_hash
    This option allows you to specify a list of element names which should
    always be forced into an hash representation.

        $tpp->set( force_hash => [ 'item', 'image' ] );

    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
    "text_node_key" option below. Note that the special wildcard name '*'
    means all elements.

  cdata_scalar_ref
    This option allows you to convert a cdata section into a reference for
    scalar on parsing an XML document.

        $tpp->set( cdata_scalar_ref => 1 );

    The default value is false, it means that each cdata section is
    converted into a scalar.

  user_agent
    This option allows you to specify a HTTP_USER_AGENT string which is used
    by parsehttp() method.

        $tpp->set( user_agent => 'Mozilla/4.0 (compatible; ...)' );

    The default string is 'XML-TreePP/#.##', where '#.##' is substituted
    with the version number of this library.

  http_lite
    This option forces pasrsehttp() method to use a HTTP::Lite instance.

        my $http = HTTP::Lite->new();
        $tpp->set( http_lite => $http );

  lwp_useragent
    This option forces parsehttp() method to use a LWP::UserAgent instance.

        my $ua = LWP::UserAgent->new();
        $ua->timeout( 60 );
        $ua->env_proxy;
        $tpp->set( lwp_useragent => $ua );

    You may use this with LWP::UserAgent::WithCache.

  base_class
    This blesses class name for each element's hashref. Each class is named
    straight as a child class of it parent class.

        $tpp->set( base_class => 'MyElement' );
        my $xml  = '<root><parent><child key="val">text</child></parent></root>';
        my $tree = $tpp->parse( $xml );
        print ref $tree->{root}->{parent}->{child}, "\n";

    A hash for <child> element above is blessed to
    "MyElement::root::parent::child" class. You may use this with
    Class::Accessor.

  elem_class
    This blesses class name for each element's hashref. Each class is named
    horizontally under the direct child of "MyElement".

        $tpp->set( base_class => 'MyElement' );
        my $xml  = '<root><parent><child key="val">text</child></parent></root>';
        my $tree = $tpp->parse( $xml );
        print ref $tree->{root}->{parent}->{child}, "\n";

    A hash for <child> element above is blessed to "MyElement::child" class.

  xml_deref
    This option dereferences the numeric character references, like &#xEB;,
    &#28450;, etc., in an XML document when this value is true.

        $tpp->set( xml_deref => 1 );

    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.

  require_xml_decl
    This option requires XML declaration at the top of XML document to
    parse.

        $tpp->set( require_xml_decl => 1 );

    This will die when <?xml .../?> declration not found.

OPTIONS FOR WRITING XML
  first_out
    This option allows you to specify a list of element/attribute names
    which should always appears at first on output XML document.

        $tpp->set( first_out => [ 'link', 'title', '-type' ] );

    The default value is null, it means alphabetical order is used.

  last_out
    This option allows you to specify a list of element/attribute names
    which should always appears at last on output XML document.

        $tpp->set( last_out => [ 'items', 'item', 'entry' ] );

  indent
    This makes the output more human readable by indenting appropriately.

        $tpp->set( indent => 2 );

    This doesn't strictly follow the XML specification but does looks nice.

  xml_decl
    This module inserts an XML declaration on top of the XML document
    generated per default. This option forces to change it to another or
    just remove it.

        $tpp->set( xml_decl => '' );

  output_encoding
    This option allows you to specify a encoding of the XML document
    generated by write/writefile methods.

        $tpp->set( output_encoding => 'UTF-8' );

    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 "Shift_JIS", "EUC-JP", "ISO-2022-JP" and "UTF-8". The default value
    is "UTF-8" which is recommended encoding.

  empty_element_tag_end
        $tpp->set( empty_element_tag_end => '>' );

    Set characters which close empty tag. The default value is ' />'.

OPTIONS FOR BOTH
  utf8_flag
    This makes utf8 flag on for every element's value parsed and makes it on
    for the XML document generated as well.

        $tpp->set( utf8_flag => 1 );

    Perl 5.8.1 or later is required to use this.

  attr_prefix
    This option allows you to specify a prefix character(s) which is
    inserted before each attribute names.

        $tpp->set( attr_prefix => '@' );

    The default character is '-'. Or set '@' to access attribute values like
    E4X, ECMAScript for XML. Zero-length prefix '' is available as well, it
    means no prefix is added.

  text_node_key
    This option allows you to specify a hash key for text nodes.

        $tpp->set( text_node_key => '#text' );

    The default key is "#text".

  ignore_error
    This module calls Carp::croak function on an error per default. This
    option makes all errors ignored and just returns.

        $tpp->set( ignore_error => 1 );

  use_ixhash
    This option keeps the order for each element appeared in XML.
    Tie::IxHash module is required.

        $tpp->set( use_ixhash => 1 );

    This makes parsing performance slow. (about 100% slower than default)

AUTHOR
    Yusuke Kawasaki, http://www.kawa.net/

REPOSITORY
    https://github.com/kawanet/XML-TreePP

COPYRIGHT
    The following copyright notice applies to all the files provided in this
    distribution, including binary files, unless explicitly noted otherwise.

    Copyright 2006-2010 Yusuke Kawasaki

LICENSE
    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.


========================================================================
* README.md
========================================================================

# NAME

XML::TreePP -- Pure Perl implementation for parsing/writing XML documents

# SYNOPSIS

parse an XML document from 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 an XML document 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 a remote XML document by 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 a remote XML document by 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 an XML document and expands it for a hash tree.
This generates an XML 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 XML document from remote web server
like the XMLHttpRequest object does at JavaScript language.

# EXAMPLES

## Parse XML file

Sample XML document:

    <?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'
                ],
            }
        }
    };

Details:

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

The prefix '-' is added on every attribute's 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.
See also ["text\_node\_key"](#text_node_key) option.

# METHODS

## new

This constructor method returns a new XML::TreePP object with `%options`.

    $tpp = XML::TreePP->new( %options );

## set

This method sets a option value for `option_name`.
If `$option_value` is not defined, its option is deleted.

    $tpp->set( option_name => $option_value );

See OPTIONS section below for details.

## get

This method returns a current option value for `option_name`.

    $tpp->get( 'option_name' );

## parse

This method reads an XML document by string and returns a hash tree converted.
The first argument is a scalar or a reference to a scalar.

        $tree = $tpp->parse( $source );

## parsefile

This method reads an XML document by file and returns a hash tree converted.
The first argument is a filename.

    $tree = $tpp->parsefile( $file );

## parsehttp

This method receives an XML document from a remote server via HTTP and
returns a hash tree converted.

    $tree = $tpp->parsehttp( $method, $url, $body, $head );

`$method` is a method of HTTP connection: GET/POST/PUT/DELETE
`$url` is an URI of an XML file.
`$body` is a request body when you use POST method.
`$head` is a request headers as a hash ref.
[LWP::UserAgent](https://metacpan.org/pod/LWP::UserAgent) module or [HTTP::Lite](https://metacpan.org/pod/HTTP::Lite) module is required to fetch a file.

    ( $tree, $xml, $code ) = $tpp->parsehttp( $method, $url, $body, $head );

In array context, This method returns also raw XML document received
and HTTP response's status code.

## write

This method parses a hash tree and returns an XML document as a string.

    $source = $tpp->write( $tree, $encode );

`$tree` is a reference to a hash tree.

## writefile

This method parses a hash tree and writes an XML document into a file.

    $tpp->writefile( $file, $tree, $encode );

`$file` is a filename to create.
`$tree` is a reference to a hash tree.

# OPTIONS FOR PARSING XML

This module accepts option parameters following:

## force\_array

This option allows you to specify a list of element names which
should always be forced into an array representation.

    $tpp->set( force_array => [ 'rdf:li', 'item', '-xmlns' ] );

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 `'*'` means all elements.

## force\_hash

This option allows you to specify a list of element names which
should always be forced into an hash representation.

    $tpp->set( force_hash => [ 'item', 'image' ] );

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 ["text\_node\_key"](#text_node_key) option below.
Note that the special wildcard name `'*'` means all elements.

## cdata\_scalar\_ref

This option allows you to convert a cdata section into a reference
for scalar on parsing an XML document.

    $tpp->set( cdata_scalar_ref => 1 );

The default value is false, it means that each cdata section is converted into a scalar.

## user\_agent

This option allows you to specify a HTTP\_USER\_AGENT string which
is used by parsehttp() method.

    $tpp->set( user_agent => 'Mozilla/4.0 (compatible; ...)' );

The default string is `'XML-TreePP/#.##'`, where `'#.##'` is
substituted with the version number of this library.

## http\_lite

This option forces pasrsehttp() method to use a [HTTP::Lite](https://metacpan.org/pod/HTTP::Lite)
instance.

    my $http = HTTP::Lite->new();
    $tpp->set( http_lite => $http );

## lwp\_useragent

This option forces parsehttp() method to use a [LWP::UserAgent](https://metacpan.org/pod/LWP::UserAgent) instance.

    my $ua = LWP::UserAgent->new();
    $ua->timeout( 60 );
    $ua->env_proxy;
    $tpp->set( lwp_useragent => $ua );

You may use this with [LWP::UserAgent::WithCache](https://metacpan.org/pod/LWP::UserAgent::WithCache).

## base\_class

This blesses class name for each element's hashref.
Each class is named straight as a child class of it parent class.

    $tpp->set( base_class => 'MyElement' );
    my $xml  = '<root><parent><child key="val">text</child></parent></root>';
    my $tree = $tpp->parse( $xml );
    print ref $tree->{root}->{parent}->{child}, "\n";

A hash for <child> element above is blessed to `MyElement::root::parent::child`
class. You may use this with [Class::Accessor](https://metacpan.org/pod/Class::Accessor).

## elem\_class

This blesses class name for each element's hashref.
Each class is named horizontally under the direct child of `MyElement`.

    $tpp->set( base_class => 'MyElement' );
    my $xml  = '<root><parent><child key="val">text</child></parent></root>';
    my $tree = $tpp->parse( $xml );
    print ref $tree->{root}->{parent}->{child}, "\n";

A hash for <child> element above is blessed to `MyElement::child` class.

## xml\_deref

This option dereferences the numeric character references, like &#xEB;,
&#28450;, etc., in an XML document when this value is true.

    $tpp->set( xml_deref => 1 );

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.

## require\_xml\_decl

This option requires XML declaration at the top of XML document to parse.

    $tpp->set( require_xml_decl => 1 );

This will die when <?xml .../?> declration not found.

# OPTIONS FOR WRITING XML

## first\_out

This option allows you to specify a list of element/attribute
names which should always appears at first on output XML document.

    $tpp->set( first_out => [ 'link', 'title', '-type' ] );

The default value is null, it means alphabetical order is used.

## last\_out

This option allows you to specify a list of element/attribute
names which should always appears at last on output XML document.

    $tpp->set( last_out => [ 'items', 'item', 'entry' ] );

## indent

This makes the output more human readable by indenting appropriately.

    $tpp->set( indent => 2 );

This doesn't strictly follow the XML specification but does looks nice.

## xml\_decl

This module inserts an XML declaration on top of the XML document generated
per default. This option forces to change it to another or just remove it.

    $tpp->set( xml_decl => '' );

## output\_encoding

This option allows you to specify a encoding of the XML document generated
by write/writefile methods.

    $tpp->set( output_encoding => 'UTF-8' );

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 `Shift_JIS`, `EUC-JP`, `ISO-2022-JP` and
`UTF-8`. The default value is `UTF-8` which is recommended encoding.

## empty\_element\_tag\_end

    $tpp->set( empty_element_tag_end => '>' );

Set characters which close empty tag. The default value is ' />'.

# OPTIONS FOR BOTH

## utf8\_flag

This makes utf8 flag on for every element's value parsed
and makes it on for the XML document generated as well.

    $tpp->set( utf8_flag => 1 );

Perl 5.8.1 or later is required to use this.

## attr\_prefix

This option allows you to specify a prefix character(s) which
is inserted before each attribute names.

    $tpp->set( attr_prefix => '@' );

The default character is `'-'`.
Or set `'@'` to access attribute values like E4X, ECMAScript for XML.
Zero-length prefix `''` is available as well, it means no prefix is added.

## text\_node\_key

This option allows you to specify a hash key for text nodes.

    $tpp->set( text_node_key => '#text' );

The default key is `#text`.

## ignore\_error

This module calls Carp::croak function on an error per default.
This option makes all errors ignored and just returns.

    $tpp->set( ignore_error => 1 );

## use\_ixhash

This option keeps the order for each element appeared in XML.
[Tie::IxHash](https://metacpan.org/pod/Tie::IxHash) module is required.

    $tpp->set( use_ixhash => 1 );

This makes parsing performance slow.
(about 100% slower than default)

# AUTHOR

Yusuke Kawasaki, http://www.kawa.net/

# REPOSITORY

https://github.com/kawanet/XML-TreePP

# COPYRIGHT

The following copyright notice applies to all the files provided in
this distribution, including binary files, unless explicitly noted
otherwise.

Copyright 2006-2010 Yusuke Kawasaki

# LICENSE

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.