1Tidy(3) User Contributed Perl Documentation Tidy(3)
2
6 XML::Tidy - tidy indenting of XML documents
7
9 This documentation refers to version 1.2.54HJnFa of XML::Tidy, which
10 was released on Sun Apr 17 19:49:15:36 2005.
11
13 use XML::Tidy;
14 # create new XML::Tidy object from MainFile.xml
16 my $tidy_obj = XML::Tidy->new('filename' => 'MainFile.xml');
17 # Tidy up the indenting
19 $tidy_obj->tidy();
20 # Write out changes back to MainFile.xml
22 $tidy_obj->write();
23
25 This module creates XML document objects (with inheritance from
26 XML::XPath) to tidy mixed-content (ie. non-data) text node indenting.
27 There are also some other handy member functions to compress && expand
28 your XML document object (into either a compact XML representation or a
29 binary one).
30
32 - maybe add support for binary char && short ints && single- precision
33 floats in bcompress()
34 - fix reload() from messing up unicode escaped &XYZ; components like
35 Copyright © -> AX && Registered ® -> AX
36 - What else does Tidy need?
37
39 new()
40 This is the standard Tidy object constructor. It can take the same
41 parameters as an XML::XPath object constructor to initialize the XML
42 document object. These can be any one of:
43 'filename' => 'SomeFile.xml'
45 'xml' => $variable_which_holds_a_bunch_of_XML_data
46 'ioref' => $file_InputOutput_reference
47 'context' => $existing_node_at_specified_context_to_become_new_obj
48 reload()
50 The reload() member function causes the latest data contained in a Tidy
51 object to be re-parsed which re-indexes all nodes. This can be
52 necessary after modifications have been made to nodes which impact the
53 tree node hierarchy because XML::XPath's find() member preserves state
54 info which can get out-of-sync. reload() is probably rarely useful by
55 itself but it is needed by strip() && prune() so it is exposed as a
56 method in case it comes in handy for other uses.
57 strip()
59 The strip() member function searches the Tidy object for all mixed-
60 content (ie. non-data) text nodes && empties them out. This will
61 basically unformat any markup indenting. strip() is used by compress()
62 && tidy() but it is exposed because it could be worthwhile by itself.
63 tidy()
65 The tidy() member function can take a single optional parameter as the
66 string that should be inserted for each indent level. Some examples:
67 # Tidy up indenting with default two (2) spaces per indent level
69 $tidy_obj->tidy();
70 # Tidy up indenting with four (4) spaces per indent level
72 $tidy_obj->tidy(' ');
73 # Tidy up indenting with one (1) tab per indent level
75 $tidy_obj->tidy("\t");
76 The default behavior is to use two (2) spaces for each indent level.
78 The Tidy object gets all mixed-content (ie. non-data) text nodes
79 reformatted to appropriate indent levels according to tree nesting
80 depth.
81 NOTE: There seems to be a bug in XML::XPath which does not allow
83 finding XML processing instructions (PIs) properly so they have been
84 commented out of tidy(). This means that tidy() unfortunately removes
85 processing instructions from files it operates on. I hope this
86 shortcoming can be repaired in the near future. tidy() also disturbs
87 some XML escapes in whatever ways XML::XPath does. It has also been
88 brought to my attention that these modules also strip CDATA tags from
89 XML files / data they operate on. Even though CDATA tags don't seem
90 very common, I wish they were easy to support. Hopefully the vast
91 majority of files will work fine.
92 compress()
94 The compress() member function calls strip() on the Tidy object then
95 creates an encoded comment which contains the names of elements &&
96 attributes as they occurred in the original document. Their respective
97 element && attribute names are replaced with just the appropriate index
98 throughout the document.
99 compress() can accept a parameter describing which node types to
101 attempt to shrink down as abbreviations. This parameter should be a
102 string of just the first letters of each node type you wish to include
103 as in the following mapping:
104 e = elements
106 a = attribute keys
107 v = attribute values *EXPERIMENTAL*
108 t = text nodes *EXPERIMENTAL*
109 c = comment nodes *EXPERIMENTAL*
110 n = namespace nodes *not-yet-implemented*
111 Attribute values ('v') && text nodes ('t') both seem to work fine with
113 current tokenization. I've still labeled them EXPERIMENTAL because
114 they seem more likely to cause problems than valid element or attribute
115 key names. I have some bugs in the comment node compression which I
116 haven't been able to find yet so that one should be avoided for now.
117 Since these three node types ('vtc') all require tokenization, they are
118 not included in default compression ('ea'). An example call which
119 includes values && text would be:
120 $tidy_obj->compress('eatv');
122 The original document structure (ie. node hierarchy) is preserved.
124 compress() significantly reduces the file size of most XML documents
125 for when size matters more than immediate human readability. expand()
126 performs the opposite conversion.
127 expand()
129 The expand() member function reads any XML::Tidy::compress comments
130 from the Tidy object && uses them to reconstruct the document that was
131 passed to compress().
132 bcompress('BinaryOutputFilename.xtb')
134 The bcompress() member function stores a binary representation of any
135 Tidy object. The format consists of:
136 0) a null-terminated version string
138 1) a byte specifying how many bytes later indices will be
139 2) the number of bytes from 1 above to designate the total string count
140 3) the number of null-terminated strings from 2 above
141 4) the number of bytes from 1 above to designate the total integer count
142 5) the number of 4-byte integers from 4 above
143 6) the number of bytes from 1 above to designate the total float count
144 7) the number of double-precision floats from 6 above
145 8) node index sets until the end of the file
146 Normal node index sets consist of two values. The first is an index
148 into the three lists (with the number of bytes from 1) as if they were
149 all linear. The second is a single-byte integer identifying the node
150 type (using standard DOM node enumerations).
151 A few special cases exist in node index sets though. If the index is
153 null, it is interpreted as a close-element tag (so no accompanying type
154 value is read). On the other end, when the index is non-zero, the type
155 value is always read. In the event that the type corresponds to an
156 attribute or a processing-instruction, the next index is read (without
157 another accompanying type value) in order to complete the data fields
158 required by those node types.
159 bexpand('BinaryInputFilename.xtb')
161 The bexpand() member function reads a binary file which was previously
162 written from bcompress(). bexpand() is an XML::Tidy object constructor
163 like new().
164 prune()
166 The prune() member function takes an XPath location to remove (along
167 with all attributes && child nodes) from the Tidy object. For example,
168 to remove all comments:
169 $tidy_obj->prune('//comment()');
171 or to remove the third baz (XPath indexing is 1-based):
173 $tidy_obj->prune('/foo/bar/baz[3]');
175 Pruning your XML tree is a form of tidying too so it snuck in here. =)
177 It seems XML::XPath objects are dramatically more useful when they all
178 have access to this class of additional member functions.
179 write()
181 The write() member function can take an optional filename parameter to
182 write out any changes to the Tidy object. If no parameters are given,
183 write() overwrites the original XML document file (if a 'filename'
184 parameter was given to the constructor).
185 write() will croak() if no filename can be found to write to.
187 write() can also take a secondary parameter which specifies an XPath
189 location to be written out as the new root element instead of the Tidy
190 object's root. Only the first matching element is written.
191 toString()
193 The toString() member function is almost identical to write() except
194 that it takes no parameters && simply returns the equivalent XML string
195 as a scalar. It is a little weird because normally only
196 XML::XPath::Node objects have a toString member but I figure it makes
197 sense to extend the same syntax to the parent object as well since it
198 is a useful option.
199
201 The following are just aliases to Node constructors. They'll work with
202 just the unique portion of the node type as the member function name.
203 e() or el() or elem() or createElement()
205 wrapper for XML::XPath::Node::Element->new()
206 a() or at() or attr() or createAttribute()
208 wrapper for XML::XPath::Node::Attribute->new()
209 c() or cm() or cmnt() or createComment()
211 wrapper for XML::XPath::Node::Comment->new()
212 t() or tx() or text() or createTextNode()
214 wrapper for XML::XPath::Node::Text->new()
215 p() or pi() or proc() or createProcessingInstruction()
217 wrapper for XML::XPath::Node::PI->new()
218 n() or ns() or nspc() or createNamespace()
220 wrapper for XML::XPath::Node::Namespace->new()
221
223 XML::Tidy also exports the same node constants as XML::XPath::Node
224 (which correspond to DOM values). These include:
225 UNKNOWN_NODE
227 ELEMENT_NODE
228 ATTRIBUTE_NODE
229 TEXT_NODE
230 CDATA_SECTION_NODE
231 ENTITY_REFERENCE_NODE
232 ENTITY_NODE
233 PROCESSING_INSTRUCTION_NODE
234 COMMENT_NODE
235 DOCUMENT_NODE
236 DOCUMENT_TYPE_NODE
237 DOCUMENT_FRAGMENT_NODE
238 NOTATION_NODE
239 ELEMENT_DECL_NODE
240 ATT_DEF_NODE
241 XML_DECL_NODE
242 ATTLIST_DECL_NODE
243 NAMESPACE_NODE
244 XML::Tidy also exports:
246 STANDARD_XML_DECL
248 which returns a reasonable default XML declaration string.
250
252 Revision history for Perl extension XML::Tidy:
253 - 1.2.54HJnFa Sun Apr 17 19:49:15:36 2005
255 * added support for binary ints && floats in bcompress()
256 * tightened up binary format && added pod
258 - 1.2.54HDR1G Sun Apr 17 13:27:01:16 2005
260 * added bcompress() && bexpand()
261 * added compress() && expand()
263 * added toString()
265 - 1.2.4CKBHxt Mon Dec 20 11:17:59:55 2004
267 * added exporting of XML::XPath::Node (DOM) constants
268 * added node object creation wrappers (like LibXML)
270 - 1.2.4CCJW4G Sun Dec 12 19:32:04:16 2004
272 * added optional 'xpath_loc' => to prune()
273 - 1.0.4CAJna1 Fri Dec 10 19:49:36:01 2004
275 * added optional 'filename' => to write()
276 - 1.0.4CAAf5B Fri Dec 10 10:41:05:11 2004
278 * removed 2nd param from tidy() so that 1st param is just indent
279 string
280 * fixed pod errors
282 - 1.0.4C9JpoP Thu Dec 9 19:51:50:25 2004
284 * added xplc option to write()
285 * added prune()
287 - 1.0.4C8K1Ah Wed Dec 8 20:01:10:43 2004
289 * inherited from XPath so that those methods can be called directly
290 * original version (separating Tidy.pm from Merge.pm)
292
294 From the command shell, please run:
295 `perl -MCPAN -e "install XML::Tidy"`
297 or uncompress the package && run the standard:
299 `perl Makefile.PL; make; make test; make install`
301
303 XML::Tidy requires:
304 Carp to allow errors to croak() from calling sub
306 XML::XPath to use XPath statements to query && update XML
308 XML::XPath::XMLParser to parse XML documents into XPath objects
310 Math::BaseCnv to handle base-64 indexing for compress() &&
312 expand()
313
315 Most source code should be Free!
316 Code I have lawful authority over is && shall be! Copyright: (c)
317 2004, Pip Stuart. Copyleft : This software is licensed under the GNU
318 General Public
319 License (version 2). Please consult the Free Software Foundation
320 (http://FSF.Org) for important information about your freedom.
321
323 Pip Stuart <Pip@CPAN.Org>
324perl v5.12.0 2010-05-07 Tidy(3)