view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

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 );