The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
XML-XMLWriter-0.1
River stage zero No dependents
++
/ XML::XMLWriter

NAME

XML::XMLWriter - Module for creating a XML document object oriented with on the fly validating towards the given DTD.

DEPENDENCIES

Perl Version

        5.004

Standard Modules

        Carp 1.01
        Encode 1.98

Nonstandard Modules

        XML::ParseDTD 0.1.3

SYNOPSIS

Example Code

        #!/usr/bin/perl

        use XML::XMLWriter;

        my @data=(['Name', 'Adress', 'Email', 'Sex'],
                  ['Herbert', 'BeerAvenue 45', 'herbert@names.org', 'Male'],
                  ['Anelise', 'SchmidtStreet 21', 'foo@bar.com', 'Female'],
                  ['XYZ', 'ZYX', 'ZY', 'XZ'],
                  ['etc...']);

        my $doc = new XML::XMLWriter(system => 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd',
                                     public => '-//W3C//DTD XHTML 1.0 Transitional//EN');

        my $html = $doc->createRoot;
        $html->head->title->_pcdata('A Table');
        my $body = $html->body;
        $body->h1->_pcdata('Here is a table!');
        my $table = $body->table({align => 'center', cellspacing => 1, cellpadding => 2, border => 1});
        for(my $i=0; $i<@data; $i++) {
          my $tr = $table->tr;
          foreach $_ (@{$data[$i]}) {
            $i==0 ? $tr->th->_pcdata($_) : $tr->td->_pcdata($_);
          }
        }
        $body->b->_pcdata("that's it!");
        $doc->print();

Example Output

        <?xml version="1.0" encoding="ISO-8859-15" standalone="no"?>
        <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" SYSTEM "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
        <html><head><title>A Table</title></head><body><h1>Here is a table!</h1><table align="center" cellspacing="1" cellpadding="2" border="1"><tr><th>Name</th><th>Adress</th><th>Email</th><th>Sex</th></tr><tr><td>Herbert</td><td>BeerAvenue 45</td><td>herbert@names.org</td><td>Male</td></tr><tr><td>Anelise</td><td>SchmidtStree 21</td><td>foo@bar.com</td><td>Female</td></tr><tr><td>XYZ</td><td>ZYX</td><td>ZY</td><td>XZ</td></tr><tr><td>etc...</td></tr></table><b>that's it!</b></body></html>

DESCRIPTION

XMLWriter is a Perl 5 object class, its purpose is to make writing XML documents easier, cleaner, safer and standard conform. Its easier because of the object oriented way XML documents are written with XMLWriter. Its cleaner because of the simple but logical API and its safe and standard conform because of the automatically done checking against the the DTD.

But still: it might be a matter of taste whether one finds XMLWriter usefull or not and it probably has some bugs (i would appreciate a lot if you report them to me), many usefull features are missing, not implemented or not even thought of and perhaps the API with all its simpleness might be confusing though. So please tell me your opinion and tell me the way how you would make XMLWriter better. Its not so easy to develop a good API for this matter.

XMLWriter contains 3 packages: XMLWriter.pm which gives you the document object, Element.pm which provides the element/tag objects and PCData.pm which represents the parsed character data the document contains. There'll probably come more objects in feature releases. The most interesting class is Element.pm. It provides some methods you can call on every document element, but besides those methods it uses the AUTOLOAD feature of perl to expect every not known method name to be the name of a tag that should be added to the list of child tags of the element the method is called on. So calling $html->head will simply add a new element (the head element) to the list of child tags of the html element. The head object is returned. Have a look at the examples for better understanding. You should also read the POD of Element.pm and PCdata.pm.

USING XML::XMLWriter

Encoding

All methods expect the data you pass them to be encoded in UTF8. So if you take data with diffrent encoding call Encode::decode(yourencoding,$data) to make it UTF8. Finally the whole document will be encoded in the document encoding (default: UTF8) before being returned.

The Constructor

new ([ %conf ])

The only argument can be a hash setting some configuration options:

  • version - XML version, defaults to 1.0, shouldn't be changed.

  • encoding - Character encoding. Defaults to UTF8.

  • public - PUBLIC IDENTIFIER. Defaults to -//W3C//DTD XHTML 1.0 Strict//EN.

  • system - SYSTEM IDENTIFIER (must always be a path/url pointing to a valid dtd). Defaults to http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd.

  • standalone - sets the standalone option of the XML declaration. Defaults to no, the only other possible value is yes.

  • root - sets the name of the root element. Defaults to html.

  • rootArgs - sets the list of arguments and their values for the root element. Defaults to {} (empty hash reference).

  • intend - sets whether intentation should be done and if so how many spaces per level. Defaults to 0, is not implemented yet, that means setting it won't have any effect.

  • checklm - the value of this option is passed to XML::ParseDTD for setting its checklm parameter. Please the the documentation of XML::ParseDTD for more information. Defaults to -1.

Methods

createRoot ([$rootelem, %arguments, $character_data])

Creates the root element and returns a XML::XMLWriter::Element object representing it.

Possible parameters:

  • 1. The root elements name. Defaults to the value of the root configuration option (see the new method).

  • 2. A hash of arguments for the root element and their values. Defaults to the value of the rootArgs configuration option (see the new method).

  • 3. A string of character data which will be appended right after the start tag. Defaults to undef, which means no data will be added.

Instead of passing the third argument you can also just do a $root->_pcdata(yourdata), its exactly the same.

get ()

Returns the XML document as a string. Every elements child list is checked and a warning is produce if its not allowed by the DTD.

Prints the XML document to STDOUT.

get_dtd ()

Returns the internally used XML::ParseDTD object.