1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
NAME
XML::LibXML::LazyBuilder - easy and lazy way to create XML documents for
XML::LibXML
SYNOPSIS
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")))));
}
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.
FUNCTIONS
DOM
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.
E
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".
Using "E" with an existing XML document
"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.
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.
# 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.
Namespaces
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.
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.
P
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).
C
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.
D
my $sub = D @text;
This function creates a "CODE" reference which returns a CDATA section.
Works identically to "C".
F
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>
DTD
my $sub = DTD $name => $public, $system;
This function creates a "CODE" reference which returns a DTD
declaration. Both $public and $system can be "undef".
EXPORT
None by default.
:all
Exports "E", "P", "C", "D", "F" and "DOM".
EXAMPLES
If you nest your code in braces and use a "package" declaration like so,
you can avoid polluting the calling package's namespace:
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:
<?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>
SEE ALSO
XML::LibXML
The Python module lxml.etree <http://lxml.de/tutorial.html>
AUTHOR
Toru Hisai <mailto:toru@torus.jp>
Namespace and non-element support by Dorian Taylor
<mailto:dorian@cpan.org>
COPYRIGHT AND LICENSE
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.
|
