XML::Generator(3)

1Generator(3)          User Contributed Perl Documentation         Generator(3)
2
3
4

NAME

6       XML::Generator - Perl extension for generating XML
7

SYNOPSIS

9         use XML::Generator ':pretty';
10
11         print foo(bar({ baz => 3 }, bam()),
12                   bar([ 'qux' => 'http://qux.com/' ],
13                         "Hey there, world"));
14
15         # OR
16
17         require XML::Generator;
18
19         my $X = XML::Generator->new(':pretty');
20
21         print $X->foo($X->bar({ baz => 3 }, $X->bam()),
22                       $X->bar([ 'qux' => 'http://qux.com/' ],
23                                 "Hey there, world"));
24
25       Either of the above yield:
26
27          <foo xmlns:qux="http://qux.com/">
28            <bar baz="3">
29              <bam />
30            </bar>
31            <qux:bar>Hey there, world</qux:bar>
32          </foo>
33

DESCRIPTION

35       In general, once you have an XML::Generator object, you then simply
36       call methods on that object named for each XML tag you wish to
37       generate.
38
39       XML::Generator can also arrange for undefined subroutines in the
40       caller's package to generate the corresponding XML, by exporting an
41       "AUTOLOAD" subroutine to your package.  Just supply an ':import'
42       argument to your "use XML::Generator;" call.  If you already have an
43       "AUTOLOAD" defined then XML::Generator can be configured to cooperate
44       with it.  See "STACKABLE AUTOLOADs".
45
46       Say you want to generate this XML:
47
48          <person>
49            <name>Bob</name>
50            <age>34</age>
51            <job>Accountant</job>
52          </person>
53
54       Here's a snippet of code that does the job, complete with pretty
55       printing:
56
57          use XML::Generator;
58          my $gen = XML::Generator->new(':pretty');
59          print $gen->person(
60                   $gen->name("Bob"),
61                   $gen->age(34),
62                   $gen->job("Accountant")
63                );
64
65       The only problem with this is if you want to use a tag name that Perl's
66       lexer won't understand as a method name, such as "shoe-size".
67       Fortunately, since you can store the name of a method in a variable,
68       there's a simple work-around:
69
70          my $shoe_size = "shoe-size";
71          $xml = $gen->$shoe_size("12 1/2");
72
73       Which correctly generates:
74
75          <shoe-size>12 1/2</shoe-size>
76
77       You can use a hash ref as the first parameter if the tag should include
78       atributes.  Normally this means that the order of the attributes will
79       be unpredictable, but if you have the Tie::IxHash module, you can use
80       it to get the order you want, like this:
81
82         use Tie::IxHash;
83         tie my %attr, 'Tie::IxHash';
84
85         %attr = (name => 'Bob',
86                  age  => 34,
87                  job  => 'Accountant',
88           'shoe-size' => '12 1/2');
89
90         print $gen->person(\%attr);
91
92       This produces
93
94         <person name="Bob" age="34" job="Accountant" shoe-size="12 1/2" />
95
96       An array ref can also be supplied as the first argument to indicate a
97       namespace for the element and the attributes.
98
99       If there is one element in the array, it is considered the URI of the
100       default namespace, and the tag will have an xmlns="URI" attribute added
101       automatically.  If there are two elements, the first should be the tag
102       prefix to use for the namespace and the second element should be the
103       URI.  In this case, the prefix will be used for the tag and an
104       xmlns:PREFIX attribute will be automatically added.  Prior to version
105       0.99, this prefix was also automatically added to each attribute name.
106       Now, the default behavior is to leave the attributes alone (although
107       you may always explicitly add a prefix to an attribute name).  If the
108       prior behavior is desired, use the constructor option
109       "qualified_attributes".
110
111       If you specify more than two elements, then each pair should correspond
112       to a tag prefix and the corresponding URL.  An xmlns:PREFIX attribute
113       will be added for each pair, and the prefix from the first such pair
114       will be used as the tag's namespace.  If you wish to specify a default
115       namespace, use '#default' for the prefix.  If the default namespace is
116       first, then the tag will use the default namespace itself.
117
118       If you want to specify a namespace as well as attributes, you can make
119       the second argument a hash ref.  If you do it the other way around, the
120       array ref will simply get stringified and included as part of the
121       content of the tag.
122
123       Here's an example to show how the attribute and namespace parameters
124       work:
125
126          $xml = $gen->account(
127                   $gen->open(['transaction'], 2000),
128                   $gen->deposit(['transaction'], { date => '1999.04.03'}, 1500)
129                 );
130
131       This generates:
132
133          <account>
134            <open xmlns="transaction">2000</open>
135            <deposit xmlns="transaction" date="1999.04.03">1500</deposit>
136          </account>
137
138       Because default namespaces inherit, XML::Generator takes care to output
139       the xmlns="URI" attribute as few times as strictly necessary.  For
140       example,
141
142          $xml = $gen->account(
143                   $gen->open(['transaction'], 2000),
144                   $gen->deposit(['transaction'], { date => '1999.04.03'},
145                     $gen->amount(['transaction'], 1500)
146                   )
147                 );
148
149       This generates:
150
151          <account>
152            <open xmlns="transaction">2000</open>
153            <deposit xmlns="transaction" date="1999.04.03">
154              <amount>1500</amount>
155            </deposit>
156          </account>
157
158       Notice how "xmlns="transaction"" was left out of the "<amount"> tag.
159
160       Here is an example that uses the two-argument form of the namespace:
161
162           $xml = $gen->widget(['wru' => 'http://www.widgets-r-us.com/xml/'],
163                               {'id'  => 123}, $gen->contents());
164
165           <wru:widget xmlns:wru="http://www.widgets-r-us.com/xml/" id="123">
166             <contents />
167           </wru:widget>
168
169       Here is an example that uses multiple namespaces.  It generates the
170       first example from the RDF primer (http://www.w3.org/TR/rdf-primer/
171       <http://www.w3.org/TR/rdf-primer/>).
172
173           my $contactNS = [contact => "http://www.w3.org/2000/10/swap/pim/contact#"];
174           $xml = $gen->xml(
175                    $gen->RDF([ rdf     => "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
176                                @$contactNS ],
177                       $gen->Person($contactNS, { 'rdf:about' => "http://www.w3.org/People/EM/contact#me" },
178                         $gen->fullName($contactNS, 'Eric Miller'),
179                         $gen->mailbox($contactNS, {'rdf:resource' => "mailto:em@w3.org"}),
180                         $gen->personalTitle($contactNS, 'Dr.'))));
181
182           <?xml version="1.0" standalone="yes"?>
183           <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
184                    xmlns:contact="http://www.w3.org/2000/10/swap/pim/contact#">
185             <contact:Person rdf:about="http://www.w3.org/People/EM/contact#me">
186               <contact:fullName>Eric Miller</contact:fullName>
187               <contact:mailbox rdf:resource="mailto:em@w3.org" />
188               <contact:personalTitle>Dr.</contact:personalTitle>
189             </Person>
190           </rdf:RDF>
191

CONSTRUCTOR

193       XML::Generator->new(':option', ...);
194
195       XML::Generator->new(option => 'value', ...);
196
197       (Both styles may be combined)
198
199       The following options are available:
200
201   :std, :standard
202       Equivalent to
203
204               escape      => 'always',
205               conformance => 'strict',
206
207   :strict
208       Equivalent to
209
210               conformance => 'strict',
211
212   :pretty[=N]
213       Equivalent to
214
215               escape      => 'always',
216               conformance => 'strict',
217               pretty      => N         # N defaults to 2
218
219   namespace
220       This value of this option must be an array reference containing one or
221       two values.  If the array contains one value, it should be a URI and
222       will be the value of an 'xmlns' attribute in the top-level tag.  If
223       there are two or more elements, the first of each pair should be the
224       namespace tag prefix and the second the URI of the namespace.  This
225       will enable behavior similar to the namespace behavior in previous
226       versions; the tag prefix will be applied to each tag.  In addition, an
227       xmlns:NAME="URI" attribute will be added to the top-level tag.  Prior
228       to version 0.99, the tag prefix was also automatically added to each
229       attribute name, unless overridden with an explicit prefix.  Now, the
230       attribute names are left alone, but if the prior behavior is desired,
231       use the constructor option "qualified_attributes".
232
233       The value of this option is used as the global default namespace.  For
234       example,
235
236           my $html = XML::Generator->new(
237                        pretty    => 2,
238                        namespace => [HTML => "http://www.w3.org/TR/REC-html40"]);
239           print $html->html(
240                   $html->body(
241                     $html->font({ face => 'Arial' },
242                                 "Hello, there")));
243
244       would yield
245
246           <HTML:html xmlns:HTML="http://www.w3.org/TR/REC-html40">
247             <HTML:body>
248               <HTML:font face="Arial">Hello, there</HTML:font>
249             </HTML:body>
250           </HTML:html>
251
252       Here is the same example except without all the prefixes:
253
254           my $html = XML::Generator->new(
255                        pretty    => 2,
256                        namespace => ["http://www.w3.org/TR/REC-html40"]);
257           print $html->html(
258                   $html->body(
259                     $html->font({ 'face' => 'Arial' },
260                                   "Hello, there")));
261
262       would yield
263
264          <html xmlns="http://www.w3.org/TR/REC-html40">
265            <body>
266               <font face="Arial">Hello, there</font>
267            </body>
268          </html>
269
270   qualifiedAttributes, qualified_attributes
271       Set this to a true value to emulate the attribute prefixing behavior of
272       XML::Generator prior to version 0.99.  Here is an example:
273
274           my $foo = XML::Generator->new(
275                       namespace => [foo => "http://foo.com/"],
276                       qualifiedAttributes => 1);
277           print $foo->bar({baz => 3});
278
279       yields
280
281           <foo:bar xmlns:foo="http://foo.com/" foo:baz="3" />
282
283   escape
284       The contents and the values of each attribute have any illegal XML
285       characters escaped if this option is supplied.  If the value is
286       'always', then &, < and > (and " within attribute values) will be
287       converted into the corresponding XML entity, although & will not be
288       converted if it looks like it could be part of a valid entity (but see
289       below).  If the value is 'unescaped', then the escaping will be turned
290       off character-by- character if the character in question is preceded by
291       a backslash, or for the entire string if it is supplied as a scalar
292       reference.  So, for example,
293
294               use XML::Generator escape => 'always';
295
296               one('<');      # <one>&lt;</one>
297               two('\&');     # <two>\&amp;</two>
298               three(\'>');   # <three>&gt;</three> (scalar refs always allowed)
299               four('&lt;');  # <four>&lt;</four> (looks like an entity)
300               five('&#34;'); # <five>&#34;</five> (looks like an entity)
301
302       but
303
304               use XML::Generator escape => 'unescaped';
305
306               one('<');     # <one>&lt;</one>
307               two('\&');    # <two>&</two>
308               three(\'>');  # <three>></three> (aiee!)
309               four('&lt;'); # <four>&amp;lt;</four> (no special case for entities)
310
311       By default, high-bit data will be passed through unmodified, so that
312       UTF-8 data can be generated with pre-Unicode perls.  If you know that
313       your data is ASCII, use the value 'high-bit' for the escape option and
314       bytes with the high bit set will be turned into numeric entities.  You
315       can combine this functionality with the other escape options by comma-
316       separating the values:
317
318         my $a = XML::Generator->new(escape => 'always,high-bit');
319         print $a->foo("<\242>");
320
321       yields
322
323         <foo>&lt;&#162;&gt;</foo>
324
325       Because XML::Generator always uses double quotes ("") around attribute
326       values, it does not escape single quotes.  If you want single quotes
327       inside attribute values to be escaped, use the value 'apos' along with
328       'always' or 'unescaped' for the escape option.  For example:
329
330           my $gen = XML::Generator->new(escape => 'always,apos');
331           print $gen->foo({'bar' => "It's all good"});
332
333           <foo bar="It&apos;s all good" />
334
335       If you actually want & to be converted to &amp; even if it looks like
336       it could be part of a valid entity, use the value 'even-entities' along
337       with 'always'.  Supplying 'even-entities' to the 'unescaped' option is
338       meaningless as entities are already escaped with that option.
339
340   pretty
341       To have nice pretty printing of the output XML (great for config files
342       that you might also want to edit by hand), supply an integer for the
343       number of spaces per level of indenting, eg.
344
345          my $gen = XML::Generator->new(pretty => 2);
346          print $gen->foo($gen->bar('baz'),
347                          $gen->qux({ tricky => 'no'}, 'quux'));
348
349       would yield
350
351          <foo>
352            <bar>baz</bar>
353            <qux tricky="no">quux</qux>
354          </foo>
355
356       You may also supply a non-numeric string as the argument to 'pretty',
357       in which case the indents will consist of repetitions of that string.
358       So if you want tabbed indents, you would use:
359
360            my $gen = XML::Generator->new(pretty => "\t");
361
362       Pretty printing does not apply to CDATA sections or Processing
363       Instructions.
364
365   conformance
366       If the value of this option is 'strict', a number of syntactic checks
367       are performed to ensure that generated XML conforms to the formal XML
368       specification.  In addition, since entity names beginning with 'xml'
369       are reserved by the W3C, inclusion of this option enables several
370       special tag names: xmlpi, xmlcmnt, xmldecl, xmldtd, xmlcdata, and xml
371       to allow generation of processing instructions, comments, XML
372       declarations, DTD's, character data sections and "final" XML documents,
373       respectively.
374
375       See "XML CONFORMANCE" and "SPECIAL TAGS" for more information.
376
377   allowedXMLTags, allowed_xml_tags
378       If you have specified 'conformance' => 'strict' but need to use tags
379       that start with 'xml', you can supply a reference to an array
380       containing those tags and they will be accepted without error.  It is
381       not an error to supply this option if 'conformance' => 'strict' is not
382       supplied, but it will have no effect.
383
384   empty
385       There are 5 possible values for this option:
386
387          self    -  create empty tags as <tag />  (default)
388          compact -  create empty tags as <tag/>
389          close   -  close empty tags as <tag></tag>
390          ignore  -  don't do anything (non-compliant!)
391          args    -  use count of arguments to decide between <x /> and <x></x>
392
393       Many web browsers like the 'self' form, but any one of the forms
394       besides 'ignore' is acceptable under the XML standard.
395
396       'ignore' is intended for subclasses that deal with HTML and other SGML
397       subsets which allow atomic tags.  It is an error to specify both
398       'conformance' => 'strict' and 'empty' => 'ignore'.
399
400       'args' will produce <x /> if there are no arguments at all, or if there
401       is just a single undef argument, and <x></x> otherwise.
402
403   version
404       Sets the default XML version for use in XML declarations.  See
405       "xmldecl" below.
406
407   encoding
408       Sets the default encoding for use in XML declarations.
409
410   dtd
411       Specify the dtd.  The value should be an array reference with three
412       values; the type, the name and the uri.
413

IMPORT ARGUMENTS

415       use XML::Generator ':option';
416
417       use XML::Generator option => 'value';
418
419       (Both styles may be combined)
420
421   :import
422       Cause "use XML::Generator;" to export an "AUTOLOAD" to your package
423       that makes undefined subroutines generate XML tags corresponding to
424       their name.  Note that if you already have an "AUTOLOAD" defined, it
425       will be overwritten.
426
427   :stacked
428       Implies :import, but if there is already an "AUTOLOAD" defined, the
429       overriding "AUTOLOAD" will still give it a chance to run.  See "STACKED
430       AUTOLOADs".
431
432   ANYTHING ELSE
433       If you supply any other options, :import is implied and the
434       XML::Generator object that is created to generate tags will be
435       constructed with those options.
436

XML CONFORMANCE

438       When the 'conformance' => 'strict' option is supplied, a number of
439       syntactic checks are enabled.  All entity and attribute names are
440       checked to conform to the XML specification, which states that they
441       must begin with either an alphabetic character or an underscore and may
442       then consist of any number of alphanumerics, underscores, periods or
443       hyphens.  Alphabetic and alphanumeric are interpreted according to the
444       current locale if 'use locale' is in effect and according to the
445       Unicode standard for Perl versions >= 5.6.  Furthermore, entity or
446       attribute names are not allowed to begin with 'xml' (in any case),
447       although a number of special tags beginning with 'xml' are allowed (see
448       "SPECIAL TAGS"). Note that you can also supply an explicit list of
449       allowed tags with the 'allowed_xml_tags' option.
450

SPECIAL TAGS

452       The following special tags are available when running under strict
453       conformance (otherwise they don't act special):
454
455   xmlpi
456       Processing instruction; first argument is target, remaining arguments
457       are attribute, value pairs.  Attribute names are syntax checked, values
458       are escaped.
459
460   xmlcmnt
461       Comment.  Arguments are concatenated and placed inside <!-- ... -->
462       comment delimiters.  Any occurences of '--' in the concatenated
463       arguments are converted to '&#45;&#45;'
464
465   xmldecl(@args)
466       Declaration.  This can be used to specify the version, encoding, and
467       other XML-related declarations (i.e., anything inside the <?xml?> tag).
468       @args can be used to control what is output, as keyword-value pairs.
469
470       By default, the version is set to the value specified in the
471       constructor, or to 1.0 if it was not specified.  This can be overridden
472       by providing a 'version' key in @args.  If you do not want the version
473       at all, explicitly provide undef as the value in @args.
474
475       By default, the encoding is set to the value specified in the
476       constructor; if no value was specified, the encoding will be left out
477       altogether.  Provide an 'encoding' key in @args to override this.
478
479       If a dtd was set in the constructor, the standalone attribute of the
480       declaration will be set to 'no' and the doctype declaration will be
481       appended to the XML declartion, otherwise the standalone attribute will
482       be set to 'yes'.  This can be overridden by providing a 'standalone'
483       key in @args.  If you do not want the standalone attribute to show up,
484       explicitly provide undef as the value.
485
486   xmldtd
487       DTD <!DOCTYPE> tag creation. The format of this method is different
488       from others. Since DTD's are global and cannot contain namespace
489       information, the first argument should be a reference to an array; the
490       elements are concatenated together to form the DTD:
491
492          print $xml->xmldtd([ 'html', 'PUBLIC', $xhtml_w3c, $xhtml_dtd ])
493
494       This would produce the following declaration:
495
496          <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
497               "DTD/xhtml1-transitional.dtd">
498
499       Assuming that $xhtml_w3c and $xhtml_dtd had the correct values.
500
501       Note that you can also specify a DTD on creation using the new()
502       method's dtd option.
503
504   xmlcdata
505       Character data section; arguments are concatenated and placed inside
506       <![CDATA[ ... ]]> character data section delimiters.  Any occurences of
507       ']]>' in the concatenated arguments are converted to ']]&gt;'.
508
509   xml
510       "Final" XML document.  Must be called with one and exactly one
511       XML::Generator-produced XML document.  Any combination of
512       XML::Generator-produced XML comments or processing instructions may
513       also be supplied as arguments.  Prepends an XML declaration, and re-
514       blesses the argument into a "final" class that can't be embedded.
515

CREATING A SUBCLASS

517       For a simpler way to implement subclass-like behavior, see "STACKABLE
518       AUTOLOADs".
519
520       At times, you may find it desireable to subclass XML::Generator. For
521       example, you might want to provide a more application-specific
522       interface to the XML generation routines provided. Perhaps you have a
523       custom database application and would really like to say:
524
525          my $dbxml = new XML::Generator::MyDatabaseApp;
526          print $dbxml->xml($dbxml->custom_tag_handler(@data));
527
528       Here, custom_tag_handler() may be a method that builds a recursive XML
529       structure based on the contents of @data. In fact, it may even be named
530       for a tag you want generated, such as authors(), whose behavior changes
531       based on the contents (perhaps creating recursive definitions in the
532       case of multiple elements).
533
534       Creating a subclass of XML::Generator is actually relatively
535       straightforward, there are just three things you have to remember:
536
537          1. All of the useful utilities are in XML::Generator::util.
538
539          2. To construct a tag you simply have to call SUPER::tagname,
540             where "tagname" is the name of your tag.
541
542          3. You must fully-qualify the methods in XML::Generator::util.
543
544       So, let's assume that we want to provide a custom HTML table() method:
545
546          package XML::Generator::CustomHTML;
547          use base 'XML::Generator';
548
549          sub table {
550              my $self = shift;
551
552              # parse our args to get namespace and attribute info
553              my($namespace, $attr, @content) =
554                 $self->XML::Generator::util::parse_args(@_)
555
556              # check for strict conformance
557              if ( $self->XML::Generator::util::config('conformance') eq 'strict' ) {
558                 # ... special checks ...
559              }
560
561              # ... special formatting magic happens ...
562
563              # construct our custom tags
564              return $self->SUPER::table($attr, $self->tr($self->td(@content)));
565          }
566
567       That's pretty much all there is to it. We have to explicitly call
568       SUPER::table() since we're inside the class's table() method. The
569       others can simply be called directly, assuming that we don't have a
570       tr() in the current package.
571
572       If you want to explicitly create a specific tag by name, or just want a
573       faster approach than AUTOLOAD provides, you can use the tag() method
574       directly. So, we could replace that last line above with:
575
576              # construct our custom tags
577              return $self->XML::Generator::util::tag('table', $attr, ...);
578
579       Here, we must explicitly call tag() with the tag name itself as its
580       first argument so it knows what to generate. These are the methods that
581       you might find useful:
582
583       XML::Generator::util::parse_args()
584           This parses the argument list and returns the namespace (arrayref),
585           attributes (hashref), and remaining content (array), in that order.
586
587       XML::Generator::util::tag()
588           This does the work of generating the appropriate tag. The first
589           argument must be the name of the tag to generate.
590
591       XML::Generator::util::config()
592           This retrieves options as set via the new() method.
593
594       XML::Generator::util::escape()
595           This escapes any illegal XML characters.
596
597       Remember that all of these methods must be fully-qualified with the
598       XML::Generator::util package name. This is because AUTOLOAD is used by
599       the main XML::Generator package to create tags. Simply calling
600       parse_args() will result in a set of XML tags called <parse_args>.
601
602       Finally, remember that since you are subclassing XML::Generator, you do
603       not need to provide your own new() method. The one from XML::Generator
604       is designed to allow you to properly subclass it.
605

STACKABLE AUTOLOADs

607       As a simpler alternative to traditional subclassing, the "AUTOLOAD"
608       that "use XML::Generator;" exports can be configured to work with a
609       pre-defined "AUTOLOAD" with the ':stacked' option.  Simply ensure that
610       your "AUTOLOAD" is defined before "use XML::Generator ':stacked';"
611       executes.  The "AUTOLOAD" will get a chance to run first; the
612       subroutine name will be in your $AUTOLOAD as normal.  Return an empty
613       list to let the default XML::Generator "AUTOLOAD" run or any other
614       value to abort it.  This value will be returned as the result of the
615       original method call.
616
617       If there is no "import" defined, XML::Generator will create one.  All
618       that this "import" does is export AUTOLOAD, but that lets your package
619       be used as if it were a subclass of XML::Generator.
620
621       An example will help:
622
623               package MyGenerator;
624
625               my %entities = ( copy => '&copy;',
626                                nbsp => '&nbsp;', ... );
627
628               sub AUTOLOAD {
629                 my($tag) = our $AUTOLOAD =~ /.*::(.*)/;
630
631                 return $entities{$tag} if defined $entities{$tag};
632                 return;
633               }
634
635               use XML::Generator qw(:pretty :stacked);
636
637       This lets someone do:
638
639               use MyGenerator;
640
641               print html(head(title("My Title", copy())));
642
643       Producing:
644
645               <html>
646                 <head>
647                   <title>My Title&copy;</title>
648                 </head>
649               </html>
650

AUTHORS

652       Benjamin Holzman <bholzman@earthlink.net>
653           Original author and maintainer
654
655       Bron Gondwana <perlcode@brong.net>
656           First modular version
657
658       Nathan Wiger <nate@nateware.com>
659           Modular rewrite to enable subclassing
660