README
1=head1 NAME
2
3XML::Parser::EasyTree - Easier tree style for XML::Parser
4
5=head1 SYNOPSIS
6
7 use XML::Parser;
8 use XML::Parser::EasyTree;
9 $XML::Parser::Easytree::Noempty=1;
10 my $p=new XML::Parser(Style=>'EasyTree');
11 my $tree=$p->parsefile('something.xml');
12
13=head1 DESCRIPTION
14
15XML::Parser::EasyTree adds a new "built-in" style called "EasyTree" to
16XML::Parser. Like XML::Parser's "Tree" style, setting this style causes
17the parser to build a lightweight tree structure representing the XML
18document. This structure is, at least in this author's opinion, easier to
19work with than the one created by the built-in style.
20
21When the parser is invoked with the EasyTree style, it returns a reference
22to an array of tree nodes, each of which is a hash reference. All nodes
23have a 'type' key whose value is the type of the node: 'e' for element
24nodes, 't' for text nodes, and 'p' for processing instruction nodes. All
25nodes also have a 'content' key whose value is a reference to an array
26holding the element's child nodes for element nodes, the string value for
27text nodes, and the data value for processing instruction nodes. Element
28nodes also have an 'attrib' key whose value is a reference to a hash of
29attribute names and values. Processing instructions also have a 'target'
30key whose value is the PI's target.
31
32EasyTree nodes are ordinary Perl hashes and are not objects. Contiguous
33runs of text are always returned in a single node.
34
35The reason the parser returns an array reference rather than the root
36element's node is that an XML document can legally contain processing
37instructions outside the root element (the xml-stylesheet PI is commonly
38used this way).
39
40If the parser's Namespaces option is set, element and attribute names will
41be prefixed with their (possibly empty) namespace URI enclosed in curly
42brackets.
43
44=head1 SPECIAL VARIABLES
45
46Two package global variables control special behaviors:
47
48=over 4
49
50=item XML::Parser::EasyTree::Latin
51
52If this is set to a nonzero value, all text, names, and values will be
53returned in ISO-8859-1 (Latin-1) encoding rather than UTF-8.
54
55=item XML::Parser::EasyTree::Noempty
56
57If this is set to a nonzero value, text nodes containing nothing but
58whitespace (such as those generated by line breaks and indentation between
59tags) will be omitted from the parse tree.
60
61=back
62
63=head1 EXAMPLE
64
65Parse a prettyprined version of the XML shown in the example for the built-in "Tree" style:
66
67 #!perl -w
68 use strict;
69 use XML::Parser;
70 use XML::Parser::EasyTree;
71 use Data::Dumper;
72
73 $XML::Parser::EasyTree::Noempty=1;
74 my $xml=<<'EOF';
75 <foo>
76 <head id="a">Hello <em>there</em>
77 </head>
78 <bar>Howdy<ref/>
79 </bar>
80 do
81 </foo>
82 EOF
83 my $p=new XML::Parser(Style=>'EasyTree');
84 my $tree=$p->parse($xml);
85 print Dumper($tree);
86
87Returns:
88
89 $VAR1 = [
90 { 'name' => 'foo',
91 'type' => 'e',
92 'content' => [
93 { 'name' => 'head',
94 'type' => 'e',
95 'content' => [
96 { 'type' => 't',
97 'content' => 'Hello '
98 },
99 { 'name' => 'em',
100 'type' => 'e',
101 'content' => [
102 { 'type' => 't',
103 'content' => 'there'
104 }
105 ],
106 'attrib' => {}
107 }
108 ],
109 'attrib' => { 'id' => 'a'
110 }
111 },
112 { 'name' => 'bar',
113 'type' => 'e',
114 'content' => [
115 { 'type' => 't',
116 'content' => 'Howdy'
117 },
118 { 'name' => 'ref',
119 'type' => 'e',
120 'content' => [],
121 'attrib' => {}
122 }
123 ],
124 'attrib' => {}
125 },
126 { 'type' => 't',
127 'content' => '
128 do
129 '
130 }
131 ],
132 'attrib' => {}
133 }
134 ];
135
136=head1 AUTHOR
137
138Eric Bohlman (ebohlman@omsdev.com)
139
140Copyright (c) 2001 Eric Bohlman. All rights reserved. This program
141is free software; you can redistribute it and/or modify it under the same
142terms as Perl itself.
143
144=head1 SEE ALSO
145
146 XML::Parser
147