The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
XML-TreePP-0.25
River stage two • 15 direct dependents • 33 total dependents
/ XML::TreePP

NAME

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

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

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.

METHODS

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

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

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

This method sets a option value for option_name. If $option_value is not defined, its option is deleted. See "OPTIONS" section below.

$tpp->get( 'option_name' );

This method returns a current option value for option_name.

$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->parsehttp( $method, $url, $body, $head );

This method receives a XML file from a remote server via HTTP and returns a hash tree converted. $method is a method of HTTP connection: GET/POST/PUT/DELETE $url is an URI of a 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 source received and HTTP response's status code.

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

This method parses a hash tree and returns a XML source generated. $tree is a referecen to a hash tree.

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

This method parses 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.

OPTIONS

$tpp->set( 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 and before with Jcode.pm, you can use Shift_JIS, EUC-JP, ISO-2022-JP and UTF-8. The default value is UTF-8.

$tpp->set( 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 or hash. Note that the special wildcard name '*' means all elements.

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

This option allows you to specify a list of element names which should always be forced into an hash representation. 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.

$tpp->set( 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.

$tpp->set( 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.

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

This option allows you to convert a cdata section into a reference for scalar on parsing XML source. If this option is false, per default, cdata section is converted into a scalar.

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

This option allows you to specify a HTTP_USER_AGENT string which is used by parsehttp() method. The default string is 'XML-TreePP/#.##', where '#.##' is substituted with the version number of this library.

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

This option allows you to specify a prefix character(s) which is inserted before each attribute names. The default character is '-'. Or set '@' to access attribute values like E4X, ECMAScript for XML. Zero-length prefix '' is also available now.

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

This option allows you to specify a hash key for text nodes. The default key is #text.

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

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

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

This module generates an XML declaration on writing an XML code per default. This option forces to change or leave it.

$tpp->set( http_lite => $http );

This option forces pasrsehttp() method to use HTTP::Lite module with its instance created like: $http = HTTP::Lite->new();

$tpp->set( lwp_useragent => $ua );

This option forces pasrsehttp() method to use LWP::UserAgent module with its instance created like: $ua = LWP::UserAgent->new();

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

This option keeps the order for each element appeared in XML. Tie::IxHash module is required. This makes parsing performance slow. (100% slower than default)

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

This makes the output more human readable by indenting appropriately. This doesn't strictly follow the XML Document Spec but does looks nice.

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

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

$tpp->set( base_class => 'MyElement' );

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

<root><parent><child>text</child></parent></root>

E.g., <child> element above is blessed to MyElement::root::parent::child class. You may use this with Class::Accessor.

$tpp->set( elem_class => 'MyElement' );

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

<root><parent><child>text</child></parent></root>

E.g., <child> element above is blessed to MyElement::child class.

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (c) 2006-2007 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.