lib/XML/Handler/Trees.pm

   1 use strict;
   2
   3 package XML::Handler::Trees;
   4 use vars qw/$VERSION/;
   5 $VERSION = '0.02';
   6
   7 package XML::Handler::Tree;
   8
   9 sub new {
  10   my $class = ref($_[0]) || $_[0];
  11   bless {},$class;
  12 }
  13
  14 sub start_document {
  15   my $self=shift;
  16   $self->{Lists}=[];
  17   $self->{Curlist}=$self->{Tree}=[];
  18 }
  19
  20 sub start_element {
  21   my ($self,$element)=@_;
  22   my $newlist;
  23   if (exists $element->{LocalName}) {
  24     # namespaces are available!
  25     $newlist = [{}];
  26     foreach my $attr (values %{$element->{Attributes}}) {
  27       if ($attr->{NamespaceURI}) {
  28         $newlist->[0]{"{$attr->{NamespaceURI}}$attr->{LocalName}"} = $attr->{Value};
  29       }
  30       else {
  31         $newlist->[0]{$attr->{Name}} = $attr->{Value};
  32       }
  33     }
  34   }
  35   elsif (ref $element->{Attributes} eq 'HASH') {
  36     $newlist=[{map {$_=>$element->{Attributes}{$_}} keys %{$element->{Attributes}}}];
  37   }
  38   else {
  39     $newlist=[{map {$_=>$element->{Attributes}{$_}{Value}} keys %{$element->{Attributes}}}];
  40   }
  41   push @{ $self->{Lists} }, $self->{Curlist};
  42   if (exists($element->{LocalName}) && $element->{NamespaceURI}) {
  43     push @{ $self->{Curlist} }, "{$element->{NamespaceURI}}$element->{LocalName}" => $newlist;
  44   }
  45   else {
  46     push @{ $self->{Curlist} }, $element->{Name} => $newlist;
  47   }
  48   $self->{Curlist} = $newlist;
  49 }
  50
  51 sub end_element {
  52   my ($self,$element)=@_;
  53   $self->{Curlist}=pop @{$self->{Lists}};
  54 }
  55
  56 sub characters {
  57   my ($self,$text)=@_;
  58   my $clist = $self->{Curlist};
  59   my $pos = $#$clist;
  60   if ($pos>0 and $clist->[$pos-1] eq '0') {
  61     $clist->[$pos].=$text->{Data};
  62   }
  63   else {
  64     push @$clist,0=>$text->{Data};
  65   }
  66 }
  67
  68 sub comment {}
  69
  70 sub processing_instruction {}
  71
  72 sub end_document {
  73   my $self=shift;
  74   delete $self->{Curlist};
  75   delete $self->{Lists};
  76   $self->{Tree};
  77 }
  78
  79 package XML::Handler::EasyTree;
  80
  81 sub new {
  82   my $class=shift;
  83   $class=ref($class) || $class;
  84   my $self={Noempty=>0,Latin=>0,Searchable=>0,@_};
  85   $self->{Noempty}||=$self->{Searchable};
  86   bless $self,$class;
  87 }
  88
  89 sub start_document {
  90   my $self = shift;
  91   $self->{Lists} = [];
  92   $self->{Curlist} = $self->{Tree} = [];
  93 }
  94
  95 sub start_element {
  96   my ($self,$element)=@_;
  97   $self->checkempty();
  98   my $newlist=[];
  99   my $newnode;
 100   if ($self->{Searchable}) {
 101     $newnode= XML::Handler::EasyTree::Searchable->new( Name => $self->nsname($element), Content => $newlist );
 102   }
 103   else {
 104     $newnode={type=>'e',attrib=>{},name=>$self->nsname($element),content=>$newlist};
 105   }
 106   if (exists $element->{LocalName}) {
 107     while (my ($name,$obj) = each %{$element->{Attributes}}) {
 108       $newnode->{attrib}{$name} = $self->encode($obj->{Value});
 109     }
 110   }
 111   elsif (ref $element->{Attributes} eq 'HASH') {
 112     while (my ($name,$val)=each %{$element->{Attributes}}) {
 113       $newnode->{attrib}{$self->nsname($name)}=$self->encode($val);
 114     }
 115   }
 116   else {
 117     foreach my $att (keys %{$element->{Attributes}}) {
 118       $newnode->{attrib}{$self->nsname($element->{Attributes}{$att})}=$self->encode($element->{Attributes}{$att}{Value});
 119     }
 120   }
 121   push @{ $self->{Lists} }, $self->{Curlist};
 122   push @{ $self->{Curlist} }, $newnode;
 123   $self->{Curlist} = $newlist;
 124 }
 125
 126 sub end_element {
 127   my $self=shift;
 128   $self->checkempty();
 129   $self->{Curlist}=pop @{$self->{Lists}};
 130 }
 131
 132 sub characters {
 133   my ($self,$text)=@_;
 134   my $clist=$self->{Curlist};
 135   if (!@$clist || $clist->[-1]{type} ne 't') {
 136     push @$clist,{type=>'t',content=>''};
 137   }
 138   $clist->[-1]{content}.=$self->encode($text->{Data});
 139 }
 140
 141 sub processing_instruction {
 142   my ($self,$pi)=@_;
 143   $self->checkempty();
 144   my $clist=$self->{Curlist};
 145   push @$clist,{type=>'p',target=>$self->encode($pi->{Target}),content=>$self->encode($pi->{Data})};
 146 }
 147
 148 sub comment {}
 149
 150 sub end_document {
 151   my $self = shift;
 152   $self->checkempty();
 153   delete $self->{Curlist};
 154   delete $self->{Lists};
 155   if ($self->{Searchable}) {
 156     return XML::Handler::EasyTree::Searchable->new( Name => '__TOPLEVEL__', Content => $self->{Tree} );
 157   }
 158   $self->{Tree};
 159 }
 160
 161 sub nsname {
 162   my ($self,$name)=@_;
 163   if (ref $name) {
 164     if (defined $name->{NamespaceURI}) {
 165       $name="{$name->{NamespaceURI}}$name->{LocalName}";
 166     }
 167     else {
 168       $name=$name->{Name};
 169     }
 170   }
 171   return $self->encode($name);
 172 }
 173
 174 sub encode {
 175   my ($self,$text)=@_;
 176   if ($self->{Latin}) {
 177     $text=~s{([\xc0-\xc3])(.)}{
 178       my $hi = ord($1);
 179       my $lo = ord($2);
 180       chr((($hi & 0x03) <<6) | ($lo & 0x3F))
 181      }ge;
 182   }
 183   $text;
 184 }
 185
 186 sub checkempty() {
 187   my $self=shift;
 188   if ($self->{Noempty}) {
 189     my $clist=$self->{Curlist};
 190     if (@$clist && $clist->[-1]{type} eq 't' && $clist->[-1]{content}=~/^\s+$/) {
 191       pop @$clist;
 192     }
 193   }
 194 }
 195
 196 package XML::Handler::EasyTree::Searchable;
 197
 198 #
 199 # new() returns a new node with the same structure at the `newnode'
 200 # hashref
 201 #
 202 # Usage: XML::Handler::EasyTree::Searchable->new( Name => $name, Content => $content );
 203 #
 204 sub new {
 205   my $type = shift;
 206   my $class = ref($type) || $type || die "must supply a object type" ;
 207
 208   my %opts = @_;
 209
 210   my $name = $opts{Name} || '';
 211   my $content = $opts{Content} || undef;
 212
 213   return bless ( {
 214                   type    => 'e',
 215                   attrib  => {},
 216                   name    => $name,
 217                   content => $content,
 218                  }, $class);
 219 }
 220
 221 #
 222 # name() returns the name of the node. Ideally, it should return a
 223 # "fully qualified" name, but it doesn't
 224 #
 225 sub name {
 226   my $self = shift;
 227   return $self->{name};
 228 }
 229
 230 #
 231 # value() returns the value associated with an object
 232 #
 233 sub value {
 234   my $self = shift;
 235
 236   return( undef )
 237     unless( ( exists $self->{content} ) && ( defined $self->{content} ) );
 238
 239   my $possible = $self->{content};
 240
 241   die "not an array" unless( "$possible" =~ /ARRAY/ );
 242
 243   $possible = $possible->[0];
 244
 245   return( undef )
 246     unless( ( exists $possible->{type} ) && ( $possible->{type} eq 't' ) );
 247
 248   return( undef )
 249     unless( ( exists $possible->{content} ) && ( defined $possible->{content} ) );
 250
 251   return $possible->{content};
 252 }
 253
 254 #
 255 # usage: $newobj = $obj->child( $name );
 256 #
 257 # child() returns a child (elements only) of the object with the $name
 258 #
 259 # for the case where there is more than one child that match $name,
 260 # the array context semantics haven't been completely worked out:
 261 # - in an array context, all children are returned.
 262 # - in scalar context, the first child matching $name is returned.
 263 #
 264 # In a scalar context, The XML::Parser::SimpleObj class returns an
 265 # object containing all the children matching $name, unless there is
 266 # only one child in which case it returns that child (see commented
 267 # code). I find that behavior confusing.
 268 #
 269 sub child {
 270   my $self = shift;
 271   my $spec = shift || '';
 272
 273   my $array = $self->{content};
 274
 275   my @rv;
 276   if( $spec ) {
 277     @rv = grep { $_->{name} eq $spec } grep { $_->{type} eq 'e' } @$array;
 278   } else {
 279     @rv = grep { $_->{type} eq 'e' } @$array;
 280   }
 281
 282   my $num = scalar( @rv );
 283
 284   if( wantarray() ) {
 285     return @rv;
 286   } else {
 287     return '' unless( $num );
 288     return $rv[0] if( $num == 1 );
 289     # my $class = ref( $self );
 290     # return $class->new( Name => "__magic_child_list_object__", Content => [ @rv ] );
 291   }
 292 }
 293
 294 #
 295 # usage: @children = $obj->children( $name );
 296 #
 297 # children() returns a list of all children (elements only) of the
 298 # $obj that match $name -- in the order in which they appeared in the
 299 # original xml text.
 300 #
 301 sub children {
 302   my $self = shift;
 303   my $array = $self->{content};
 304   my $spec = shift || '';
 305
 306
 307   my @rv;
 308   if( $spec ) {
 309     @rv = grep { $_->{name} eq $spec } grep { $_->{type} eq 'e' } @$array;
 310   } else {
 311     @rv = grep { $_->{type} eq 'e' } @$array;
 312   }
 313
 314   return @rv;
 315 }
 316
 317 #
 318 # usage: @children_names = $obj->children_names();
 319 #
 320 # children_names() returns a list of all the names of the objects
 321 # children (elements only) in the order in which they appeared in the
 322 # original text
 323 #
 324 sub children_names {
 325   my $self = shift;
 326   my $array = $self->{content};
 327
 328   return map { $_->{name} } grep { $_->{type} eq 'e' } @$array;
 329 }
 330
 331 #
 332 # usage: $attrib = $obj->attribute( $att_name );
 333 #
 334 # attribute() returns the string associated with the attribute of the
 335 # object. If not found returns a null string.
 336 #
 337 sub attribute {
 338   my $self = shift;
 339   my $spec = shift || return '';
 340
 341   return '' unless( ( exists $self->{attrib} ) && ( defined $self->{attrib} ) );
 342
 343   my $attrib = $self->{attrib};
 344   return '' unless( ( exists $attrib->{$spec} ) && ( defined $attrib->{$spec} ) );
 345
 346   return $attrib->{$spec};
 347 }
 348
 349 #
 350 # usage: @attribute_list = $obj->attribute_list();
 351 #
 352 # attribute_list() returns a list (in no particular order) of the
 353 # attribute names associated with the object
 354 #
 355 sub attribute_list {
 356   my $self = shift;
 357
 358   return '' unless( ( exists $self->{attrib} ) && ( defined $self->{attrib} ) );
 359
 360   my $attrib = $self->{attrib};
 361   return '' unless( "$attrib" =~ /HASH/ );
 362
 363   return keys %$attrib;
 364 }
 365
 366 #
 367 # usage: $text = $obj->dump_tree();
 368 #
 369 # dump_tree() returns a textual representation (in xml form) of the
 370 # object's heirarchy. Only elements are processed.
 371 #
 372 #
 373 sub dump_tree {
 374   my $self = shift;
 375   my %opts = @_;
 376
 377   my $pretty = delete $opts{-pretty};
 378
 379   my $name      = $self->name();
 380   my $value     = $self->value();
 381   my @children  = $self->children();
 382
 383   my $text = '';
 384   unless( $name eq '__TOPLEVEL__' ) {
 385       $text .= "<$name";
 386       for my $att ( $self->attribute_list() ) {
 387           $text .= sprintf( " %s=\"%s\"", $att, encode($self->attribute( $att )) );
 388       }
 389       $text .= ">";
 390
 391       if( $value ) {
 392           $text .= encode($value);
 393       }
 394   }
 395
 396
 397   for my $child ( @children ) {
 398     $text .= $child->dump_tree();
 399   }
 400
 401   unless( $name eq '__TOPLEVEL__' ) {
 402       $text .= "</$name>";
 403   }
 404
 405   return $text;
 406 }
 407
 408 #
 409 # usage: $text = $obj->pretty_dump_tree();
 410 #
 411 # pretty_dump_tree() is identical to dump_tree(), except that newline
 412 # and indentation embellishments are added
 413 #
 414 sub pretty_dump_tree {
 415   my $self = shift;
 416   my $tab = shift || 0;
 417
 418   my $indent = " " x ( 2 * $tab );
 419
 420   my $name      = $self->name();
 421   my $value     = $self->value();
 422   my @children  = $self->children();
 423
 424   my $text = '';
 425   unless( $name eq '__TOPLEVEL__' ) {
 426       $text .= "$indent<$name";
 427       for my $att ( $self->attribute_list() ) {
 428           $text .= sprintf( " %s=\"%s\"", $att, encode($self->attribute( $att )) );
 429       }
 430       $text .= ">";
 431
 432       if( defined $value ) {
 433           $text .= encode($value);
 434           $text .= "</$name>\n";
 435           return $text;
 436       } else {
 437           $text .= "\n";
 438       }
 439   }
 440
 441   for my $child ( @children ) {
 442     $text .= $child->pretty_dump_tree( $tab + 1 );
 443   }
 444
 445   unless( $name eq '__TOPLEVEL__' ) {
 446       $text .= "$indent</$name>\n";
 447   }
 448
 449   return $text;
 450 }
 451
 452 sub encode {
 453   my $encstr=shift;
 454   my %encodings=('&'=>'amp','<'=>'lt','>'=>'gt','"'=>'quot',"'"=>'apos');
 455   $encstr=~s/([&<>"'])/&$encodings{$1};/g;
 456   $encstr;
 457 }
 458
 459 package XML::Handler::TreeBuilder;
 460
 461 use vars qw(@ISA);
 462 @ISA=qw(XML::Element);
 463
 464 sub new {
 465   require XML::Element;
 466   my $class = ref($_[0]) || $_[0];
 467   my $self = XML::Element->new('NIL');
 468   $self->{'_element_class'} = 'XML::Element';
 469   $self->{'_store_comments'}     = 0;
 470   $self->{'_store_pis'}          = 0;
 471   $self->{'_store_declarations'} = 0;
 472   $self->{_stack}=[];
 473   bless $self, $class;
 474 }
 475
 476 sub start_document {}
 477
 478 sub start_element {
 479   my ($self,$element)=@_;
 480   my @attlist;
 481   if (exists $element->{LocalName}) {
 482     @attlist=map {$_=>$element->{Attributes}{$_}{Value}} keys %{$element->{Attributes}};
 483   }
 484   elsif (ref $element->{Attributes} eq 'HASH') {
 485     @attlist=map {$_=>$element->{Attributes}{$_}} keys %{$element->{Attributes}};
 486   }
 487   else {
 488     @attlist=map {$_=>$element->{Attributes}{$_}{Value}} keys %{$element->{Attributes}};
 489   }
 490   if(@{$self->{_stack}}) {
 491     push @{$self->{_stack}}, $self->{'_element_class'}->new($element->{Name},@attlist);
 492     $self->{_stack}[-2]->push_content( $self->{_stack}[-1] );
 493   }
 494   else {
 495     $self->tag($element->{Name});
 496     while(@attlist) {
 497       $self->attr(splice(@attlist,0,2));
 498     }
 499     push @{$self->{_stack}}, $self;
 500   }
 501 }
 502
 503 sub end_element {
 504   my $self=shift;
 505   pop @{$self->{_stack}};
 506   return
 507 }
 508
 509 sub characters {
 510   my ($self,$text)=@_;
 511   $self->{_stack}[-1]->push_content($text->{Data});
 512 }
 513
 514 sub comment {
 515   my ($self,$comment)=@_;
 516   return unless $self->{'_store_comments'};
 517   (@{$self->{_stack}} ? $self->{_stack}[-1] : $self)->push_content(
 518       $self->{'_element_class'}->new('~comment', 'text' => $comment->{Data})
 519     );
 520   return;
 521 }
 522
 523 sub processing_instruction {
 524   my ($self,$pi)=@_;
 525   return unless $self->{'_store_pis'};
 526   (@{$self->{_stack}} ? $self->{_stack}[-1] : $self)->push_content(
 527       $self->{'_element_class'}->new('~pi', 'text' => "$pi->{Target} $pi->{Data}")
 528     );
 529   return;
 530 }
 531
 532 sub end_document {
 533   my $self=shift;
 534   return $self;
 535 }
 536
 537 sub _elem # universal accessor...
 538 {
 539   my($self, $elem, $val) = @_;
 540   my $old = $self->{$elem};
 541   $self->{$elem} = $val if defined $val;
 542   return $old;
 543 }
 544
 545 sub store_comments { shift->_elem('_store_comments', @_); }
 546 sub store_declarations { shift->_elem('_store_declarations', @_); }
 547 sub store_pis      { shift->_elem('_store_pis', @_); }
 548
 549 1;
 550 __END__
 551
 552 =head1 NAME
 553
 554 XML::Handler::Trees - PerlSAX handlers for building tree structures
 555
 556 =head1 SYNOPSIS
 557
 558   use XML::Handler::Trees;
 559   use XML::Parser::PerlSAX;
 560
 561   my $p=XML::Parser::PerlSAX->new();
 562   my $h=XML::Handler::Tree->new();
 563   my $tree=$p->parse(Handler=>$h,Source=>{SystemId=>'file.xml'});
 564
 565   my $p=XML::Parser::PerlSAX->new();
 566   my $h=XML::Handler::EasyTree->new(Noempty=>1);
 567   my $easytree=$p->parse(Handler=>$h,Source=>{SystemId=>'file.xml'});
 568
 569   my $p=XML::Parser::PerlSAX->new();
 570   my $h=XML::Handler::TreeBuilder->new();
 571   $h->store_pis(1);
 572   my $tree=$p->parse(Handler=>$h,Source=>{SystemId=>'file.xml'});
 573
 574 =head1 DESCRIPTION
 575
 576 XML::Handler::Trees provides three PerlSAX handler classes for building
 577 tree structures.  XML::Handler::Tree builds the same type of tree as the
 578 "Tree" style in XML::Parser.  XML::Handler::EasyTree builds the same
 579 type of tree as the "EasyTree" style added to XML::Parser by
 580 XML::Parser::EasyTree.  XML::Handler::TreeBuilder builds the same type
 581 of tree as Sean M. Burke's XML::TreeBuilder.  These classes make it
 582 possible to construct these tree structures from sources other than
 583 XML::Parser.
 584
 585 All three handlers can be driven by either PerlSAX 1 or PerlSAX 2
 586 drivers.  In all cases, the end_document() method returns a reference to
 587 the constructed tree, which normally becomes the return value of the
 588 PerlSAX driver.
 589
 590 =head1 CLASS XML::Handler::Tree
 591
 592 This handler builds the same type of tree structure as the "Tree" style
 593 in XML::Parser.  Some modules such as Dan Brian's XML::SimpleObject work
 594 with this type of tree.  See the documentation for XML::Parser for details.
 595
 596 =head2 METHODS
 597
 598 =over 4
 599
 600 =item $handler = XML::Handler::Tree->new()
 601
 602 Creates a handler object.
 603
 604 =back
 605
 606 =head1 CLASS XML::Handler::EasyTree
 607
 608 This handler builds a lightweight tree structure representing the XML
 609 document.  This structure is, at least in this author's opinion, easier to
 610 work with than the "standard" style of tree.  It is the same type of
 611 structure as built by XML::Parser when using XML::Parser::EasyTree, or
 612 by the get_simple_tree method in XML::Records.
 613
 614 The tree is returned as a reference to an array of tree nodes, each of
 615 which is a hash reference. All nodes have a 'type' key whose value is
 616 the type of the node: 'e' for element nodes, 't' for text nodes, and 'p'
 617 for processing instruction nodes. All nodes also have a 'content' key
 618 whose value is a reference to an array holding the element's child nodes
 619 for element nodes, the string value for text nodes, and the data value
 620 for processing instruction nodes. Element nodes also have an 'attrib'
 621 key whose value is a reference to a hash of attribute names and values and a 'name'
 622 key whose value is the element's name.  Processing instructions also have
 623 a 'target' key whose value is the PI's target.
 624
 625 EasyTree nodes are ordinary Perl hashes and are not objects.  Contiguous
 626 runs of text are always returned in a single node.
 627
 628 The reason the parser returns an array reference rather than the root
 629 element's node is that an XML document can legally contain processing
 630 instructions outside the root element (the xml-stylesheet PI is commonly
 631 used this way).
 632
 633 If namespace information is available (only possible with PerlSAX 2),
 634 element and attribute names will be prefixed with their (possibly empty)
 635 namespace URI enclosed in curly brackets, and namespace prefixes will be
 636 stripped from names.
 637
 638 =head2 METHODS
 639
 640 =over 4
 641
 642 =item $handler = XML::Handler::EasyTree->new([options])
 643
 644 Creates a handler object.  Options can be provided hash-style:
 645
 646 =over 4
 647
 648 =item Noempty
 649
 650 If this is set to a true value, text nodes consisting entirely of
 651 whitespace will not be stored in the tree.  The default is false.
 652
 653 =item Latin
 654
 655 If this is set to a true value, characters with Unicode values in the
 656 Latin-1 range (160-255) will be stored in the tree as Latin-1 rather
 657 than UTF-8.  The default is false.
 658
 659 =item Searchable
 660
 661 If this is set to a true value, the parser will return a tree of XML::Handler::EasyTree::Searchable
 662 objects rather than bare array references, providing access to the navigation methods
 663 listed below.  The top-level node returned will be a dummy element node with a name of "__TOPLEVEL__".
 664 It is false by default.  Setting this option automatically enables the Noempty option.
 665
 666 =back
 667
 668 =back
 669
 670 =head2 XML::Handler::EasyTree::Searchable METHODS
 671
 672 If the Searchable option is set, all nodes in the tree will be XML::Handler::EasyTree::Searchable objects,
 673 which have the same structure as EasyTree nodes but also implement the following methods similar to
 674 those in XML::SimpleObject.
 675
 676 =over 4
 677
 678 =item $name = $node->name()
 679
 680 Returns the name of the node. Ideally, it should return a
 681 "fully qualified" name, but it doesn't.
 682
 683 =item $val = $node->value()
 684
 685 Returns the text value associated with a node object.  Returns undef if the node has
 686 no text children or its first child is not a text node.
 687
 688 =item $newobj = $obj->child( $name );
 689
 690 Returns a child (elements only) of the object with the $name.
 691
 692 For the case where there is more than one child that match $name,
 693 the array context semantics haven't been completely worked out:
 694 - in an array context, all children are returned.
 695 - in scalar context, the first child matching $name is returned.
 696
 697 In a scalar context, The XML::Parser::SimpleObj class returns an
 698 object containing all the children matching $name, unless there is
 699 only one child in which case it returns that child (see commented
 700 code). I find that behavior confusing.
 701
 702 =item @children = $obj->children( $name );
 703
 704 Returns a list of all children (elements only) of the
 705 $obj that match $name -- in the order in which they appeared in the
 706 original xml text.
 707
 708 =item @children_names = $obj->children_names();
 709
 710 Returns a list of all the names of the objects
 711 children (elements only) in the order in which they appeared in the
 712 original text.
 713
 714 =item $attrib = $obj->attribute( $att_name );
 715
 716 Returns the string associated with the attribute of the
 717 object. If not found returns a null string.
 718
 719 =item @attribute_list = $obj->attribute_list();
 720
 721 Returns a list (in no particular order) of the
 722 attribute names associated with the object
 723
 724 =item $text = $obj->dump_tree();
 725
 726 Returns a textual representation (in xml form) of the
 727 object's hierarchy. Only elements are processed. The result will
 728 be in whatever character encoding the SAX driver delivered (which may
 729 not be the same encoding as the original source).
 730
 731 =item $text = $obj->pretty_dump_tree();
 732
 733 Identical to dump_tree(), except that newline
 734 and indentation embellishments are added
 735
 736 =back
 737
 738 =head2 EXAMPLE
 739
 740  #! /usr/bin/perl -w
 741
 742  use XML::Handler::Trees;
 743  use XML::Parser::PerlSAX;
 744  use strict;
 745
 746  my $p=XML::Parser::PerlSAX->new();
 747  my $h=XML::Handler::EasyTree->new( Searchable=>1 );
 748  my $easytree=$p->parse( Handler => $h, Source => { SystemId => 'systemB.xml' } );
 749
 750  my $vme = $easytree->child( "vmesystem" );
 751
 752  print "\n";
 753  print "vmesystem config: ", $vme->attribute( "configuration_name" ), "\n";
 754
 755  print "\n";
 756  print "vmesystem children: ", join( ', ', $vme->children_names() ), "\n";
 757
 758  print "\n";
 759  print "gps model is ", $vme->child( "gps" )->child( "model" )->value(), "\n";
 760  my $gps = $vme->child( "gps" );
 761  print "gps slot is ", $gps->child( "slot" )->value(), "\n";
 762
 763  print "\n";
 764  print "reconstructed XML: \n";
 765  print $easytree->dump_tree(), "\n";
 766
 767  # print "\n";
 768  # print "recontructed XML (pretty): \n";
 769  # print $easytree->pretty_dump_tree(), "\n";
 770
 771  print "\n";
 772  exit;
 773
 774 =head1 CLASS XML::Handler::TreeBuilder
 775
 776 This handler builds XML document trees constructed of
 777 XML::Element objects (XML::Element is a subclass of HTML::Element
 778 adapted for XML).  To use it, XML::TreeBuilder and its prerequisite
 779 HTML::Tree need to be installed.  See the documentation for those
 780 modules for information on how to work with these tree structures.
 781
 782 =head2 METHODS
 783
 784 =over 4
 785
 786 =item $handler = XML::Handler::TreeBuilder->new()
 787
 788 Creates a handler which builds a tree rooted in an XML::Element.
 789
 790 =item $root->store_comments(value)
 791
 792 This determines whether comments will be stored in the tree (not all SAX
 793 drivers generate comment events).  Currently, this is off by default.
 794
 795 =item $root->store_declarations(value)
 796
 797 This determines whether markup declarations will be stored in the tree.
 798 Currently, this is off by default.  The present implementation does not
 799 store markup declarations in any case; this method is provided for future use.
 800
 801 =item $root->store_pis(value)
 802
 803 This determines whether processing instructions will be stored in the tree.
 804 Currently, this is off (false) by default.
 805
 806 =back
 807
 808 =head1 AUTHOR
 809
 810 Eric Bohlman (ebohlman@omsdev.com)
 811
 812 PerlSAX 2 compatibility added by Matt Sergeant (matt@sergeant.org)
 813
 814 XML::EasyTree::Searchable written by Stuart McDow (smcdow@moontower.org)
 815
 816 Copyright (c) 2001 Eric Bohlman.
 817
 818 Portions of this code Copyright (c) 2001 Matt Sergeant.
 819
 820 Portions of this code Copyright (c) 2001 Stuart McDow.
 821
 822 All rights reserved. This program is free software; you can redistribute it
 823 and/or modify it under the same terms as Perl itself.
 824
 825 =head1 SEE ALSO
 826
 827  L<perl>
 828  L<XML::Parser>
 829  L<XML::SimpleObject>
 830  L<XML::Parser::EasyTree>
 831  L<XML::TreeBuilder>
 832  L<XML::Element>
 833  L<HTML::Element>
 834  L<PerlSAX>
 835
 836 =cut
 837