view release on metacpan or  search on metacpan

lib/XML/Hash/XS.pm  view on Meta::CPAN

package XML::Hash::XS;

use 5.008008;
use strict;
use warnings;
use vars qw($VERSION @EXPORT @EXPORT_OK);
use base 'Exporter';
@EXPORT_OK = @EXPORT = qw( hash2xml xml2hash );

$VERSION = '0.64';

require XSLoader;
XSLoader::load('XML::Hash::XS', $VERSION);

use vars qw($method $output $root $version $encoding $utf8 $indent $canonical
    $use_attr $content $xml_decl $doc $max_depth $attr $text $trim $cdata
    $comm $buf_size $keep_root $force_array $force_content $merge_text
    $suppress_empty
);

# 'NATIVE' or 'LX'
$method         = 'NATIVE';

# native options
$output         = undef;
$root           = 'root';
$version        = '1.0';
$encoding       = '';
$utf8           = 1;
$indent         = 0;
$canonical      = 0;
$use_attr       = 0;
$content        = undef;
$xml_decl       = 1;
$keep_root      = 1;
$doc            = 0;
$max_depth      = 1024;
$buf_size       = 4096;
$trim           = 0;
$force_array    = undef;
$force_content  = 0;
$merge_text     = 0;
$suppress_empty = 0;

# XML::Hash::LX options
$attr           = '-';
$text           = '#text';
$cdata          = undef;
$comm           = undef;

1;
__END__
=head1 NAME

XML::Hash::XS - Simple and fast hash to XML and XML to hash conversion written in C

=begin HTML

<p><a href="https://metacpan.org/pod/XML::Hash::XS" target="_blank"><img alt="CPAN version" src="https://badge.fury.io/pl/XML-Hash-XS.svg"></a> <a href="https://travis-ci.org/yoreek/XML-Hash-XS" target="_blank"><img title="Build Status Images" src="h...

=end HTML

=head1 SYNOPSIS

    use XML::Hash::XS;

    my $xmlstr = hash2xml \%hash;
    hash2xml \%hash, output => $fh;

    my $hash = xml2hash $xmlstr;
    my $hash = xml2hash \$xmlstr;
    my $hash = xml2hash 'test.xml', encoding => 'cp1251';
    my $hash = xml2hash $fh;
    my $hash = xml2hash *STDIN;

Or OOP way:

    use XML::Hash::XS qw();

    my $conv   = XML::Hash::XS->new(utf8 => 0, encoding => 'utf-8')
    my $xmlstr = $conv->hash2xml(\%hash, utf8 => 1);
    my $hash   = $conv->xml2hash($xmlstr, encoding => 'cp1251');

=head1 DESCRIPTION

This module implements simple hash to XML and XML to hash conversion written in C.

During conversion uses minimum of memory, XML or hash is written directly without building DOM.

Some features are optional and are available with appropriate libraries:

=over 2

=item * XML::LibXML library is required  in order to build DOM

=item * ICU or iconv library is required in order to perform charset conversions

=back

=head1 FUNCTIONS

=head2 hash2xml $hash, [ %options ]

$hash is reference to hash

    hash2xml
        {
            node1 => 'value1',

lib/XML/Hash/XS.pm  view on Meta::CPAN

=item max_depth [ = 1024 ] I<# xml2hash>

Maximum recursion depth.

=item buf_size [ = 4096 ] I<# hash2xml+xml2hash>

Buffer size for reading end encoding data.

=item keep_root [ = 1 ] I<# hash2xml+xml2hash>

Keep root element.

=item filter [ = undef ] I<# xml2hash>

Filter nodes matched by pattern and return reference to array of nodes.

Sample:

    my $xml = <<'XML';
        <root>
           <item1>111</item1>
           <item2>222</item2>
           <item3>333</item3>
        </root>
    XML

    my $nodes = xml2hash($xml, filter => '/root/item1');
    # $nodes = [ 111 ]

    my $nodes = xml2hash($xml, filter => ['/root/item1', '/root/item2']);
    # $nodes = [ 111, 222 ]

    my $nodes = xml2hash($xml, filter => qr[/root/item\d$]);
    # $nodes = [ 111, 222, 333 ]

It may be used to parse large XML because does not require a lot of memory.

=item cb [ = undef ] I<# xml2hash>

This option is used in conjunction with "filter" option and defines callback
that will called for each matched node.

Sample:

    xml2hash($xml, filter => qr[/root/item\d$], cb => sub {
        print $_[0], "\n";
    });
    # 111
    # 222
    # 333

=item method [ = 'NATIVE' ] I<# hash2xml>

experimental support the conversion methods other libraries

if method is 'LX' then conversion result is the same as using L<XML::Hash::LX> library

Note: for 'LX' method following additional options are available:
    attr
    cdata
    text
    comm

=back

=head1 OBJECT SERIALISATION(hash2xml)

=over 2

=item 1. When object has a "toString" method

In this case, the <toString> method of object is invoked in scalar context.
It must return a single scalar that can be directly encoded into XML.

Example:

    use XML::LibXML;
    local $XML::LibXML::skipXMLDeclaration = 1;
    my $doc = XML::LibXML->new->parse_string('<foo bar="1"/>');
    print hash2xml({ doc => $doc }, indent => 2, xml_decl => 0);
    =>
    <root>
      <doc><foo bar="1"/></doc>
    </root>

=item 2. When object has overloaded stringification

In this case, the stringification method of object is invoked and result is directly encoded into XML.

Example:

    package Test {
        use overload '""' => sub { shift->stringify }, fallback => 1;
        sub new {
            my ($class, $str) = @_;
            bless { str => $str }, $class;
        }
        sub stringify {
            shift->{str}
        }
    }
    my $obj = Test->new('test string');
    print hash2xml({ obj => $obj }, indent => 2, xml_decl => 0);
    =>
    <root>
      <obj>test string</obj>
    </root>

=item 3. When object has a "iternext" method ("NATIVE" method only)

In this case, the <iternext> method method will invoke a few times until the return value is not undefined.

Example:

    my $count = 0;
    my $o = bless {}, 'Iterator';
    *Iterator::iternext = sub { $count++ < 3 ? { count => $count } : undef };
    print hash2xml({ item => $o }, use_attr => 1, indent => 2, xml_decl => 0);
    =>
    <root>