Petr Pajas > XML-CompactTree-0.03 > XML::CompactTree

Download:
XML-CompactTree-0.03.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.03   Source  

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

Document or Document Fragment Nodes

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

Text, CDATA, Comment and White-Space Nodes

Unparsed Entity, Processing-Instruction, and Notation Nodes

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
syntax highlighting: