NAME

XML::Struct::Reader - Read XML stream into XML data structures

VERSION

version 0.11

SYNOPSIS

    my $reader = XML::Struct::Reader->new( from => "file.xml" );
    my $data   = $reader->read;

DESCRIPTION

This module reads from an XML stream via XML::LibXML::Reader and return a Perl data structure with ordered XML (see XML::Struct).

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 hash reference or an empty list if no attributes were found.

readContent( [ $stream ] )

Read all child elements of an XML element and return the result as array reference or as empty list if no children were found. 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, 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 ".." or //, no node tests...). Namespaces are not supported yet.

whitespace

Include ignorable whitespace as text elements (disabled by default)

AUTHOR

Jakob Voß

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 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.