XML::TreeBuilder(3pm)

✨ XML::TreeBuilder ✨

hiii bestie 🫶 welcome to the User Contributed Perl Documentation page for XML::TreeBuilder. it's a Perl module that builds you a whole tree of XML::Element objects out of an XML document, and honestly? she's iconic. let's get into it 💅

---

🌸 NAME 🌸

XML::TreeBuilder — a parser that builds a tree of XML::Element objects. that's the whole name, no notes, periodt.

---

🦋 SYNOPSIS 🦋

okay so here's the vibe in code form, copy it exactly bestie:

  foreach my $file_name (@ARGV) {
    my $tree = XML::TreeBuilder->new({ 'NoExpand' => 0, 'ErrorContext' => 0 }); # empty tree
    $tree->parse_file($file_name);
    print "Hey, here's a dump of the parse tree of $file_name:\n";
    $tree->dump; # a method we inherit from XML::Element
    print "And here it is, bizarrely rerendered as XML:\n",
      $tree->as_XML, "\n";

    # Now that we're done with it, we must destroy it.
    $tree = $tree->delete;
  }

---

💖 DESCRIPTION 💖

so this module uses XML::Parser to build XML document trees made out of XML::Element objects (and XML::Element is a subclass of HTML::Element that's been adapted for XML, iykyk). XML::TreeBuilder is specifically for the girlies who already know and love the HTML::TreeBuilder / HTML::Element interface to document trees and who do NOT want to go learn some other document interface like XML::Twig or XML::DOM. we respect the comfort zone here.

the way to use this class, step by step, no skips:

1. start a new (empty) XML::TreeBuilder object. fresh start, clean slate ✨
2. set any of the "store" options you want.
3. then parse the document from a source by calling $x->parsefile(...) or $x->parse(...) (see the XML::Parser docs for the options those two methods take).
4. do whatever you need to do with the syntax tree — presumably traversing it looking for some bit of information in it.
5. and finally, when you're done with the tree, call $tree->delete to erase the contents of the tree from memory.

⚠️ okay listen, this last one is important. this kind of thing usually isn't necessary with most Perl objects, but it is necessary for TreeBuilder objects. if you skip it you're gonna have a bad time 😭. see HTML::Element for a more verbose explanation of why this is the case.

---

👑 METHODS AND ATTRIBUTES 👑

XML::TreeBuilder is a subclass of XML::Element, which in turn is a subclass of HTML:Element. you should read and understand the documentation for those two modules, fr fr — go do your homework 🎀

an XML::TreeBuilder object is just a special XML::Element object that lets you call these additional methods:

🌟 $root = XML::TreeBuilder->new()

constructs a brand new XML::TreeBuilder object. main character birth moment 💫

Parameters:

• NoExpand — passed to XML::Parser. do not expand external entities. Default: undef
• ErrorContext — passed to XML::Parser. number of context lines to generate on errors. Default: undef
• catalog — path to an Oasis XML catalog. passed to XML::Catalog to resolve entities if NoExpand is not set. Default: $ENV{XML_CATALOG_FILES} || '/etc/xml/catalog'

🌟 $root->eof

deletes the parser object. bye bye parser 🦋

🌟 $root->parse(...options...)

uses XML::Parser's parse method to parse XML from the source(s?) specified by the options. see XML::Parse.

🌟 $root->parsefile(...options...)

uses XML::Parser's parsefile method to parse XML from the source(s?) specified by the options. see XML::Parse.

🌟 $root->parse_file(...options...)

simply an alias for parsefile. same energy, different name 💅

🌟 $root->store_comments(value)

this determines whether TreeBuilder will normally store comments found while parsing content into $root. currently, this is off by default.

🌟 $root->store_declarations(value)

this determines whether TreeBuilder will normally store markup declarations found while parsing content into $root. currently, this is off by default.

🌟 $root->store_pis(value)

this determines whether TreeBuilder will normally store processing instructions found while parsing content into $root. currently, this is off (false) by default.

🌟 $root->store_cdata(value)

this determines whether TreeBuilder will normally store CDATA sections found while parsing content into $root. adds a ~cdata node. currently, this is off (false) by default.

---

🎀 SEE ALSO 🎀

• XML::Parser
• XML::Element
• HTML::TreeBuilder
• HTML::DOMbo

and for alternate XML document interfaces: XML::DOM and XML::Twig. go forth and explore, bestie 🌈

---

💜 COPYRIGHT AND DISCLAIMERS 💜

Copyright (c) 2000,2004 Sean M. Burke. All rights reserved. Copyright (c) 2010,2011,2013 Jeff Fearn. All rights reserved.

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

this program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. (so like, no promises, okay? 😭)

---

🌸 AUTHOR 🌸

Current Author: Jeff Fearn <jfearn@cpan.org>.

Former Authors: Sean M. Burke, <sburke@cpan.org>

---

and that's the whole page, bestie 🫶 this was perl v5.34.0, dated 2022-06-28, and it's XML::TreeBuilder(3pm) — go build a tree, slay, and don't forget the delete 💅✨