.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "XML::Hash::XS 3pm"
.TH XML::Hash::XS 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
XML::Hash::XS \- Simple and fast hash to XML and XML to hash conversion written in C
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use XML::Hash::XS;
\&
\&    my $xmlstr = hash2xml \e%hash;
\&    hash2xml \e%hash, output => $fh;
\&
\&    my $hash = xml2hash $xmlstr;
\&    my $hash = xml2hash \e$xmlstr;
\&    my $hash = xml2hash \*(Aqtest.xml\*(Aq, encoding => \*(Aqcp1251\*(Aq;
\&    my $hash = xml2hash $fh;
\&    my $hash = xml2hash *STDIN;
.Ve
.PP
Or OOP way:
.PP
.Vb 1
\&    use XML::Hash::XS qw();
\&
\&    my $conv   = XML::Hash::XS\->new(utf8 => 0, encoding => \*(Aqutf\-8\*(Aq)
\&    my $xmlstr = $conv\->hash2xml(\e%hash, utf8 => 1);
\&    my $hash   = $conv\->xml2hash($xmlstr, encoding => \*(Aqcp1251\*(Aq);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module implements simple hash to XML and XML to hash conversion written in C.
.PP
During conversion uses minimum of memory, XML or hash is written directly without building DOM.
.PP
Some features are optional and are available with appropriate libraries:
.IP \(bu 2
XML::LibXML library is required  in order to build DOM
.IP \(bu 2
ICU or iconv library is required in order to perform charset conversions
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.ie n .SS "hash2xml $hash, [ %options ]"
.el .SS "hash2xml \f(CW$hash\fP, [ \f(CW%options\fP ]"
.IX Subsection "hash2xml $hash, [ %options ]"
\&\f(CW$hash\fR is reference to hash
.PP
.Vb 11
\&    hash2xml
\&        {
\&            node1 => \*(Aqvalue1\*(Aq,
\&            node2 => [ \*(Aqvalue21\*(Aq, { node22 => \*(Aqvalue22\*(Aq } ],
\&            node3 => \e\*(Aqvalue3\*(Aq,
\&            node4 => sub { return \*(Aqvalue4\*(Aq },
\&            node5 => sub { return { node51 => \*(Aqvalue51\*(Aq } },
\&        },
\&        canonical => 1,
\&        indent    => 2,
\&    ;
.Ve
.PP
will convert to:
.PP
.Vb 10
\&    <?xml version="1.0" encoding="utf\-8"?>
\&    <root>
\&      <node1>value1</node1>
\&      <node2>value21</node2>
\&      <node2>
\&        <node22>value22</node22>
\&      </node2>
\&      <node3>value3</node3>
\&      <node4>value4</node4>
\&      <node5>
\&        <node51>value51</node51>
\&      </node5>
\&    </root>
.Ve
.PP
and (use_attr=1):
.PP
.Vb 12
\&    hash2xml
\&        {
\&            node1 => \*(Aqvalue1\*(Aq,
\&            node2 => [ \*(Aqvalue21\*(Aq, { node22 => \*(Aqvalue22\*(Aq } ],
\&            node3 => \e\*(Aqvalue3\*(Aq,
\&            node4 => sub { return \*(Aqvalue4\*(Aq },
\&            node5 => sub { return { node51 => \*(Aqvalue51\*(Aq } },
\&        },
\&        use_attr  => 1,
\&        canonical => 1,
\&        indent    => 2,
\&    ;
.Ve
.PP
will convert to:
.PP
.Vb 6
\&    <?xml version="1.0" encoding="utf\-8"?>
\&    <root node1="value1" node3="value3" node4="value4">
\&      <node2>value21</node2>
\&      <node2 node22="value22"/>
\&      <node5 node51="value51"/>
\&    </root>
.Ve
.ie n .SS "xml2hash $xml, [ %options ]"
.el .SS "xml2hash \f(CW$xml\fP, [ \f(CW%options\fP ]"
.IX Subsection "xml2hash $xml, [ %options ]"
\&\f(CW$xml\fR may be string, reference to string, file handle or tied file handle:
.PP
.Vb 2
\&    xml2hash \*(Aq<root>text</root>\*(Aq;
\&    # output: \*(Aqtext\*(Aq
\&
\&    xml2hash \*(Aq<root a="1" b="2">text</root>\*(Aq;
\&    # output: { a => \*(Aq1\*(Aq, b => \*(Aq2\*(Aq, content => \*(Aqtext\*(Aq }
\&
\&    open(my $fh, \*(Aq<\*(Aq, \*(Aqtest.xml\*(Aq);
\&    xml2hash $fh;
\&
\&    xml2hash *STDIN;
.Ve
.SH OPTIONS
.IX Header "OPTIONS"
.IP "doc [ => 0 ] \fI# hash2xml\fR" 4
.IX Item "doc [ => 0 ] # hash2xml"
if doc is '1', then returned value is XML::LibXML::Document.
.IP "root [ = 'root' ] \fI# hash2xml\fR" 4
.IX Item "root [ = 'root' ] # hash2xml"
Root node name.
.IP "version [ = '1.0' ] \fI# hash2xml\fR" 4
.IX Item "version [ = '1.0' ] # hash2xml"
XML document version
.IP "encoding [ = 'utf\-8' ] \fI# hash2xml+xml2hash\fR" 4
.IX Item "encoding [ = 'utf-8' ] # hash2xml+xml2hash"
XML input/output encoding
.IP "indent [ = 0 ] \fI# hash2xml\fR" 4
.IX Item "indent [ = 0 ] # hash2xml"
if indent great than "0", XML output should be indented according to its hierarchic structure.
This value determines the number of spaces.
.Sp
if indent is "0", XML output will all be on one line.
.IP "output [ = undef ] \fI# hash2xml\fR" 4
.IX Item "output [ = undef ] # hash2xml"
XML output method
.Sp
if output is undefined, XML document dumped into string.
.Sp
if output is FH, XML document writes directly to a filehandle or a stream.
.IP "canonical [ = 0 ] \fI# hash2xml\fR" 4
.IX Item "canonical [ = 0 ] # hash2xml"
if canonical is "1", converter will be write hashes sorted by key.
.Sp
if canonical is "0", order of the element will be pseudo-randomly.
.IP "use_attr [ = 0 ] \fI# hash2xml\fR" 4
.IX Item "use_attr [ = 0 ] # hash2xml"
if use_attr is "1", converter will be use the attributes.
.Sp
if use_attr is "0", converter will be use tags only.
.IP "content [ = undef ] \fI# hash2xml+xml2hash\fR" 4
.IX Item "content [ = undef ] # hash2xml+xml2hash"
if defined that the key name for the text content(used only if use_attr=1).
.IP "force_array => [ = undef ] \fI# xml2hash\fR" 4
.IX Item "force_array => [ = undef ] # xml2hash"
This option is similar to "ForceArray" from XML::Simple module: <https://metacpan.org/pod/XML::Simple#ForceArray\-=%3E\-1\-%23\-in\-important>.
.IP "force_content => [ = 0 ] \fI# xml2hash\fR" 4
.IX Item "force_content => [ = 0 ] # xml2hash"
This option is similar to "ForceContent" from XML::Simple module: <https://metacpan.org/pod/XML::Simple#ForceContent\-=%3E\-1\-%23\-in\-seldom\-used>.
.IP "merge_text [ = 0 ] \fI# xml2hash\fR" 4
.IX Item "merge_text [ = 0 ] # xml2hash"
Setting this option to "1" will cause merge adjacent text nodes.
.IP "xml_decl [ = 1 ] \fI# hash2xml\fR" 4
.IX Item "xml_decl [ = 1 ] # hash2xml"
if xml_decl is "1", output will start with the XML declaration '<?xml version="1.0" encoding="utf\-8"?>'.
.Sp
if xml_decl is "0", XML declaration will not be output.
.IP "trim [ = 0 ] \fI# hash2xml+xml2hash\fR" 4
.IX Item "trim [ = 0 ] # hash2xml+xml2hash"
Trim leading and trailing whitespace from text nodes.
.IP "suppress_empty => [ = 0 ] \fI# xml2hash\fR" 4
.IX Item "suppress_empty => [ = 0 ] # xml2hash"
This option is similar to "SuppressEmpty" from XMl::Simple module: <https://metacpan.org/pod/XML::Simple#SuppressEmpty\-=%3E\-1\-%7C\-''\-%7C\-undef\-%23\-in+out\-handy>.
.IP "utf8 [ = 1 ] \fI# hash2xml+xml2hash\fR" 4
.IX Item "utf8 [ = 1 ] # hash2xml+xml2hash"
Turn on utf8 flag for strings if enabled.
.IP "max_depth [ = 1024 ] \fI# xml2hash\fR" 4
.IX Item "max_depth [ = 1024 ] # xml2hash"
Maximum recursion depth.
.IP "buf_size [ = 4096 ] \fI# hash2xml+xml2hash\fR" 4
.IX Item "buf_size [ = 4096 ] # hash2xml+xml2hash"
Buffer size for reading end encoding data.
.IP "keep_root [ = 0 ] \fI# xml2hash\fR" 4
.IX Item "keep_root [ = 0 ] # xml2hash"
Keep root element.
.IP "filter [ = undef ] \fI# xml2hash\fR" 4
.IX Item "filter [ = undef ] # xml2hash"
Filter nodes matched by pattern and return reference to array of nodes.
.Sp
Sample:
.Sp
.Vb 7
\&    my $xml = <<\*(AqXML\*(Aq;
\&        <root>
\&           <item1>111</item1>
\&           <item2>222</item2>
\&           <item3>333</item3>
\&        </root>
\&    XML
\&
\&    my $nodes = xml2hash($xml, filter => \*(Aq/root/item1\*(Aq);
\&    # $nodes = [ 111 ]
\&
\&    my $nodes = xml2hash($xml, filter => [\*(Aq/root/item1\*(Aq, \*(Aq/root/item2\*(Aq]);
\&    # $nodes = [ 111, 222 ]
\&
\&    my $nodes = xml2hash($xml, filter => qr[/root/item\ed$]);
\&    # $nodes = [ 111, 222, 333 ]
.Ve
.Sp
It may be used to parse large XML because does not require a lot of memory.
.IP "cb [ = undef ] \fI# xml2hash\fR" 4
.IX Item "cb [ = undef ] # xml2hash"
This option is used in conjunction with "filter" option and defines callback
that will called for each matched node.
.Sp
Sample:
.Sp
.Vb 6
\&    xml2hash($xml, filter => qr[/root/item\ed$], cb => sub {
\&        print $_[0], "\en";
\&    });
\&    # 111
\&    # 222
\&    # 333
.Ve
.IP "method [ = 'NATIVE' ] \fI# hash2xml\fR" 4
.IX Item "method [ = 'NATIVE' ] # hash2xml"
experimental support the conversion methods other libraries
.Sp
if method is 'LX' then conversion result is the same as using XML::Hash::LX library
.Sp
Note: for 'LX' method following additional options are available:
    attr
    cdata
    text
    comm
.SH "OBJECT SERIALISATION(hash2xml)"
.IX Header "OBJECT SERIALISATION(hash2xml)"
.IP "1. When object has a ""toString"" method" 2
.IX 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.
.Sp
Example:
.Sp
.Vb 8
\&    use XML::LibXML;
\&    local $XML::LibXML::skipXMLDeclaration = 1;
\&    my $doc = XML::LibXML\->new\->parse_string(\*(Aq<foo bar="1"/>\*(Aq);
\&    print hash2xml({ doc => $doc }, indent => 2, xml_decl => 0);
\&    =>
\&    <root>
\&      <doc><foo bar="1"/></doc>
\&    </root>
.Ve
.IP "2. When object has overloaded stringification" 2
.IX Item "2. When object has overloaded stringification"
In this case, the stringification method of object is invoked and result is directly encoded into XML.
.Sp
Example:
.Sp
.Vb 10
\&    package Test {
\&        use overload \*(Aq""\*(Aq => sub { shift\->stringify }, fallback => 1;
\&        sub new {
\&            my ($class, $str) = @_;
\&            bless { str => $str }, $class;
\&        }
\&        sub stringify {
\&            shift\->{str}
\&        }
\&    }
\&    my $obj = Test\->new(\*(Aqtest string\*(Aq);
\&    print hash2xml({ obj => $obj }, indent => 2, xml_decl => 0);
\&    =>
\&    <root>
\&      <obj>test string</obj>
\&    </root>
.Ve
.IP "3. When object has a ""iternext"" method (""NATIVE"" method only)" 2
.IX 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.
.Sp
Example:
.Sp
.Vb 10
\&    my $count = 0;
\&    my $o = bless {}, \*(AqIterator\*(Aq;
\&    *Iterator::iternext = sub { $count++ < 3 ? { count => $count } : undef };
\&    print hash2xml({ item => $o }, use_attr => 1, indent => 2, xml_decl => 0);
\&    =>
\&    <root>
\&      <item count="1"/>
\&      <item count="2"/>
\&      <item count="3"/>
\&    </root>
.Ve
.Sp
This can be used to generate a large XML using minimum memory, example with DBI:
.Sp
.Vb 12
\&    my $sth = $dbh\->prepare(\*(AqSELECT * FROM foo WHERE bar=?\*(Aq);
\&    $sth\->execute(...);
\&    my $o = bless {}, \*(AqIterator\*(Aq;
\&    *Iterator::iternext = sub { $sth\->fetchrow_hashref() };
\&    open(my $fh, \*(Aq>\*(Aq, \*(Aqdata.xml\*(Aq);
\&    hash2xml({ row => $o }, use_attr => 1, indent => 2, xml_decl => 0, output => $fh);
\&    =>
\&    <root>
\&      <row bar="..." ... />
\&      <row bar="..." ... />
\&      ...
\&    </root>
.Ve
.SH BENCHMARK
.IX Header "BENCHMARK"
Performance benchmark in comparison with some popular modules(hash2xml):
.PP
.Vb 5
\&                    Rate     XML::Hash XML::Hash::LX   XML::Simple XML::Hash::XS
\&    XML::Hash     65.0/s            \-\-           \-6%          \-37%          \-99%
\&    XML::Hash::LX 68.8/s            6%            \-\-          \-33%          \-99%
\&    XML::Simple    103/s           58%           49%            \-\-          \-98%
\&    XML::Hash::XS 4879/s         7404%         6988%         4658%            \-\-
.Ve
.PP
Benchmark was done on <http://search.cpan.org/uploads.rdf>
.SH AUTHOR
.IX Header "AUTHOR"
Yuriy Ustushenko, <yoreek@yahoo.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2012\-2021 Yuriy Ustushenko
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.