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
24 document. The module handles all escaping for attribute values and
25 character data and constructs different types of markup, such as tags,
26 comments, 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
34 processing mode. In Namespace mode, the module will generate Namespace
35 Declarations 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])
44 Create a new XML::Writer object:
45 my $writer = new XML::Writer(OUTPUT => $output, NEWLINES => 1);
47 Arguments are an anonymous hash array of parameters:
49 OUTPUT
51 An object blessed into IO::Handle or one of its subclasses
52 (such as IO::File), or a reference to a string; if this
53 parameter is not present, the module will write to standard
54 output. If a string reference is passed, it will capture the
55 generated XML (as a string; to get bytes use the "Encode"
56 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
69 second 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
76 parameter), then the module will use this hash to look up
77 preferred 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
85 prefix 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
180 element 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
192 element 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
206 automatically 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 '&'
221 characters in the $data argument will automatically be escaped
222 using 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
236 necessarily 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
275 parameter for the constructor.
276 Querying XML
278 in_element($name)
279 Return a true value if the most recent open element matches $name:
280 if ($writer->in_element('dl')) {
282 $writer->startTag('dt');
283 } else {
284 $writer->startTag('li');
285 }
286 within_element($name)
288 Return a true value if any open element matches $name:
289 if ($writer->within_element('body')) {
291 $writer->startTag('h1');
292 } else {
293 $writer->startTag('title');
294 }
295 current_element()
297 Return the name of the currently open element:
298 my $name = $writer->current_element();
300 This is the equivalent of
302 my $name = $writer->ancestor(0);
304 ancestor($n)
306 Return the name of the nth ancestor, where $n=0 for the current
307 open element.
308 Additional Namespace Support
310 As of 0.510, these methods may be used while writing a document.
311 addPrefix($uri, $prefix)
313 Add a preferred mapping between a Namespace URI and a prefix. See
314 also the PREFIX_MAP constructor parameter.
315 To set the default namespace, omit the $prefix parameter or set it
317 to ''.
318 removePrefix($uri)
320 Remove a preferred mapping between a Namespace URI and a prefix.
321 forceNSDecl($uri)
323 Indicate that a namespace declaration for this URI should be
324 included with the next element to be started.
325
327 With the default settings, the XML::Writer module can detect several
328 basic XML well-formedness errors:
329 · Lack of a (top-level) document element, or multiple document
331 elements.
332 · Unclosed start tags.
334 · Misplaced delimiters in the contents of processing instructions or
336 comments.
337 · Misplaced or duplicate XML declaration(s).
339 · Misplaced or duplicate DOCTYPE declaration(s).
341 · Mismatch between the document type name in the DOCTYPE declaration
343 and the name of the document element.
344 · Mismatched start and end tags.
346 · Attempts to insert character data outside the document element.
348 · Duplicate attributes with the same name.
350 During Namespace processing, the module can detect the following
352 additional errors:
353 · Attempts to use PI targets or element or attribute names containing
355 a colon.
356 · Attempts to use attributes with names beginning "xmlns".
358 To ensure full error detection, a program must also invoke the end
360 method when it has finished writing a document:
361 $writer->startTag('greeting');
363 $writer->characters("Hello, world!");
364 $writer->endTag('greeting');
365 $writer->end();
366 This error reporting can catch many hidden bugs in Perl programs that
368 create XML documents; however, if necessary, it can be turned off by
369 providing an UNSAFE parameter:
370 my $writer = new XML::Writer(OUTPUT => $output, UNSAFE => 1);
372
374 David Megginson <david@megginson.com>
375
377 Copyright 1999, 2000 David Megginson <david@megginson.com>
378 Copyright 2004, 2005 Joseph Walton <joe@kafsemo.org>
380 This module is free software; you can redistribute it and/or modify it
382 under the terms of the MIT License. See the LICENSE file included with
383 this distribution.
384
386 XML::Parser
387perl v5.12.0 2008-12-03 Writer(3)