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, complete with pretty-printing:
use XML::Generator;
my $gen = XML::Generator->new('escape' => 'always', 'pretty' => 2);
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:
<account type="checking" id="34578">
<transaction:open>2000</transaction:open>
<transaction:deposit transaction: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 character-by-character if the character in question is preceded by a backslash, or for the entire string if it is supplied as a scalar reference. So, for example,
my $a = XML::Generator->new('escape' => 'always');
my $b = XML::Generator->new('escape' => 'true');
print $a->foo('<', $b->bar('3 \> 4', \" && 6 < 5"), '\&', '>');would yield
<foo><<bar>3 > 4 && 6 < 5</bar>\&></foo>pretty
To have nice pretty printing of the output XML (great for config files that you might also want to edit by hand), pass an integer for the number of spaces per level of indenting, eg.
my $gen = XML::Generator->new('pretty' => 2);
print $gen->foo($gen->bar('baz'),
$gen->qux({'tricky' => 'no'}, 'quux')
);would yield
<foo>
<bar>baz</bar>
<qux tricky="no">quux</qux>
</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, xmlcdata, and xml to allow generation of processing instructions, comments, XML declarations, character data sections and "final" XML documents, 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 ']]>'.
xml
"Final" XML document. Must be called with one and exactly one argument, which must be an XML::Generator-produced XML document. Prepends an XML declaration, and re-blesses the argument into a "final" class, which can't be embedded.
AUTHORS
Benjamin Holzman, bholzman@earthlink.net
Bron Gondwana, perlcode@brong.net