.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PerlData 3pm"
.TH PerlData 3pm "2022-11-20" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::Generator::PerlData \- Perl extension for generating SAX2 events from nested Perl data structures.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use XML::Generator::PerlData;
\&  use SomeSAX2HandlerOrFilter;
\&
\&  ## Simple style ##
\&
\&  # get a deeply nested Perl data structure...
\&  my $hash_ref = $obj\->getScaryNestedDataStructure();
\&
\&  # create an instance of a handler class to forward events to...
\&  my $handler = SomeSAX2HandlerOrFilter\->new();
\&
\&  # create an instance of the PerlData driver...
\&  my $driver  = XML::Generator::PerlData\->new( Handler => $handler );
\&
\&  # generate XML from the data structure...
\&  $driver\->parse( $hash_ref );
\&
\&
\&  ## Or, Stream style ##
\&
\&  use XML::Generator::PerlData;
\&  use SomeSAX2HandlerOrFilter;
\&
\&  # create an instance of a handler class to forward events to...
\&  my $handler = SomeSAX2HandlerOrFilter\->new();
\&
\&  # create an instance of the PerlData driver...
\&  my $driver  = XML::Generator::PerlData\->new( Handler => $handler );
\&
\&  # start the event stream...
\&  $driver\->parse_start();
\&
\&  # pass the data through in chunks
\&  # (from a database handle here)
\&  while ( my $array_ref = $dbd_sth\->fetchrow_arrayref ) {
\&      $driver\->parse_chunk( $array_ref );
\&  }
\&
\&  # end the event stream...
\&  $driver\->parse_end();
.Ve
.PP
and you're done...
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
XML::Generator::PerlData provides a simple way to generate \s-1SAX2\s0 events
from nested Perl data structures, while providing finer-grained control
over the resulting document streams.
.PP
Processing comes in two flavors: \fBSimple Style\fR and \fBStream Style\fR:
.PP
In a nutshell, 'simple style' is best used for those cases where you have a single
Perl data structure that you want to convert to \s-1XML\s0 as quickly and painlessly as possible. 'Stream
style' is more useful for cases where you are receiving chunks of data (like from a \s-1DBI\s0 handle)
and you want to process those chunks as they appear. See \fB\s-1PROCESSING METHODS\s0\fR for more info about
how each style works.
.SH "CONSTRUCTOR METHOD AND CONFIGURATION OPTIONS"
.IX Header "CONSTRUCTOR METHOD AND CONFIGURATION OPTIONS"
.SS "new"
.IX Subsection "new"
(class constructor)
.PP
\&\fBAccepts:\fR An optional hash of configuration options.
.PP
\&\fBReturns:\fR A new instance of the XML::Generator::PerlData class.
.PP
Creates a new instance of XML::Generator::PerlData.
.PP
While basic usage of this module is designed to be simple and straightforward,
there is a small host of options available to help ensure that the \s-1SAX\s0 event streams
(and by extension the \s-1XML\s0 documents) that are created from the data structures you
pass are in just the format that you want.
.PP
\fIOptions\fR
.IX Subsection "Options"
.IP "\(bu" 4
\&\fBHandler\fR (required)
.Sp
XML::Generator::PerlData is a \s-1SAX\s0 Driver/Generator. As such, it
needs a \s-1SAX\s0 Handler or Filter class to forward its events to. The value for this
option must be an instance of a SAX2\-aware Handler or Filter.
.IP "\(bu" 4
\&\fBrootname\fR (optional)
.Sp
Sets the name of the top-level (root) element. The default is 'document'.
.IP "\(bu" 4
\&\fBdefaultname\fR (optional)
.Sp
Sets the default name to be used for elements when no other logical name
is available (think lists-of-lists). The default is 'default'.
.IP "\(bu" 4
\&\fBkeymap\fR (optional)
.Sp
Often, the names of the keys in a given hash do not map directly to the \s-1XML\s0
elements names that you want to appear in the resulting document. The option
contains a set of keyname\->element name mappings for the current process.
.IP "\(bu" 4
\&\fBskipelements\fR (optional)
.Sp
Passed in as an array reference, this option sets the internal list of keynames
that will be skipped over during processing. Note that any descendant structures
belonging to those keys will also be skipped.
.IP "\(bu" 4
\&\fBattrmap\fR (optional)
.Sp
Used to determine which 'children' of a given hash key/element\-name will
be forwarded as attributes of that element rather than as child elements.
.Sp
(see \s-1CAVEATS\s0 for a discussion of the limitations of this method.)
.IP "\(bu" 4
\&\fBnamespaces\fR (optional)
.Sp
Sets the internal list of namespace/prefix pairs for the current process. It takes
the form of a hash, where the keys are the URIs of the given namespace and the
values are the associated prefix.
.Sp
To set a default (unprefixed) namespace, set the prefix to '#default'.
.IP "\(bu" 4
\&\fBnamespacemap\fR (optional)
.Sp
Sets which elements in the result will be bound to which declared namespaces. It
takes the form of a hash of key/value pairs where the keys are one of the declared
namespace URIs that are relevant to the current process and the values are either
single key/element names or an array reference of key/element names.
.IP "\(bu" 4
\&\fBskiproot\fR (optional)
.Sp
When set to a defined value, this option blocks the generator from adding
the top-level root element when \fBparse()\fR or \fBparse_start()\fR and \fBparse_end()\fR
are called.
.Sp
\&\fIDo not\fR use this option unless you are absolutely sure you know what you
are doing and why, since the resulting event stream will most likely
produce non-well-formed \s-1XML.\s0
.IP "\(bu" 4
\&\fBbindattrs\fR (optional)
.Sp
When set to a defined value, this option tells the generator to bind attributes
to the same namespace as element that contains them. By default attributes will
be unbound and unprefixed.
.IP "\(bu" 4
\&\fBprocessing_instructions\fR (optional)
.Sp
This option provides a way to include \s-1XML\s0 processing instructions events into
the generated stream before the root element is emitted. The value of this key
can be either a hash reference or an array reference of hash references.
For example, when connected to XML::SAX::Writer:
.Sp
.Vb 8
\&    $pd\->new( Handler => $writer_instance,
\&              rootname => \*(Aqdocument\*(Aq,
\&              processing_instructions => {
\&                \*(Aqxml\-stylesheet\*(Aq => {
\&                     href => \*(Aq/path/to/stylesheet.xsl\*(Aq,
\&                     type => \*(Aqtext/xml\*(Aq,
\&                 },
\&              });
.Ve
.Sp
would generate
.Sp
.Vb 4
\&  <?xml version="1.0"?>
\&  <?xml\-stylesheet href="/path/to/stylesheet.xsl" type="text/xsl" ?>
\&  <document>
\&    ...
.Ve
.Sp
Where multiple processing instructions will have the same target and/or where the document order of those PIs matter, an array reference should be used instead. For example:
.Sp
.Vb 11
\&    $pd\->new( Handler => $writer_instance,
\&              rootname => \*(Aqdocument\*(Aq,
\&              processing_instructions => [
\&                \*(Aqxml\-stylesheet\*(Aq => {
\&                    href => \*(Aq/path/to/stylesheet.xsl\*(Aq,
\&                    type => \*(Aqtext/xml\*(Aq,
\&                },
\&                \*(Aqxml\-stylesheet\*(Aq => {
\&                    href => \*(Aq/path/to/second/stylesheet.xsl\*(Aq,
\&                    type => \*(Aqtext/xml\*(Aq,
\&                }
\&
\&           ]);
.Ve
.Sp
would produce:
.Sp
.Vb 5
\&  <?xml version="1.0"?>
\&  <?xml\-stylesheet href="/path/to/stylesheet.xsl" type="text/xsl" ?>
\&  <?xml\-stylesheet href="/path/to/second/stylesheet.xsl" type="text/xsl" ?>
\&  <document>
\&    ...
.Ve
.SH "PROCESSING METHODS"
.IX Header "PROCESSING METHODS"
.SS "Simple style processing"
.IX Subsection "Simple style processing"
.IP "\fBparse\fR" 4
.IX Item "parse"
\&\fBAccepts:\fR A reference to a Perl data structure. Optionally, a hash of config options.
.Sp
\&\fBReturns:\fR [none]
.Sp
The core method used during 'simple style' processing, this method accepts a reference
to a Perl data structure and, based on the options passed, produces a stream of \s-1SAX\s0 events
that can be used to transform that structure into \s-1XML.\s0 The optional second argument is
a hash of config options identical to those detailed in the \s-1OPTIONS\s0 section of the
the \fBnew()\fR constructor description.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->parse( \e%my_hash );
\&
\&  $pd\->parse( \e%my_hash, rootname => \*(Aqrecordset\*(Aq );
\&
\&  $pd\->parse( \e@my_list, %some_options );
\&
\&  $pd\->parse( $my_hashref );
\&
\&  $pd\->parse( $my_arrayref, keymap => { default => [\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq] } );
.Ve
.SS "Stream style processing"
.IX Subsection "Stream style processing"
.IP "\fBparse_start\fR" 4
.IX Item "parse_start"
\&\fBAccepts:\fR An optional hash of config options.
.Sp
\&\fBReturns:\fR [none]
.Sp
Starts the \s-1SAX\s0 event stream and (unless configured not to)
fires the event the top-level root element. The optional argument is
a hash of config options identical to those detailed in the \s-1OPTIONS\s0 section of the
the \fBnew()\fR constructor description.
.Sp
\&\fBExample:\fR
.Sp
.Vb 1
\&  $pd\->parse_start();
.Ve
.IP "\fBparse_end\fR" 4
.IX Item "parse_end"
\&\fBAccepts:\fR [none].
.Sp
\&\fBReturns:\fR Varies. Returns what the final Handler returns.
.Sp
Ends the \s-1SAX\s0 event stream and (unless configured not to)
fires the event to close the top-level root element.
.Sp
\&\fBExample:\fR
.Sp
.Vb 1
\&  $pd\->parse_end();
.Ve
.IP "\fBparse_chunk\fR" 4
.IX Item "parse_chunk"
\&\fBAccepts:\fR A reference to a Perl data structure.
.Sp
\&\fBReturns:\fR [none]
.Sp
The core method used during 'stream style' processing, this method accepts a reference
to a Perl data structure and, based on the options passed, produces a stream of \s-1SAX\s0 events
that can be used to transform that structure into \s-1XML.\s0
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->parse_chunk( \e%my_hash );
\&
\&  $pd\->parse_chunk( \e@my_list );
\&
\&  $pd\->parse_chunk( $my_hashref );
\&
\&  $pd\->parse_chunk( $my_arrayref );
.Ve
.SH "CONFIGURATION METHODS"
.IX Header "CONFIGURATION METHODS"
All config options can be passed to calls to the \fBnew()\fR constructor using the
typical \*(L"hash of named properties\*(R" syntax. The methods below offer direct
access to the individual options (or ways to add/remove the smaller definitions
contained by those options).
.IP "\fBinit\fR" 4
.IX Item "init"
\&\fBAccepts:\fR The same configuration options that can be passed to the \fBnew()\fR constructor.
.Sp
\&\fBReturns:\fR [none]
.Sp
See the list of \fB\s-1OPTIONS\s0\fR above in the definition of \fBnew()\fR for details.
.IP "\fBrootname\fR" 4
.IX Item "rootname"
\&\fBAccepts:\fR A string or [none].
.Sp
\&\fBReturns:\fR The current root name.
.Sp
When called with an argument, this method sets the name of the top-level (root) element. It
always returns the name of the current (or new) root name.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->rootname( $new_name );
\&
\&  my $current_root = $pd\->rootname();
.Ve
.IP "\fBdefaultname\fR" 4
.IX Item "defaultname"
\&\fBAccepts:\fR A string or [none]
.Sp
\&\fBReturns:\fR The current default element name.
.Sp
When called with an argument, this method sets the name of the default element. It
always returns the name of the current (or new) default name.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->defaultname( $new_name );
\&
\&  my $current_default = $pd\->defaultname();
.Ve
.IP "\fBkeymap\fR" 4
.IX Item "keymap"
\&\fBAccepts:\fR A hash (or hash reference) containing a series of keyname\->elementname mappings or [none].
.Sp
\&\fBReturns:\fR The current keymap hash (as a plain hash, or hash reference depending on caller context).
.Sp
When called with a hash (hash reference) as its argument, this method sets/resets the entire internal
keyname\->elementname mappings definitions (where 'keyname' means the name of a given
key in the hash and 'elementname' is the name used when firing \s-1SAX\s0 events for that key).
.Sp
In addition to simple name\->othername mappings, value of a keymap option can also a reference
to a subroutine (or an anonymous sub). The keyname will be passed as the sole argument to
this subroutine and the sub is expected to return the new element name. In the cases of nested
arrayrefs, no keyname will be passed, but you can still generate the name from scratch.
.Sp
Extending that idea, keymap will also accept a default mapping using the key '*' that will
be applied to all elements that do have an explicit mapping configured.
.Sp
To add new mappings or remove existing ones without having to reset the whole list of
mappings, see \fBadd_keymap()\fR and \fBdelete_keymap()\fR respectively.
.Sp
If your are using \*(L"stream style\*(R" processing, this method should be used with caution since
altering this mapping during processing may result in not-well-formed \s-1XML.\s0
.Sp
\&\fBExamples:\fR
.Sp
.Vb 2
\&  $pd\->keymap( keyname    => \*(Aqothername\*(Aq,
\&               anotherkey => \*(Aqsomeothername\*(Aq );
\&
\&  $pd\->keymap( \e%mymap );
\&
\&  # make all tags lower case
\&  $pd\->keymap( \*(Aq*\*(Aq    => sub{ return lc( $_[0];} );
\&
\&  # process keys named \*(Aqkeyname\*(Aq with a local sub
\&  $pd\->keymap( keyname    => \e&my_namer,
\&
\&  my %kmap_hash = $pd\->keymap();
\&
\&  my $kmap_hashref = $pd\->keymap();
.Ve
.IP "\fBadd_keymap\fR" 4
.IX Item "add_keymap"
\&\fBAccepts:\fR A hash (or hash reference) containing a series of keyname\->elementname mappings.
.Sp
\&\fBReturns:\fR [none]
.Sp
Adds a series of keyname\->elementname mappings (where 'keyname' means the name of a given
key in the hash and 'elementname' is the name used when firing \s-1SAX\s0 events for that key).
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->add_keymap( keyname => \*(Aqothername\*(Aq );
\&
\&  $pd\->add_keymap( \e%hash_of_mappings );
.Ve
.IP "\fBdelete_keymap\fR" 4
.IX Item "delete_keymap"
\&\fBAccepts:\fR A list (or array reference) of element/keynames.
.Sp
\&\fBReturns:\fR [none]
.Sp
Deletes a list of keyname\->elementname mappings (where 'keyname' means the name of a given
key in the hash and 'elementname' is the name used when firing \s-1SAX\s0 events for that key).
.Sp
This method should be used with caution since altering this mapping during processing
may result in not-well-formed \s-1XML.\s0
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->delete_keymap( \*(Aqsome\*(Aq, \*(Aqkey\*(Aq, \*(Aqnames\*(Aq );
\&
\&  $pd\->delete_keymap( \e@keynames );
.Ve
.IP "\fBskipelements\fR" 4
.IX Item "skipelements"
\&\fBAccepts:\fR A list (or array reference) containing a series of key/element names or [none].
.Sp
\&\fBReturns:\fR The current skipelements array (as a plain list, or array reference depending on caller context).
.Sp
When called with an array (array reference) as its argument, this method sets/resets the entire internal
skipelement definitions (which determines which keys will not be 'parsed' during processing).
.Sp
To add new mappings or remove existing ones without having to reset the whole list of
mappings, see \fBadd_skipelements()\fR and \fBdelete_skipelements()\fR respectively.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->skipelements( \*(Aqelname\*(Aq, \*(Aqothername\*(Aq, \*(Aqthirdname\*(Aq );
\&
\&  $pd\->skipelements( \e@skip_names );
\&
\&  my @skiplist = $pd\->skipelements();
\&
\&  my $skiplist_ref = $pd\->skipelements();
.Ve
.IP "\fBadd_skipelements\fR" 4
.IX Item "add_skipelements"
\&\fBAccepts:\fR A list (or array reference) containing a series of key/element names.
.Sp
\&\fBReturns:\fR [none]
.Sp
Adds a list of key/element names to skip during processing.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->add_skipelements( \*(Aqsome\*(Aq, \*(Aqkey\*(Aq, \*(Aqnames\*(Aq );
\&
\&  $pd\->add_skipelements( \e@keynames );
.Ve
.IP "\fBdelete_skipelements\fR" 4
.IX Item "delete_skipelements"
\&\fBAccepts:\fR A list (or array reference) containing a series of key/element names.
.Sp
\&\fBReturns:\fR [none]
.Sp
Deletes a list of key/element names to skip during processing.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->delete_skipelements( \*(Aqsome\*(Aq, \*(Aqkey\*(Aq, \*(Aqnames\*(Aq );
\&
\&  $pd\->delete_skipelements( \e@keynames );
.Ve
.IP "\fBcharmap\fR" 4
.IX Item "charmap"
\&\fBAccepts:\fR A hash (or hash reference) containing a series of parent/child keyname pairs or [none].
.Sp
\&\fBReturns:\fR The current charmap hash (as a plain hash, or hash reference depending on caller context).
.Sp
When called with a hash (hash reference) as its argument, this method sets/resets the entire internal
keyname/elementname\->characters children mappings definitions (where 'keyname' means the name of a given
key in the hash and 'characters children' is list containing the nested keynames that should be passed as
the text children of the element named 'keyname' (instead of being processed as child elements or attributes).
.Sp
To add new mappings or remove existing ones without having to reset the whole list of
mappings, see \fBadd_charmap()\fR and \fBdelete_charmap()\fR respectively.
.Sp
See \s-1CAVEATS\s0 for the limitations that relate to this method.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->charmap( elname => [\*(Aqlist\*(Aq, \*(Aqof\*(Aq, \*(Aqnested\*(Aq, \*(Aqkeynames\*(Aq );
\&
\&  $pd\->charmap( \e%mymap );
\&
\&  my %charmap_hash = $pd\->charmap();
\&
\&  my $charmap_hashref = $pd\->charmap();
.Ve
.IP "\fBadd_charmap\fR" 4
.IX Item "add_charmap"
\&\fBAccepts:\fR A hash or hash reference containing a series of parent/child keyname pairs.
.Sp
\&\fBReturns:\fR [none]
.Sp
Adds a series of parent-key \-> child-key relationships that define which of the
possible child keys will be processed as text children of the created 'parent'
element.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->add_charmap( parentname =>  [\*(Aqlist\*(Aq, \*(Aqof\*(Aq, \*(Aqchild\*(Aq, \*(Aqkeys\*(Aq] );
\&
\&  $pd\->add_charmap( parentname =>  \*(Aqchildkey\*(Aq );
\&
\&  $pd\->add_charmap( \e%parents_and_kids );
.Ve
.IP "\fBdelete_charmap\fR" 4
.IX Item "delete_charmap"
\&\fBAccepts:\fR A list (or array reference) of element/keynames.
.Sp
\&\fBReturns:\fR [none]
.Sp
Deletes a list of parent-key \-> child-key relationships from the instance-wide
hash of "parent\->nested names to pass as text children definitions. If you
need to alter the list of child names (without deleting the parent key) use
\&\fBadd_charmap()\fR to reset the parent-key's definition.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->delete_charmap( \*(Aqsome\*(Aq, \*(Aqparent\*(Aq, \*(Aqkeys\*(Aq );
\&
\&  $pd\->delete_charmap( \e@parentkeynames );
.Ve
.IP "\fBattrmap\fR" 4
.IX Item "attrmap"
\&\fBAccepts:\fR A hash (or hash reference) containing a series of parent/child keyname pairs or [none].
.Sp
\&\fBReturns:\fR The current attrmap hash (as a plain hash, or hash reference depending on caller context).
.Sp
When called with a hash (hash reference) as its argument, this method sets/resets the entire internal
keyname/elementname\->attr children mappings definitions (where 'keyname' means the name of a given
key in the hash and 'attr children' is list containing the nested keynames that should be passed as
attributes of the element named 'keyname' (instead of as child elements).
.Sp
To add new mappings or remove existing ones without having to reset the whole list of
mappings, see \fBadd_attrmap()\fR and \fBdelete_attrmap()\fR respectively.
.Sp
See \s-1CAVEATS\s0 for the limitations that relate to this method.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->attrmap( elname => [\*(Aqlist\*(Aq, \*(Aqof\*(Aq, \*(Aqnested\*(Aq, \*(Aqkeynames\*(Aq );
\&
\&  $pd\->attr( \e%mymap );
\&
\&  my %attrmap_hash = $pd\->attrmap();
\&
\&  my $attrmap_hashref = $pd\->attrmap();
.Ve
.IP "\fBadd_attrmap\fR" 4
.IX Item "add_attrmap"
\&\fBAccepts:\fR A hash or hash reference containing a series of parent/child keyname pairs.
.Sp
\&\fBReturns:\fR [none]
.Sp
Adds a series of parent-key \-> child-key relationships that define which of the
possible child keys will be processed as attributes of the created 'parent'
element.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->add_attrmap( parentname =>  [\*(Aqlist\*(Aq, \*(Aqof\*(Aq, \*(Aqchild\*(Aq, \*(Aqkeys\*(Aq] );
\&
\&  $pd\->add_attrmap( parentname =>  \*(Aqchildkey\*(Aq );
\&
\&  $pd\->add_attrmap( \e%parents_and_kids );
.Ve
.IP "\fBdelete_attrmap\fR" 4
.IX Item "delete_attrmap"
\&\fBAccepts:\fR A list (or array reference) of element/keynames.
.Sp
\&\fBReturns:\fR [none]
.Sp
Deletes a list of parent-key \-> child-key relationships from the instance-wide
hash of \*(L"parent\->nested names to pass as attributes\*(R" definitions. If you
need to alter the list of child names (without deleting the parent key) use
\&\fBadd_attrmap()\fR to reset the parent-key's definition.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->delete_attrmap( \*(Aqsome\*(Aq, \*(Aqparent\*(Aq, \*(Aqkeys\*(Aq );
\&
\&  $pd\->delete_attrmap( \e@parentkeynames );
.Ve
.IP "\fBbindattrs\fR" 4
.IX Item "bindattrs"
\&\fBAccepts:\fR 1 or 0 or [none].
.Sp
\&\fBReturns:\fR undef or 1 based on the current state of the bindattrs option.
.Sp
Consider:
.Sp
.Vb 1
\&  <myns:foo bar="quux"/>
.Ve
.Sp
and
.Sp
.Vb 1
\&  <myns:foo myns:bar="quux"/>
.Ve
.Sp
are \fInot\fR functionally equivalent.
.Sp
By default, attributes will be forwarded as \fInot\fR being bound to the namespace
of the containing element (like the first example above). Setting this
option to a true value alters that behavior.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->bindattrs(1); # attributes now bound and prefixed.
\&
\&  $pd\->bindattrs(0);
\&
\&  my $is_binding = $pd\->bindattrs();
.Ve
.IP "\fBadd_namespace\fR" 4
.IX Item "add_namespace"
\&\fBAccepts:\fR A hash containing the defined keys 'uri' and 'prefix'.
.Sp
\&\fBReturns:\fR [none]
.Sp
Add a namespace URI/prefix pair to the instance-wide list of \s-1XML\s0 namespaces
that will be used while processing. The reserved prefix '#default' can
be used to set the default (unprefixed) namespace declaration for elements.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 2
\&  $pd\->add_namespace( uri    => \*(Aqhttp://myhost.tld/myns\*(Aq,
\&                      prefix => \*(Aqmyns\*(Aq );
\&
\&  $pd\->add_namespace( uri    => \*(Aqhttp://myhost.tld/default\*(Aq,
\&                      prefix => \*(Aq#default\*(Aq );
.Ve
.Sp
See \fBnamespacemap()\fR or the namespacemap option detailed in \fBnew()\fR for details
about how to associate key/element name with a given namespace.
.IP "\fBnamespacemap\fR" 4
.IX Item "namespacemap"
\&\fBAccepts:\fR A hash (or hash reference) containing a series of uri\->key/element name mappings or [none].
.Sp
\&\fBReturns:\fR The current namespacemap hash (as a plain hash, or hash reference depending on caller context).
.Sp
When called with a hash (hash reference) as its argument, this method sets/resets the entire internal
namespace \s-1URI\-\s0>keyname/elementname mappings definitions (where 'keyname' means the name of a given
key in the hash and 'namespace \s-1URI\s0' is a declared namespace \s-1URI\s0 for the given process).
.Sp
To add new mappings or remove existing ones without having to reset the whole list of
mappings, see \fBadd_namespacemap()\fR and \fBdelete_namespacemap()\fR respectively.
.Sp
If your are using \*(L"stream style\*(R" processing, this method should be used with caution since
altering this mapping during processing may result in not-well-formed \s-1XML.\s0
.Sp
\&\fBExamples:\fR
.Sp
.Vb 2
\&  $pd\->add_namespace( uri    => \*(Aqhttp://myhost.tld/myns\*(Aq,
\&                      prefix => \*(Aqmyns\*(Aq );
\&
\&  $pd\->namespacemap( \*(Aqhttp://myhost.tld/myns\*(Aq => elname );
\&
\&  $pd\->namespacemap( \*(Aqhttp://myhost.tld/myns\*(Aq => [ \*(Aqlist\*(Aq,  \*(Aqof\*(Aq,  \*(Aqelnames\*(Aq ] );
\&
\&  $pd\->namespacemap( \e%mymap );
\&
\&  my %nsmap_hash = $pd\->namespacemap();
\&
\&  my $nsmap_hashref = $pd\->namespacemap();
.Ve
.IP "\fBadd_namespacemap\fR" 4
.IX Item "add_namespacemap"
\&\fBAccepts:\fR A hash (or hash reference) containing a series of uri\->key/element name mappings
.Sp
\&\fBReturns:\fR [none]
.Sp
Adds one or more namespace\->element/keyname rule to the instance-wide
list of mappings.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->add_namespacemap( \*(Aqhttp://myhost.tld/foo\*(Aq => [\*(Aqsome\*(Aq, \*(Aqlist\*(Aq, \*(Aqof\*(Aq \*(Aqkeys\*(Aq] );
\&
\&  $pd\->add_namespacemap( %new_nsmappings );
.Ve
.IP "\fBremove_namespacemap\fR" 4
.IX Item "remove_namespacemap"
\&\fBAccepts:\fR A list (or array reference) of element/keynames.
.Sp
\&\fBReturns:\fR [none]
.Sp
Removes a list of namespace\->element/keyname rules to the instance-wide
list of mappings.
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->delete_namespacemap( \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq );
\&
\&  $pd\->delete_namespacemap( \e@list_of_keynames );
.Ve
.SH "SAX EVENT METHODS"
.IX Header "SAX EVENT METHODS"
As a subclass of XML::SAX::Base, XML::Generator::PerlData allows you to
call all of the \s-1SAX\s0 event methods directly to insert arbitrary events
into the stream as needed. While its use in this way is probably a
\&\fIBad Thing\fR (and only relevant to \*(L"stream style\*(R" processing)  it is
good to know that such fine-grained access is there if you need it.
.PP
With that aside, there may be cases (again, using the \*(L"stream style\*(R") where
you'll want to insert single elements into the output (wrapping each
array in series of arrays in single 'record' elements, for example).
.PP
The following methods may be used to simplify this task by allowing you
to pass in simple element name strings and have the result 'just work' without
requiring an expert knowledge of the Perl \s-1SAX2\s0 implementation or
forcing you to keep track of things like namespace context.
.PP
Take care to ensure that every call to \fBstart_tag()\fR has a corresponding call to \fBend_tag()\fR
or your documents will not be well-formed.
.IP "\fBstart_tag\fR" 4
.IX Item "start_tag"
\&\fBAccepts:\fR A string containing an element name and an optional hash of simple key/value attributes.
.Sp
\&\fBReturns:\fR [none]
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->start_tag( $element_name );
\&
\&  $pd\->start_tag( $element_name, id => $generated_id );
\&
\&  $pd\->start_tag( $element_name, %some_attrs );
.Ve
.IP "\fBend_tag\fR" 4
.IX Item "end_tag"
\&\fBAccepts:\fR A string containing an element name.
.Sp
\&\fBReturns:\fR [none]
.Sp
\&\fBExamples:\fR
.Sp
.Vb 1
\&  $pd\->end_tag( $element_name );
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
In general, \s-1XML\s0 is based on the idea that every bit of data is going to have a
corresponding name (Elements, Attributes, etc.). While this is not at all a
Bad Thing, it means that some Perl data structures do not map cleanly onto
an \s-1XML\s0 representation.
.PP
Consider:
.PP
.Vb 1
\&  my %hash = ( foo => [\*(Aqone\*(Aq, \*(Aqtwo\*(Aq, \*(Aqthree\*(Aq] );
.Ve
.PP
How do you represent that as \s-1XML\s0? Is it three 'foo' elements, or
is it a 'foo' parent element with 3 mystery children? XML::Generator::PerlData
chooses the former. Or:
.PP
.Vb 3
\&  <foo>one</foo>
\&  <foo>two</foo>
\&  <foo>three</foo>
.Ve
.PP
Now consider:
.PP
.Vb 1
\&  my @lol = ( [\*(Aqone\*(Aq, \*(Aqtwo\*(Aq, \*(Aqthree\*(Aq], [\*(Aqfour\*(Aq, \*(Aqfive\*(Aq, \*(Aqsix\*(Aq] );
.Ve
.PP
In this case you wind up with a pile of elements named 'default'. You can
work around this by doing \f(CW$pd\fR\->add_keymap( default => ['list', 'of', 'names'] )
but that only works if you know how many entries are going to be in each nested
list.
.PP
The practical implication here is that the current version of XML::Generator::PerlData
favors data structures that are based on hashes of hashes for deeply nested structures (especally
when using \fBSimple Style\fR processing) and some options like \f(CW\*(C`attrmap\*(C'\fR do not work for
arrays at all. Future versions will address these issues if sanely possible.
.SH "AUTHOR"
.IX Header "AUTHOR"
Kip Hampton, khampton@totalcinema.com
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
(c) Kip Hampton, 2002\-2014, All Rights Reserved.
.SH "LICENSE"
.IX Header "LICENSE"
This module is released under the Perl Artistic Licence and
may be redistributed under the same terms as perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1XML::SAX\s0, XML::SAX::Writer.