- init
- Accepts: The same configuration options that can be passed to the
new() constructor.
Returns: [none]
See the list of OPTIONS above in the definition of
new() for details.
- rootname
- Accepts: A string or [none].
Returns: The current root name.
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.
Examples:
$pd->rootname( $new_name );
my $current_root = $pd->rootname();
- defaultname
- Accepts: A string or [none]
Returns: The current default element name.
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.
Examples:
$pd->defaultname( $new_name );
my $current_default = $pd->defaultname();
- keymap
- Accepts: A hash (or hash reference) containing a series of
keyname->elementname mappings or [none].
Returns: The current keymap hash (as a plain hash, or
hash reference depending on caller context).
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 SAX events for that
key).
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.
Extending that idea, keymap will also accept a default mapping
using the key '*' that will be applied to all elements that do have an
explict mapping configured.
To add new mappings or remove existing ones without having to
reset the whole list of mappings, see add_keymap() and
delete_keymap() respectively.
If your are using "stream style" processing, this
method should be used with caution since altering this mapping during
processing may result in not-well-formed XML.
Examples:
$pd->keymap( keyname => 'othername',
anotherkey => 'someothername' );
$pd->keymap( \%mymap );
# make all tags lower case
$pd->keymap( '*' => sub{ return lc( $_[0];} );
# process keys named 'keyname' with a local sub
$pd->keymap( keyname => \&my_namer,
my %kmap_hash = $pd->keymap();
my $kmap_hashref = $pd->keymap();
- add_keymap
- Accepts: A hash (or hash reference) containing a series of
keyname->elementname mappings.
Returns: [none]
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 SAX events for that key).
Examples:
$pd->add_keymap( keyname => 'othername' );
$pd->add_keymap( \%hash_of_mappings );
- delete_keymap
- Accepts: A list (or array reference) of element/keynames.
Returns: [none]
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 SAX events for that key).
This method should be used with caution since altering this
mapping during processing may result in not-well-formed XML.
Examples:
$pd->delete_keymap( 'some', 'key', 'names' );
$pd->delete_keymap( \@keynames );
- skipelements
- Accepts: A list (or array reference) containing a series of
key/element names or [none].
Returns: The current skipelements array (as a plain
list, or array reference depending on caller context).
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).
To add new mappings or remove existing ones without having to
reset the whole list of mappings, see add_skipelements() and
delete_skipelements() respectively.
Examples:
$pd->skipelements( 'elname', 'othername', 'thirdname' );
$pd->skipelements( \@skip_names );
my @skiplist = $pd->skipelements();
my $skiplist_ref = $pd->skipelements();
- add_skipelements
- Accepts: A list (or array reference) containing a series of
key/element names.
Returns: [none]
Adds a list of key/element names to skip during
processing.
Examples:
$pd->add_skipelements( 'some', 'key', 'names' );
$pd->add_skipelements( \@keynames );
- delete_skipelements
- Accepts: A list (or array reference) containing a series of
key/element names.
Returns: [none]
Deletes a list of key/element names to skip during
processing.
Examples:
$pd->delete_skipelements( 'some', 'key', 'names' );
$pd->delete_skipelements( \@keynames );
- charmap
- Accepts: A hash (or hash reference) containing a series of
parent/child keyname pairs or [none].
Returns: The current charmap hash (as a plain hash, or
hash reference depending on caller context).
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).
To add new mappings or remove existing ones without having to
reset the whole list of mappings, see add_charmap() and
delete_charmap() respectively.
See CAVEATS for the limitations that relate to this
method.
Examples:
$pd->charmap( elname => ['list', 'of', 'nested', 'keynames' );
$pd->charmap( \%mymap );
my %charmap_hash = $pd->charmap();
my $charmap_hashref = $pd->charmap();
- add_charmap
- Accepts: A hash or hash reference containing a series of
parent/child keyname pairs.
Returns: [none]
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.
Examples:
$pd->add_charmap( parentname => ['list', 'of', 'child', 'keys'] );
$pd->add_charmap( parentname => 'childkey' );
$pd->add_charmap( \%parents_and_kids );
- delete_charmap
- Accepts: A list (or array reference) of element/keynames.
Returns: [none]
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 add_charmap() to reset the
parent-key's definition.
Examples:
$pd->delete_charmap( 'some', 'parent', 'keys' );
$pd->delete_charmap( \@parentkeynames );
- attrmap
- Accepts: A hash (or hash reference) containing a series of
parent/child keyname pairs or [none].
Returns: The current attrmap hash (as a plain hash, or
hash reference depending on caller context).
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).
To add new mappings or remove existing ones without having to
reset the whole list of mappings, see add_attrmap() and
delete_attrmap() respectively.
See CAVEATS for the limitations that relate to this
method.
Examples:
$pd->attrmap( elname => ['list', 'of', 'nested', 'keynames' );
$pd->attr( \%mymap );
my %attrmap_hash = $pd->attrmap();
my $attrmap_hashref = $pd->attrmap();
- add_attrmap
- Accepts: A hash or hash reference containing a series of
parent/child keyname pairs.
Returns: [none]
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.
Examples:
$pd->add_attrmap( parentname => ['list', 'of', 'child', 'keys'] );
$pd->add_attrmap( parentname => 'childkey' );
$pd->add_attrmap( \%parents_and_kids );
- delete_attrmap
- Accepts: A list (or array reference) of element/keynames.
Returns: [none]
Deletes a list of parent-key -> child-key relationships
from the instance-wide hash of "parent->nested names to pass as
attributes" definitions. If you need to alter the list of child
names (without deleting the parent key) use add_attrmap() to
reset the parent-key's definition.
Examples:
$pd->delete_attrmap( 'some', 'parent', 'keys' );
$pd->delete_attrmap( \@parentkeynames );
- bindattrs
- Accepts: 1 or 0 or [none].
Returns: undef or 1 based on the current state of the
bindattrs option.
Consider:
<myns:foo bar="quux"/>
and
<myns:foo myns:bar="quux"/>
are not functionally equivalent.
By default, attributes will be forwarded as not being
bound to the namespace of the containing element (like the first example
above). Setting this option to a true value alters that behavior.
Examples:
$pd->bindattrs(1); # attributes now bound and prefixed.
$pd->bindattrs(0);
my $is_binding = $pd->bindattrs();
- add_namespace
- Accepts: A hash containing the defined keys 'uri' and 'prefix'.
Returns: [none]
Add a namespace URI/prefix pair to the instance-wide list of
XML namespaces that will be used while processing. The reserved prefix
'#default' can be used to set the default (unprefixed) namespace
declaration for elements.
Examples:
$pd->add_namespace( uri => 'http://myhost.tld/myns',
prefix => 'myns' );
$pd->add_namespace( uri => 'http://myhost.tld/default',
prefix => '#default' );
See namespacemap() or the namespacemap option detailed
in new() for details about how to associate key/element name with
a given namespace.
- namespacemap
- Accepts: A hash (or hash reference) containing a series of
uri->key/element name mappings or [none].
Returns: The current namespacemap hash (as a plain
hash, or hash reference depending on caller context).
When called with a hash (hash reference) as its argument, this
method sets/resets the entire internal namespace
URI->keyname/elementname mappings definitions (where 'keyname' means
the name of a given key in the hash and 'namespace URI' is a declared
namespace URI for the given process).
To add new mappings or remove existing ones without having to
reset the whole list of mappings, see add_namespacemap() and
delete_namespacemap() respectively.
If your are using "stream style" processing, this
method should be used with caution since altering this mapping during
processing may result in not-well-formed XML.
Examples:
$pd->add_namespace( uri => 'http://myhost.tld/myns',
prefix => 'myns' );
$pd->namespacemap( 'http://myhost.tld/myns' => elname );
$pd->namespacemap( 'http://myhost.tld/myns' => [ 'list', 'of', 'elnames' ] );
$pd->namespacemap( \%mymap );
my %nsmap_hash = $pd->namespacemap();
my $nsmap_hashref = $pd->namespacemap();
- add_namespacemap
- Accepts: A hash (or hash reference) containing a series of
uri->key/element name mappings
Returns: [none]
Adds one or more namespace->element/keyname rule to the
instance-wide list of mappings.
Examples:
$pd->add_namespacemap( 'http://myhost.tld/foo' => ['some', 'list', 'of' 'keys'] );
$pd->add_namespacemap( %new_nsmappings );
- remove_namespacemap
- Accepts: A list (or array reference) of element/keynames.
Returns: [none]
Removes a list of namespace->element/keyname rules to the
instance-wide list of mappings.
Examples:
$pd->delete_namespacemap( 'foo', 'bar', 'baz' );
$pd->delete_namespacemap( \@list_of_keynames );