XML::LibXML::LazyBuilder - easy and lazy way to create XML documents for XML::LibXML
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"))))); }
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.
my $doc = DOM (E $name => \%attr, @children), $var, $enc; # With defaults, this is shorthand for: my $doc = E($name => \%attr, @children)->(XML::LibXML::Document->new);
Generates a XML::LibXML::Document object. The first argument is a CODE reference created by E. $var represents the version in the XML declaration, and $enc is the character encoding, which default to 1.0 and utf-8, respectively.
XML::LibXML::Document
CODE
E
$var
$enc
1.0
utf-8
my $sub = E tagname => \%attr, @children; my $doc = DOM $sub;
This function returns a CODE reference which itself evaluates to an XML::LibXML::Element object. The function returned from E expects an XML::LibXML::Document object as its only argument, which is conveniently provided by "DOM".
E can also be used to compose the subtree of an existing XML element. Instead of supplying a name as the first argument of E, supply an XML::LibXML::Element object. Note, however, that any attributes present in that object will be overwritten by \%attr, and the supplied element must 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.
\%attr
As such, any XML::LibXML::Document object passed into the function returned by E will be ignored in favour of the document connected to the supplied element. This also means that E($elem => \%attr, @children)->($ignored_dom); can be called in void context, because it will just return $elem.
E($elem => \%attr, @children)->($ignored_dom);
$elem
# parse an existing XML document my $doc = XML::LibXML->load_xml(location => 'my.xml'); # find an element of interest my ($existing) = $doc->findnodes('//some-element[1]'); # prepare the subtree my $sub = E $existing => \%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't care about the output of this function, since it # will have modified $doc, which we already have access to.
Note as well that members of @children can be XML::LibXML::Node objects.
@children
Qualified element names and namespace declaration attributes will behave largely as expected. This means that:
E 'foo:bar' => { 'xmlns:foo' => 'urn:x-foo:' }; # ...
...will properly induct the generated element into the foo namespace. E attempts to infer the namespace mapping from the document, so child elements with qualified names will inherit the mapping from their ancestors.
foo
CAVEAT: When E is executed in the context of an element name 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 E, the namespace search begins there and ascends to the root. If you have any concerns about collisions of namespace declarations, use that form instead.
my $sub = P target => { key => 'value' }, @othertext;
This function returns a CODE reference which returns a processing instruction. If you pass in a HASH 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 "print" in perlfunc, which means if you want spaces between them, you likewise need to add them yourself).
my $sub = C @text;
This function creates a CODE reference which returns a comment. Again, @text is simply concatenated, so if you wish to do any additional formatting, do so before passing it in.
@text
my $sub = D @text;
This function creates a CODE reference which returns a CDATA section. Works identically to "C".
my $sub = F @children;
This function creates a CODE reference which returns a document fragment. Since "DOM" can only accept a single node-generating function, it is particularly useful for the following idiom:
my $doc = DOM F( (P 'xml-stylesheet' => { type => 'text/xsl', href => '/foo.xsl' }), (E mydoc => {}, @children));
Which produces:
<?xml version="1.0" encoding="utf-8"?> <?xml-stylesheet type="text/xsl" href="/foo.xsl"?> <mydoc>...</mydoc>
my $sub = DTD $name => $public, $system;
This function creates a CODE reference which returns a DTD declaration. Both $public and $system can be undef.
$public
$system
undef
None by default.
Exports "E", "P", "C", "D", "F" and "DOM".
If you nest your code in braces and use a package declaration like so, you can avoid polluting the calling package's namespace:
package
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"))))); }
Then, $d->toString will generate XML like this:
$d->toString
<?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>
XML::LibXML
The Python module lxml.etree
Toru Hisai
Namespace and non-element support by Dorian Taylor
Copyright (C) 2008, 2012 by Toru Hisai
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.
To install XML::LibXML::LazyBuilder, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XML::LibXML::LazyBuilder
CPAN shell
perl -MCPAN -e shell install XML::LibXML::LazyBuilder
For more information on module installation, please visit the detailed CPAN module installation guide.