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
- $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.
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.
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¶
Sean M. Burke, <sburke@cpan.org>