1YAWriter(3) User Contributed Perl Documentation YAWriter(3)
2
6 XML::Handler::YAWriter - Yet another Perl SAX XML Writer
7
9 use XML::Handler::YAWriter;
10 my $ya = new XML::Handler::YAWriter( %options );
12 my $perlsax = new XML::Parser::PerlSAX( 'Handler' => $ya );
13
15 YAWriter implements Yet Another XML::Handler::Writer. The reasons for
16 this one are that I needed a flexible escaping technique, and want some
17 kind of pretty printing. If an instance of YAWriter is created without
18 any options, the default behavior is to produce an array of strings
19 containing the XML in :
20 @{$ya->{Strings}}
22 Options
24 Options are given in the usual 'key' => 'value' idiom.
25 Output IO::File
27 This option tells YAWriter to use an already open file for output,
28 instead of using $ya->{Strings} to store the array of strings. It
29 should be noted that the only thing the object needs to implement
30 is the print method. So anything can be used to receive a stream of
31 strings from YAWriter.
32 AsFile string
34 This option will cause start_document to open named file and
35 end_document to close it. Use the literal dash "-" if you want to
36 print on standard output.
37 AsPipe string
39 This option will cause start_document to open a pipe and
40 end_document to close it. The pipe is a normal shell command.
41 Secure shell comes handy but has a 2GB limit on most systems.
42 AsArray boolean
44 This option will force storage of the XML in $ya->{Strings}, even
45 if the Output option is given.
46 AsString boolean
48 This option will cause end_document to return the complete XML
49 document in a single string. Most SAX drivers return the value of
50 end_document as a result of their parse method. As this may not
51 work with some combinations of SAX drivers and filters, a join of
52 $ya->{Strings} in the controlling method is preferred.
53 Encoding string
55 This will change the default encoding from UTF-8 to anything you
56 like. You should ensure that given data are already in this
57 encoding or provide an Escape hash, to tell YAWriter about the
58 recoding.
59 Escape hash
61 The Escape hash defines substitutions that have to be done to any
62 string, with the exception of the processing_instruction and
63 doctype_decl methods, where I think that escaping of target and
64 data would cause more trouble than necessary.
65 The default value for Escape is
67 $XML::Handler::YAWriter::escape = {
69 '&' => '&',
70 '<' => '<',
71 '>' => '>',
72 '"' => '"',
73 '--' => '--'
74 };
75 YAWriter will use an evaluated sub to make the recoding based on a
77 given Escape hash reasonably fast. Future versions may use XS to
78 improve this performance bottleneck.
79 Pretty hash
81 Hash of string => boolean tuples, to define kind of prettyprinting.
82 Default to undef. Possible string values:
83 AddHiddenNewline boolean
85 Add hidden newline before ">"
86 AddHiddenAttrTab boolean
88 Add hidden tabulation for attributes
89 CatchEmptyElement boolean
91 Catch empty Elements, apply "/>" compression
92 CatchWhiteSpace boolean
94 Catch whitespace with comments
95 CompactAttrIndent
97 Places Attributes on the same line as the Element
98 IsSGML boolean
100 This option will cause start_document, processing_instruction
101 and doctype_decl to appear as SGML. The SGML is still well-
102 formed of course, if your SAX events are well-formed.
103 NoComments boolean
105 Supress Comments
106 NoDTD boolean
108 Supress DTD
109 NoPI boolean
111 Supress Processing Instructions
112 NoProlog boolean
114 Supress <?xml ... ?> Prolog
115 NoWhiteSpace boolean
117 Supress WhiteSpace to clean documents from prior pretty
118 printing.
119 PrettyWhiteIndent boolean
121 Add visible indent before any eventstring
122 PrettyWhiteNewline boolean
124 Add visible newlines before any eventstring
125 SAX1 boolean (not yet implemented)
127 Output only SAX1 compliant eventstrings
128 Notes:
130 Correct handling of start_document and end_document is required!
131 The YAWriter Object initialises its structures during start_document
133 and does its cleanup during end_document. If you forget to call
134 start_document, any other method will break during the run. Most likely
135 place is the encode method, trying to eval undef as a subroutine. If
136 you forget to call end_document, you should not use a single instance
137 of YAWriter more than once.
138 For small documents AsArray may be the fastest method and AsString the
140 easiest one to receive the output of YAWriter. But AsString and AsArray
141 may run out of memory with infinite SAX streams. The only method
142 XML::Handler::Writer calls on a given Output object is the print
143 method. So it's easy to use a self written Output object to improve
144 streaming.
145 A single instance of XML::Handler::YAWriter is able to produce more
147 than one file in a single run. Be sure to provide a fresh IO::File as
148 Output before you call start_document and close this File after calling
149 end_document. Or provide a filename in AsFile, so start_document and
150 end_document can open and close its own filehandle.
151 Automatic recoding between 8bit and 16bit does not work in any Perl
153 correctly !
154 I have Perl-5.00563 at home and here I can specify "use utf8;" in the
156 right places to make recoding work. But I dislike saying "use 5.00555;"
157 because many systems run 5.00503.
158 If you use some 8bit character set internally and want use national
160 characters, either state your character as Encoding to be ISO-8859-1,
161 or provide an Escape hash similar to the following :
162 $ya->{'Escape'} = {
164 '&' => '&',
165 '<' => '<',
166 '>' => '>',
167 '"' => '"',
168 '--' => '--'
169 'A~X' => 'ö'
170 'A~X' => 'ä'
171 'A~X' => 'ü'
172 'A~X' => 'Ö'
173 'A~X' => 'Ä'
174 'A~X' => 'Ü'
175 'A~X' => 'ß'
176 };
177 You may abuse YAWriter to clean whitespace from XML documents. Take a
179 look at test.pl, doing just that with an XML::Edifact message, without
180 querying the DTD. This may work in 99% of the cases where you want to
181 get rid of ignorable whitespace caused by the various forms of pretty
182 printing.
183 my $ya = new XML::Handler::YAWriter(
185 'Output' => new IO::File ( ">-" );
186 'Pretty' => {
187 'NoWhiteSpace'=>1,
188 'NoComments'=>1,
189 'AddHiddenNewline'=>1,
190 'AddHiddenAttrTab'=>1,
191 } );
192 XML::Handler::Writer implements any method XML::Parser::PerlSAX wants.
194 This extends the Java SAX1.0 specification. I have in mind using
195 Pretty=>SAX1=>1 to disable this feature, if abusing YAWriter for a SAX
196 proxy.
197
199 Michael Koehne, Kraehe@Copyleft.De
200
202 "Derksen, Eduard (Enno), CSCIO" <enno@att.com> helped me with the
203 Escape hash and gave quite a lot of useful comments.
204
206 perl and XML::Parser::PerlSAX
207perl v5.12.0 2010-05-07 YAWriter(3)