NAME¶
XML::Struct::Reader - Read XML streams into XML data structures
VERSION¶
version 0.23
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 option "from" 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 Voss
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2014 by Jakob Voss.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.