@@ -3,9 +3,10 @@ package XML::Generator::PerlData;
use strict;
use XML::SAX::Base;
use vars qw($VERSION @ISA $NS_XMLNS $NS_XML);
-use Data::Dumper;
+use Scalar::Util qw(refaddr);
+
# some globals
-$VERSION = '0.91';
+$VERSION = '0.93';
@ISA = qw( XML::SAX::Base );
$NS_XML = 'http://www.w3.org/XML/1998/namespace';
$NS_XMLNS = 'http://www.w3.org/2000/xmlns/';
@@ -47,6 +48,7 @@ sub init {
$self->{RootName} ||= 'document';
$self->{DefaultElementName} ||= 'default';
$self->{TokenReplacementChar} ||= '_';
+ $self->{Seen} ||= {};
if ( defined $args{namespaces} ) {
foreach my $uri ( keys( %{$args{namespaces}} )) {
@@ -54,13 +56,25 @@ sub init {
}
}
+ # allow perlified PIs
+ if ( defined( $args{processing_instructions} )) {
+ $self->{ProcessingInstructions} = [];
+
+ if ( ref( $args{processing_instructions} ) eq 'ARRAY' ) {
+ $self->{ProcessingInstructions} = $args{processing_instructions};
+ }
+ elsif ( ref( $args{processing_instructions} ) eq 'HASH' ) {
+ foreach my $k ( keys( %{$args{processing_instructions}} )) {
+ push @{$self->{ProcessingInstructions}}, ( $k => $args{processing_instructions}->{$k} );
+ }
+ }
+ }
+
# let 'em change handlers if they want.
if ( defined $args{Handler} ) {
$self->set_handler( $args{Handler} );
}
-
-
if ( defined( $args{attrmap} ) ) {
$self->{Attrmap} = {};
while ( my ($k, $v) = ( each( %{$args{attrmap}} ) )) {
@@ -86,7 +100,7 @@ sub init {
$self->{Charmap} ||= {};
# Skipelements:
- # Makes sense from an interface standpoint for the user
+ # Makes sense from an interface standpoint for the user
# to pass an array ref, but it makes it more efficient to
# implement if its a hash ref. Let's pull a little juju.
@@ -95,7 +109,6 @@ sub init {
%skippers = map { $_, 1} @{$args{skipelements}}
}
- #warn "SKIPPPERS " . Dumper( \%args );
$self->{Skipelements} = \%skippers;
}
@@ -106,6 +119,14 @@ sub parse_start {
$self->start_document( {} );
+ if ( defined( $self->{ProcessingInstructions} ) && scalar( @{$self->{ProcessingInstructions}}) > 0 ) {
+ my $pis = delete $self->{ProcessingInstructions};
+
+ while ( my ( $target, $data ) = ( splice( @$pis, 0, 2)) ) {
+ $self->parse_pi( $target, $data );
+ }
+ }
+
unless ( defined $self->{SkipRoot} ) {
$self->start_element( $self->_start_details( $self->{RootName} ) );
push @{$self->{_Parents}}, $self->{RootName};
@@ -117,7 +138,7 @@ sub parse_end {
unless ( defined $self->{SkipRoot} ) {
$self->end_element( $self->_end_details( $self->{RootName} ) );
}
-
+
foreach my $uri ( keys( %{$self->{DeclaredNamespaces}} )) {
next if $uri eq $NS_XMLNS;
next if $uri eq $NS_XML;
@@ -162,6 +183,15 @@ sub parse_chunk {
}
}
+# Check if we have visited a given reference before
+sub circular {
+ my($self, $ref) = @_;
+ my $addr = refaddr($ref);
+ my $result = $self->{Seen}->{$addr};
+ $self->{Seen}->{$addr} = 1;
+ return $result;
+}
+
sub hashref2SAX {
my $self = shift;
@@ -169,13 +199,14 @@ sub hashref2SAX {
my $char_data = '';
+ return if $self->circular($hashref);
+
ELEMENT: foreach my $key (keys (%{$hashref} )) {
my $value = $hashref->{$key};
my $element_name = $self->_keymapped_name( $key );
-
+
next if defined $self->{Skipelements}->{$element_name};
-
if ( defined $self->{_Parents}->[-1] and defined $self->{Attrmap}->{$self->{_Parents}->[-1]} ) {
foreach my $name ( @{$self->{Attrmap}->{$self->{_Parents}->[-1]}} ) {
next ELEMENT if $name eq $element_name;
@@ -207,7 +238,7 @@ ELEMENT: foreach my $key (keys (%{$hashref} )) {
if ( ref( $value->{$child} ) ) {
warn "Cannot use a reference value " . $value->{$child} . " for key '$child' as XML attribute\n";
next ATTR;
- }
+ }
$attrs{$name} = $value->{$child};
}
@@ -233,6 +264,8 @@ sub arrayref2SAX {
my $passed_name = shift || $self->{_Parents}->[-1];
my $temp_name = $self->_keymapped_name( $passed_name );
+ return if $self->circular($arrayref);
+
my $element_name;
my $i;
@@ -250,9 +283,7 @@ ELEMENT: for ( $i = 0; $i < @{$arrayref}; $i++ ) {
$element_name = $temp_name;
}
-
next if defined $self->{Skipelements}->{$element_name};
-
my $type = $self->get_type( $arrayref->[$i] );
@@ -275,11 +306,11 @@ ELEMENT: for ( $i = 0; $i < @{$arrayref}; $i++ ) {
warn "Cannot use a reference value " . $value->{$child} . " for key '$child' as XML attribute\n";
next ATTR;
}
-
+
$attrs{$name} = $value->{$child};
}
}
- }
+ }
$self->start_element( $self->_start_details( $element_name, \%attrs ) );
push @{$self->{_Parents}}, $element_name;
$self->hashref2SAX( $arrayref->[$i] );
@@ -288,7 +319,7 @@ ELEMENT: for ( $i = 0; $i < @{$arrayref}; $i++ ) {
}
else {
$self->start_element( $self->_start_details( $element_name ) );
- $self->characters( {Data => $arrayref->[$i]} );
+ $self->characters( {Data => $arrayref->[$i]} );
$self->end_element( $self->_end_details( $element_name ) );
}
}
@@ -305,7 +336,7 @@ sub get_type {
}
else {
# we were passed an object, yuk.
- # props to barrie slaymaker for the tip here... mine was much fuglier. ;-)
+ # props to barrie slaymaker for the tip here... mine was much fuglier. ;-)
if ( UNIVERSAL::isa( $wtf, "HASH" ) ) {
return 'HASH';
}
@@ -360,7 +391,7 @@ sub namespacemap {
}
}
}
-
+
return wantarray ? %{$self->{Namespacemap}} : $self->{Namespacemap};
}
@@ -387,7 +418,7 @@ sub delete_namespacemap {
foreach my $uri ( keys( %{$self->{Namespacemap}} )) {
my $i;
for ($i = 0; $i < scalar @{$self->{Namespacemap}->{$uri}}; $i++) {
- splice @{$self->{Namespacemap}->{$uri}}, $i, 1 if $self->{Namespacemap}->{$uri}->[$i] eq $name;
+ splice @{$self->{Namespacemap}->{$uri}}, $i, 1 if $self->{Namespacemap}->{$uri}->[$i] eq $name;
}
delete $self->{Namespacemap}->{$uri} unless scalar @{$self->{Namespacemap}->{$uri}} > 0;
}
@@ -405,7 +436,7 @@ sub attrmap {
else {
%attrmap = @_;
}
-
+
while ( my ($k, $v) = each( %attrmap )) {
if ( ref( $v ) ) {
$self->{Attrmap}->{$k} = $v;
@@ -415,7 +446,7 @@ sub attrmap {
}
}
}
-
+
return wantarray ? %{$self->{Attrmap}} : $self->{Attrmap};
}
@@ -426,7 +457,7 @@ sub add_attrmap {
if ( ref( $_[0] )) {
%attrmap = %{$_[0]};
}
- else {
+ else {
%attrmap = @_;
}
@@ -438,21 +469,20 @@ sub add_attrmap {
$self->{Attrmap}->{$k} = [ $v ];
}
}
-
}
}
sub delete_attrmap {
my $self = shift;
- my @mapped;
+ my @mapped;
if ( scalar( @_ ) > 0 ) {
if ( ref( $_[0] )) {
- @mapped = @{$_[0]};
+ @mapped = @{$_[0]};
}
else {
- @mapped = @_;
+ @mapped = @_;
}
- foreach my $name ( @mapped ) {
+ foreach my $name ( @mapped ) {
delete $self->{Attrmap}->{$name} if $self->{Attrmap}->{$name};
}
}
@@ -468,7 +498,7 @@ sub charmap {
else {
%charmap = @_;
}
-
+
while ( my ($k, $v) = each( %charmap )) {
if ( ref( $v ) ) {
$self->{Charmap}->{$k} = $v;
@@ -478,7 +508,7 @@ sub charmap {
}
}
}
-
+
return wantarray ? %{$self->{Charmap}} : $self->{Charmap};
}
@@ -489,7 +519,7 @@ sub add_charmap {
if ( ref( $_[0] )) {
%charmap = %{$_[0]};
}
- else {
+ else {
%charmap = @_;
}
@@ -501,21 +531,20 @@ sub add_charmap {
$self->{Charmap}->{$k} = [ $v ];
}
}
-
}
}
sub delete_charmap {
my $self = shift;
- my @mapped;
+ my @mapped;
if ( scalar( @_ ) > 0 ) {
if ( ref( $_[0] )) {
- @mapped = @{$_[0]};
+ @mapped = @{$_[0]};
}
else {
- @mapped = @_;
+ @mapped = @_;
}
- foreach my $name ( @mapped ) {
+ foreach my $name ( @mapped ) {
delete $self->{Charmap}->{$name} if $self->{Charmap}->{$name};
}
}
@@ -528,7 +557,7 @@ sub add_keymap {
if ( ref( $_[0] )) {
%keymap = %{$_[0]};
}
- else {
+ else {
%keymap = @_;
}
@@ -545,7 +574,7 @@ sub delete_keymap {
if ( ref( $_[0] )) {
@mapped = @{$_[0]};
}
- else {
+ else {
@mapped = @_;
}
foreach my $name ( @mapped ) {
@@ -566,7 +595,7 @@ sub add_skipelements {
}
foreach my $name ( @skippers ) {
$self->{Skipelements}->{$name} = 1;
- }
+ }
}
}
@@ -582,13 +611,13 @@ sub delete_skipelements {
}
foreach my $name ( @skippers ) {
delete $self->{Skipelements}->{$name} if $self->{Skipelements}->{$name};
- }
+ }
}
}
sub rootname {
my ($self, $rootname) = @_;
-
+
# ubu: add a check to warn them if the processing has already begun?
if ( defined $rootname ) {
$self->{RootName} = $rootname;
@@ -621,7 +650,7 @@ sub defaultname {
}
return $self->{DefaultElementName};
}
-
+
sub keymap {
my $self = shift;
my %keymap;
@@ -649,14 +678,40 @@ sub skipelements {
@skippers = @_;
}
my %skippers = map { $_, 1} @skippers;
- $self->{Skipelements} = \%skippers;
+ $self->{Skipelements} = \%skippers;
}
-
+
my @skippers_out = keys %{$self->{Skipelements}} || ();
return wantarray ? @skippers_out : \@skippers_out;
}
+#XXX
+sub parse_pi {
+ my $self = shift;
+ my ( $target, $data_in ) = @_;
+
+ my $data_out = '';
+
+ my $ref = $self->get_type( $data_in );
+
+ if ( $ref eq 'SCALAR' ) {
+ $data_out = $$data_in;
+ }
+ elsif ( $ref eq 'ARRAY' ) {
+ $data_out = join ' ', @{$data_in};
+ }
+ elsif ( $ref eq 'HASH' ) {
+ foreach my $k (keys( %{$data_in} )) {
+ $data_out .= qq|$k="| . $data_in->{$k} . qq|" |;
+ }
+ }
+ else {
+ $data_out = $data_in;
+ }
+
+ $self->processing_instruction({ Target => $target, Data => $data_out });
+}
###
# Convenience helpers to make 'stream style' friendly
@@ -696,7 +751,7 @@ sub _keymapped_name {
}
elsif ( defined $self->{Keymap}->{'*'} ) {
my $temp_name = $self->{Keymap}->{'*'};
-
+
if ( ref( $temp_name ) eq 'CODE' ) {
$element_name = &{$temp_name}( $name );
}
@@ -729,7 +784,7 @@ sub _start_details {
my $key_uri = $uri || "";
$real_attrs{"\{$key_uri\}$lname"} = {
- Name => $qname,
+ Name => $qname,
LocalName => $lname,
Prefix => $prefix,
NamespaceURI => $uri,
@@ -746,8 +801,8 @@ sub _start_details {
my $key_uri;
my $ns_uri;
- # this, like the Java version of SAX2, explicitly follows production 5.2 of the
- # W3C Namespaces rec.-- specifically:
+ # this, like the Java version of SAX2, explicitly follows production 5.2 of the
+ # W3C Namespaces rec.-- specifically:
# http://www.w3.org/TR/1999/REC-xml-names-19990114/#defaulting
if ( $self->{Namespaces}->{$uri} eq '#default' ) {
@@ -764,12 +819,10 @@ sub _start_details {
#$key_uri = "";
$key_uri = $NS_XMLNS;
$ns_uri = $NS_XMLNS;
-
-
- }
+ }
$real_attrs{"\{$key_uri\}$lname"} = {
Name => $qname,
- LocalName => $lname,
+ LocalName => $lname,
Prefix => $prefix,
NamespaceURI => $ns_uri,
Value => $uri };
@@ -798,7 +851,6 @@ sub _start_details {
push @{$self->{InScopeNamespaceStack}}, [$uri, $prefix];
}
-
return \%element;
}
@@ -809,7 +861,7 @@ sub _end_details {
my %element = (LocalName => $lname,
Name => $qname,
Prefix => $prefix,
- NamespaceURI => $uri,
+ NamespaceURI => $uri,
);
if ( defined $uri and grep { $element_name eq $_ } @{$self->{Namespacemap}->{$uri}} ) {
@@ -848,9 +900,9 @@ sub _namespace_fixer {
if ( $prefix ) {
$qname = $prefix . ':' . $lname;
}
- }
+ }
}
- $qname ||= $lname;
+ $qname ||= $lname;
return ($uri, $prefix, $qname, $lname);
}
@@ -860,13 +912,12 @@ sub _name_fixer {
# UNICODE WARNING
$name =~ s|^[^a-zA-Z_:]{1}|_|g;
$name =~ tr|a-zA-Z0-9._:-|_|c;
-
+
return $name;
}
1;
__END__
-# Below is the stub of documentation for your module. You better edit it!
=head1 NAME
@@ -890,8 +941,8 @@ XML::Generator::PerlData - Perl extension for generating SAX2 events from nested
# generate XML from the data structure...
$driver->parse( $hash_ref );
-
-
+
+
## Or, Stream style ##
use XML::Generator::PerlData;
@@ -899,10 +950,10 @@ XML::Generator::PerlData - Perl extension for generating SAX2 events from nested
# 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();
@@ -915,11 +966,11 @@ XML::Generator::PerlData - Perl extension for generating SAX2 events from nested
# end the event stream...
$driver->parse_end();
-and you're done...
+and you're done...
=head1 DESCRIPTION
-XML::Generator::PerlData provides a simple way to generate SAX2 events
+XML::Generator::PerlData provides a simple way to generate SAX2 events
from nested Perl data structures, while providing finer-grained control
over the resulting document streams.
@@ -929,13 +980,13 @@ In a nutshell, 'simple style' is best used for those cases where you have a a si
Perl data structure that you want to convert to XML as quickly and painlessly as possible. 'Stream
style' is more useful for cases where you are receiving chunks of data (like from a DBI handle)
and you want to process those chunks as they appear. See B<PROCESSING METHODS> for more info about
-how each style works.
+how each style works.
=head1 CONSTRUCTOR METHOD AND CONFIGURATION OPTIONS
-=over 4
+=head2 new
-=item B<new> (class constructor)
+(class constructor)
B<Accepts:> An optional hash of configuration options.
@@ -948,12 +999,14 @@ there is a small host of options available to help ensure that the SAX event str
(and by extension the XML documents) that are created from the data structures you
pass are in just the format that you want.
-=head2 OPTIONS
+=head3 Options
+
+=over 4
=item * B<Handler> (required)
XML::Generator::PerlData is a SAX Driver/Generator. As such, it
-needs a SAX Handler or Filter class to forward its events to. The value for this
+needs a SAX 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.
=item * B<rootname> (optional)
@@ -962,7 +1015,7 @@ Sets the name of the top-level (root) element. The default is 'document'.
=item * B<defaultname> (optional)
-Sets the default name to be used for elements when no other logical name
+Sets the default name to be used for elements when no other logical name
is available (think lists-of-lists). The default is 'default'.
=item * B<keymap> (optional)
@@ -973,21 +1026,21 @@ contains a set of keyname->element name mappings for the current process.
=item * B<skipelements> (optional)
-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
+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.
=item * B<attrmap> (optional)
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.
+be forwarded as attributes of that element rather than as child elements.
(see CAVEATS for a discussion of the limitations of this method.)
=item * B<namespaces> (optional)
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
+the form of a hash, where the keys are the URIs of the given namespace and the
values are the associated prefix.
To set a default (unprefixed) namespace, set the prefix to '#default'.
@@ -995,7 +1048,7 @@ To set a default (unprefixed) namespace, set the prefix to '#default'.
=item * B<namespacemap> (optional)
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
+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.
@@ -1003,25 +1056,68 @@ single key/element names or an array reference of key/element names.
When set to a defined value, this option blocks the generator from adding
the top-level root element when parse() or parse_start() and parse_end()
-are called.
+are called.
-I<Do not> use this option unless you absolutely sure you know what you
+I<Do not> use this option unless you absolutely sure you know what you
are doing and why, since the resulting event stream will most likely
produce non-well-formed XML.
=item * B<bindattrs> (optional)
-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.
+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.
+
+=item * B<processing_instructions> (optional)
+
+This option provides a way to include XML 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 L<XML::SAX::Writer>:
+
+ $pd->new( Handler => $writer_instance,
+ rootname => 'document',
+ processing_instructions => {
+ 'xml-stylesheet' => {
+ href => '/path/to/stylesheet.xsl',
+ type => 'text/xml',
+ },
+ });
+
+would generate
+
+ <?xml version="1.0"?>
+ <?xml-stylesheet href="/path/to/stylesheet.xsl" type="text/xsl" ?>
+ <document>
+ ...
+
+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:
+
+ $pd->new( Handler => $writer_instance,
+ rootname => 'document',
+ processing_instructions => [
+ 'xml-stylesheet' => {
+ href => '/path/to/stylesheet.xsl',
+ type => 'text/xml',
+ },
+ 'xml-stylesheet' => {
+ href => '/path/to/second/stylesheet.xsl',
+ type => 'text/xml',
+ }
+
+ ]);
+
+would produce:
+
+ <?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>
+ ...
=back
=head1 PROCESSING METHODS
-=over 4
+=head2 Simple style processing
-=head2 SIMPLE STYLE PROCESSING
+=over 4
=item B<parse>
@@ -1033,7 +1129,7 @@ The core method used during 'simple style' processing, this method accepts a ref
to a Perl data structure and, based on the options passed, produces a stream of SAX events
that can be used to transform that structure into XML. The optional second argument is
a hash of config options identical to those detailed in the OPTIONS section of the
-the new() constructor description.
+the new() constructor description.
B<Examples:>
@@ -1047,8 +1143,11 @@ B<Examples:>
$pd->parse( $my_arrayref, keymap => { default => ['foo', 'bar', 'baz'] } );
+=back
+
+=head2 Stream style processing
-=head2 STREAM STYLE PROCESSING
+=over 4
=item B<parse_start>
@@ -1056,7 +1155,7 @@ B<Accepts:> An optional hash of config options.
B<Returns:> [none]
-Starts the SAX event stream and (unless configured not to)
+Starts the SAX 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 OPTIONS section of the
the new() constructor description.
@@ -1077,7 +1176,7 @@ fires the event to close the top-level root element.
B<Example:>
- $pd->parse_end();
+ $pd->parse_end();
=item B<parse_chunk>
@@ -1105,7 +1204,7 @@ B<Examples:>
=head1 CONFIGURATION METHODS
All config options can be passed to calls to the new() constructor using the
-typical "hash of named properties" syntax. The methods below offer direct
+typical "hash of named properties" syntax. The methods below offer direct
access to the individual options (or ways to add/remove the smaller definitions
contained by those options).
@@ -1127,12 +1226,12 @@ B<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.
-
-B<Examples:>
- $pd->rootname( $new_name );
+B<Examples:>
+
+ $pd->rootname( $new_name );
- my $current_root = $pd->rootname();
+ my $current_root = $pd->rootname();
=item B<defaultname>
@@ -1140,14 +1239,14 @@ B<Accepts:> A string or [none]
B<Returns:> The current default element name.
-When called with an argument, this method sets the name of the default element. It
+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.
-B<Examples:>
+B<Examples:>
- $pd->defaultname( $new_name );
+ $pd->defaultname( $new_name );
- my $current_default = $pd->defaultname();
+ my $current_default = $pd->defaultname();
=item B<keymap>
@@ -1155,7 +1254,7 @@ B<Accepts:> A hash (or hash reference) containing a series of keyname->elementna
B<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
+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).
@@ -1170,25 +1269,25 @@ 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
+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.
-B<Examples:>
+B<Examples:>
$pd->keymap( keyname => 'othername',
- anotherkey => 'someothername' );
+ anotherkey => 'someothername' );
- $pd->keymap( \%mymap );
+ $pd->keymap( \%mymap );
# make all tags lower case
- $pd->keymap( '*' => sub{ return lc( $_[0];} );
+ $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_hash = $pd->keymap();
- my $kmap_hashref = $pd->keymap();
+ my $kmap_hashref = $pd->keymap();
=item B<add_keymap>
@@ -1199,11 +1298,11 @@ B<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).
-B<Examples:>
+B<Examples:>
- $pd->add_keymap( keyname => 'othername' );
+ $pd->add_keymap( keyname => 'othername' );
- $pd->add_keymap( \%hash_of_mappings );
+ $pd->add_keymap( \%hash_of_mappings );
=item B<delete_keymap>
@@ -1217,33 +1316,33 @@ key in the hash and 'elementname' is the name used when firing SAX events for th
This method should be used with caution since altering this mapping during processing
may result in not-well-formed XML.
-B<Examples:>
+B<Examples:>
- $pd->delete_keymap( 'some', 'key', 'names' );
+ $pd->delete_keymap( 'some', 'key', 'names' );
- $pd->delete_keymap( \@keynames );
+ $pd->delete_keymap( \@keynames );
=item B<skipelements>
B<Accepts:> A list (or array reference) containing a series of key/element names or [none].
B<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
+
+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.
-B<Examples:>
+B<Examples:>
$pd->skipelements( 'elname', 'othername', 'thirdname' );
- $pd->skipelements( \@skip_names );
+ $pd->skipelements( \@skip_names );
- my @skiplist = $pd->skipelements();
+ my @skiplist = $pd->skipelements();
- my $skiplist_ref = $pd->skipelements();
+ my $skiplist_ref = $pd->skipelements();
=item B<add_skipelements>
@@ -1253,11 +1352,11 @@ B<Returns:> [none]
Adds a list of key/element names to skip during processing.
-B<Examples:>
+B<Examples:>
- $pd->add_skipelements( 'some', 'key', 'names' );
+ $pd->add_skipelements( 'some', 'key', 'names' );
- $pd->add_skipelements( \@keynames );
+ $pd->add_skipelements( \@keynames );
=item B<delete_skipelements>
@@ -1267,11 +1366,11 @@ B<Returns:> [none]
Deletes a list of key/element names to skip during processing.
-B<Examples:>
+B<Examples:>
- $pd->delete_skipelements( 'some', 'key', 'names' );
+ $pd->delete_skipelements( 'some', 'key', 'names' );
- $pd->delete_skipelements( \@keynames );
+ $pd->delete_skipelements( \@keynames );
=item B<charmap>
@@ -1279,7 +1378,7 @@ B<Accepts:> A hash (or hash reference) containing a series of parent/child keyna
B<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
+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).
@@ -1289,15 +1388,15 @@ mappings, see add_charmap() and delete_charmap() respectively.
See CAVEATS for the limitations that relate to this method.
-B<Examples:>
+B<Examples:>
$pd->charmap( elname => ['list', 'of', 'nested', 'keynames' );
- $pd->charmap( \%mymap );
+ $pd->charmap( \%mymap );
- my %charmap_hash = $pd->charmap();
+ my %charmap_hash = $pd->charmap();
- my $charmap_hashref = $pd->charmap();
+ my $charmap_hashref = $pd->charmap();
=item B<add_charmap>
@@ -1309,13 +1408,13 @@ 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.
-B<Examples:>
+B<Examples:>
- $pd->add_charmap( parentname => ['list', 'of', 'child', 'keys'] );
+ $pd->add_charmap( parentname => ['list', 'of', 'child', 'keys'] );
- $pd->add_charmap( parentname => 'childkey' );
+ $pd->add_charmap( parentname => 'childkey' );
- $pd->add_charmap( \%parents_and_kids );
+ $pd->add_charmap( \%parents_and_kids );
=item B<delete_charmap>
@@ -1326,13 +1425,13 @@ B<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.
+add_charmap() to reset the parent-key's definition.
-B<Examples:>
+B<Examples:>
- $pd->delete_charmap( 'some', 'parent', 'keys' );
+ $pd->delete_charmap( 'some', 'parent', 'keys' );
- $pd->delete_charmap( \@parentkeynames );
+ $pd->delete_charmap( \@parentkeynames );
=item B<attrmap>
@@ -1340,7 +1439,7 @@ B<Accepts:> A hash (or hash reference) containing a series of parent/child keyna
B<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
+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).
@@ -1350,15 +1449,15 @@ mappings, see add_attrmap() and delete_attrmap() respectively.
See CAVEATS for the limitations that relate to this method.
-B<Examples:>
+B<Examples:>
$pd->attrmap( elname => ['list', 'of', 'nested', 'keynames' );
- $pd->attr( \%mymap );
+ $pd->attr( \%mymap );
- my %attrmap_hash = $pd->attrmap();
+ my %attrmap_hash = $pd->attrmap();
- my $attrmap_hashref = $pd->attrmap();
+ my $attrmap_hashref = $pd->attrmap();
=item B<add_attrmap>
@@ -1370,13 +1469,13 @@ 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.
-B<Examples:>
+B<Examples:>
- $pd->add_attrmap( parentname => ['list', 'of', 'child', 'keys'] );
+ $pd->add_attrmap( parentname => ['list', 'of', 'child', 'keys'] );
- $pd->add_attrmap( parentname => 'childkey' );
+ $pd->add_attrmap( parentname => 'childkey' );
- $pd->add_attrmap( \%parents_and_kids );
+ $pd->add_attrmap( \%parents_and_kids );
=item B<delete_attrmap>
@@ -1387,13 +1486,13 @@ B<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.
+add_attrmap() to reset the parent-key's definition.
-B<Examples:>
+B<Examples:>
- $pd->delete_attrmap( 'some', 'parent', 'keys' );
+ $pd->delete_attrmap( 'some', 'parent', 'keys' );
- $pd->delete_attrmap( \@parentkeynames );
+ $pd->delete_attrmap( \@parentkeynames );
=item B<bindattrs>
@@ -1412,16 +1511,16 @@ and
are I<not> functionally equivalent.
By default, attributes will be forwarded as I<not> being bound to the namespace
-of the containing element (like the first example above). Setting this
+of the containing element (like the first example above). Setting this
option to a true value alters that behavior.
-B<Examples:>
+B<Examples:>
$pd->bindattrs(1); # attributes now bound and prefixed.
- $pd->bindattrs(0);
+ $pd->bindattrs(0);
- my $is_binding = $pd->bindattrs();
+ my $is_binding = $pd->bindattrs();
=item B<add_namespace>
@@ -1431,9 +1530,9 @@ B<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.
+be used to set the default (unprefixed) namespace declaration for elements.
-B<Examples:>
+B<Examples:>
$pd->add_namespace( uri => 'http://myhost.tld/myns',
prefix => 'myns' );
@@ -1441,7 +1540,7 @@ B<Examples:>
$pd->add_namespace( uri => 'http://myhost.tld/default',
prefix => '#default' );
-See namespacemap() or the namespacemap option detailed in new() for details
+See namespacemap() or the namespacemap option detailed in new() for details
about how to associate key/element name with a given namespace.
=item B<namespacemap>
@@ -1449,18 +1548,18 @@ about how to associate key/element name with a given namespace.
B<Accepts:> A hash (or hash reference) containing a series of uri->key/element name mappings or [none].
B<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
+
+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
+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.
-B<Examples:>
+B<Examples:>
$pd->add_namespace( uri => 'http://myhost.tld/myns',
@@ -1470,11 +1569,11 @@ B<Examples:>
$pd->namespacemap( 'http://myhost.tld/myns' => [ 'list', 'of', 'elnames' ] );
- $pd->namespacemap( \%mymap );
+ $pd->namespacemap( \%mymap );
- my %nsmap_hash = $pd->namespacemap();
+ my %nsmap_hash = $pd->namespacemap();
- my $nsmap_hashref = $pd->namespacemap();
+ my $nsmap_hashref = $pd->namespacemap();
=item B<add_namespacemap>
@@ -1485,7 +1584,7 @@ B<Returns:> [none]
Adds one or more namespace->element/keyname rule to the instance-wide
list of mappings.
-B<Examples:>
+B<Examples:>
$pd->add_namespacemap( 'http://myhost.tld/foo' => ['some', 'list', 'of' 'keys'] );
@@ -1500,30 +1599,30 @@ B<Returns:> [none]
Removes a list of namespace->element/keyname rules to the instance-wide
list of mappings.
-B<Examples:>
+B<Examples:>
- $pd->delete_namespacemap( 'foo', 'bar', 'baz' );
+ $pd->delete_namespacemap( 'foo', 'bar', 'baz' );
- $pd->delete_namespacemap( \@list_of_keynames );
+ $pd->delete_namespacemap( \@list_of_keynames );
=back
=head1 SAX EVENT METHODS
As a subclass of XML::SAX::Base, XML::Generator::PerlData allows you to
-call all of the SAX event methods directly to insert arbitrary events
-into the stream as needed. While its use in this way is probably a
-I<Bad Thing> (and only relevant to "stream style" processing) it is
+call all of the SAX event methods directly to insert arbitrary events
+into the stream as needed. While its use in this way is probably a
+I<Bad Thing> (and only relevant to "stream style" processing) it is
good to know that such fine-grained access is there if you need it.
-With that aside, there may be cases (again, using the "stream style") where
-you'll want to insert single elements into the output (wrapping each
-array in series of arrays in single 'record' elements, for example).
+With that aside, there may be cases (again, using the "stream style") where
+you'll want to insert single elements into the output (wrapping each
+array in series of arrays in single 'record' elements, for example).
-The following methods may be used to simplify this task by allowing you
+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 SAX2 implementation or
-forcing you to keep track of things like namespace context.
+requiring an expert knowledge of the Perl SAX2 implementation or
+forcing you to keep track of things like namespace context.
Take care to ensure that every call to start_tag() has a corresponding call to end_tag()
or your documents will not be well-formed.
@@ -1536,8 +1635,8 @@ B<Accepts:> A string containing an element name and an optional hash of simple k
B<Returns:> [none]
-B<Examples:>
-
+B<Examples:>
+
$pd->start_tag( $element_name );
$pd->start_tag( $element_name, id => $generated_id );
@@ -1550,9 +1649,9 @@ B<Accepts:> A string containing an element name.
B<Returns:> [none]
-B<Examples:>
+B<Examples:>
- $pd->end_tag( $element_name );
+ $pd->end_tag( $element_name );
=back
@@ -1561,14 +1660,14 @@ B<Examples:>
In general, XML 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 XML representation.
+an XML representation.
Consider:
my %hash = ( foo => ['one', 'two', 'three'] );
How do you represent that as XML? Is it three 'foo' elements, or
-is it a 'foo' parent element with 3 mystery children? XML::Generator::PerlData
+is it a 'foo' parent element with 3 mystery children? XML::Generator::PerlData
chooses the former. Or:
<foo>one</foo>
@@ -1595,16 +1694,16 @@ Kip Hampton, khampton@totalcinema.com
=head1 COPYRIGHT
-(c) Kip Hampton, 2002, All Rights Reserved.
+(c) Kip Hampton, 2002-2014, All Rights Reserved.
-=head1 LICENCE
+=head1 LICENSE
This module is released under the Perl Artistic Licence and
may be redistributed under the same terms as perl itself.
=head1 SEE ALSO
-XML::SAX.
+L<XML::SAX>, L<XML::SAX::Writer>.
=cut