1Writer(3) User Contributed Perl Documentation Writer(3)
2
6 XML::Writer - Perl extension for writing XML documents.
7
9 use XML::Writer;
10 use IO::File;
11 my $output = new IO::File(">output.xml");
13 my $writer = new XML::Writer(OUTPUT => $output);
15 $writer->startTag("greeting",
16 "class" => "simple");
17 $writer->characters("Hello, world!");
18 $writer->endTag("greeting");
19 $writer->end();
20 $output->close();
21
23 XML::Writer is a helper module for Perl programs that write an XML doc‐
24 ument. The module handles all escaping for attribute values and char‐
25 acter data and constructs different types of markup, such as tags, com‐
26 ments, and processing instructions.
27 By default, the module performs several well-formedness checks to catch
29 errors during output. This behaviour can be extremely useful during
30 development and debugging, but it can be turned off for production-
31 grade code.
32 The module can operate either in regular mode in or Namespace process‐
34 ing mode. In Namespace mode, the module will generate Namespace Decla‐
35 rations itself, and will perform additional checks on the output.
36 Additional support is available for a simplified data mode with no
38 mixed content: newlines are automatically inserted around elements and
39 elements can optionally be indented based as their nesting level.
40
42 Writing XML
43 new([$params])
45 Create a new XML::Writer object:
46 my $writer = new XML::Writer(OUTPUT => $output, NEWLINES => 1);
48 Arguments are an anonymous hash array of parameters:
50 OUTPUT
52 An object blessed into IO::Handle or one of its subclasses
53 (such as IO::File), or a reference to a string; if this parame‐
54 ter is not present, the module will write to standard output.
55 If a string reference is passed, it will capture the generated
56 XML (as a string; to get bytes use the "Encode" module).
57 NAMESPACES
59 A true (1) or false (0, undef) value; if this parameter is
60 present and its value is true, then the module will accept two-
61 member array reference in the place of element and attribute
62 names, as in the following example:
63 my $rdfns = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
65 my $writer = new XML::Writer(NAMESPACES => 1);
66 $writer->startTag([$rdfns, "Description"]);
67 The first member of the array is a namespace URI, and the sec‐
69 ond part is the local part of a qualified name. The module
70 will automatically generate appropriate namespace declarations
71 and will replace the URI part with a prefix.
72 PREFIX_MAP
74 A hash reference; if this parameter is present and the module
75 is performing namespace processing (see the NAMESPACES parame‐
76 ter), then the module will use this hash to look up preferred
77 prefixes for namespace URIs:
78 my $rdfns = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
80 my $writer = new XML::Writer(NAMESPACES => 1,
81 PREFIX_MAP => {$rdfns => 'rdf'});
82 The keys in the hash table are namespace URIs, and the values
84 are the associated prefixes. If there is not a preferred pre‐
85 fix for the namespace URI in this hash, then the module will
86 automatically generate prefixes of the form "__NS1", "__NS2",
87 etc.
88 To set the default namespace, use '' for the prefix.
90 FORCED_NS_DECLS
92 An array reference; if this parameter is present, the document
93 element will contain declarations for all the given namespace
94 URIs. Declaring namespaces in advance is particularly useful
95 when a large number of elements from a namespace are siblings,
96 but don't share a direct ancestor from the same namespace.
97 NEWLINES
99 A true or false value; if this parameter is present and its
100 value is true, then the module will insert an extra newline
101 before the closing delimiter of start, end, and empty tags to
102 guarantee that the document does not end up as a single, long
103 line. If the parameter is not present, the module will not
104 insert the newlines.
105 UNSAFE
107 A true or false value; if this parameter is present and its
108 value is true, then the module will skip most well-formedness
109 error checking. If the parameter is not present, the module
110 will perform the well-formedness error checking by default.
111 Turn off error checking at your own risk!
112 DATA_MODE
114 A true or false value; if this parameter is present and its
115 value is true, then the module will enter a special data mode,
116 inserting newlines automatically around elements and (unless
117 UNSAFE is also specified) reporting an error if any element has
118 both characters and elements as content.
119 DATA_INDENT
121 A numeric value; if this parameter is present, it represents
122 the indent step for elements in data mode (it will be ignored
123 when not in data mode).
124 ENCODING
126 A character encoding; currently this must be one of 'utf-8' or
127 'us-ascii'. If present, it will be used for the underlying
128 character encoding and as the default in the XML declaration.
129 end()
131 Finish creating an XML document. This method will check that the
132 document has exactly one document element, and that all start tags
133 are closed:
134 $writer->end();
136 xmlDecl([$encoding, $standalone])
138 Add an XML declaration to the beginning of an XML document. The
139 version will always be "1.0". If you provide a non-null encoding
140 or standalone argument, its value will appear in the declaration
141 (any non-null value for standalone except 'no' will automatically
142 be converted to 'yes'). If not given here, the encoding will be
143 taken from the ENCODING argument. Pass the empty string to suppress
144 this behaviour.
145 $writer->xmlDecl("UTF-8");
147 doctype($name, [$publicId, $systemId])
149 Add a DOCTYPE declaration to an XML document. The declaration must
150 appear before the beginning of the root element. If you provide a
151 publicId, you must provide a systemId as well, but you may provide
152 just a system ID by passing 'undef' for the publicId.
153 $writer->doctype("html");
155 comment($text)
157 Add a comment to an XML document. If the comment appears outside
158 the document element (either before the first start tag or after
159 the last end tag), the module will add a carriage return after it
160 to improve readability. In data mode, comments will be treated as
161 empty tags:
162 $writer->comment("This is a comment");
164 pi($target [, $data])
166 Add a processing instruction to an XML document:
167 $writer->pi('xml-stylesheet', 'href="style.css" type="text/css"');
169 If the processing instruction appears outside the document element
171 (either before the first start tag or after the last end tag), the
172 module will add a carriage return after it to improve readability.
173 The $target argument must be a single XML name. If you provide the
175 $data argument, the module will insert its contents following the
176 $target argument, separated by a single space.
177 startTag($name [, $aname1 => $value1, ...])
179 Add a start tag to an XML document. Any arguments after the ele‐
180 ment name are assumed to be name/value pairs for attributes: the
181 module will escape all '&', '<', '>', and '"' characters in the
182 attribute values using the predefined XML entities:
183 $writer->startTag('doc', 'version' => '1.0',
185 'status' => 'draft',
186 'topic' => 'AT&T');
187 All start tags must eventually have matching end tags.
189 emptyTag($name [, $aname1 => $value1, ...])
191 Add an empty tag to an XML document. Any arguments after the ele‐
192 ment name are assumed to be name/value pairs for attributes (see
193 startTag() for details):
194 $writer->emptyTag('img', 'src' => 'portrait.jpg',
196 'alt' => 'Portrait of Emma.');
197 endTag([$name])
199 Add an end tag to an XML document. The end tag must match the
200 closest open start tag, and there must be a matching and properly-
201 nested end tag for every start tag:
202 $writer->endTag('doc');
204 If the $name argument is omitted, then the module will automati‐
206 cally supply the name of the currently open element:
207 $writer->startTag('p');
209 $writer->endTag();
210 dataElement($name, $data [, $aname1 => $value1, ...])
212 Print an entire element containing only character data. This is
213 equivalent to
214 $writer->startTag($name [, $aname1 => $value1, ...]);
216 $writer->characters($data);
217 $writer->endTag($name);
218 characters($data)
220 Add character data to an XML document. All '<', '>', and '&' char‐
221 acters in the $data argument will automatically be escaped using
222 the predefined XML entities:
223 $writer->characters("Here is the formula: ");
225 $writer->characters("a < 100 && a > 5");
226 You may invoke this method only within the document element (i.e.
228 after the first start tag and before the last end tag).
229 In data mode, you must not use this method to add whitespace
231 between elements.
232 raw($data)
234 Print data completely unquoted and unchecked to the XML document.
235 For example "raw('<')" will print a literal < character. This nec‐
236 essarily bypasses all well-formedness checking, and is therefore
237 only available in unsafe mode.
238 This can sometimes be useful for printing entities which are
240 defined for your XML format but the module doesn't know about, for
241 example for XHTML.
242 cdata($data)
244 As "characters()" but writes the data quoted in a CDATA section,
245 that is, between <![CDATA[ and ]]>. If the data to be written
246 itself contains ]]>, it will be written as several consecutive
247 CDATA sections.
248 cdataElement($name, $data [, $aname1 => $value1, ...])
250 As "dataElement()" but the element content is written as one or
251 more CDATA sections (see "cdata()").
252 setOutput($output)
254 Set the current output destination, as in the OUTPUT parameter for
255 the constructor.
256 getOutput()
258 Return the current output destination, as in the OUTPUT parameter
259 for the constructor.
260 setDataMode($mode)
262 Enable or disable data mode, as in the DATA_MODE parameter for the
263 constructor.
264 getDataMode()
266 Return the current data mode, as in the DATA_MODE parameter for the
267 constructor.
268 setDataIndent($step)
270 Set the indent step for data mode, as in the DATA_INDENT parameter
271 for the constructor.
272 getDataIndent()
274 Return the indent step for data mode, as in the DATA_INDENT parame‐
275 ter for the constructor.
276 Querying XML
278 in_element($name)
280 Return a true value if the most recent open element matches $name:
281 if ($writer->in_element('dl')) {
283 $writer->startTag('dt');
284 } else {
285 $writer->startTag('li');
286 }
287 within_element($name)
289 Return a true value if any open element matches $name:
290 if ($writer->within_element('body')) {
292 $writer->startTag('h1');
293 } else {
294 $writer->startTag('title');
295 }
296 current_element()
298 Return the name of the currently open element:
299 my $name = $writer->current_element();
301 This is the equivalent of
303 my $name = $writer->ancestor(0);
305 ancestor($n)
307 Return the name of the nth ancestor, where $n=0 for the current
308 open element.
309 Additional Namespace Support
311 As of 0.510, these methods may be used while writing a document.
313 addPrefix($uri, $prefix)
315 Add a preferred mapping between a Namespace URI and a prefix. See
316 also the PREFIX_MAP constructor parameter.
317 To set the default namespace, omit the $prefix parameter or set it
319 to ''.
320 removePrefix($uri)
322 Remove a preferred mapping between a Namespace URI and a prefix.
323 forceNSDecl($uri)
325 Indicate that a namespace declaration for this URI should be
326 included with the next element to be started.
327
329 With the default settings, the XML::Writer module can detect several
330 basic XML well-formedness errors:
331 · Lack of a (top-level) document element, or multiple document ele‐
333 ments.
334 · Unclosed start tags.
336 · Misplaced delimiters in the contents of processing instructions or
338 comments.
339 · Misplaced or duplicate XML declaration(s).
341 · Misplaced or duplicate DOCTYPE declaration(s).
343 · Mismatch between the document type name in the DOCTYPE declaration
345 and the name of the document element.
346 · Mismatched start and end tags.
348 · Attempts to insert character data outside the document element.
350 · Duplicate attributes with the same name.
352 During Namespace processing, the module can detect the following addi‐
354 tional errors:
355 · Attempts to use PI targets or element or attribute names containing
357 a colon.
358 · Attempts to use attributes with names beginning "xmlns".
360 To ensure full error detection, a program must also invoke the end
362 method when it has finished writing a document:
363 $writer->startTag('greeting');
365 $writer->characters("Hello, world!");
366 $writer->endTag('greeting');
367 $writer->end();
368 This error reporting can catch many hidden bugs in Perl programs that
370 create XML documents; however, if necessary, it can be turned off by
371 providing an UNSAFE parameter:
372 my $writer = new XML::Writer(OUTPUT => $output, UNSAFE => 1);
374
376 David Megginson <david@megginson.com>
377
379 Copyright 1999, 2000 David Megginson <david@megginson.com>
380 Copyright 2004, 2005 Joseph Walton <joe@kafsemo.org>
382
384 XML::Parser
385perl v5.8.8 2008-02-20 Writer(3)