writer(3)

NAME

XML::Writer - Perl extension for writing XML documents.

SYNOPSIS

use XML::Writer;
use IO;
my $output = new IO::File(">output.xml");
my $writer = new XML::Writer(OUTPUT => $output);
$writer->startTag("greeting",
                  "class" => "simple");
$writer->characters("Hello, world!");
$writer->endTag("greeting");
$writer->end();
$output->close();

DESCRIPTION

XML::Writer is a helper module for Perl programs that
write an XML document. The module handles all escaping
for attribute values and character data and constructs
different types of markup, such as tags, comments, and
processing instructions.

By default, the module performs several well-formedness
checks to catch errors during output. This behaviour can
be extremely useful during development and debugging, but
it can be turned off for production-grade code.

The module can operate either in regular mode in or Names
pace processing mode. In Namespace mode, the module will
generate Namespace Declarations itself, and will perform
additional checks on the output.

Additional support is available for a simplified data mode
with no mixed content: newlines are automatically inserted
around elements and elements can optionally be indented
based as their nesting level.

METHODS

Writing XML

new([$params]): Create a new XML::Writer object:

my $writer = new XML::Writer(OUTPUT => $output, NEW

LINES => 1);; Arguments are an anonymous hash array of parameters:; OUTPUT
An object blessed into IO::Handle or one of its
subclasses (such as IO::File); if this parameter
is not present, the module will write to standard
output.; NAMESPACES
A true (1) or false (0, undef) value; if this
parameter is present and its value is true, then
the module will accept two-member array reference
in the place of element and attribute names, as in
the following example:

my $rdfns = "http://www.w3.org/1999/02/22-rdf

syntax-ns#";
my $writer = new XML::Writer(NAMESPACES => 1);
$writer->startTag([$rdfns, "Description"]);

The first member of the array is a namespace URI,
and the second part is the local part of a quali
fied name. The module will automatically generate
appropriate namespace declarations and will
replace the URI part with a prefix.; PREFIX_MAP
A hash reference; if this parameter is present and
the module is performing namespace processing (see
the NAMESPACES parameter), then the module will
use this hash to look up preferred prefixes for
namespace URIs:

my $rdfns = "http://www.w3.org/1999/02/22-rdf

syntax-ns#";
my $writer = new XML::Writer(NAMESPACES => 1,
PREFIX_MAP =>

{$rdfns => 'rdf'});
The keys in the hash table are namespace URIs, and the values are the associated prefixes. If there is not a preferred prefix for the namespace URI in this hash, then the module will automatically gen erate prefixes of the form "__NS1", "__NS2", etc.
To set the default namespace, use '' for the pre fix.
NEWLINES: A true or false value; if this parameter is pre
sent and its value is true, then the module will
insert an extra newline before the closing delim
iter of start, end, and empty tags to guarantee
that the document does not end up as a single,
long line. If the paramter is not present, the
module will not insert the newlines.
UNSAFE: A true or false value; if this parameter is pre
sent and its value is true, then the module will
skip most well-formedness error checking. If the
parameter is not present, the module will perform
the well-formedness error checking by default.
Turn off error checking at your own risk!
DATA_MODE: A true or false value; if this parameter is pre
sent and its value is true, then the module will
enter a special data mode, inserting newlines
automatically around elements and (unless UNSAFE
is also specified) reporting an error if any ele
ment has both characters and elements as content.
DATA_INDENT: A numeric value; if this parameter is present, it
represents the indent step for elements in data
mode (it will be ignored when not in data mode).
end(): Finish creating an XML document. This method will
check that the document has exactly one document ele
ment, and that all start tags are closed:

$writer->end();; xmlDecl([$encoding, $standalone])
Add an XML declaration to the beginning of an XML doc
ument. The version will always be "1.0". If you pro
vide a non-null encoding or standalone argument, its
value will appear in the declaration (and non-null
value for standalone except 'no' will automatically be
converted to 'yes').

$writer->xmlDecl("UTF-8");

doctype($name, [$publicId, $systemId])

Add a DOCTYPE declaration to an XML document. The
declaration must appear before the beginning of the
root element. If you provide a publicId, you must
provide a systemId as well, but you may provide just a
system ID.

$writer->doctype("html");

comment($text)

Add a comment to an XML document. If the comment
appears outside the document element (either before
the first start tag or after the last end tag), the
module will add a carriage return after it to improve
readability:

$writer->comment("This is a comment");

pi($target [, $data])

Add a processing instruction to an XML document:

$writer->pi('xml-stylesheet', 'href="style.css"

type="text/css"');

If the processing instruction appears outside the doc
ument element (either before the first start tag or
after the last end tag), the module will add a car
riage return after it to improve readability.

The $target argument must be a single XML name. If
you provide the $data argument, the module will insert
its contents following the $target argument, separated
by a single space.

startTag($name [, $aname1 => $value1, ...])

Add a start tag to an XML document. Any arguments
after the element name are assumed to be name/value
pairs for attributes: the module will escape all '&',
'<', '>', and '"' characters in the attribute values
using the predefined XML entities:

$writer->startTag('doc', 'version' => '1.0',
'status' => 'draft',
'topic' => 'AT&T');
All start tags must eventually have matching end tags.
emptyTag($name [, $aname1 => $value1, ...]): Add an empty tag to an XML document. Any arguments
after the element name are assumed to be name/value
pairs for attributes (see startTag() for details):

$writer->emptyTag('img', 'src' => 'portrait.jpg',
'alt' => 'Portrait of Em

ma.');
endTag([$name]): Add an end tag to an XML document. The end tag must
match the closest open start tag, and there must be a
matching and properly-nested end tag for every start
tag:

$writer->endTag('doc');; If the $name argument is omitted, then the module will
automatically supply the name of the currently open
element:

$writer->startTag('p');
$writer->endTag();; dataElement($name, $data [, $aname1 => $value1, ...])
Print an entire element containing only character
data. This is equivalent to

$writer->startTag($name [, $aname1 => $value1,

...]);
$writer->characters($data);
$writer->endTag($name);

characters($data)

Add character data to an XML document. All '<', '>',
and '&' characters in the $data argument will automat
ically be escaped using the predefined XML entities:

$writer->characters("Here is the formula: ");
$writer->characters("a < 100 && a > 5");

You may invoke this method only within the document
element (i.e. after the first start tag and before the
last end tag).

In data mode, you must not use this method to add
whitespace between elements.

setOutput($output)

Set the current output destination, as in the OUTPUT
parameter for the constructor.

getOutput()

Return the current output destination, as in the OUT
PUT parameter for the constructor.

setDataMode($mode)

Enable or disable data mode, as in the DATA_MODE
parameter for the constructor.

getDataMode()

Return the current data mode, as in the DATA_MODE
parameter for the constructor.

setDataIndent($step)

Set the indent step for data mode, as in the
DATA_INDENT parameter for the constructor.

getDataIndent()

Return the indent step for data mode, as in the
DATA_INDENT parameter for the constructor.

Querying XML

in_element($name)

Return a true value if the most recent open element
matches $name:

if ($writer->in_element('dl')) {
$writer->startTag('dt');

} else {

$writer->startTag('li');

}

within_element($name)

Return a true value if any open elemnet matches $name:

if ($writer->within_element('body')) {
$writer->startTag('h1');

} else {

$writer->startTag('title');

}

current_element()

Return the name of the currently open element:

my $name = $writer->current_element();

This is the equivalent of

my $name = $writer->ancestor(0);

ancestor($n)

Return the name of the nth ancestor, where $n=0 for
the current open element.

Additional Namespace Support

WARNING: you must not use these methods while you are
writing a document, or the results will be unpredictable.

addPrefix($uri, $prefix)

Add a preferred mapping between a Namespace URI and a
prefix. See also the PREFIX_MAP constructor parame
ter.

To set the default namespace, omit the $prefix parame
ter or set it to ''.

removePrefix($uri)

Remove a preferred mapping between a Namespace URI and
a prefix.

To set the default namespace, omit the $prefix parame
ter or set it to ''.

ERROR REPORTING

With the default settings, the XML::Writer module can
detect several basic XML well-formedness errors:

� Lack of a (top-level) document element, or multiple: document elements.
� Unclosed start tags.
� Misplaced delimiters in the contents of processing: instructions or comments.
� Misplaced or duplicate XML declaration(s).
� Misplaced or duplicate DOCTYPE declaration(s).
� Mismatch between the document type name in the DOCTYPE: declaration and the name of the document element.
� Mismatched start and end tags.
� Attempts to insert character data outside the document: element.
� Duplicate attributes with the same name.
During Namespace processing, the module can detect the following additional errors:
� Attempts to use PI targets or element or attribute: names containing a colon.
� Attempts to use attributes with names beginning: "xmlns".
To ensure full error detection, a program must also invoke the end method when it has finished writing a document:: $writer->startTag('greeting');
$writer->characters("Hello, world!");
$writer->endTag('greeting');
$writer->end();
This error reporting can catch many hidden bugs in Perl programs that create XML documents; however, if necessary, it can be turned off by providing an UNSAFE parameter:: my $writer = new XML::Writer(OUTPUT => $output, UNSAFE; => 1);

AUTHOR

David Megginson, david@megginson.com

docs.sk

comprehensive documentation repository

Most Viewed