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