NAME

XML::Handler::Trees - PerlSAX handlers for building tree structures

SYNOPSIS

  use XML::Handler::Trees;
  use XML::Parser::PerlSAX;
  my $p=XML::Parser::PerlSAX->new();
  my $h=XML::Handler::Tree->new();
  my $tree=$p->parse(Handler=>$h,Source=>{SystemId=>'file.xml'});
  my $p=XML::Parser::PerlSAX->new();
  my $h=XML::Handler::EasyTree->new(Noempty=>1);
  my $easytree=$p->parse(Handler=>$h,Source=>{SystemId=>'file.xml'});
  my $p=XML::Parser::PerlSAX->new();
  my $h=XML::Handler::TreeBuilder->new();
  $h->store_pis(1);
  my $tree=$p->parse(Handler=>$h,Source=>{SystemId=>'file.xml'});

DESCRIPTION

XML::Handler::Trees provides three PerlSAX handler classes for building tree structures. XML::Handler::Tree builds the same type of tree as the "Tree" style in XML::Parser. XML::Handler::EasyTree builds the same type of tree as the "EasyTree" style added to XML::Parser by XML::Parser::EasyTree. XML::Handler::TreeBuilder builds the same type of tree as Sean M. Burke's XML::TreeBuilder. These classes make it possible to construct these tree structures from sources other than XML::Parser.

All three handlers can be driven by either PerlSAX 1 or PerlSAX 2 drivers. In all cases, the end_document() method returns a reference to the constructed tree, which normally becomes the return value of the PerlSAX driver.

CLASS XML::Handler::Tree

This handler builds the same type of tree structure as the "Tree" style in XML::Parser. Some modules such as Dan Brian's XML::SimpleObject work with this type of tree. See the documentation for XML::Parser for details.

CLASS XML::Handler::EasyTree

This handler builds a lightweight tree structure representing the XML document. This structure is, at least in this author's opinion, easier to work with than the "standard" style of tree. It is the same type of structure as built by XML::Parser when using XML::Parser::EasyTree, or by the get_simple_tree method in XML::Records.

The tree is returned as a reference to an array of tree nodes, each of which is a hash reference. All nodes have a 'type' key whose value is the type of the node: 'e' for element nodes, 't' for text nodes, and 'p' for processing instruction nodes. All nodes also have a 'content' key whose value is a reference to an array holding the element's child nodes for element nodes, the string value for text nodes, and the data value for processing instruction nodes. Element nodes also have an 'attrib' key whose value is a reference to a hash of attribute names and values and a 'name' key whose value is the element's name. Processing instructions also have a 'target' key whose value is the PI's target.

EasyTree nodes are ordinary Perl hashes and are not objects. Contiguous runs of text are always returned in a single node.

The reason the parser returns an array reference rather than the root element's node is that an XML document can legally contain processing instructions outside the root element (the xml-stylesheet PI is commonly used this way).

If namespace information is available (only possible with PerlSAX 2), element and attribute names will be prefixed with their (possibly empty) namespace URI enclosed in curly brackets, and namespace prefixes will be stripped from names.

 #! /usr/bin/perl -w
 
 use XML::Handler::Trees;
 use XML::Parser::PerlSAX;
 use strict;
 
 my $p=XML::Parser::PerlSAX->new();
 my $h=XML::Handler::EasyTree->new( Searchable=>1 );
 my $easytree=$p->parse( Handler => $h, Source => { SystemId => 'systemB.xml' } );
 
 my $vme = $easytree->child( "vmesystem" );
 
 print "\n";
 print "vmesystem config: ", $vme->attribute( "configuration_name" ), "\n";
 
 print "\n";
 print "vmesystem children: ", join( ', ', $vme->children_names() ), "\n";
 
 print "\n";
 print "gps model is ", $vme->child( "gps" )->child( "model" )->value(), "\n";
 my $gps = $vme->child( "gps" );
 print "gps slot is ", $gps->child( "slot" )->value(), "\n";
 
 print "\n";
 print "reconstructed XML: \n";
 print $easytree->dump_tree(), "\n";
 
 # print "\n";
 # print "recontructed XML (pretty): \n";
 # print $easytree->pretty_dump_tree(), "\n";
 
 print "\n";
 exit;

CLASS XML::Handler::TreeBuilder

This handler builds XML document trees constructed of XML::Element objects (XML::Element is a subclass of HTML::Element adapted for XML). To use it, XML::TreeBuilder and its prerequisite HTML::Tree need to be installed. See the documentation for those modules for information on how to work with these tree structures.

AUTHOR

Eric Bohlman (ebohlman@omsdev.com)

PerlSAX 2 compatibility added by Matt Sergeant (matt@sergeant.org)

XML::EasyTree::Searchable written by Stuart McDow (smcdow@moontower.org)

Copyright (c) 2001 Eric Bohlman.

Portions of this code Copyright (c) 2001 Matt Sergeant.

Portions of this code Copyright (c) 2001 Stuart McDow.

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

 L<perl>
 L<XML::Parser>
 L<XML::SimpleObject>
 L<XML::Parser::EasyTree>
 L<XML::TreeBuilder>
 L<XML::Element>
 L<HTML::Element>
 L<PerlSAX>