.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XML::LibXML::LazyBuilder 3pm"
.TH XML::LibXML::LazyBuilder 3pm "2012-11-25" "perl v5.14.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::LibXML::LazyBuilder \- easy and lazy way to create XML documents
for XML::LibXML
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use XML::LibXML::LazyBuilder;
\&
\&  {
\&      package XML::LibXML::LazyBuilder;
\&      $d = DOM (E A => {at1 => "val1", at2 => "val2"},
\&                ((E B => {}, ((E "C"),
\&                              (E D => {}, "Content of D"))),
\&                 (E E => {}, ((E F => {}, "Content of F"),
\&                              (E "G")))));
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module significantly abridges the overhead of working with
XML::LibXML by enabling developers to write concise, nested
structures that evaluate into XML::LibXML objects.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "\s-1DOM\s0"
.IX Subsection "DOM"
.Vb 1
\&    my $doc = DOM (E $name => \e%attr, @children), $var, $enc;
\&
\&    # With defaults, this is shorthand for:
\&
\&    my $doc = E($name => \e%attr,
\&                @children)\->(XML::LibXML::Document\->new);
.Ve
.PP
Generates a \f(CW\*(C`XML::LibXML::Document\*(C'\fR object. The first argument is a
\&\f(CW\*(C`CODE\*(C'\fR reference created by \f(CW\*(C`E\*(C'\fR. \f(CW$var\fR represents the version in
the \s-1XML\s0 declaration, and \f(CW$enc\fR is the character encoding, which
default to \f(CW1.0\fR and \f(CW\*(C`utf\-8\*(C'\fR, respectively.
.SS "E"
.IX Subsection "E"
.Vb 1
\&    my $sub = E tagname => \e%attr, @children;
\&
\&    my $doc = DOM $sub;
.Ve
.PP
This function returns a \f(CW\*(C`CODE\*(C'\fR reference which itself evaluates to an
XML::LibXML::Element object. The function returned from \f(CW\*(C`E\*(C'\fR
expects an XML::LibXML::Document object as its only argument, which
is conveniently provided by \*(L"\s-1DOM\s0\*(R".
.PP
\fIUsing \f(CI\*(C`E\*(C'\fI with an existing \s-1XML\s0 document\fR
.IX Subsection "Using E with an existing XML document"
.PP
\&\f(CW\*(C`E\*(C'\fR can also be used to compose the subtree of an existing \s-1XML\s0
element. Instead of supplying a name as the first argument of \f(CW\*(C`E\*(C'\fR,
supply an XML::LibXML::Element object. Note, however, that any
attributes present in that object will be overwritten by \f(CW\*(C`\e%attr\*(C'\fR,
and the supplied element \fImust\fR be bound to a document, or the
function will croak. This is to ensure that the subtree is connected
to the element's document and not some other document.
.PP
As such, any XML::LibXML::Document object passed into the function
returned by \f(CW\*(C`E\*(C'\fR will be ignored in favour of the document connected
to the supplied element. This also means that \f(CW\*(C`E($elem => \e%attr,
@children)\->($ignored_dom);\*(C'\fR can be called in void context, because
it will just return \f(CW$elem\fR.
.PP
.Vb 2
\&    # parse an existing XML document
\&    my $doc = XML::LibXML\->load_xml(location => \*(Aqmy.xml\*(Aq);
\&
\&    # find an element of interest
\&    my ($existing) = $doc\->findnodes(\*(Aq//some\-element[1]\*(Aq);
\&
\&    # prepare the subtree
\&    my $sub = E $existing => \e%attr, @children;
\&
\&    # this will overwrite the attributes of $existing and append
\&    # @children to it; normally the document is passed as an argument
\&    # but in this case it would be derived from $existing.
\&
\&    $sub\->();
\&
\&    # we also don\*(Aqt care about the output of this function, since it
\&    # will have modified $doc, which we already have access to.
.Ve
.PP
Note as well that members of \f(CW@children\fR can be XML::LibXML::Node
objects.
.PP
\fINamespaces\fR
.IX Subsection "Namespaces"
.PP
Qualified element names and namespace declaration attributes will
behave largely as expected. This means that:
.PP
.Vb 1
\&    E \*(Aqfoo:bar\*(Aq => { \*(Aqxmlns:foo\*(Aq => \*(Aqurn:x\-foo:\*(Aq }; # ...
.Ve
.PP
\&...will properly induct the generated element into the \f(CW\*(C`foo\*(C'\fR
namespace. E attempts to infer the namespace mapping from the
document, so child elements with qualified names will inherit the
mapping from their ancestors.
.Sp
.RS 4
\&\fB\s-1CAVEAT:\s0\fR When \f(CW\*(C`E\*(C'\fR is executed in the context of an \fIelement name\fR
rather than with an existing XML::LibXML::Element, the namespace
mappings are scanned from the context of the document root, in
document order. This means that the last namespace declaration that
appears in the existing document (depth-first) will occupy the given
prefix. When an existing element is passed into \f(CW\*(C`E\*(C'\fR, the namespace
search begins there and ascends to the root. If you have any concerns
about collisions of namespace declarations, use that form instead.
.RE
.SS "P"
.IX Subsection "P"
.Vb 1
\&    my $sub = P target => { key => \*(Aqvalue\*(Aq }, @othertext;
.Ve
.PP
This function returns a \f(CW\*(C`CODE\*(C'\fR reference which returns a processing
instruction. If you pass in a \s-1HASH\s0 reference as the first argument, it
will be turned into key-value pairs using double-quotes on the
values. This means you have to take care of your own escaping of any
double quotes that may be in the values. The rest of the arguments are
concatenated into a string (intended to behave like \*(L"print\*(R" in perlfunc,
which means if you want spaces between them, you likewise need to add
them yourself).
.SS "C"
.IX Subsection "C"
.Vb 1
\&    my $sub = C @text;
.Ve
.PP
This function creates a \f(CW\*(C`CODE\*(C'\fR reference which returns a comment.
Again, \f(CW@text\fR is simply concatenated, so if you wish to do any
additional formatting, do so before passing it in.
.SS "D"
.IX Subsection "D"
.Vb 1
\&    my $sub = D @text;
.Ve
.PP
This function creates a \f(CW\*(C`CODE\*(C'\fR reference which returns a \s-1CDATA\s0
section. Works identically to \*(L"C\*(R".
.SS "F"
.IX Subsection "F"
.Vb 1
\&    my $sub = F @children;
.Ve
.PP
This function creates a \f(CW\*(C`CODE\*(C'\fR reference which returns a document
fragment. Since \*(L"\s-1DOM\s0\*(R" can only accept a single node-generating
function, it is particularly useful for the following idiom:
.PP
.Vb 3
\&    my $doc = DOM F(
\&        (P \*(Aqxml\-stylesheet\*(Aq => { type => \*(Aqtext/xsl\*(Aq, href => \*(Aq/foo.xsl\*(Aq }),
\&        (E mydoc => {}, @children));
.Ve
.PP
Which produces:
.PP
.Vb 3
\&    <?xml version="1.0" encoding="utf\-8"?>
\&    <?xml\-stylesheet type="text/xsl" href="/foo.xsl"?>
\&    <mydoc>...</mydoc>
.Ve
.SS "\s-1DTD\s0"
.IX Subsection "DTD"
.Vb 1
\&    my $sub = DTD $name => $public, $system;
.Ve
.PP
This function creates a \f(CW\*(C`CODE\*(C'\fR reference which returns a \s-1DTD\s0
declaration. Both \f(CW$public\fR and \f(CW$system\fR can be \f(CW\*(C`undef\*(C'\fR.
.SH "EXPORT"
.IX Header "EXPORT"
None by default.
.SS ":all"
.IX Subsection ":all"
Exports \*(L"E\*(R", \*(L"P\*(R", \*(L"C\*(R", \*(L"D\*(R", \*(L"F\*(R" and \*(L"\s-1DOM\s0\*(R".
.SH "EXAMPLES"
.IX Header "EXAMPLES"
If you nest your code in braces and use a \f(CW\*(C`package\*(C'\fR declaration like
so, you can avoid polluting the calling package's namespace:
.PP
.Vb 9
\&  my $d;
\&  {
\&      package XML::LibXML::LazyBuilder;
\&      $d = DOM (E A => {at1 => "val1", at2 => "val2"},
\&                ((E B => {}, ((E "C"),
\&                              (E D => {}, "Content of D"))),
\&                 (E E => {}, ((E F => {}, "Content of F"),
\&                              (E "G")))));
\&  }
.Ve
.PP
Then, \f(CW\*(C`$d\->toString\*(C'\fR will generate \s-1XML\s0 like this:
.PP
.Vb 2
\&  <?xml version="1.0" encoding="utf\-8"?>
\&  <A at1="val1" at2="val2"><B><C/><D>Content of D</D></B><E><F>Content of F</F><G/></E></A>
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
XML::LibXML
.PP
The Python module lxml.etree <http://lxml.de/tutorial.html>
.SH "AUTHOR"
.IX Header "AUTHOR"
Toru Hisai <mailto:toru@torus.jp>
.PP
Namespace and non-element support by Dorian Taylor <mailto:dorian@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2008, 2012 by Toru Hisai
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.10.0 or,
at your option, any later version of Perl 5 you may have available.