Devil Killer Is Here MiNi Shell
MiNi SheLL

Current Path : /proc/thread-self/root/usr/local/man/man3/
Linux boscustweb5004.eigbox.net 5.4.91 #1 SMP Wed Jan 20 18:10:28 EST 2021 x86_64
Current File : //proc/thread-self/root/usr/local/man/man3/XML::Generator.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Generator 3"
.TH Generator 3 "2004-03-23" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
XML::Generator \- Perl extension for generating XML
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use XML::Generator ':pretty';
.Ve
.PP
.Vb 3
\&  print foo(bar({ baz => 3 }, bam()),
\&            bar([ 'qux' => 'http://qux.com/' ],
\&                  "Hey there, world"));
.Ve
.PP
.Vb 1
\&  # OR
.Ve
.PP
.Vb 1
\&  use XML::Generator ();
.Ve
.PP
.Vb 1
\&  my $X = XML::Generator->new(':pretty');
.Ve
.PP
.Vb 3
\&  print $X->foo($X->bar({ baz => 3 }, $X->bam()),
\&                $X->bar([ 'qux' => 'http://qux.com/' ],
\&                          "Hey there, world"));
.Ve
.PP
Either of the above yield:
.PP
.Vb 6
\&   <foo xmlns:qux="http://qux.com/">
\&     <bar baz="3">
\&       <bam />
\&     </bar>
\&     <qux:bar>Hey there, world</qux:bar>
\&   </foo>
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
In general, once you have an XML::Generator object, you then simply call
methods on that object named for each \s-1XML\s0 tag you wish to generate. 
.PP
By default, \f(CW\*(C`use XML::Generator;\*(C'\fR tries to export an \f(CW\*(C`AUTOLOAD\*(C'\fR
subroutine to your package, which allows you to simply call any undefined
methods in your current package to get pieces of \s-1XML\s0.  If you already
have an \f(CW\*(C`AUTOLOAD\*(C'\fR defined then XML::Generator will not override it
unless you tell it to.  See \*(L"\s-1STACKABLE\s0 AUTOLOADs\*(R".
.PP
Say you want to generate this \s-1XML:\s0
.PP
.Vb 5
\&   <person>
\&     <name>Bob</name>
\&     <age>34</age>
\&     <job>Accountant</job>
\&   </person>
.Ve
.PP
Here's a snippet of code that does the job, complete with pretty printing:
.PP
.Vb 7
\&   use XML::Generator;
\&   my $gen = XML::Generator->new(':pretty');
\&   print $gen->person(
\&            $gen->name("Bob"),
\&            $gen->age(34),
\&            $gen->job("Accountant")
\&         );
.Ve
.PP
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 \*(L"shoe\-size\*(R".  Fortunately,
since you can always call methods as variable names, there's a simple
work\-around:
.PP
.Vb 2
\&   my $shoe_size = "shoe-size";
\&   $xml = $gen->$shoe_size("12 1/2");
.Ve
.PP
Which correctly generates:
.PP
.Vb 1
\&   <shoe-size>12 1/2</shoe-size>
.Ve
.PP
You can use a hash ref as the first parameter if the tag should include
atributes.  Normally this means that the order of the attributes will be
unpredictable, but if you have the Tie::IxHash module, you can use it
to get the order you want, like this:
.PP
.Vb 2
\&  use Tie::IxHash;
\&  tie my %attr, 'Tie::IxHash';
.Ve
.PP
.Vb 4
\&  %attr = (name => 'Bob', 
\&           age  => 34,
\&           job  => 'Accountant',
\&    'shoe-size' => '12 1/2');
.Ve
.PP
.Vb 1
\&  print $gen->person(\e%attr);
.Ve
.PP
This produces
.PP
.Vb 1
\&  <person name="Bob" age="34" job="Accountant" shoe-size="12 1/2" />
.Ve
.PP
An array ref can also be supplied as the first argument to indicate
a namespace for the element and the attributes.
.PP
\&\fB\s-1WARNING\s0! ** \s-1BACKWARDS\s0 \s-1INCOMPATIBILITY\s0 **\fR
.PP
As of version 0.94, the semantics of namespaces have changed.  Now, if there is
one element in the array, it is considered the \s-1URI\s0 of the default namespace, and
the tag will have an xmlns=\*(L"\s-1URI\s0\*(R" attribute added automatically.  If there are two
elements, the first should be the tag prefix to use for the namespace and the
second element should be the \s-1URI\s0.  In this case, the prefix will be used for
the tag and an xmlns:PREFIX attribute will be automatically added.  Prior to version
0.99, this prefix was also automatically added to each attribute name.  Now, the
default behavior is to leave the attributes alone (although you may always explicitly
add a prefix to an attribute name).  If the prior behavior is desired, use the
constructor option \f(CW\*(C`qualifiedAttributes\*(C'\fR.
.PP
It is an error to supply more than two elements in a namespace.
.PP
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.
.PP
Here's an example to show how the attribute and namespace parameters work:
.PP
.Vb 4
\&   $xml = $gen->account(
\&            $gen->open(['transaction'], 2000),
\&            $gen->deposit(['transaction'], { date => '1999.04.03'}, 1500)
\&          );
.Ve
.PP
This generates:
.PP
.Vb 4
\&   <account>
\&     <open xmlns="transaction">2000</open>
\&     <deposit xmlns="transaction" date="1999.04.03">1500</deposit>
\&   </account>
.Ve
.PP
Because default namespaces inherit, XML::Generator takes care to output
the xmlns=\*(L"\s-1URI\s0\*(R" attribute as few times as strictly necessary.  For example,
.PP
.Vb 6
\&   $xml = $gen->account(
\&            $gen->open(['transaction'], 2000),
\&            $gen->deposit(['transaction'], { date => '1999.04.03'},
\&              $gen->amount(['transaction'], 1500)
\&            )
\&          );
.Ve
.PP
This generates:
.PP
.Vb 6
\&   <account>
\&     <open xmlns="transaction">2000</open>
\&     <deposit xmlns="transaction" date="1999.04.03">
\&       <amount>1500</amount>
\&     </deposit>
\&   </account>
.Ve
.PP
Notice how \f(CW\*(C`xmlns="transaction"\*(C'\fR was left out of the \f(CW\*(C`<amount\*(C'\fR> tag.
.PP
Here is an example that uses the two-argument form of the namespace:
.PP
.Vb 2
\&    $xml = $gen->widget(['wru' => 'http://www.widgets-r-us.com/xml/'],
\&                        {'id'  => 123}, $gen->contents());
.Ve
.PP
.Vb 3
\&    <wru:widget xmlns:wru="http://www.widgets-r-us.com/xml/" id="123">
\&      <contents />
\&    </wru:widget>
.Ve
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
XML::Generator\->new(':option', ...);
.PP
XML::Generator\->new(option => 'value', ...);
.PP
(Both styles may be combined)
.PP
The following options are available:
.Sh ":std, :standard"
.IX Subsection ":std, :standard"
Equivalent to 
.PP
.Vb 2
\&        escape      => 'always',
\&        conformance => 'strict',
.Ve
.Sh ":strict"
.IX Subsection ":strict"
Equivalent to
.PP
.Vb 1
\&        conformance => 'strict',
.Ve
.Sh ":pretty[=N]"
.IX Subsection ":pretty[=N]"
Equivalent to
.PP
.Vb 3
\&        escape      => 'always',
\&        conformance => 'strict',
\&        pretty      => N         # N defaults to 2
.Ve
.Sh ":[no]import"
.IX Subsection ":[no]import"
Force the exporting behavior of \f(CW\*(C`use XML::Generator;\*(C'\fR.  Generates a
warning when passed as an argument to \f(CW\*(C`new\*(C'\fR.
.Sh ":stacked"
.IX Subsection ":stacked"
Implies :import, but if there is already an \f(CW\*(C`AUTOLOAD\*(C'\fR defined, the
overriding \f(CW\*(C`AUTOLOAD\*(C'\fR will still give it a chance to run.  See \*(L"\s-1STACKED\s0 AUTOLOADs\*(R". Generates a warning when passed as an argument to \f(CW\*(C`new\*(C'\fR.
.Sh "namespace"
.IX Subsection "namespace"
\&\fB\s-1WARNING\s0! ** \s-1BACKWARDS\s0 \s-1INCOMPATIBILITY\s0 **\fR
.PP
As of version 0.94, this must be an array reference containing one or
two values.  If the array contains one value, it should be a \s-1URI\s0 and will
be the value of an 'xmlns' attribute in the top-level tag.  If there
are two elements, the first should be the namespace tag prefix and the
second the \s-1URI\s0 of the namespace.  This will enable behavior similar
to the namespace behavior in previous versions; the tag prefix will be
applied to each tag.  In addition, an xmlns:NAME=\*(L"\s-1URI\s0\*(R" attribute will be
added to the top-level tag.  Prior to version 0.99, the tag prefix was also
automatically added to each attribute name, unless overridden with an explicit
prefix.  Now, the attribute names are left alone, but if the prior behavior is
desired, use the constructor option \f(CW\*(C`qualifiedAttributes\*(C'\fR.
.PP
The value of this option is used as the global default namespace.
For example,
.PP
.Vb 7
\&    my $html = XML::Generator->new(
\&                 pretty    => 2,
\&                 namespace => [HTML => "http://www.w3.org/TR/REC-html40"]);
\&    print $html->html(
\&            $html->body(
\&              $html->font({ face => 'Arial' },
\&                          "Hello, there")));
.Ve
.PP
would yield
.PP
.Vb 5
\&    <HTML:html xmlns:HTML="http://www.w3.org/TR/REC-html40">
\&      <HTML:body>
\&        <HTML:font face="Arial">Hello, there</HTML:font>
\&      </HTML:body>
\&    </HTML:html>
.Ve
.PP
Here is the same example except without all the prefixes:
.PP
.Vb 7
\&    my $html = XML::Generator->new(
\&                 pretty    => 2,
\&                 namespace => ["http://www.w3.org/TR/REC-html40"]);
\&    print $html->html(
\&            $html->body(
\&              $html->font({ 'face' => 'Arial' },
\&                            "Hello, there")));
.Ve
.PP
would yield
.PP
.Vb 5
\&   <html xmlns="http://www.w3.org/TR/REC-html40">
\&     <body>
\&        <font face="Arial">Hello, there</font>
\&     </body>
\&   </html>
.Ve
.Sh "qualifiedAttributes"
.IX Subsection "qualifiedAttributes"
Set this to a true value to emulate the attribute prefixing behavior of
XML::Generator prior to version 0.99.  Here is an example:
.PP
.Vb 4
\&    my $foo = XML::Generator->new(
\&                namespace => [foo => "http://foo.com/"],
\&                qualifiedAttributes => 1);
\&    print $foo->bar({baz => 3});
.Ve
.PP
yields
.PP
.Vb 1
\&    <foo:bar xmlns:foo="http://foo.com/" foo:baz="3" />
.Ve
.Sh "escape"
.IX Subsection "escape"
The contents and the values of each attribute have any illegal \s-1XML\s0
characters escaped if this option is supplied.  If the value is 'always',
then &, < and > (and " within attribute values) will be converted into
the corresponding \s-1XML\s0 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,
.PP
.Vb 1
\&        use XML::Generator escape => 'always';
.Ve
.PP
.Vb 3
\&        one('<');    # <one>&lt;</one>
\&        two('\e&');   # <two>\e&amp;</two>
\&        three(\e'>'); # <three>&gt;</three> (scalar refs always allowed)
.Ve
.PP
but
.PP
.Vb 1
\&        use XML::Generator escape => 1;
.Ve
.PP
.Vb 3
\&        one('<');    # <one>&lt;</one>
\&        two('\e&');   # <two>&</two>
\&        three(\e'>'); # <three>></three> (aiee!)
.Ve
.PP
By default, high-bit data will be passed through unmodified, so that
\&\s-1UTF\-8\s0 data can be generated with pre-Unicode perls.  If you know that
your data is \s-1ASCII\s0, use the value 'high\-bit' for the escape option
and bytes with the high bit set will be turned into numeric entities.
You can combine this functionality with the other escape options by
comma-separating the values:
.PP
.Vb 2
\&  my $a = XML::Generator->new(escape => 'always,high-bit');
\&  print $a->foo("<\e242>");
.Ve
.PP
yields
.PP
.Vb 1
\&  <foo>&lt;&#162;&gt;</foo>
.Ve
.PP
Because XML::Generator always uses double quotes ("") around attribute
values, it does not escape single quotes.  If you want single quotes
inside attribute values to be escaped, use the value 'apos' along with
\&'always' or 'true' for the escape option.  For example:
.PP
.Vb 2
\&    my $gen = XML::Generator->new(escape => 'always,apos');
\&    print $gen->foo({'bar' => "It's all good"});
.Ve
.PP
.Vb 1
\&    <foo bar="It&apos;s all good" />
.Ve
.Sh "pretty"
.IX Subsection "pretty"
To have nice pretty printing of the output \s-1XML\s0 (great for config files
that you might also want to edit by hand), supply an integer for the
number of spaces per level of indenting, eg.
.PP
.Vb 3
\&   my $gen = XML::Generator->new(pretty => 2);
\&   print $gen->foo($gen->bar('baz'),
\&                   $gen->qux({ tricky => 'no'}, 'quux'));
.Ve
.PP
would yield
.PP
.Vb 4
\&   <foo>
\&     <bar>baz</bar>
\&     <qux tricky="no">quux</qux>
\&   </foo>
.Ve
.PP
You may also supply a non-numeric string as the argument to 'pretty', in
which case the indents will consist of repetitions of that string.  So if
you want tabbed indents, you would use:
.PP
.Vb 1
\&     my $gen = XML::Generator->new(pretty => "\et");
.Ve
.PP
Pretty printing does not apply to \s-1CDATA\s0 sections or Processing Instructions.
.Sh "conformance"
.IX Subsection "conformance"
If the value of this option is 'strict', a number of syntactic
checks are performed to ensure that generated \s-1XML\s0 conforms to the
formal \s-1XML\s0 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, xmldtd, xmlcdata,
and xml to allow generation of processing instructions, comments, \s-1XML\s0
declarations, \s-1DTD\s0's, character data sections and \*(L"final\*(R" \s-1XML\s0 documents,
respectively.
.PP
See \*(L"\s-1XML\s0 \s-1CONFORMANCE\s0\*(R" and \*(L"\s-1SPECIAL\s0 \s-1TAGS\s0\*(R" for more information.
.Sh "allowed_xml_tags"
.IX Subsection "allowed_xml_tags"
If you have specified 'conformance' => 'strict' but need to use tags
that start with 'xml', you can supply a reference to an array containing
those tags and they will be accepted without error.  It is not an error
to supply this option if 'conformance' => 'strict' is not supplied,
but it will have no effect.
.Sh "empty"
.IX Subsection "empty"
There are 5 possible values for this option:
.PP
.Vb 5
\&   self    -  create empty tags as <tag />  (default)
\&   compact -  create empty tags as <tag/>
\&   close   -  close empty tags as <tag></tag>
\&   ignore  -  don't do anything (non-compliant!)
\&   args    -  use count of arguments to decide between <x /> and <x></x>
.Ve
.PP
Many web browsers like the 'self' form, but any one of the forms besides
\&'ignore' is acceptable under the \s-1XML\s0 standard.
.PP
\&'ignore' is intended for subclasses that deal with \s-1HTML\s0 and other
\&\s-1SGML\s0 subsets which allow atomic tags.  It is an error to specify both
\&'conformance' => 'strict' and 'empty' => 'ignore'.
.PP
\&'args' will produce <x /> if there are no arguments at all, or if there
is just a single undef argument, and <x></x> otherwise.
.Sh "version"
.IX Subsection "version"
Sets the default \s-1XML\s0 version for use in \s-1XML\s0 declarations.
See \*(L"xmldecl\*(R" below.
.Sh "encoding"
.IX Subsection "encoding"
Sets the default encoding for use in \s-1XML\s0 declarations.
.Sh "dtd"
.IX Subsection "dtd"
Specify the dtd.  The value should be an array reference with three
values; the type, the name and the uri.
.SH "XML CONFORMANCE"
.IX Header "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 \s-1XML\s0 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 \*(L"\s-1SPECIAL\s0 \s-1TAGS\s0\*(R"). Note that you can also supply an explicit
list of allowed tags with the 'allowed_xml_tags' option.
.SH "SPECIAL TAGS"
.IX Header "SPECIAL TAGS"
The following special tags are available when running under strict
conformance (otherwise they don't act special):
.Sh "xmlpi"
.IX Subsection "xmlpi"
Processing instruction; first argument is target, remaining arguments
are attribute, value pairs.  Attribute names are syntax checked, values
are escaped.
.Sh "xmlcmnt"
.IX Subsection "xmlcmnt"
Comment.  Arguments are concatenated and placed inside <!\-\- ... \-\-> comment
delimiters.  Any occurences of '\-\-' in the concatenated arguments are
converted to '&#45;&#45;'
.Sh "xmldecl(@args)"
.IX Subsection "xmldecl(@args)"
Declaration.  This can be used to specify the version, encoding, and other
XML-related declarations (i.e., anything inside the <?xml?> tag).  \f(CW@args\fR can
be used to control what is output, as keyword-value pairs.
.PP
By default, the version is set to the value specified in the constructor, or
to 1.0 if it was not specified.  This can be overridden by providing a 'version'
key in \f(CW@args\fR.  If you do not want the version at all, explicitly provide undef
as the value in \f(CW@args\fR.
.PP
By default, the encoding is set to the value specified in the constructor; if
no value was specified, the encoding will be left out altogether.  Provide an
\&'encoding' key in \f(CW@args\fR to override this.
.PP
If a dtd was set in the constructor, the standalone attribute of the declaration
will be set to 'no' and the doctype declaration will be appended to the \s-1XML\s0
declartion, otherwise the standalone attribute will be set to 'yes'.  This can be
overridden by providing a 'standalone' key in \f(CW@args\fR.  If you do not want the
standalone attribute to show up, explicitly provide undef as the value.
.Sh "xmldtd"
.IX Subsection "xmldtd"
\&\s-1DTD\s0 <!DOCTYPE> tag creation. The format of this method is different from 
others. Since \s-1DTD\s0's are global and cannot contain namespace information,
the first argument should be a reference to an array; the elements are
concatenated together to form the \s-1DTD:\s0
.PP
.Vb 1
\&   print $xml->xmldtd([ 'html', 'PUBLIC', $xhtml_w3c, $xhtml_dtd ])
.Ve
.PP
This would produce the following declaration:
.PP
.Vb 2
\&   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
\&        "DTD/xhtml1-transitional.dtd">
.Ve
.PP
Assuming that \f(CW$xhtml_w3c\fR and \f(CW$xhtml_dtd\fR had the correct values.
.PP
Note that you can also specify a \s-1DTD\s0 on creation using the \fInew()\fR method's
dtd option.
.Sh "xmlcdata"
.IX Subsection "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 ']]&gt;'.
.Sh "xml"
.IX Subsection "xml"
\&\*(L"Final\*(R" \s-1XML\s0 document.  Must be called with one and exactly one
XML::Generator\-produced \s-1XML\s0 document.  Any combination of
XML::Generator\-produced \s-1XML\s0 comments or processing instructions may
also be supplied as arguments.  Prepends an \s-1XML\s0 declaration, and
re-blesses the argument into a \*(L"final\*(R" class that can't be embedded.
.SH "CREATING A SUBCLASS"
.IX Header "CREATING A SUBCLASS"
For a simpler way to implement subclass-like behavior, see \*(L"\s-1STACKABLE\s0 AUTOLOADs\*(R".
.PP
At times, you may find it desireable to subclass XML::Generator. For
example, you might want to provide a more application-specific interface
to the \s-1XML\s0 generation routines provided. Perhaps you have a custom
database application and would really like to say:
.PP
.Vb 2
\&   my $dbxml = new XML::Generator::MyDatabaseApp;
\&   print $dbxml->xml($dbxml->custom_tag_handler(@data));
.Ve
.PP
Here, \fIcustom_tag_handler()\fR may be a method that builds a recursive \s-1XML\s0
structure based on the contents of \f(CW@data\fR. In fact, it may even be named
for a tag you want generated, such as \fIauthors()\fR, whose behavior changes
based on the contents (perhaps creating recursive definitions in the
case of multiple elements).
.PP
Creating a subclass of XML::Generator is actually relatively
straightforward, there are just three things you have to remember:
.PP
.Vb 1
\&   1. All of the useful utilities are in XML::Generator::util.
.Ve
.PP
.Vb 2
\&   2. To construct a tag you simply have to call SUPER::tagname,
\&      where "tagname" is the name of your tag.
.Ve
.PP
.Vb 1
\&   3. You must fully-qualify the methods in XML::Generator::util.
.Ve
.PP
So, let's assume that we want to provide a custom \s-1HTML\s0 \fItable()\fR method:
.PP
.Vb 2
\&   package XML::Generator::CustomHTML;
\&   use base 'XML::Generator';
.Ve
.PP
.Vb 2
\&   sub table {
\&       my $self = shift;
.Ve
.PP
.Vb 3
\&       # parse our args to get namespace and attribute info
\&       my($namespace, $attr, @content) =
\&          $self->XML::Generator::util::parse_args(@_)
.Ve
.PP
.Vb 4
\&       # check for strict conformance
\&       if ( $self->XML::Generator::util::config('conformance') eq 'strict' ) {
\&          # ... special checks ...
\&       }
.Ve
.PP
.Vb 1
\&       # ... special formatting magic happens ...
.Ve
.PP
.Vb 3
\&       # construct our custom tags
\&       return $self->SUPER::table($attr, $self->tr($self->td(@content)));
\&   }
.Ve
.PP
That's pretty much all there is to it. We have to explicitly call
\&\fISUPER::table()\fR since we're inside the class's \fItable()\fR method. The others
can simply be called directly, assuming that we don't have a \fItr()\fR in the
current package.
.PP
If you want to explicitly create a specific tag by name, or just want a
faster approach than \s-1AUTOLOAD\s0 provides, you can use the \fItag()\fR method
directly. So, we could replace that last line above with:
.PP
.Vb 2
\&       # construct our custom tags 
\&       return $self->XML::Generator::util::tag('table', $attr, ...);
.Ve
.PP
Here, we must explicitly call \fItag()\fR with the tag name itself as its first
argument so it knows what to generate. These are the methods that you might
find useful:
.IP "\fIXML::Generator::util::parse_args()\fR" 4
.IX Item "XML::Generator::util::parse_args()"
This parses the argument list and returns the namespace (arrayref), attributes
(hashref), and remaining content (array), in that order.
.IP "\fIXML::Generator::util::tag()\fR" 4
.IX Item "XML::Generator::util::tag()"
This does the work of generating the appropriate tag. The first argument must
be the name of the tag to generate.
.IP "\fIXML::Generator::util::config()\fR" 4
.IX Item "XML::Generator::util::config()"
This retrieves options as set via the \fInew()\fR method.
.IP "\fIXML::Generator::util::escape()\fR" 4
.IX Item "XML::Generator::util::escape()"
This escapes any illegal \s-1XML\s0 characters.
.PP
Remember that all of these methods must be fully-qualified with the
XML::Generator::util package name. This is because \s-1AUTOLOAD\s0 is used by 
the main XML::Generator package to create tags. Simply calling \fIparse_args()\fR
will result in a set of \s-1XML\s0 tags called <parse_args>.
.PP
Finally, remember that since you are subclassing XML::Generator, you do
not need to provide your own \fInew()\fR method. The one from XML::Generator
is designed to allow you to properly subclass it.
.SH "STACKABLE AUTOLOADs"
.IX Header "STACKABLE AUTOLOADs"
As a simpler alternative to traditional subclassing, the \f(CW\*(C`AUTOLOAD\*(C'\fR
that \f(CW\*(C`use XML::Generator;\*(C'\fR exports can be configured to work with a
pre-defined \f(CW\*(C`AUTOLOAD\*(C'\fR with the ':stacked' option.  Simply ensure that
your \f(CW\*(C`AUTOLOAD\*(C'\fR is defined before \f(CW\*(C`use XML::Generator ':stacked';\*(C'\fR
executes.  The \f(CW\*(C`AUTOLOAD\*(C'\fR will get a chance to run first; the subroutine
name will be in your \f(CW$AUTOLOAD\fR as normal.  Return an empty list to let
the default XML::Generator \f(CW\*(C`AUTOLOAD\*(C'\fR run or any other value to abort it.
This value will be returned as the result of the original method call.
.PP
If there is no \f(CW\*(C`import\*(C'\fR defined, XML::Generator will create one.
All that this \f(CW\*(C`import\*(C'\fR does is export \s-1AUTOLOAD\s0, but that lets your
package be used as if it were a subclass of XML::Generator.
.PP
An example will help:
.PP
.Vb 1
\&        package MyGenerator;
.Ve
.PP
.Vb 2
\&        my %entities = ( copy => '&copy;',
\&                         nbsp => '&nbsp;', ... );
.Ve
.PP
.Vb 2
\&        sub AUTOLOAD {
\&          my($tag) = our $AUTOLOAD =~ /.*::(.*)/;
.Ve
.PP
.Vb 3
\&          return $entities{$tag} if defined $entities{$tag};
\&          return;
\&        }
.Ve
.PP
.Vb 1
\&        use XML::Generator qw(:pretty :stacked);
.Ve
.PP
This lets someone do:
.PP
.Vb 1
\&        use MyGenerator;
.Ve
.PP
.Vb 1
\&        print html(head(title("My Title", copy())));
.Ve
.PP
Producing:
.PP
.Vb 5
\&        <html>
\&          <head>
\&            <title>My Title&copy;</title>
\&          </head>
\&        </html>
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "Benjamin Holzman <bholzman@earthlink.net>" 4
.IX Item "Benjamin Holzman <bholzman@earthlink.net>"
Original author and maintainer
.IP "Bron Gondwana <perlcode@brong.net>" 4
.IX Item "Bron Gondwana <perlcode@brong.net>"
First modular version
.IP "Nathan Wiger <nate@nateware.com>" 4
.IX Item "Nathan Wiger <nate@nateware.com>"
Modular rewrite to enable subclassing
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "The XML::Writer module" 4
.IX Item "The XML::Writer module"
http://search.cpan.org/search?mode=module&query=XML::Writer
.IP "The XML::Handler::YAWriter module" 4
.IX Item "The XML::Handler::YAWriter module"
http://search.cpan.org/search?mode=module&query=XML::Handler::YAWriter
Creat By MiNi SheLL
Email: devilkiller@gmail.com