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 = IO::File->new(">output.xml");
13 my $writer = XML::Writer->new(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 = XML::Writer->new(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, or any blessed
53 object that has a print() method; if this parameter is not
54 present, the module will write to standard output. If a string
55 reference is passed, it will capture the generated XML (as a
56 string; to get bytes use the "Encode" module).
57 If the string self is passed, the output will be captured
59 internally by the object, and can be accessed via the
60 "to_string()" method, or by calling the object in a string
61 context.
62 my $writer = XML::Writer->new( OUTPUT => 'self' );
64 $writer->dataElement( hello => 'world' );
66 print $writer->to_string; # outputs <hello>world</hello>
68 print "$writer"; # ditto
69 NAMESPACES
71 A true (1) or false (0, undef) value; if this parameter is
72 present and its value is true, then the module will accept two-
73 member array reference in the place of element and attribute
74 names, as in the following example:
75 my $rdfns = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
77 my $writer = XML::Writer->new(NAMESPACES => 1);
78 $writer->startTag([$rdfns, "Description"]);
79 The first member of the array is a namespace URI, and the
81 second part is the local part of a qualified name. The module
82 will automatically generate appropriate namespace declarations
83 and will replace the URI part with a prefix.
84 PREFIX_MAP
86 A hash reference; if this parameter is present and the module
87 is performing namespace processing (see the NAMESPACES
88 parameter), then the module will use this hash to look up
89 preferred prefixes for namespace URIs:
90 my $rdfns = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
92 my $writer = XML::Writer->new(NAMESPACES => 1,
93 PREFIX_MAP => {$rdfns => 'rdf'});
94 The keys in the hash table are namespace URIs, and the values
96 are the associated prefixes. If there is not a preferred
97 prefix for the namespace URI in this hash, then the module will
98 automatically generate prefixes of the form "__NS1", "__NS2",
99 etc.
100 To set the default namespace, use '' for the prefix.
102 FORCED_NS_DECLS
104 An array reference; if this parameter is present, the document
105 element will contain declarations for all the given namespace
106 URIs. Declaring namespaces in advance is particularly useful
107 when a large number of elements from a namespace are siblings,
108 but don't share a direct ancestor from the same namespace.
109 NEWLINES
111 A true or false value; if this parameter is present and its
112 value is true, then the module will insert an extra newline
113 before the closing delimiter of start, end, and empty tags to
114 guarantee that the document does not end up as a single, long
115 line. If the parameter is not present, the module will not
116 insert the newlines.
117 UNSAFE
119 A true or false value; if this parameter is present and its
120 value is true, then the module will skip most well-formedness
121 error checking. If the parameter is not present, the module
122 will perform the well-formedness error checking by default.
123 Turn off error checking at your own risk!
124 DATA_MODE
126 A true or false value; if this parameter is present and its
127 value is true, then the module will enter a special data mode,
128 inserting newlines automatically around elements and (unless
129 UNSAFE is also specified) reporting an error if any element has
130 both characters and elements as content.
131 DATA_INDENT
133 A numeric value or white space; if this parameter is present,
134 it represents the indent step for elements in data mode (it
135 will be ignored when not in data mode). If it is white space it
136 will be repeated for each level of indentation.
137 ENCODING
139 A character encoding to use for the output; currently this must
140 be one of 'utf-8' or 'us-ascii'. If present, it will be used
141 for the underlying character encoding and as the default in the
142 XML declaration. All character data should be passed as
143 Unicode strings when an encoding is set.
144 CHECK_PRINT
146 A true or false value; if this parameter is present and its
147 value is true, all prints to the underlying output will be
148 checked for success. Failures will cause a croak rather than
149 being ignored.
150 end()
152 Finish creating an XML document. This method will check that the
153 document has exactly one document element, and that all start tags
154 are closed:
155 $writer->end();
157 If OUTPUT as been set to self, "end()" will return the generated
159 document as well.
160 xmlDecl([$encoding, $standalone])
162 Add an XML declaration to the beginning of an XML document. The
163 version will always be "1.0". If you provide a non-null encoding
164 or standalone argument, its value will appear in the declaration
165 (any non-null value for standalone except 'no' will automatically
166 be converted to 'yes'). If not given here, the encoding will be
167 taken from the ENCODING argument. Pass the empty string to suppress
168 this behaviour.
169 $writer->xmlDecl("UTF-8");
171 doctype($name, [$publicId, $systemId])
173 Add a DOCTYPE declaration to an XML document. The declaration must
174 appear before the beginning of the root element. If you provide a
175 publicId, you must provide a systemId as well, but you may provide
176 just a system ID by passing 'undef' for the publicId.
177 $writer->doctype("html");
179 comment($text)
181 Add a comment to an XML document. If the comment appears outside
182 the document element (either before the first start tag or after
183 the last end tag), the module will add a carriage return after it
184 to improve readability. In data mode, comments will be treated as
185 empty tags:
186 $writer->comment("This is a comment");
188 pi($target [, $data])
190 Add a processing instruction to an XML document:
191 $writer->pi('xml-stylesheet', 'href="style.css" type="text/css"');
193 If the processing instruction appears outside the document element
195 (either before the first start tag or after the last end tag), the
196 module will add a carriage return after it to improve readability.
197 The $target argument must be a single XML name. If you provide the
199 $data argument, the module will insert its contents following the
200 $target argument, separated by a single space.
201 startTag($name [, $aname1 => $value1, ...])
203 Add a start tag to an XML document. Any arguments after the
204 element name are assumed to be name/value pairs for attributes: the
205 module will escape all '&', '<', '>', and '"' characters in the
206 attribute values using the predefined XML entities:
207 $writer->startTag('doc', 'version' => '1.0',
209 'status' => 'draft',
210 'topic' => 'AT&T');
211 All start tags must eventually have matching end tags.
213 emptyTag($name [, $aname1 => $value1, ...])
215 Add an empty tag to an XML document. Any arguments after the
216 element name are assumed to be name/value pairs for attributes (see
217 startTag() for details):
218 $writer->emptyTag('img', 'src' => 'portrait.jpg',
220 'alt' => 'Portrait of Emma.');
221 endTag([$name])
223 Add an end tag to an XML document. The end tag must match the
224 closest open start tag, and there must be a matching and properly-
225 nested end tag for every start tag:
226 $writer->endTag('doc');
228 If the $name argument is omitted, then the module will
230 automatically supply the name of the currently open element:
231 $writer->startTag('p');
233 $writer->endTag();
234 dataElement($name, $data [, $aname1 => $value1, ...])
236 Print an entire element containing only character data. This is
237 equivalent to
238 $writer->startTag($name [, $aname1 => $value1, ...]);
240 $writer->characters($data);
241 $writer->endTag($name);
242 characters($data)
244 Add character data to an XML document. All '<', '>', and '&'
245 characters in the $data argument will automatically be escaped
246 using the predefined XML entities:
247 $writer->characters("Here is the formula: ");
249 $writer->characters("a < 100 && a > 5");
250 You may invoke this method only within the document element (i.e.
252 after the first start tag and before the last end tag).
253 In data mode, you must not use this method to add whitespace
255 between elements.
256 raw($data)
258 Print data completely unquoted and unchecked to the XML document.
259 For example "raw('<')" will print a literal < character. This
260 necessarily bypasses all well-formedness checking, and is therefore
261 only available in unsafe mode.
262 This can sometimes be useful for printing entities which are
264 defined for your XML format but the module doesn't know about, for
265 example for XHTML.
266 cdata($data)
268 As "characters()" but writes the data quoted in a CDATA section,
269 that is, between <![CDATA[ and ]]>. If the data to be written
270 itself contains ]]>, it will be written as several consecutive
271 CDATA sections.
272 cdataElement($name, $data [, $aname1 => $value1, ...])
274 As "dataElement()" but the element content is written as one or
275 more CDATA sections (see "cdata()").
276 setOutput($output)
278 Set the current output destination, as in the OUTPUT parameter for
279 the constructor.
280 getOutput()
282 Return the current output destination, as in the OUTPUT parameter
283 for the constructor.
284 setDataMode($mode)
286 Enable or disable data mode, as in the DATA_MODE parameter for the
287 constructor.
288 getDataMode()
290 Return the current data mode, as in the DATA_MODE parameter for the
291 constructor.
292 setDataIndent($step)
294 Set the indent step for data mode, as in the DATA_INDENT parameter
295 for the constructor.
296 getDataIndent()
298 Return the indent step for data mode, as in the DATA_INDENT
299 parameter for the constructor.
300 Querying XML
302 in_element($name)
303 Return a true value if the most recent open element matches $name:
304 if ($writer->in_element('dl')) {
306 $writer->startTag('dt');
307 } else {
308 $writer->startTag('li');
309 }
310 within_element($name)
312 Return a true value if any open element matches $name:
313 if ($writer->within_element('body')) {
315 $writer->startTag('h1');
316 } else {
317 $writer->startTag('title');
318 }
319 current_element()
321 Return the name of the currently open element:
322 my $name = $writer->current_element();
324 This is the equivalent of
326 my $name = $writer->ancestor(0);
328 ancestor($n)
330 Return the name of the nth ancestor, where $n=0 for the current
331 open element.
332 Additional Namespace Support
334 As of 0.510, these methods may be used while writing a document.
335 addPrefix($uri, $prefix)
337 Add a preferred mapping between a Namespace URI and a prefix. See
338 also the PREFIX_MAP constructor parameter.
339 To set the default namespace, omit the $prefix parameter or set it
341 to ''.
342 removePrefix($uri)
344 Remove a preferred mapping between a Namespace URI and a prefix.
345 forceNSDecl($uri)
347 Indicate that a namespace declaration for this URI should be
348 included with the next element to be started.
349
351 With the default settings, the XML::Writer module can detect several
352 basic XML well-formedness errors:
353 · Lack of a (top-level) document element, or multiple document
355 elements.
356 · Unclosed start tags.
358 · Misplaced delimiters in the contents of processing instructions or
360 comments.
361 · Misplaced or duplicate XML declaration(s).
363 · Misplaced or duplicate DOCTYPE declaration(s).
365 · Mismatch between the document type name in the DOCTYPE declaration
367 and the name of the document element.
368 · Mismatched start and end tags.
370 · Attempts to insert character data outside the document element.
372 · Duplicate attributes with the same name.
374 During Namespace processing, the module can detect the following
376 additional errors:
377 · Attempts to use PI targets or element or attribute names containing
379 a colon.
380 · Attempts to use attributes with names beginning "xmlns".
382 To ensure full error detection, a program must also invoke the end
384 method when it has finished writing a document:
385 $writer->startTag('greeting');
387 $writer->characters("Hello, world!");
388 $writer->endTag('greeting');
389 $writer->end();
390 This error reporting can catch many hidden bugs in Perl programs that
392 create XML documents; however, if necessary, it can be turned off by
393 providing an UNSAFE parameter:
394 my $writer = XML::Writer->new(OUTPUT => $output, UNSAFE => 1);
396 PRINTING OUTPUT
398 If OUTPUT has been set to self and the object has been called in a
399 string context, it'll return the xml document.
400 to_string
402 If OUTPUT has been set to self, calls an implicit "end()" on the
403 document and prints it. Dies if OUTPUT has been set to anything
404 else.
405
407 David Megginson <david@megginson.com>
408
410 Copyright (c) 1999 by Megginson Technologies.
411 Copyright (c) 2003 Ed Avis <ed@membled.com>
413 Copyright (c) 2004-2010 Joseph Walton <joe@kafsemo.org>
415 Redistribution and use in source and compiled forms, with or without
417 modification, are permitted under any circumstances. No warranty.
418
420 XML::Parser
421perl v5.30.1 2020-01-30 Writer(3)