NAME
XML::Struct::Reader - Read XML streams into XML data structures
VERSION
version 0.22
SYNOPSIS
my $reader = XML::Struct::Reader->new( from => "file.xml" );
my $data = $reader->read;
DESCRIPTION
This module reads an XML stream (via XML::LibXML::Reader) into XML::Struct/MicroXML data structures.
METHODS
read = readNext ( [ $stream ] [, $path ] )
Read the next XML element from a stream. If no path option is specified, the reader's path option is used ("*
" by default, first matching the root, then every other element).
readDocument( [ $stream ] [, $path ] )
Read an entire XML document. In contrast to read
/readNext
, this method always reads the entire stream. The return value is the first element (that is the root element by default) in scalar context and a list of elements in array context. Multiple elements can be returned for instance when a path was specified to select document fragments.
readElement( [ $stream ] )
Read an XML element from a stream and return it as array reference with element name, attributes, and child elements. In contrast to method read
, this method expects the stream to be at an element node ($stream->nodeType == 1
) or bad things might happed.
readAttributes( [ $stream ] )
Read all XML attributes from a stream and return a (possibly empty) hash reference.
readContent( [ $stream ] )
Read all child elements of an XML element and return the result as (possibly empty) array reference. Significant whitespace is only included if option whitespace
is enabled.
CONFIGURATION
- from
-
A source to read from. Possible values include a string or string reference with XML data, a filename, an URL, a file handle, instances of XML::LibXML::Document or XML::LibXML::Element, and a hash reference with options passed to XML::LibXML::Reader.
- stream
-
A XML::LibXML::Reader to read from. If no stream has been defined, one must pass a stream parameter to the
read...
methods. Setting a source with optionfrom
automatically sets a stream. - attributes
-
Include attributes (enabled by default). If disabled, the representation of an XML element will be
[ $name => \@children ]
instead of
[ $name => \%attributes, \@children ]
- path
-
Optional path expression to be used as default value when calling
read
. Pathes must either be absolute (starting with "/
") or consist of a single element name. The special name "*
" matches all element names.A path is a very reduced form of an XPath expressions (no axes, no "
..
", no node tests,//
only at the start...). Namespaces are not supported yet. - whitespace
-
Include ignorable whitespace as text elements (disabled by default)
- ns
-
Define how XML namespaces should be processed. By default (value '
keep
'), this document:<doc> <x:foo xmlns:x="http://example.org/" bar="doz" /> </doc>
is transformed to this structure, keeping namespace prefixes and declarations as unprocessed element names and attributes:
[ 'doc', {}, [ [ 'x:foo', { 'bar' => 'doz', 'xmlns:x' => 'http://example.org/' } ] ]
Setting this option to '
strip
' will remove all namespace prefixes and namespace declaration attributes, so the result would be:[ 'doc', {}, [ [ 'foo', { 'bar' => 'doz' } ] ]
Setting this option to '
disallow
' results in an error when namespace prefixes or declarations are read.Expanding namespace URIs ('
expand'
) is not supported yet. - simple
-
Convert XML to simple key-value structure as known from XML::Simple.
- depth
-
Only transform to a given depth. All elements below the given depth are returned unmodified (not cloned) as ordered XML:
$data = simpleXML($xml, depth => 2) $content = $data->{x}->{y}; # array or scalar (if existing)
This option is useful for instance to access document-oriented XML embedded in data oriented XML.
Use any negative or non-numeric value for unlimited depth. The root element only counts as one level if option
root
is enabled. Depth zero (and depth one if with root) are only supported experimentally! - root
- content
-
These options are only relevant when option
simple
is true. See XML::Struct::Simple for documentation.
AUTHOR
Jakob Voß
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by Jakob Voß.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.