Provided by: libxml-compacttree-perl_0.03-2_all bug

NAME

       XML::CompactTree - builder of compact tree structures from XML documents

VERSION

       Version 0.03

SYNOPSIS

           use XML::CompactTree;
           use XML::LibXML::Reader;

           my $reader = XML::LibXML::Reader->new(location => $url);
           ...
           my $tree = XML::CompactTree::readSubtreeToPerl($reader);
           ...

DESCRIPTION

       This module provides functions that use XML::LibXML::Reader to parse an XML document into
       a parse tree formed of nested arrays (and hashes).

       It aims to be fast in doing that and to presreve all relevant information from the XML
       (including namespaces, document order, mixed content, etc.). It sacrifices user
       friendliness for speed.

       IMPORTANT: There is an even more efficient XS implementation of this module called
       XML::CompactTree::XS with 100% equivalent functionality.

PURPOSE

       I wrote this module because I noticed that repeated calls to methods implemented in C (XS)
       were very expensive in Perl.

       Therefore traversing a large DOM tree using XML::LibXML or iterating over an XML stream
       using XML::LibXML::Reader was much slower than traversing similarly large and structured
       native Perl data structures.

       This module allows the user to build a document parse tree consisting of native Perl data
       structures (arrays and optionally hashes) using XML::LibXML::Reader with minimal number of
       XS calls.

       (Note that there XML::CompactTree::XS is 100% equivalent of this module that manages the
       same with just one XS call.)

       It does not provide full DOM navigation but attempts to provide maximum amount of
       information.  Its memory footprint should be somewhat smaller than that of a corresponding
       XML::LibXML DOM tree.

EXPORT

       By default, the following constants are exported (":flags" export tag) to be used as flags
       for the tree builder:

          XCT_IGNORE_WS
          XCT_IGNORE_SIGNIFICANT_WS
          XCT_IGNORE_PROCESSING_INSTRUCTIONS
          XCT_IGNORE_COMMENTS
          XCT_USE_QNAMES           /* not yet implemented */
          XCT_KEEP_NS_DECLS
          XCT_TEXT_AS_STRING       /* not yet implemented */
          XCT_ATTRIBUTE_ARRAY
          XCT_PRESERVE_PARENT      /* not yet implemented */
          XCT_MERGE_TEXT_NODES     /* not yet implemented */
          XCT_DOCUMENT_ROOT

FUNCTIONS

   readSubtreeToPerl( $reader, $flags, \my %ns )
       Uses a given XML::LibXML::Reader parser objects to parse a subtree at the current reader
       position to build a tree formed of nested arrays (see "OUTPUT FORMAT").

       reader
           A XML::LibXML::Reader object to use as the reader. While building the tree, the reader
           moves to the next node on the current or higher level.

       flags
           An integer consisting of 1 bit flags (see constants in the EXPORT section).  Use
           binary or (|) to combine individual flags.

           The following flags are NOT implemented yet:

              XCT_USE_QNAMES, XCT_TEXT_AS_STRING, XCT_PRESERVE_PARENT, XCT_MERGE_TEXT_NODES

       ns  You may pass an empty hash reference that will be populated by a namespace_uri to
           namespace_index map, that can be used to decode namespace indexes in the resulting
           data structure (see OUTPUT FORMAT).

   readLevelToPerl( $reader, $flags, $ns )
       Like "readSubtreeToPerl", but reads the subtree at the current reader position and all its
       following siblings.  It returns an array reference of representations of these subtrees as
       in the format described in "OUTPUT FORMAT".

OUTPUT FORMAT

       The result of parsing a subtree is a Perl array reference $node contains a node type
       followed by node data whose interpretation on further positions in $node depends on the
       node type, as described below:

   Any Node
       •    $node->[0] is an integer representing the node type. Use XML::LibXML::Reader node-tye
            constants, e.g. XML_READER_TYPE_ELEMENT for an element node, XML_READER_TYPE_TEXT for
            text node, etc.

   Document or Document Fragment Nodes
       •    $node->[1] contains the document encoding

       •    $node->[2] is an array reference containing similar represention of all the child
            nodes of the document (fragment).

       Note: XML::LibXML::Reader does not document node by default, which means that calling
       readSubtreeToPerl on a reader object in its initial state only parses the first node in
       the document (which can be the root element, but also a comment or a processing
       instruction). Use XCT_DOCUMENT_ROOT flag to force creating a document node in such case.

   Element nodes
       •    $node->[1] is the local name (UTF-8 encoded character string)

       •    $node->[2] is the namespace index (see NAMESPACES below)

       •    $node->[3] is undef if the element has no attributes. Otherwise if
            XCT_ATTRIBUTE_ARRAY flag was used, $node->[3] is an array reference of the form "[
            name1, value1, name2, value2, ....]" of attribute names and corresponding values. If
            XCT_ATTRIBUTE_ARRAY flag was not used, then $node->[3] is a hash reference mapping
            attribute names to the corresponding attribute values "{ name1="value1,
            name2=>value2...}>

            The flag XCT_KEEP_NS_DECLS controls whether namespace declarations (xmlns=... or
            xmlns:prefix=...) are included along with normal attributes or not.

            Note: there is no support for namespaced attributes yet, but the attribute names are
            stored as QNames, so one can always use XCT_KEEP_NS_DECLS to keep track of namespace
            prefix declarations and do the resolving manually. Support for namespaced attributes
            is planned.

       •    If XTC_LINE_NUMBERS flag was used, $node->[4] contains the line number of the element
            and $node->[5] contains an array reference containing similar representions of the
            child nodes of the current node.

       •    If XTC_LINE_NUMBERS flag was NOT used, $node->[4] contains an array reference of
            similar representations of the child nodes of the current node.

   Text, CDATA, Comment and White-Space Nodes
       •    $node->[1] contains the node value (UTF-8 encoded character string)

   Unparsed Entity, Processing-Instruction, and Notation Nodes
       •    $node->[1] contains the local name (there is no support for namespaces on these types
            of nodes yet)

       •    $node->[2] contains the node value

   Skipping Less-Significant Nodes
       White-space (non-significant or significant), processing-instruction and comment nodes can
       be completely skipped, using the following flags:

          XCT_IGNORE_WS
          XCT_IGNORE_SIGNIFICANT_WS
          XCT_IGNORE_PROCESSING_INSTRUCTIONS
          XCT_IGNORE_COMMENTS

NAMESPACES

       Namespaces of element nodes are stored in the element node as an integer. 0 always
       represents nodes without namespace, all other namespaces are assigned unique numbers in an
       increasing order as they appear. You can pass an empty hash reference to the parsing
       functions to obtain the mapping.

   Example
         use XML::CompactTree;
         use XML::LibXML::Reader;

         my $reader = XML::LibXML::Reader->new(location => $ARGV[0]);
         my %ns;
         my $data = XML::CompactTree::readSubtreeToPerl( $reader, XCT_DOCUMENT_ROOT, \%ns );
         $ns_map[$ns{$_}]=$_ for keys %ns;
         my @nodes = ($data);
         while (@nodes) {
           my $node = shift @nodes;
           my $type = $node->[0];
           if ($type == XML_READER_TYPE_ELEMENT) {
             print "element $node->[1] is from ns $node->[2] '$ns_map[$node->[2]]'\n";
             push @nodes, @{$node->[4]}; # queue children
           } elsif ($type == XML_READER_TYPE_DOCUMENT) {
             push @nodes, @{$node->[2]}; # queue children
           }
         }

PLANNED FEATURES

       Planned flags:

          XCT_USE_QNAMES - use QNames instead of local names for all nodes
          XCT_TEXT_AS_STRING - put text nodes into the tree as plain scalars
          XCT_PRESERVE_PARENT - add a slot with a weak reference to the parent node
          XCT_MERGE_TEXT_NODES - merge adjacent text/cdata nodes together

       Features: allow blessing the array refs to default or user-specified classes; the default
       classes would provide a very small subset of DOM methods to retrieve node information,
       manipulate the tree, and possibly serialize the parse tree back to XML.

AUTHOR

       Petr Pajas, "<pajas@matfyz.cz>"

BUGS

       Please report any bugs or feature requests to "bug-xml-compacttree-xs@rt.cpan.org", or
       through the web interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=XML-CompactTree-XS>.  I will be notified,
       and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE

       Copyright 2008-2009 Petr Pajas, All Rights Reserved.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

SEE ALSO

         XML::CompactTree::XS

         XML::LibXML::Reader