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

NAME

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

SYNOPSIS

 ROOT=CustomerAdd
 XML_FILE=$ROOT.xml
 OUTPUT_PKG = XML::Quickbooks::$ROOT
 HASH_DEPTH=4 #counting from 0, which level of XML file should hash keys start mapping from
 OUTPATH_PREPEND=lib
 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
  xwc $XML_FILE $OUTPUT_PKG $HASH_DEPTH $OUTPUT_PREPEND $EXTENDS

DESCRIPTION

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

XML

 <note>
  <to>
    <person>
      Bob
    </person>
  </to>
  <from>Jani</from>
  <heading>Reminder</heading>
  <body>Don't forget me this weekend!</body>
 </note>

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 } );
 $tree->parse_file('t/sample.xml');

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

Perl

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

 my $xml = XML::Note->new;
 $xml->data(\%data);
 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

perl_pkg

the name of the Perl package that will represent the xml_file

hash_depth

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: https://member.developer.intuit.com/qbSDK-current/Common/newOSR/index.html

For instance the CustomerAdd xml starts like this:

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

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' } ;

prepend_lib

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'

extends

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.

SEE ALSO

Source code repository

https://github.com/metaperl/xml-writer-compiler

XML::Toolkit

XML::Toolkit

XML::Element::Tolol

XML::Element::Tolol

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

http://perlmonks.org/index.pl?node_id=910617

Control Windows Quickbooks with Win32::OLE

http://perlmonks.org/index.pl?node_id=909187

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

http://perlmonks.org/index.pl?node_id=913713

COPYRIGHT

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.

AUTHOR

Terrence Brannon <tbone@cpan.org>

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 352:

Unterminated C< ... > sequence

Around line 358:

Unterminated C< ... > sequence