/ 
XML-Writer-0.1
River stage three • 74 direct dependents • 438 total dependents
/ XML::Writer

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);
$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.

[[TODO]]

METHODS

new([$output, $noErrorChecking])

Create a new XML::Writer object. The $output argument should be an object blessed into IO::Handle or one of its subclasses (such as IO::File); if it is null, the module will automatically use standard output.

The second argument, if true, turns off error checking.

end()

Finish creating an XML document. This method will check that the document has exactly one document element, and that all start tags are closed.

xmlDecl([$standalone])

Add an XML declaration to the beginning of an XML document. The version will always be "1.0", and the encoding will always be "UTF-8". If you provide the $standalone argument, the module will include it as the value of the 'standalone' pseudo-attribute.

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.

pi($target [, $data])

Add a processing instruction to an XML document. If the processing instruction 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.

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.

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: the module will escape all '&', '<', '>', and '"' characters in the attribute values using the predefined XML entities.

endTag($name)

Add an end tag to an XML document. The end tag must match the closest open start tag.

characters($data)

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

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

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.

To ensure full error detection, a program must also invoke the end method when it has finished writing a document:

$writer->startElement('greeting');
$writer->characters("Hello, world!");
$writer->endElement('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 a true value as the second argument of the constructor:

my $writer = new XML::Writer($output, 1);

AUTHOR

David Megginson, david@megginson.com

SEE ALSO

XML::Parser