1YAWriter(3)           User Contributed Perl Documentation          YAWriter(3)
2
3
4

NAME

6       XML::Handler::YAWriter - Yet another Perl SAX XML Writer
7

SYNOPSIS

9         use XML::Handler::YAWriter;
10
11         my $ya = new XML::Handler::YAWriter( %options );
12         my $perlsax = new XML::Parser::PerlSAX( 'Handler' => $ya );
13

DESCRIPTION

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
21         @{$ya->{Strings}}
22
23   Options
24       Options are given in the usual 'key' => 'value' idiom.
25
26       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
33       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
38       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
43       AsArray boolean
44           This option will force storage of the XML in $ya->{Strings}, even
45           if the Output option is given.
46
47       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
54       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
60       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
66           The default value for Escape is
67
68               $XML::Handler::YAWriter::escape = {
69                       '&'  => '&',
70                       '<'  => '&lt;',
71                       '>'  => '&gt;',
72                       '"'  => '&quot;',
73                       '--' => '&#45;&#45;'
74                       };
75
76           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
80       Pretty hash
81           Hash of string => boolean tuples, to define kind of prettyprinting.
82           Default to undef. Possible string values:
83
84           AddHiddenNewline boolean
85               Add hidden newline before ">"
86
87           AddHiddenAttrTab boolean
88               Add hidden tabulation for attributes
89
90           CatchEmptyElement boolean
91               Catch empty Elements, apply "/>" compression
92
93           CatchWhiteSpace boolean
94               Catch whitespace with comments
95
96           CompactAttrIndent
97               Places Attributes on the same line as the Element
98
99           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
104           NoComments boolean
105               Supress Comments
106
107           NoDTD boolean
108               Supress DTD
109
110           NoPI boolean
111               Supress Processing Instructions
112
113           NoProlog boolean
114               Supress <?xml ... ?> Prolog
115
116           NoWhiteSpace boolean
117               Supress WhiteSpace to clean documents from prior pretty
118               printing.
119
120           PrettyWhiteIndent boolean
121               Add visible indent before any eventstring
122
123           PrettyWhiteNewline boolean
124               Add visible newlines before any eventstring
125
126           SAX1 boolean (not yet implemented)
127               Output only SAX1 compliant eventstrings
128
129   Notes:
130       Correct handling of start_document and end_document is required!
131
132       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
139       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
146       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
152       Automatic recoding between 8bit and 16bit does not work in any Perl
153       correctly !
154
155       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
159       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
163           $ya->{'Escape'} = {
164                           '&'  => '&amp;',
165                           '<'  => '&lt;',
166                           '>'  => '&gt;',
167                           '"'  => '&quot;',
168                           '--' => '&#45;&#45;'
169                           'A~X' => '&ouml;'
170                           'A~X' => '&auml;'
171                           'A~X' => '&uuml;'
172                           'A~X' => '&Ouml;'
173                           'A~X' => '&Auml;'
174                           'A~X' => '&Uuml;'
175                           'A~X' => '&szlig;'
176                           };
177
178       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
184           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
193       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

AUTHOR

199       Michael Koehne, Kraehe@Copyleft.De
200

Thanks

202       "Derksen, Eduard (Enno), CSCIO" <enno@att.com> helped me with the
203       Escape hash and gave quite a lot of useful comments.
204

SEE ALSO

206       perl and XML::Parser::PerlSAX
207
208
209
210perl v5.12.0                      2010-05-07                       YAWriter(3)
Impressum