Debian Codegraph @

README

raw
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