XML::Writer::Compiler - create XML::Writer based classes whose instances can generate, refine and extend sample XML


 OUTPUT_PKG = XML::Quickbooks::$ROOT
 HASH_DEPTH=4 #counting from 0, which level of XML file should hash keys start mapping from
 EXTENDS=XML::Quickbooks # the XML class we generate, XML::Quickbooks::CustomerAdd has the parent XML::Quickbooks

 # Now run the compiler on the XML file to produce an XML class, which produces XML when a hashref is supplied
 # Also possible to subclass the generated XML class to customize XML generation when hashrefs are inadequate


XML::Writer::Compiler is a module which takes a sample XML document and creates a single class from it. This class contains methods for each tag of the XML. The instance of the class can generate XML with the content supplied via a hashref. Subclassing the generated class allows more precise control over how the object-oriented XML generation occurs.

The CPAN module most similar to XML::Writer::Compiler is XML::Toolkit.

Simple Example


  <body>Don't forget me this weekend!</body>

Compile XML to Perl class

This step is normally done via the xwc script, but you can also write Perl code to compile XML:

 my $compiler = XML::Writer::Compiler->new;

 my $tree = XML::TreeBuilder->new( { 'NoExpand' => 0, 'ErrorContext' => 0 } );

 my $pkg = XML::Note';
 my $class = $compiler->buildclass( $pkg, $tree, 0, '' );


 my %data = (
    note => {
        to => { person => 'Satan' },
        from => [ [ via => 'postcard', russia => 'with love' ], 'moneypenny' ]

 my $xml = XML::Note->new;
 warn  $xml->xml->string->value;

Subclassing Example

If a simple substitution from a hashref of data will not suffice, then you can take the methods of the generated class and subclass them for things like repeating or conditional content. See the test file repeating.t for an example.

USAGE of xwc

The xwc script is the most common way to convert an XML file to an equivalent Perl class. The script takes the following arguments

xml_file (required)

the full/relative path to the sample XML file


the name of the Perl package that will represent the xml_file


An XML file has nesting levels, or depth. Oftentimes, the outer levels will never be rewritten via the data hashref you supply. As a result, you dont want to have to several levels of your hashref before you actually specify the data you want to bind.

Concretely, let's take some XML from the Quickbooks SDK:

For instance the CustomerAdd xml starts like this:

  <QBXMLMsgsRq onError="stopOnError">
    <CustomerAdd> <!-- required -->
     <Name >STRTYPE</Name> <!-- required -->
     <IsActive >BOOLTYPE</IsActive>

Now, none of the XML from the root to the XPath QBXML/QBXMLMsgsRq/CustomerAddRq/CustomerAdd needs any binding from the hashref. If you compiled this XML and had hash_depth>> set to 0, then to set the name your hashref would have to look like:

  my %data = ( QBXML => { QXBMLMsgsRq => { CustomerAddRq => { CustomerAdd => { Name => 'Bob Jones' }}}}} ;

In contrast , if you compiled this XML and had hash_depth>> set to 4, then to set the name your hashref would only have to look like:

  my %data = (  Name => 'Bob Jones' } ;


The generated class file has a path generated from splitting the class name on double colon. In most cases, you will want to write the class file to a path with 'lib' prepended and so you would set this option to 'lib'


The XML class file is a Moose class and can extend any superclass. E.g., in the XML::Quickbooks distribution, each XML class file extends XML::Quickbooks.


Source code repository





Moose, the tree structure of XML and object-oriented inheritance hiearchies

Control Windows Quickbooks with Win32::OLE

generating XML with data structures and Perl classes - the XML::Element::Tolol approach


Copyright RANGE('2011-07-25', NOW()) Terrence Brannon.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.


Terrence Brannon <>

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 352:

Unterminated C< ... > sequence

Around line 358:

Unterminated C< ... > sequence