NAME
XML::Generator - Perl extension for generating XML
SYNOPSIS
use XML::Generator;
my $x = XML::Generator->new('escape' => 'always', 'conformance' => 'strict');
print $x->foo($x->bar({baz=>3}, $x->bam()),
$x->bar(['qux'],"Hey there,\n", "world"));
__END__
# The above would yield:
<foo><bar baz="3"><bam /></bar><qux:bar>Hey there,
world</qux:bar></foo>DESCRIPTION
In general, once you have an XML::Generator object (which will actually be blessed into the XML::Generator::auto package), you call methods on that object for each XML tag you wish to generate. Say you want to generate this XML:
<person>
<name>Bob</name>
<age>34</age>
<job>Accountant</job>
</person>Here's a snippet of code that does the job, modulo the pretty-printing:
use XML::Generator;
my $gen = XML::Generator->new('escape' => 'always');
my $xml = $gen->person(
$gen->name("Bob"),
$gen->age(34),
$gen->job("Accountant"));The only problem with this is if you want to use a tag name that Perl's lexer won't understand as a method name, such as "shoe-size". Fortunately, since you can always call methods as variable names, there's a simple work-around:
my $shoe_size = "shoe-size";
$xml = $gen->$shoe_size("12 1/2");Which correctly generates:
<shoe-size>12 1/2</shoe-size>You can use a hash ref as the first parameter if the tag should include atributes. An array ref can be supplied as the first argument to indicate a namespace for the element and the attributes (the elements of the array are concatenated with ':'). Under strict conformance, however, you are only allowed one namespace component.
If you want to specify a namespace as well as attributes, you can make the second argument a hash ref. If you do it the other way around, the array ref will simply get stringified and included as part of the content of the tag. If an XML::Generator object has a namespace set, and a namespace is also supplied to the tag, the supplied namespace overrides the default.
Here's an example to show how the attribute and namespace parameters work:
$xml = $gen->account({'type' => 'checking', 'id' => '34758'},
$gen->open(['transaction'], 2000),
$gen->deposit(['transaction'], {'date' => '1999.04.03'},
1500));This generates (again, modulo pretty-printing):
<account type="checking" id="34578">
<transaction:open>2000</transaction:open>
<transaction:deposit date="1999.04.03">1500</transaction:deposit>
</account>CONSTRUCTOR
XML::Generator->new( OPTIONS );
The following options are available:
namespace
The value of this option is used as the global default namespace. For example,
my $html = XML::Generator->new('namespace' => 'HTML');
print $html->font({face => 'Arial'}, "Hello, there");would yield
<HTML:font HTML:face="Arial">Hello, there</HTML:font>escape
The contents and the values of each attribute have the illegal XML characters escaped if this option is supplied. If the value is 'always', then &, < and > (and " within attribute values) will be converted into the corresponding XML entity. If the value is any other true value, then the escaping will be turned off if the character in question is preceded by a backslash. So, for example,
my $a = XML::Generator->new('escape' => 'always');
my $b = XML::Generator->new('escape' => 'true');
print $a->foo('<', $b->bar('3 \> 4'), '\&', '>');would yield
<foo><<bar>3 > 4</bar>\&></foo>conformance
If the value of this option is 'strict', a number of syntactic checks are performed to ensure that generated XML conforms to the formal XML specification. In addition, since entity names beginning with 'xml' are reserved by the W3C, inclusion of this option enables several special tag names; xmlpi, xmlcmnt, xmldecl and xmlcdata, to allow generation of processing instructions, comments, XML declarations and character data sections, respectively.
See "XML CONFORMANCE" and "SPECIAL TAGS" for more information.
XML CONFORMANCE
When the 'conformance' => 'strict' option is supplied, a number of syntactic checks are enabled. All entity and attribute names are checked to conform to the XML specification, which states that they must begin with either an alphabetic character or an underscore and may then consist of any number of alphanumerics, underscores, periods or hyphens. Alphabetic and alphanumeric are interpreted according to the current locale if 'use locale' is in effect and according to the Unicode standard for Perl versions >= 5.6. Furthermore, entity or attribute names are not allowed to begin with 'xml' (in any case), although a number of special tags beginning with 'xml' are allowed (see "SPECIAL TAGS").
In addition, only one namespace component will be allowed when strict conformance is in effect, and attribute names can be given a specific namespace, which will override both the default namespace and the tag- specific namespace. For example,
my $gen = XML::Generator->new('conformance' => 'strict',
'namespace' => 'foo');
my $xml = $gen->bar({ 'a' => 1 },
$gen->baz(['bam'], { 'b' => 2, 'name:c' => 3 }));will generate:
<foo:bar foo:a="1">
<bam:baz bam:b="2" name:c="3" />
</foo:bar>SPECIAL TAGS
The following special tags are available:
xmlpi
Processing instruction; first argument is target, remaining arguments are attribute, value pairs. Attribute names are syntax checked, values are escaped.
xmlcmnt
Comment. Arguments are concatenated and placed inside <!-- ... --> comment delimiters. Any occurences of '--' in the concatenated arguments are converted to '--'
xmldecl
XML Declaration.
xmlcdata
Character data section; arguments are concatenated and placed inside <![CDATA[ ... ]]> character data section delimiters. Any occurences of ']]>' in the concatenated arguments are converted to ']]>'.
AUTHORS
Benjamin Holzman, bholzman@earthlink.net
Bron Gondwana, perlcode@brong.net