Debian Codegraph @

README

raw
1 NAME
2 XML::TreePP -- Pure Perl implementation for parsing/writing XML
3 documents
4
5 SYNOPSIS
6 parse an XML document from file into hash tree:
7
8 use XML::TreePP;
9 my $tpp = XML::TreePP->new();
10 my $tree = $tpp->parsefile( "index.rdf" );
11 print "Title: ", $tree->{"rdf:RDF"}->{item}->[0]->{title}, "\n";
12 print "URL: ", $tree->{"rdf:RDF"}->{item}->[0]->{link}, "\n";
13
14 write an XML document as string from hash tree:
15
16 use XML::TreePP;
17 my $tpp = XML::TreePP->new();
18 my $tree = { rss => { channel => { item => [ {
19 title => "The Perl Directory",
20 link => "http://www.perl.org/",
21 }, {
22 title => "The Comprehensive Perl Archive Network",
23 link => "http://cpan.perl.org/",
24 } ] } } };
25 my $xml = $tpp->write( $tree );
26 print $xml;
27
28 get a remote XML document by HTTP-GET and parse it into hash tree:
29
30 use XML::TreePP;
31 my $tpp = XML::TreePP->new();
32 my $tree = $tpp->parsehttp( GET => "http://use.perl.org/index.rss" );
33 print "Title: ", $tree->{"rdf:RDF"}->{channel}->{title}, "\n";
34 print "URL: ", $tree->{"rdf:RDF"}->{channel}->{link}, "\n";
35
36 get a remote XML document by HTTP-POST and parse it into hash tree:
37
38 use XML::TreePP;
39 my $tpp = XML::TreePP->new( force_array => [qw( item )] );
40 my $cgiurl = "http://search.hatena.ne.jp/keyword";
41 my $keyword = "ajax";
42 my $cgiquery = "mode=rss2&word=".$keyword;
43 my $tree = $tpp->parsehttp( POST => $cgiurl, $cgiquery );
44 print "Link: ", $tree->{rss}->{channel}->{item}->[0]->{link}, "\n";
45 print "Desc: ", $tree->{rss}->{channel}->{item}->[0]->{description}, "\n";
46
47 DESCRIPTION
48 XML::TreePP module parses an XML document and expands it for a hash
49 tree. This generates an XML document from a hash tree as the opposite
50 way around. This is a pure Perl implementation and requires no modules
51 depended. This can also fetch and parse an XML document from remote web
52 server like the XMLHttpRequest object does at JavaScript language.
53
54 EXAMPLES
55 Parse XML file
56 Sample XML document:
57
58 <?xml version="1.0" encoding="UTF-8"?>
59 <family name="Kawasaki">
60 <father>Yasuhisa</father>
61 <mother>Chizuko</mother>
62 <children>
63 <girl>Shiori</girl>
64 <boy>Yusuke</boy>
65 <boy>Kairi</boy>
66 </children>
67 </family>
68
69 Sample program to read a xml file and dump it:
70
71 use XML::TreePP;
72 use Data::Dumper;
73 my $tpp = XML::TreePP->new();
74 my $tree = $tpp->parsefile( "family.xml" );
75 my $text = Dumper( $tree );
76 print $text;
77
78 Result dumped:
79
80 $VAR1 = {
81 'family' => {
82 '-name' => 'Kawasaki',
83 'father' => 'Yasuhisa',
84 'mother' => 'Chizuko',
85 'children' => {
86 'girl' => 'Shiori'
87 'boy' => [
88 'Yusuke',
89 'Kairi'
90 ],
91 }
92 }
93 };
94
95 Details:
96
97 print $tree->{family}->{father}; # the father's given name.
98
99 The prefix '-' is added on every attribute's name.
100
101 print $tree->{family}->{"-name"}; # the family name of the family
102
103 The array is used because the family has two boys.
104
105 print $tree->{family}->{children}->{boy}->[1]; # The second boy's name
106 print $tree->{family}->{children}->{girl}; # The girl's name
107
108 Text node and attributes:
109 If a element has both of a text node and attributes or both of a text
110 node and other child nodes, value of a text node is moved to "#text"
111 like child nodes.
112
113 use XML::TreePP;
114 use Data::Dumper;
115 my $tpp = XML::TreePP->new();
116 my $source = '<span class="author">Kawasaki Yusuke</span>';
117 my $tree = $tpp->parse( $source );
118 my $text = Dumper( $tree );
119 print $text;
120
121 The result dumped is following:
122
123 $VAR1 = {
124 'span' => {
125 '-class' => 'author',
126 '#text' => 'Kawasaki Yusuke'
127 }
128 };
129
130 The special node name of "#text" is used because this elements has
131 attribute(s) in addition to the text node. See also "text_node_key"
132 option.
133
134 METHODS
135 new
136 This constructor method returns a new XML::TreePP object with %options.
137
138 $tpp = XML::TreePP->new( %options );
139
140 set
141 This method sets a option value for "option_name". If $option_value is
142 not defined, its option is deleted.
143
144 $tpp->set( option_name => $option_value );
145
146 See OPTIONS section below for details.
147
148 get
149 This method returns a current option value for "option_name".
150
151 $tpp->get( 'option_name' );
152
153 parse
154 This method reads an XML document by string and returns a hash tree
155 converted. The first argument is a scalar or a reference to a scalar.
156
157 $tree = $tpp->parse( $source );
158
159 parsefile
160 This method reads an XML document by file and returns a hash tree
161 converted. The first argument is a filename.
162
163 $tree = $tpp->parsefile( $file );
164
165 parsehttp
166 This method receives an XML document from a remote server via HTTP and
167 returns a hash tree converted.
168
169 $tree = $tpp->parsehttp( $method, $url, $body, $head );
170
171 $method is a method of HTTP connection: GET/POST/PUT/DELETE $url is an
172 URI of an XML file. $body is a request body when you use POST method.
173 $head is a request headers as a hash ref. LWP::UserAgent module or
174 HTTP::Lite module is required to fetch a file.
175
176 ( $tree, $xml, $code ) = $tpp->parsehttp( $method, $url, $body, $head );
177
178 In array context, This method returns also raw XML document received and
179 HTTP response's status code.
180
181 write
182 This method parses a hash tree and returns an XML document as a string.
183
184 $source = $tpp->write( $tree, $encode );
185
186 $tree is a reference to a hash tree.
187
188 writefile
189 This method parses a hash tree and writes an XML document into a file.
190
191 $tpp->writefile( $file, $tree, $encode );
192
193 $file is a filename to create. $tree is a reference to a hash tree.
194
195 OPTIONS FOR PARSING XML
196 This module accepts option parameters following:
197
198 force_array
199 This option allows you to specify a list of element names which should
200 always be forced into an array representation.
201
202 $tpp->set( force_array => [ 'rdf:li', 'item', '-xmlns' ] );
203
204 The default value is null, it means that context of the elements will
205 determine to make array or to keep it scalar or hash. Note that the
206 special wildcard name '*' means all elements.
207
208 force_hash
209 This option allows you to specify a list of element names which should
210 always be forced into an hash representation.
211
212 $tpp->set( force_hash => [ 'item', 'image' ] );
213
214 The default value is null, it means that context of the elements will
215 determine to make hash or to keep it scalar as a text node. See also
216 "text_node_key" option below. Note that the special wildcard name '*'
217 means all elements.
218
219 cdata_scalar_ref
220 This option allows you to convert a cdata section into a reference for
221 scalar on parsing an XML document.
222
223 $tpp->set( cdata_scalar_ref => 1 );
224
225 The default value is false, it means that each cdata section is
226 converted into a scalar.
227
228 user_agent
229 This option allows you to specify a HTTP_USER_AGENT string which is used
230 by parsehttp() method.
231
232 $tpp->set( user_agent => 'Mozilla/4.0 (compatible; ...)' );
233
234 The default string is 'XML-TreePP/#.##', where '#.##' is substituted
235 with the version number of this library.
236
237 http_lite
238 This option forces pasrsehttp() method to use a HTTP::Lite instance.
239
240 my $http = HTTP::Lite->new();
241 $tpp->set( http_lite => $http );
242
243 lwp_useragent
244 This option forces parsehttp() method to use a LWP::UserAgent instance.
245
246 my $ua = LWP::UserAgent->new();
247 $ua->timeout( 60 );
248 $ua->env_proxy;
249 $tpp->set( lwp_useragent => $ua );
250
251 You may use this with LWP::UserAgent::WithCache.
252
253 base_class
254 This blesses class name for each element's hashref. Each class is named
255 straight as a child class of it parent class.
256
257 $tpp->set( base_class => 'MyElement' );
258 my $xml = '<root><parent><child key="val">text</child></parent></root>';
259 my $tree = $tpp->parse( $xml );
260 print ref $tree->{root}->{parent}->{child}, "\n";
261
262 A hash for <child> element above is blessed to
263 "MyElement::root::parent::child" class. You may use this with
264 Class::Accessor.
265
266 elem_class
267 This blesses class name for each element's hashref. Each class is named
268 horizontally under the direct child of "MyElement".
269
270 $tpp->set( base_class => 'MyElement' );
271 my $xml = '<root><parent><child key="val">text</child></parent></root>';
272 my $tree = $tpp->parse( $xml );
273 print ref $tree->{root}->{parent}->{child}, "\n";
274
275 A hash for <child> element above is blessed to "MyElement::child" class.
276
277 xml_deref
278 This option dereferences the numeric character references, like &#xEB;,
279 &#28450;, etc., in an XML document when this value is true.
280
281 $tpp->set( xml_deref => 1 );
282
283 Note that, for security reasons and your convenient, this module
284 dereferences the predefined character entity references, &amp;, &lt;,
285 &gt;, &apos; and &quot;, and the numeric character references up to
286 U+007F without xml_deref per default.
287
288 require_xml_decl
289 This option requires XML declaration at the top of XML document to
290 parse.
291
292 $tpp->set( require_xml_decl => 1 );
293
294 This will die when <?xml .../?> declration not found.
295
296 OPTIONS FOR WRITING XML
297 first_out
298 This option allows you to specify a list of element/attribute names
299 which should always appears at first on output XML document.
300
301 $tpp->set( first_out => [ 'link', 'title', '-type' ] );
302
303 The default value is null, it means alphabetical order is used.
304
305 last_out
306 This option allows you to specify a list of element/attribute names
307 which should always appears at last on output XML document.
308
309 $tpp->set( last_out => [ 'items', 'item', 'entry' ] );
310
311 indent
312 This makes the output more human readable by indenting appropriately.
313
314 $tpp->set( indent => 2 );
315
316 This doesn't strictly follow the XML specification but does looks nice.
317
318 xml_decl
319 This module inserts an XML declaration on top of the XML document
320 generated per default. This option forces to change it to another or
321 just remove it.
322
323 $tpp->set( xml_decl => '' );
324
325 output_encoding
326 This option allows you to specify a encoding of the XML document
327 generated by write/writefile methods.
328
329 $tpp->set( output_encoding => 'UTF-8' );
330
331 On Perl 5.8.0 and later, you can select it from every encodings
332 supported by Encode.pm. On Perl 5.6.x and before with Jcode.pm, you can
333 use "Shift_JIS", "EUC-JP", "ISO-2022-JP" and "UTF-8". The default value
334 is "UTF-8" which is recommended encoding.
335
336 empty_element_tag_end
337 $tpp->set( empty_element_tag_end => '>' );
338
339 Set characters which close empty tag. The default value is ' />'.
340
341 OPTIONS FOR BOTH
342 utf8_flag
343 This makes utf8 flag on for every element's value parsed and makes it on
344 for the XML document generated as well.
345
346 $tpp->set( utf8_flag => 1 );
347
348 Perl 5.8.1 or later is required to use this.
349
350 attr_prefix
351 This option allows you to specify a prefix character(s) which is
352 inserted before each attribute names.
353
354 $tpp->set( attr_prefix => '@' );
355
356 The default character is '-'. Or set '@' to access attribute values like
357 E4X, ECMAScript for XML. Zero-length prefix '' is available as well, it
358 means no prefix is added.
359
360 text_node_key
361 This option allows you to specify a hash key for text nodes.
362
363 $tpp->set( text_node_key => '#text' );
364
365 The default key is "#text".
366
367 ignore_error
368 This module calls Carp::croak function on an error per default. This
369 option makes all errors ignored and just returns.
370
371 $tpp->set( ignore_error => 1 );
372
373 use_ixhash
374 This option keeps the order for each element appeared in XML.
375 Tie::IxHash module is required.
376
377 $tpp->set( use_ixhash => 1 );
378
379 This makes parsing performance slow. (about 100% slower than default)
380
381 AUTHOR
382 Yusuke Kawasaki, http://www.kawa.net/
383
384 REPOSITORY
385 https://github.com/kawanet/XML-TreePP
386
387 COPYRIGHT
388 The following copyright notice applies to all the files provided in this
389 distribution, including binary files, unless explicitly noted otherwise.
390
391 Copyright 2006-2010 Yusuke Kawasaki
392
393 LICENSE
394 This library is free software; you can redistribute it and/or modify it
395 under the same terms as Perl itself.
396