NAME

Data::XML::Variant - Output XML 'variants'

VERSION

Version 0.01

SYNOPSIS

 use Data::XML::Variant;

 my $xml = Data::XML::Variant->new(
     {
         'doc'         => 'doc',
         'ns:customer' => 'customer',
         'sales'       => 'sales',
     }
 );
 print $xml->doc(
     [ 'xmlns:customer' => $url ],
     $xml->customer([id => 1], 'bob'),
     $xml->customer([id => 2], 'alice'),
     $xml->customer([id => 3], 'charlie'),
     $xml->sales("3000.12"),
 );
 __END__
 <doc xmlns:ns="$url">
   <ns:customer id="1">bob</ns:customer>
   <ns:customer id="2">alice</ns:customer>
   <ns:customer id="3">charlie</ns:customer>
   <sales>3000.12</sales>
 </doc>
 

Note: newlines and indentation were added in the above example for illustrative purposes only. See NEWLINES in the Data::XML::Variant::Build documentation.

DESCRIPTION

Many shops have "legacy" XML variants which look very similar to XML but aren't quite there. Unfortunately, this means that most XML generating tools will not build this "legacy" XML. Sometimes they require attributes in a specific order, don't quote attributes, fail to close tags, use illegal characters, etc. Rather than writing your own code to produce bad XML, this module at least allows you to do this systematically.

Data::XML::Variant makes it very, very easy to write XML. It also makes it very easy to shoot yourself in the foot. You are responsible for all output. If you get it wrong, you've been warned. On the plus side, you don't have to worry about namespaces, inserting arbitrary data (very handy if you have an XML snippet from somewhere else), or remembering a lot of complicated stuff.

This module should not be used casually. It assumes that you, the programmer, really want to do what you're asking it to do. As a result, do not use this module unless you have a test suite which can verify that you're really creating the XML you need. It's easy to create bogus XML with this.

EXPORT

None.

METHODS

new

 my $xml = XML::Compose->new(
     {
         $tag1 => $method1,
         $tag2 => $method2,
     }
 );

new accepts a hashref of tags and their appropriate methods. Methods must begin with a lower-case later. Tags will be built with the exact text used. Namespaces will not be checked, validated, whatever.

See the Add method in Data::XML::Variant::Build for more information about how methods are added.

Instance methods.

See Data::XML::Variant::Build for a list of built-in methods. Public methods all begin with an upper case letter to distinguish them from the methods you add as tags.

A more complicated example

Just to let you see a better example:

 my $xml = Data::XML::Variant->new({
     'ns:foo'  => 'foo',
     'bar'     => 'bar',
     'ns2:baz' => 'baz',
 });
 print $xml->Decl, # add declaration (optional)
       $xml->PI('xml-stylesheet', [type => 'text/xsl', href=>"$xslt_url"]),
       $xml->foo(
           [ id => 3, 'xmlns:ns2' => $url],
           $xml->bar('silly'),
           $xml->Comment('this is a > comment'),
           $xml->baz(['asdf:some_attr' => 'value'], 'whee!'),
       );

 __END__
 <?xml version="1.0">
 <?xml-stylesheet type="text/xsl" href="$xslt_url"?>
 <ns:foo id="3" xmlns:ns2="$url">
 <bar>silly</bar>
 <!-- this is a &gt; comment -->
 <ns2:baz asdf:some_attr="value">whee!</ns2:baz>
 </ns:foo>

SHOULD YOU USE THIS MODULE?

You probably don't want to use this module if you need to produce well-formed XML. However, this module will allow you to do that. Regardless of whether or not you use this module, because XML variants are frequently sloppy, you should not use this unless you are in the habit of writing automated tests. It's very easy to generate XML (or something similar) which does not match your expectations.

AUTHOR

Curtis "Ovid" Poe, <ovid@cpan.org>

BUGS

Please report any bugs or feature requests to bug-data-xml-variant@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-XML-Variant. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2005 Curtis "Ovid" Poe, all rights reserved.

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

cpanm Data::XML::Variant

perl -MCPAN -e shell
install Data::XML::Variant