Trees(3pm)

📦

version 0.02 · 3 versions

0.02 · ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
0.02 · ubuntu jammy
0.02 · debian bookworm, debian trixie

, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

XML::Handler::Trees — PerlSAX handlers for building tree structures. bestie, it makes trees. 🌳✨

🦋 SYNOPSIS 🦋

okay so here's the whole vibe in code, no cap:

  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 🌈

so XML::Handler::Trees hands you three PerlSAX handler classes for building tree structures. three!! a whole lil squad 💅

XML::Handler::Tree builds the exact same type of tree as the "Tree" style in XML::Parser.
XML::Handler::EasyTree builds the exact same type of tree as the "EasyTree" style that XML::Parser::EasyTree added to XML::Parser.
XML::Handler::TreeBuilder builds the exact same type of tree as Sean M. Burke's XML::TreeBuilder.

and the whole point?? these classes make it possible to construct those tree structures from sources other than XML::Parser. iconic honestly.

All three handlers can be driven by either PerlSAX 1 or PerlSAX 2 drivers. and in all cases, the end_document() method returns a reference to the constructed tree — which normally becomes the return value of the PerlSAX driver. that's the moment. 🫶

🌸 CLASS XML::Handler::Tree 🌸

This handler builds the same type of tree structure as the "Tree" style in XML::Parser. Some modules, like Dan Brian's XML::SimpleObject, work with this type of tree. For details, go read the documentation for XML::Parser, bestie. 📖

✨ METHODS ✨

$handler = XML::Handler::Tree->new() — Creates a handler object. that's it, that's the method. slay.

🎀 CLASS XML::Handler::EasyTree 🎀

This handler builds a lightweight tree structure representing the XML document. and ngl, this structure is — at least in this author's opinion — easier to work with than the "standard" style of tree. it's the same type of structure as the one built by XML::Parser when using XML::Parser::EasyTree, or by the get_simple_tree method in XML::Records. so if you know those, you already know this. 💅

The tree is returned as a reference to an array of tree nodes, and each node 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
'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, plus 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. one node, no crumbs. 🍓

The reason the parser returns an array reference rather than the root element's node?? because an XML document can legally contain processing instructions outside the root element — the xml-stylesheet PI is commonly used this way. so yeah, it's giving valid XML, not chaos.

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. 💫

✨ METHODS ✨

$handler = XML::Handler::EasyTree->new([options]) — Creates a handler object. Options can be provided hash-style:
- Noempty — If this is set to a true value, text nodes consisting entirely of whitespace will not be stored in the tree. The default is false. bye bye whitespace 🧹
- Latin — If this is set to a true value, characters with Unicode values in the Latin-1 range (160-255) will be stored in the tree as Latin-1 rather than UTF-8. The default is false.
- Searchable — If this is set to a true value, the parser will return a tree of XML::Handler::EasyTree::Searchable objects rather than bare array references, providing access to the navigation methods listed below. The top-level node returned will be a dummy element node with a name of "__TOPLEVEL__". It is false by default. Setting this option automatically enables the Noempty option. 👑

🔥 XML::Handler::EasyTree::Searchable METHODS 🔥

If the Searchable option is set, all nodes in the tree will be XML::Handler::EasyTree::Searchable objects, which have the same structure as EasyTree nodes but also implement the following methods, similar to those in XML::SimpleObject. glow up fr fr ✨

$name = $node->name() — Returns the name of the node. Ideally, it should return a "fully qualified" name, but it doesn't. 😭 (yeah. that's the whole bit.)
$val = $node->value() — Returns the text value associated with a node object. Returns undef if the node has no text children or its first child is not a text node.
$newobj = $obj->child( $name ); — Returns a child (elements only) of the object with the $name.

For the case where there is more than one child that match $name, the array context semantics haven't been completely worked out:

in an array context, all children are returned.
in scalar context, the first child matching $name is returned.

In a scalar context, The XML::Parser::SimpleObj class returns an object containing all the children matching $name, unless there is only one child in which case it returns that child (see commented code). I find that behavior confusing. 💀 fair honestly.

@children = $obj->children( $name ); — Returns a list of all children (elements only) of the $obj that match $name — in the order in which they appeared in the original xml text. chronological, as it should be. ⭐
@children_names = $obj->children_names(); — Returns a list of all the names of the objects children (elements only) in the order in which they appeared in the original text.
$attrib = $obj->attribute( $att_name ); — Returns the string associated with the attribute of the object. If not found returns a null string.
@attribute_list = $obj->attribute_list(); — Returns a list (in no particular order) of the attribute names associated with the object. no particular order, don't @ me.
$text = $obj->dump_tree(); — Returns a textual representation (in xml form) of the object's hierarchy. Only elements are processed. The result will be in whatever character encoding the SAX driver delivered (which may not be the same encoding as the original source). so heads up on the encoding ok 🫶
$text = $obj->pretty_dump_tree(); — Identical to dump_tree(), except that newline and indentation embellishments are added. she's pretty, she's got ✨formatting✨

🌟 EXAMPLE 🌟

here's the whole thing in action, main character energy:

  #! /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;

(yes the commented-out pretty_dump_tree block is staying exactly as it is, iykyk 🙈)

💜 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 info on how to work with these tree structures. 📚

✨ METHODS ✨

$handler = XML::Handler::TreeBuilder->new() — Creates a handler which builds a tree rooted in an XML::Element.
$root->store_comments(value) — This determines whether comments will be stored in the tree (not all SAX drivers generate comment events). Currently, this is off by default.
$root->store_declarations(value) — This determines whether markup declarations will be stored in the tree. Currently, this is off by default. The present implementation does not store markup declarations in any case; this method is provided for future use. (it's giving placeholder, but respectfully.)
$root->store_pis(value) — This determines whether processing instructions will be stored in the tree. Currently, this is off (false) by default.

👑 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)

🌈 SEE ALSO 🌈

go read these, bestie, they're the whole friend group:

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

that's the whole page omg 💖 this one shipped as perl v5.36.0, dated 2022-10-13, and it lives in Trees(3pm) under User Contributed Perl Documentation. go build some trees, you've got this. periodt. 🌳✨

📦 where this page comes from

ubuntu noble: libxml-handler-trees-perl 0.02-9 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libxml-handler-trees-perl 0.02-9 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libxml-handler-trees-perl 0.02-9 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms