.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XML::TreeBuilder 3pm"
.TH XML::TreeBuilder 3pm "2015-06-05" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::TreeBuilder \- Parser that builds a tree of XML::Element objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\&  foreach my $file_name (@ARGV) {
\&    my $tree = XML::TreeBuilder\->new({ \*(AqNoExpand\*(Aq => 0, \*(AqErrorContext\*(Aq => 0 }); # empty tree
\&    $tree\->parse_file($file_name);
\&    print "Hey, here\*(Aqs a dump of the parse tree of $file_name:\en";
\&    $tree\->dump; # a method we inherit from XML::Element
\&    print "And here it is, bizarrely rerendered as XML:\en",
\&      $tree\->as_XML, "\en";
\&    
\&    # Now that we\*(Aqre done with it, we must destroy it.
\&    $tree = $tree\->delete;
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module uses XML::Parser to make \s-1XML\s0 document trees constructed of
XML::Element objects (and XML::Element is a subclass of HTML::Element
adapted for \s-1XML\s0).  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 \s-1XML::DOM.\s0
.PP
The way to use this class is to:
.PP
1. start a new (empty) XML::TreeBuilder object.
.PP
2. set any of the \*(L"store\*(R" options you want.
.PP
3. then parse the document from a source by calling
\&\f(CW\*(C`$x\->parsefile(...)\*(C'\fR
or
\&\f(CW\*(C`$x\->parse(...)\*(C'\fR (See XML::Parser docs for the options
that these two methods take)
.PP
4. do whatever you need to do with the syntax tree, presumably
involving traversing it looking for some bit of information in it,
.PP
5. and finally, when you're done with the tree, call \f(CW$tree\fR\->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.
.SH "METHODS AND ATTRIBUTES"
.IX Header "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.
.PP
An XML::TreeBuilder object is just a special XML::Element object that
allows you to call these additional methods:
.ie n .IP "$root = XML::TreeBuilder\->\fInew()\fR" 4
.el .IP "\f(CW$root\fR = XML::TreeBuilder\->\fInew()\fR" 4
.IX Item "$root = XML::TreeBuilder->new()"
Construct a new XML::TreeBuilder object.
.Sp
Parameters:
.RS 4
.IP "NoExpand" 4
.IX Item "NoExpand"
.Vb 2
\&    Passed to XML::Parser. Do not Expand external entities.
\&    Default: undef
.Ve
.IP "ErrorContext" 4
.IX Item "ErrorContext"
.Vb 2
\&    Passed to XML::Parser. Number of context lines to generate on errors.
\&    Default: undef
.Ve
.IP "catalog" 4
.IX Item "catalog"
.Vb 2
\&    Path to an Oasis XML catalog. Passed to XML::Catalog to resolve entities if NoExpand is not set.
\&    Default: $ENV{XML_CATALOG_FILES} || \*(Aq/etc/xml/catalog\*(Aq
.Ve
.RE
.RS 4
.RE
.ie n .IP "$root\->eof" 4
.el .IP "\f(CW$root\fR\->eof" 4
.IX Item "$root->eof"
Deletes parser object.
.ie n .IP "$root\->parse(...options...)" 4
.el .IP "\f(CW$root\fR\->parse(...options...)" 4
.IX Item "$root->parse(...options...)"
Uses XML::Parser's \f(CW\*(C`parse\*(C'\fR method to parse \s-1XML\s0 from the source(s?)
specified by the options.  See XML::Parse
.ie n .IP "$root\->parsefile(...options...)" 4
.el .IP "\f(CW$root\fR\->parsefile(...options...)" 4
.IX Item "$root->parsefile(...options...)"
Uses XML::Parser's \f(CW\*(C`parsefile\*(C'\fR method to parse \s-1XML\s0 from the source(s?)
specified by the options.  See XML::Parse
.ie n .IP "$root\->parse_file(...options...)" 4
.el .IP "\f(CW$root\fR\->parse_file(...options...)" 4
.IX Item "$root->parse_file(...options...)"
Simply an alias for \f(CW\*(C`parsefile\*(C'\fR.
.ie n .IP "$root\->store_comments(value)" 4
.el .IP "\f(CW$root\fR\->store_comments(value)" 4
.IX Item "$root->store_comments(value)"
This determines whether TreeBuilder will normally store comments found
while parsing content into \f(CW$root\fR.  Currently, this is off by default.
.ie n .IP "$root\->store_declarations(value)" 4
.el .IP "\f(CW$root\fR\->store_declarations(value)" 4
.IX Item "$root->store_declarations(value)"
This determines whether TreeBuilder will normally store markup
declarations found while parsing content into \f(CW$root\fR.  Currently,
this is off by default.
.ie n .IP "$root\->store_pis(value)" 4
.el .IP "\f(CW$root\fR\->store_pis(value)" 4
.IX Item "$root->store_pis(value)"
This determines whether TreeBuilder will normally store processing
instructions found while parsing content into \f(CW$root\fR.
Currently, this is off (false) by default.
.ie n .IP "$root\->store_cdata(value)" 4
.el .IP "\f(CW$root\fR\->store_cdata(value)" 4
.IX Item "$root->store_cdata(value)"
This determines whether TreeBuilder will normally store \s-1CDATA\s0
sectitons found while parsing content into \f(CW$root\fR. Adds a ~cdata node.
.Sp
Currently, this is off (false) by default.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
XML::Parser, XML::Element, HTML::TreeBuilder, HTML::DOMbo.
.PP
And for alternate \s-1XML\s0 document interfaces, \s-1XML::DOM\s0 and XML::Twig.
.SH "COPYRIGHT AND DISCLAIMERS"
.IX Header "COPYRIGHT AND DISCLAIMERS"
Copyright (c) 2000,2004 Sean M. Burke.  All rights reserved.
Copyright (c) 2010,2011,2013 Jeff Fearn. All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.PP
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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Current Author:
	Jeff Fearn <jfearn@cpan.org>.
.PP
Former Authors:
	Sean M. Burke, <sburke@cpan.org>