Debian Codegraph @

README

raw
1 NAME
2 XML::Tidy - tidy indenting of XML documents
3
4 VERSION
5 This documentation refers to version 1.20 of XML::Tidy, which was
6 released on Sun Jul 9 09:43:30:08 -0500 2017.
7
8 SYNOPSIS
9 #!/usr/bin/perl
10 use strict;use warnings;
11 use utf8;use XML::Tidy;
12
13 # create new XML::Tidy object by loading: MainFile.xml
14 my $tidy_obj = XML::Tidy->new('filename' => 'MainFile.xml');
15
16 # tidy up the indenting
17 $tidy_obj->tidy();
18
19 # write out changes back to MainFile.xml
20 $tidy_obj->write();
21
22 DESCRIPTION
23 This module creates XML document objects (with inheritance from
24 XML::XPath) to tidy mixed-content (i.e., non-data) text node indenting.
25 There are also some other handy member functions to compress and expand
26 your XML document object (into either a compact XML representation or a
27 binary one).
28
29 USAGE
30 new()
31 This is the standard Tidy object constructor. Except for the added
32 'binary' option, it can take the same parameters as an XML::XPath object
33 constructor to initialize the XML document object. These can be any one
34 of:
35
36 'filename' => 'SomeFile.xml'
37 'binary' => 'SomeBinaryFile.xtb'
38 'xml' => $variable_which_holds_a_bunch_of_XML_data
39 'ioref' => $file_InputOutput_reference
40 'context' => $existing_node_at_specified_context_to_become_new_obj
41
42 reload()
43 The reload() member function causes the latest data contained in a Tidy
44 object to be re-parsed (which re-indexes all nodes).
45
46 This can be necessary after modifications have been made to nodes which
47 impact the tree node hierarchy because XML::XPath's find() member
48 preserves state information which can get out-of-sync.
49
50 reload() is probably rarely useful by itself but it is needed by strip()
51 and prune() so it is exposed as a method in case it comes in handy for
52 other uses.
53
54 strip()
55 The strip() member function searches the Tidy object for all
56 mixed-content (i.e., non-data) text nodes and empties them out. This
57 will basically unformat any markup indenting.
58
59 strip() is used by compress() and tidy() but it is exposed because it is
60 also worthwhile by itself.
61
62 tidy()
63 The tidy() member function can take a single optional parameter as the
64 string that should be inserted for each indent level. Some examples:
65
66 # Tidy up indenting with default two (2) spaces per indent level
67 $tidy_obj->tidy();
68
69 # Tidy up indenting with four (4) spaces per indent level
70 $tidy_obj->tidy(' ');
71
72 # Tidy up indenting with one (1) tab per indent level
73 $tidy_obj->tidy('tab' );
74
75 # Tidy up indenting with two (2) tabs per indent level
76 $tidy_obj->tidy("\t\t");
77
78 The default behavior is to use two (2) spaces for each indent level. The
79 Tidy object gets all mixed-content (i.e., non-data) text nodes
80 reformatted to appropriate indent levels according to tree nesting
81 depth.
82
83 NOTE: tidy() disturbs some XML escapes in whatever ways XML::XPath does.
84 It has been brought to my attention that these modules also strip CDATA
85 tags from XML files / data they operate on. Even though CDATA tags don't
86 seem very common, I would very much like for them to work smoothly too.
87 Hopefully the vast majority of files will work fine and future support
88 for any of the more rare types can be added later.
89
90 Additionally, please take notice that every call to tidy() (as well as
91 reload, strip, and most other XML::Tidy functions) leak some memory due
92 to their usage of XPath's findnodes command. This issue was described
93 helpfully at <HTTPS://RT.CPAN.Org/Ticket/Display.html?id=120296>. Thanks
94 to Jozef!
95
96 compress()
97 The compress() member function calls strip() on the Tidy object then
98 creates an encoded comment which contains the names of elements and
99 attributes as they occurred in the original document. Their respective
100 element and attribute names are replaced with just the appropriate index
101 throughout the document.
102
103 compress() can accept a parameter describing which node types to attempt
104 to shrink down as abbreviations. This parameter should be a string of
105 just the first letters of each node type you wish to include as in the
106 following mapping:
107
108 e = elements
109 a = attribute keys
110 v = attribute values *EXPERIMENTAL*
111 t = text nodes *EXPERIMENTAL*
112 c = comment nodes *EXPERIMENTAL*
113 n = namespace nodes *not-yet-implemented*
114
115 Attribute values ('v') and text nodes ('t') both seem to work fine with
116 current tokenization. I've still labeled them EXPERIMENTAL because they
117 seem more likely to cause problems than valid element or attribute key
118 names. I have some bugs in the comment node compression which I haven't
119 been able to find yet so that one should be avoided for now. Since these
120 three node types ('vtc') all require tokenization, they are not included
121 in default compression ('ea'). An example call which includes values and
122 text would be:
123
124 $tidy_obj->compress('eavt');
125
126 The original document structure (i.e., node hierarchy) is preserved.
127 compress() significantly reduces the file size of most XML documents for
128 when size matters more than immediate human readability. expand()
129 performs the opposite conversion.
130
131 expand()
132 The expand() member function reads any XML::Tidy::compress comments from
133 the Tidy object and uses them to reconstruct the document that was
134 passed to compress().
135
136 bcompress('BinaryOutputFilename.xtb')
137 The bcompress() member function stores a binary representation of any
138 Tidy object. The format consists of:
139
140 0) a null-terminated version string
141 1) a byte specifying how many bytes later indices will be
142 2) the number of bytes from 1 above to designate the total string count
143 3) the number of null-terminated strings from 2 above
144 4) the number of bytes from 1 above to designate the total integer count
145 5) the number of 4-byte integers from 4 above
146 6) the number of bytes from 1 above to designate the total float count
147 7) the number of 8-byte (double-precision) floats from 6 above
148 8) node index sets until the end of the file
149
150 Normal node index sets consist of two values. The first is an index
151 (again the number of bytes long comes from 1) into the three lists as if
152 they were all linear. The second is a single-byte integer identifying
153 the node type (using standard DOM node type enumerations).
154
155 A few special cases exist in node index sets though. If the index is
156 null, it is interpreted as a close-element tag (so no accompanying type
157 value is read). On the other end, when the index is non-zero, the type
158 value is always read. In the event that the type corresponds to an
159 attribute or a processing instruction, the next index is read (without
160 another accompanying type value) in order to complete the data fields
161 required by those node types.
162
163 NOTE: Please bear in mind that the encoding of binary integers and
164 floats only works properly if the values are not surrounded by spaces or
165 other delimiters and each is contained in its own single node. This is
166 necessary to enable thorough reconstruction of whitespace from the
167 original document. I recommend storing every numerical value as an
168 isolated attribute value or text node without any surrounding
169 whitespace.
170
171 # Examples which encode all numbers as binary:
172 <friend name="goodguy" category="15">
173 <hitpoints>31.255</hitpoints>
174 <location>
175 <x>-15.65535</x>
176 <y>16383.7</y>
177 <z>-1023.63</z>
178 </location>
179 </friend>
180
181 # Examples which encode all numbers as strings:
182 <enemy name="badguy" category=" 666 ">
183 <hitpoints> 2.0 </hitpoints>
184 <location> 4.0 -2.0 4.0 </location>
185 </enemy>
186
187 The default file extension is .xtb (for XML::Tidy Binary).
188
189 bexpand('BinaryInputFilename.xtb')
190 The bexpand() member function reads a binary file which was previously
191 written from bcompress(). bexpand() is an XML::Tidy object constructor
192 like new() so it can be called like:
193
194 my $xtbo = XML::Tidy->bexpand('BinaryInputFilename.xtb');
195
196 prune()
197 The prune() member function takes an XPath location to remove (along
198 with all attributes and child nodes) from the Tidy object. For example,
199 to remove all comments:
200
201 $tidy_obj->prune('//comment()');
202
203 or to remove the third baz (XPath indexing is 1-based):
204
205 $tidy_obj->prune('/foo/bar/baz[3]');
206
207 Pruning your XML tree is a form of tidying too so it snuck in here. =)
208
209 write()
210 The write() member function can take an optional filename parameter to
211 write out any changes to the Tidy object. If no parameters are given,
212 write() overwrites the original XML document file (if a 'filename'
213 parameter was given to the constructor).
214
215 write() will croak() if no filename can be found to write to.
216
217 write() can also take a secondary parameter which specifies an XPath
218 location to be written out as the new root element instead of the Tidy
219 object's root. Only the first matching element is written.
220
221 toString()
222 The toString() member function is almost identical to write() except
223 that it takes no parameters and simply returns the equivalent XML string
224 as a scalar. It is a little weird because normally only XML::XPath::Node
225 objects have a toString() member but I figure it makes sense to extend
226 the same syntax to the parent object as well, since it is a useful
227 option.
228
229 createNode Wrappers
230 The following are just aliases to Node constructors. They'll work with
231 just the unique portion of the node type as the member function name.
232
233 e() or el() or elem() or createElement()
234 wrapper for XML::XPath::Node::Element->new()
235
236 a() or at() or attr() or createAttribute()
237 wrapper for XML::XPath::Node::Attribute->new()
238
239 c() or cm() or cmnt() or createComment()
240 wrapper for XML::XPath::Node::Comment->new()
241
242 t() or tx() or text() or createTextNode()
243 wrapper for XML::XPath::Node::Text->new()
244
245 p() or pi() or proc() or createProcessingInstruction()
246 wrapper for XML::XPath::Node::PI->new()
247
248 n() or ns() or nspc() or createNamespace()
249 wrapper for XML::XPath::Node::Namespace->new()
250
251 EXPORTED CONSTANTS
252 Since they are sometimes needed to compare against, XML::Tidy also
253 exports the same node constants as XML::XPath::Node (which correspond to
254 DOM values). These include:
255
256 UNKNOWN_NODE
257 ELEMENT_NODE
258 ATTRIBUTE_NODE
259 TEXT_NODE
260 CDATA_SECTION_NODE
261 ENTITY_REFERENCE_NODE
262 ENTITY_NODE
263 PROCESSING_INSTRUCTION_NODE
264 COMMENT_NODE
265 DOCUMENT_NODE
266 DOCUMENT_TYPE_NODE
267 DOCUMENT_FRAGMENT_NODE
268 NOTATION_NODE
269 ELEMENT_DECL_NODE
270 ATT_DEF_NODE
271 XML_DECL_NODE
272 ATTLIST_DECL_NODE
273 NAMESPACE_NODE
274 XML::Tidy also exports:
275
276 STANDARD_XML_DECL
277 which returns a reasonable default XML declaration string (assuming
278 typical "utf-8" encoding).
279
280 TODO
281 - fix reload() from messing up Unicode escaped &XYZ; components like
282 Copyright &#xA9; and Registered &#xAE; (probably needs pre and post
283 processing)
284 - write many better UTF-8 tests
285 - support namespaces
286 - handle CDATA
287
288 CHANGES
289 Revision history for Perl extension XML::Tidy:
290
291 - 1.20 H79M9hU8 Sun Jul 9 09:43:30:08 -0500 2017
292 * removed broken Build.PL to resolve
293 <HTTPS://RT.CPAN.Org/Ticket/Display.html?id=122406>. (Thank you,
294 Slaven.)
295
296 - 1.18 H78M5qm1 Sat Jul 8 05:52:48:01 -0500 2017
297 * fixed new() to check file or xml to detect standalone in
298 declaration, from <HTTPS://RT.CPAN.Org/Ticket/Display.html?id=122389>
299 (Thanks Alex!)
300
301 * traced tidy() memory leak from
302 <HTTPS://RT.CPAN.Org/Ticket/Display.html?id=120296> (Thanks Jozef!)
303 which seems to come from every XPath->findnodes() call
304
305 * aligned synopsis comments
306
307 * updated write() to use output encoding UTF-8 since that's what
308 almost all XML should rely on (with thanks to RJBS for teaching me
309 much from his great talk at <HTTPS://YouTube.Com/watch?v=TmTeXcEixEg>)
310
311 * collapsed trailing curly braces on code blocks
312
313 * added croak for any failed file open attempt
314
315 - 1.16 G6LM4EST Tue Jun 21 04:14:28:29 -0500 2016
316 * stopped using my old fragile package generation and manually updated
317 all distribution files (though Dist::Zilla should let me generate much
318 again)
319
320 * updated license to GPLv3+
321
322 * fixed 00pod.t and 01podc.t to eval the Test modules from issue and
323 patch: <HTTPS://RT.CPAN.Org/Public/Bug/Display.html?id=85592> (Thanks
324 again MichielB.)
325
326 * replaced all old '&&' with 'and' in POD
327
328 - 1.14 G6JMERCY Sun Jun 19 14:27:12:34 -0500 2016
329 * separated old PT from VERSION to fix non-numeric issue:
330 <HTTPS://RT.CPAN.Org/Public/Bug/Display.html?id=56073> (Thanks to
331 Slaven.)
332
333 * removed Unicode from POD but added encoding utf8 anyway to pass
334 tests and resolve issues:
335 <HTTPS://RT.CPAN.Org/Public/Bug/Display.html?id=92434> and
336 <HTTPS://RT.CPAN.Org/Public/Bug/Display.html?id=85592> (Thanks to
337 Sudhanshu and MichielB.)
338
339 - 1.12.B55J2qn Thu May 5 19:02:52:49 2011
340 * made "1.0" float binarize as float again, rather than just "1" int
341
342 * cleaned up POD and fixed EXPORTED CONSTANTS heads blocking together
343
344 - 1.10.B52FpLx Mon May 2 15:51:21:59 2011
345 * added tests for undefined non-standard XML declaration to suppress
346 warnings
347
348 - 1.8.B2AMvdl Thu Feb 10 22:57:39:47 2011
349 * aligned .t code
350
351 * added test for newline before -r to try to resolve:
352 <HTTPS://RT.CPAN.Org/Ticket/Display.html?id=65471> (Thanks, Leandro.)
353
354 * fixed off-by-one error when new gets a readable (non-newline)
355 filename (that's not "filename" without a pre-'filename' param) to
356 resolve: <HTTPS://RT.CPAN.Org/Ticket/Display.html?id=65151> (Thanks,
357 Simone.)
358
359 - 1.6.A7RJKwl Tue Jul 27 19:20:58:47 2010
360 * added head2 POD for EXPORTED CONSTANTS to try to pass t/00podc.t
361
362 - 1.4.A7QCvHw Mon Jul 26 12:57:17:58 2010
363 * hacked a little test for non-UTF-8 decl str to resolve FrankGoss'
364 need for ISO-8859-1 decl encoding to persist through tidying
365
366 * md sure META.yml is being generated correctly for the CPAN
367
368 * updated license to GPLv3
369
370 - 1.2.75BACCB Fri May 11 10:12:12:11 2007
371 * made "1.0" float binarize as just "1" int
372
373 * made ints signed and bounds checked
374
375 * added new('binary' => 'BinFilename.xtb') option
376
377 - 1.2.54HJnFa Sun Apr 17 19:49:15:36 2005
378 * fixed tidy() processing instruction stripping problem
379
380 * added support for binary ints and floats in bcompress()
381
382 * tightened up binary format and added pod
383
384 - 1.2.54HDR1G Sun Apr 17 13:27:01:16 2005
385 * added bcompress() and bexpand()
386
387 * added compress() and expand()
388
389 * added toString()
390
391 - 1.2.4CKBHxt Mon Dec 20 11:17:59:55 2004
392 * added exporting of XML::XPath::Node (DOM) constants
393
394 * added node object creation wrappers (like LibXML)
395
396 - 1.2.4CCJW4G Sun Dec 12 19:32:04:16 2004
397 * added optional 'xpath_loc' => to prune()
398
399 - 1.0.4CAJna1 Fri Dec 10 19:49:36:01 2004
400 * added optional 'filename' => to write()
401
402 - 1.0.4CAAf5B Fri Dec 10 10:41:05:11 2004
403 * removed 2nd param from tidy() so that 1st param is just indent
404 string
405
406 * fixed pod errors
407
408 - 1.0.4C9JpoP Thu Dec 9 19:51:50:25 2004
409 * added xplc option to write()
410
411 * added prune()
412
413 - 1.0.4C8K1Ah Wed Dec 8 20:01:10:43 2004
414 * inherited from XPath so that those methods can be called directly
415
416 * original version (separating Tidy.pm from Merge.pm)
417
418 INSTALL
419 From the command shell, please run:
420
421 `perl -MCPAN -e "install XML::Tidy"`
422
423 or uncompress the package and run the standard:
424
425 `perl Makefile.PL; make; make test; make install`
426
427 FILES
428 XML::Tidy requires:
429
430 Carp to allow errors to croak() from calling sub
431
432 XML::XPath to use XPath statements to query and update XML
433
434 XML::XPath::XMLParser to parse XML documents into XPath objects
435
436 Math::BaseCnv to handle base-64 indexing for compress() and expand()
437
438 BUGS
439 Please report any bugs or feature requests to bug-XML-Tidy at
440 RT.CPAN.Org, or through the web interface at
441 <HTTPS://RT.CPAN.Org/NoAuth/ReportBug.html?Queue=XML-Tidy>. I will be
442 notified, and then you can be updated of progress on your bug as I
443 address fixes.
444
445 SUPPORT
446 You can find documentation for this module (after it is installed) with
447 the perldoc command.
448
449 `perldoc XML::Tidy`
450
451 You can also look for information at:
452
453 RT: CPAN's Request Tracker
454
455 HTTPS://RT.CPAN.Org/NoAuth/Bugs.html?Dist=XML-Tidy
456
457 AnnoCPAN: Annotated CPAN documentation
458
459 HTTP://AnnoCPAN.Org/dist/XML-Tidy
460
461 CPAN Ratings
462
463 HTTPS://CPANRatings.Perl.Org/d/XML-Tidy
464
465 Search CPAN
466
467 HTTP://Search.CPAN.Org/dist/XML-Tidy
468
469 LICENSE
470 Most source code should be Free! Code I have lawful authority over is
471 and shall be! Copyright: (c) 2004-2017, Pip Stuart. Copyleft : This
472 software is licensed under the GNU General Public License (version 3 or
473 later). Please consult <HTTPS://GNU.Org/licenses/gpl-3.0.txt> for
474 important information about your freedom. This is Free Software: you are
475 free to change and redistribute it. There is NO WARRANTY, to the extent
476 permitted by law. See <HTTPS://FSF.Org> for further information.
477
478 AUTHOR
479 Pip Stuart <[email protected]>
480