| 1 |
NAME |
| 2 |
XML::LibXML::LazyBuilder - easy and lazy way to create XML documents for |
| 3 |
XML::LibXML |
| 4 |
|
| 5 |
SYNOPSIS |
| 6 |
use XML::LibXML::LazyBuilder; |
| 7 |
|
| 8 |
{ |
| 9 |
package XML::LibXML::LazyBuilder; |
| 10 |
$d = DOM (E A => {at1 => "val1", at2 => "val2"}, |
| 11 |
((E B => {}, ((E "C"), |
| 12 |
(E D => {}, "Content of D"))), |
| 13 |
(E E => {}, ((E F => {}, "Content of F"), |
| 14 |
(E "G"))))); |
| 15 |
} |
| 16 |
|
| 17 |
DESCRIPTION |
| 18 |
This module significantly abridges the overhead of working with |
| 19 |
XML::LibXML by enabling developers to write concise, nested structures |
| 20 |
that evaluate into XML::LibXML objects. |
| 21 |
|
| 22 |
FUNCTIONS |
| 23 |
DOM |
| 24 |
my $doc = DOM (E $name => \%attr, @children), $var, $enc; |
| 25 |
|
| 26 |
# With defaults, this is shorthand for: |
| 27 |
|
| 28 |
my $doc = E($name => \%attr, |
| 29 |
@children)->(XML::LibXML::Document->new); |
| 30 |
|
| 31 |
Generates a "XML::LibXML::Document" object. The first argument is a |
| 32 |
"CODE" reference created by "E". $var represents the version in the XML |
| 33 |
declaration, and $enc is the character encoding, which default to 1.0 |
| 34 |
and "utf-8", respectively. |
| 35 |
|
| 36 |
E |
| 37 |
my $sub = E tagname => \%attr, @children; |
| 38 |
|
| 39 |
my $doc = DOM $sub; |
| 40 |
|
| 41 |
This function returns a "CODE" reference which itself evaluates to an |
| 42 |
XML::LibXML::Element object. The function returned from "E" expects an |
| 43 |
XML::LibXML::Document object as its only argument, which is conveniently |
| 44 |
provided by "DOM". |
| 45 |
|
| 46 |
Using "E" with an existing XML document |
| 47 |
"E" can also be used to compose the subtree of an existing XML element. |
| 48 |
Instead of supplying a name as the first argument of "E", supply an |
| 49 |
XML::LibXML::Element object. Note, however, that any attributes present |
| 50 |
in that object will be overwritten by "\%attr", and the supplied element |
| 51 |
*must* be bound to a document, or the function will croak. This is to |
| 52 |
ensure that the subtree is connected to the element's document and not |
| 53 |
some other document. |
| 54 |
|
| 55 |
As such, any XML::LibXML::Document object passed into the function |
| 56 |
returned by "E" will be ignored in favour of the document connected to |
| 57 |
the supplied element. This also means that "E($elem => \%attr, |
| 58 |
@children)->($ignored_dom);" can be called in void context, because it |
| 59 |
will just return $elem. |
| 60 |
|
| 61 |
# parse an existing XML document |
| 62 |
my $doc = XML::LibXML->load_xml(location => 'my.xml'); |
| 63 |
|
| 64 |
# find an element of interest |
| 65 |
my ($existing) = $doc->findnodes('//some-element[1]'); |
| 66 |
|
| 67 |
# prepare the subtree |
| 68 |
my $sub = E $existing => \%attr, @children; |
| 69 |
|
| 70 |
# this will overwrite the attributes of $existing and append |
| 71 |
# @children to it; normally the document is passed as an argument |
| 72 |
# but in this case it would be derived from $existing. |
| 73 |
|
| 74 |
$sub->(); |
| 75 |
|
| 76 |
# we also don't care about the output of this function, since it |
| 77 |
# will have modified $doc, which we already have access to. |
| 78 |
|
| 79 |
Note as well that members of @children can be XML::LibXML::Node objects. |
| 80 |
|
| 81 |
Namespaces |
| 82 |
Qualified element names and namespace declaration attributes will behave |
| 83 |
largely as expected. This means that: |
| 84 |
|
| 85 |
E 'foo:bar' => { 'xmlns:foo' => 'urn:x-foo:' }; # ... |
| 86 |
|
| 87 |
...will properly induct the generated element into the "foo" namespace. |
| 88 |
E attempts to infer the namespace mapping from the document, so child |
| 89 |
elements with qualified names will inherit the mapping from their |
| 90 |
ancestors. |
| 91 |
|
| 92 |
CAVEAT: When "E" is executed in the context of an *element name* |
| 93 |
rather than with an existing XML::LibXML::Element, the namespace |
| 94 |
mappings are scanned from the context of the document root, in |
| 95 |
document order. This means that the last namespace declaration that |
| 96 |
appears in the existing document (depth-first) will occupy the given |
| 97 |
prefix. When an existing element is passed into "E", the namespace |
| 98 |
search begins there and ascends to the root. If you have any |
| 99 |
concerns about collisions of namespace declarations, use that form |
| 100 |
instead. |
| 101 |
|
| 102 |
P |
| 103 |
my $sub = P target => { key => 'value' }, @othertext; |
| 104 |
|
| 105 |
This function returns a "CODE" reference which returns a processing |
| 106 |
instruction. If you pass in a HASH reference as the first argument, it |
| 107 |
will be turned into key-value pairs using double-quotes on the values. |
| 108 |
This means you have to take care of your own escaping of any double |
| 109 |
quotes that may be in the values. The rest of the arguments are |
| 110 |
concatenated into a string (intended to behave like "print" in perlfunc, |
| 111 |
which means if you want spaces between them, you likewise need to add |
| 112 |
them yourself). |
| 113 |
|
| 114 |
C |
| 115 |
my $sub = C @text; |
| 116 |
|
| 117 |
This function creates a "CODE" reference which returns a comment. Again, |
| 118 |
@text is simply concatenated, so if you wish to do any additional |
| 119 |
formatting, do so before passing it in. |
| 120 |
|
| 121 |
D |
| 122 |
my $sub = D @text; |
| 123 |
|
| 124 |
This function creates a "CODE" reference which returns a CDATA section. |
| 125 |
Works identically to "C". |
| 126 |
|
| 127 |
F |
| 128 |
my $sub = F @children; |
| 129 |
|
| 130 |
This function creates a "CODE" reference which returns a document |
| 131 |
fragment. Since "DOM" can only accept a single node-generating function, |
| 132 |
it is particularly useful for the following idiom: |
| 133 |
|
| 134 |
my $doc = DOM F( |
| 135 |
(P 'xml-stylesheet' => { type => 'text/xsl', href => '/foo.xsl' }), |
| 136 |
(E mydoc => {}, @children)); |
| 137 |
|
| 138 |
Which produces: |
| 139 |
|
| 140 |
<?xml version="1.0" encoding="utf-8"?> |
| 141 |
<?xml-stylesheet type="text/xsl" href="/foo.xsl"?> |
| 142 |
<mydoc>...</mydoc> |
| 143 |
|
| 144 |
DTD |
| 145 |
my $sub = DTD $name => $public, $system; |
| 146 |
|
| 147 |
This function creates a "CODE" reference which returns a DTD |
| 148 |
declaration. Both $public and $system can be "undef". |
| 149 |
|
| 150 |
EXPORT |
| 151 |
None by default. |
| 152 |
|
| 153 |
:all |
| 154 |
Exports "E", "P", "C", "D", "F" and "DOM". |
| 155 |
|
| 156 |
EXAMPLES |
| 157 |
If you nest your code in braces and use a "package" declaration like so, |
| 158 |
you can avoid polluting the calling package's namespace: |
| 159 |
|
| 160 |
my $d; |
| 161 |
{ |
| 162 |
package XML::LibXML::LazyBuilder; |
| 163 |
$d = DOM (E A => {at1 => "val1", at2 => "val2"}, |
| 164 |
((E B => {}, ((E "C"), |
| 165 |
(E D => {}, "Content of D"))), |
| 166 |
(E E => {}, ((E F => {}, "Content of F"), |
| 167 |
(E "G"))))); |
| 168 |
} |
| 169 |
|
| 170 |
Then, "$d->toString" will generate XML like this: |
| 171 |
|
| 172 |
<?xml version="1.0" encoding="utf-8"?> |
| 173 |
<A at1="val1" at2="val2"><B><C/><D>Content of D</D></B><E><F>Content of F</F><G/></E></A> |
| 174 |
|
| 175 |
SEE ALSO |
| 176 |
XML::LibXML |
| 177 |
|
| 178 |
The Python module lxml.etree <http://lxml.de/tutorial.html> |
| 179 |
|
| 180 |
AUTHOR |
| 181 |
Toru Hisai <mailto:[email protected]> |
| 182 |
|
| 183 |
Namespace and non-element support by Dorian Taylor |
| 184 |
<mailto:[email protected]> |
| 185 |
|
| 186 |
COPYRIGHT AND LICENSE |
| 187 |
Copyright (C) 2008, 2012 by Toru Hisai |
| 188 |
|
| 189 |
This library is free software; you can redistribute it and/or modify it |
| 190 |
under the same terms as Perl itself, either Perl version 5.10.0 or, at |
| 191 |
your option, any later version of Perl 5 you may have available. |
| 192 |
|