1XML::TreeBuilder(3)   User Contributed Perl Documentation  XML::TreeBuilder(3)
2
3
4

NAME

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

SYNOPSIS

9         foreach my $file_name (@ARGV) {
10           my $tree = XML::TreeBuilder->new({ 'NoExpand' => 0, 'ErrorContext' => 0 }); # empty tree
11           $tree->parse_file($file_name);
12           print "Hey, here's a dump of the parse tree of $file_name:\n";
13           $tree->dump; # a method we inherit from XML::Element
14           print "And here it is, bizarrely rerendered as XML:\n",
15             $tree->as_XML, "\n";
16
17           # Now that we're done with it, we must destroy it.
18           $tree = $tree->delete;
19         }
20

DESCRIPTION

22       This module uses XML::Parser to make XML document trees constructed of
23       XML::Element objects (and XML::Element is a subclass of HTML::Element
24       adapted for XML).  XML::TreeBuilder is meant particularly for people
25       who are used to the HTML::TreeBuilder / HTML::Element interface to
26       document trees, and who don't want to learn some other document
27       interface like XML::Twig or XML::DOM.
28
29       The way to use this class is to:
30
31       1. start a new (empty) XML::TreeBuilder object.
32
33       2. set any of the "store" options you want.
34
35       3. then parse the document from a source by calling
36       "$x->parsefile(...)"  or "$x->parse(...)" (See XML::Parser docs for the
37       options that these two methods take)
38
39       4. do whatever you need to do with the syntax tree, presumably
40       involving traversing it looking for some bit of information in it,
41
42       5. and finally, when you're done with the tree, call $tree->delete to
43       erase the contents of the tree from memory.  This kind of thing usually
44       isn't necessary with most Perl objects, but it's necessary for
45       TreeBuilder objects.  See HTML::Element for a more verbose explanation
46       of why this is the case.
47

METHODS AND ATTRIBUTES

49       XML::TreeBuilder is a subclass of XML::Element, which in turn is a
50       subclass of HTML:Element.  You should read and understand the
51       documentation for those two modules.
52
53       An XML::TreeBuilder object is just a special XML::Element object that
54       allows you to call these additional methods:
55
56       $root = XML::TreeBuilder->new()
57           Construct a new XML::TreeBuilder object.
58
59           Parameters:
60
61           NoExpand
62                   Passed to XML::Parser. Do not Expand external entities.
63                   Default: undef
64
65           ErrorContext
66                   Passed to XML::Parser. Number of context lines to generate on errors.
67                   Default: undef
68
69           catalog
70                   Path to an Oasis XML catalog. Passed to XML::Catalog to resolve entities if NoExpand is not set.
71                   Default: $ENV{XML_CATALOG_FILES} || '/etc/xml/catalog'
72
73       $root->eof
74           Deletes parser object.
75
76       $root->parse(...options...)
77           Uses XML::Parser's "parse" method to parse XML from the source(s?)
78           specified by the options.  See XML::Parse
79
80       $root->parsefile(...options...)
81           Uses XML::Parser's "parsefile" method to parse XML from the
82           source(s?)  specified by the options.  See XML::Parse
83
84       $root->parse_file(...options...)
85           Simply an alias for "parsefile".
86
87       $root->store_comments(value)
88           This determines whether TreeBuilder will normally store comments
89           found while parsing content into $root.  Currently, this is off by
90           default.
91
92       $root->store_declarations(value)
93           This determines whether TreeBuilder will normally store markup
94           declarations found while parsing content into $root.  Currently,
95           this is off by default.
96
97       $root->store_pis(value)
98           This determines whether TreeBuilder will normally store processing
99           instructions found while parsing content into $root.  Currently,
100           this is off (false) by default.
101
102       $root->store_cdata(value)
103           This determines whether TreeBuilder will normally store CDATA
104           sectitons found while parsing content into $root. Adds a ~cdata
105           node.
106
107           Currently, this is off (false) by default.
108

SEE ALSO

110       XML::Parser, XML::Element, HTML::TreeBuilder, HTML::DOMbo.
111
112       And for alternate XML document interfaces, XML::DOM and XML::Twig.
113

115       Copyright (c) 2000,2004 Sean M. Burke.  All rights reserved.  Copyright
116       (c) 2010,2011,2013 Jeff Fearn. All rights reserved.
117
118       This library is free software; you can redistribute it and/or modify it
119       under the same terms as Perl itself.
120
121       This program is distributed in the hope that it will be useful, but
122       without any warranty; without even the implied warranty of
123       merchantability or fitness for a particular purpose.
124

AUTHOR

126       Current Author:      Jeff Fearn <jfearn@cpan.org>.
127
128       Former Authors:      Sean M. Burke, <sburke@cpan.org>
129
130
131
132perl v5.36.0                      2023-01-20               XML::TreeBuilder(3)
Impressum