NAME

       XML::TreeBuilder - Parser that builds a tree of XML::Element objects

SYNOPSIS

         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

       This module uses XML::Parser to make XML document trees constructed of XML::Element objects (and
       XML::Element is a subclass of HTML::Element adapted for XML).  XML::TreeBuilder is meant particularly for
       people who are used to the HTML::TreeBuilder / HTML::Element interface to document trees, and who don't
       want to learn some other document interface like XML::Twig or XML::DOM.

       The way to use this class is to:

       1. start a new (empty) XML::TreeBuilder object.

       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
       XML::Parser docs for the options that these two methods take)

       4. do whatever you need to do with the syntax tree, presumably involving 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.  This kind of thing usually isn't necessary with most Perl objects, but it's necessary for
       TreeBuilder objects.  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.

       An XML::TreeBuilder object is just a special XML::Element object that allows you to call these additional
       methods:

       $root = XML::TreeBuilder->new()
           Construct a new XML::TreeBuilder object.

           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 parser object.

       $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".

       $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 sectitons 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.

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.

AUTHOR

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

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

perl v5.34.0                                       2022-06-28                              XML::TreeBuilder(3pm)