1Writer(3) User Contributed Perl Documentation Writer(3)
2
6 XML::SAX::Writer - SAX2 Writer
7
9 use XML::SAX::Writer;
10 use XML::SAX::SomeDriver;
11 my $w = XML::SAX::Writer->new;
13 my $d = XML::SAX::SomeDriver->new(Handler => $w);
14 $d->parse('some options...');
16
18 Why yet another XML Writer ?
19 A new XML Writer was needed to match the SAX2 effort because quite
20 naturally no existing writer understood SAX2. My first intention had
21 been to start patching XML::Handler::YAWriter as it had previously been
22 my favourite writer in the SAX1 world.
23 However the more I patched it the more I realised that what I thought
25 was going to be a simple patch (mostly adding a few event handlers and
26 changing the attribute syntax) was turning out to be a rewrite due to
27 various ideas I'd been collecting along the way. Besides, I couldn't
28 find a way to elegantly make it work with SAX2 without breaking the
29 SAX1 compatibility which people are probably still using. There are of
30 course ways to do that, but most require user interaction which is
31 something I wanted to avoid.
32 So in the end there was a new writer. I think it's in fact better this
34 way as it helps keep SAX1 and SAX2 separated.
35
37 · new(%hash)
38 This is the constructor for this object. A It takes a number of
40 parameters, all of which are optional.
41 · -- Output
43 This parameter can be one of several things. A If it is a simple
45 scalar, it is interpreted as a filename which will be opened for
46 writing. A If it is a scalar reference, output will be appended to
47 this scalar. A If it is an array reference, output will be pushed
48 onto this array as it is generated. A If it is a filehandle, then
49 output will be sent to this filehandle.
50 Finally, it is possible to pass an object for this parameter, in
52 which case it is assumed to be an object that implements the
53 consumer interface described later in the documentation.
54 If this parameter is not provided, then output is sent to STDOUT.
56 · -- Escape
58 This should be a hash reference where the keys are characters
60 sequences that should be escaped and the values are the escaped
61 form of the sequence. A By default, this module will escape the
62 ampersand (&), less than (<), greater than (>), double quote ("),
63 and apostrophe ('). Note that some browsers don't support the
64 ' escape used for apostrophes so that you should be careful
65 when outputting XHTML.
66 If you only want to add entries to the Escape hash, you can first
68 copy the contents of %XML::SAX::Writer::DEFAULT_ESCAPE.
69 · -- CommentEscape
71 Comment content often needs to be escaped differently from other
73 content. This option works exactly as the previous one except that
74 by default it only escapes the double dash (--) and that the
75 contents can be copied from %XML::SAX::Writer::COMMENT_ESCAPE.
76 · -- EncodeFrom
78 The character set encoding in which incoming data will be provided.
80 This defaults to UTF-8, which works for US-ASCII as well.
81 · -- EncodeTo
83 The character set encoding in which output should be encoded.
85 A Again, this defaults to UTF-8.
86
88 XML::SAX::Writer can receive pluggable consumer objects that will be in
89 charge of writing out what is formatted by this module. Setting a
90 Consumer is done by setting the Output option to the object of your
91 choice instead of to an array, scalar, or file handle as is more
92 commonly done (internally those in fact map to Consumer classes and and
93 simply available as options for your convienience).
94 If you don't understand this, don't worry. You don't need it most of
96 the time.
97 That object can be from any class, but must have two methods in its
99 API. It is also strongly recommended that it inherits from
100 XML::SAX::Writer::ConsumerInterface so that it will not break if that
101 interface evolves over time. There are examples at the end of
102 XML::SAX::Writer's code.
103 The two methods that it needs to implement are:
105 · output STRING
107 (Required)
109 This is called whenever the Writer wants to output a string
111 formatted in XML. Encoding conversion, character escaping, and
112 formatting have already taken place. It's up to the consumer to do
113 whatever it wants with the string.
114 · finalize()
116 (Optional)
118 This is called once the document has been output in its entirety,
120 during the end_document event. end_document will in fact return
121 whatever finalize() returns, and that in turn should be returned by
122 parse() for whatever parser was invoked. It might be useful if you
123 need to provide feedback of some sort.
124 Here's an example of a custom consumer. Note the extra "$" signs in
126 front of $self; the base class is optimized for the overwhelmingly
127 common case where only one data member is required and $self is a
128 reference to that data member.
129 package MyConsumer;
131 @ISA = qw( XML::SAX::Writer::ConsumerInterface );
133 use strict;
135 sub new {
137 my $self = shift->SUPER::new( my $output );
138 $$self = ''; # Note the extra '$'
140 return $self;
142 }
143 sub output {
145 my $self = shift;
146 $$self .= uc shift;
147 }
148 sub get_output {
150 my $self = shift;
151 return $$self;
152 }
153 And here's one way to use it:
155 my $c = MyConsumer->new;
157 my $w = XML::SAX::Writer->new( Output => $c );
158 ## ... send events to $w ...
160 print $c->get_output;
162 If you need to store more that one data member, pass in an array or
164 hash reference:
165 my $self = shift->SUPER::new( {} );
167 and access it like:
169 sub output {
171 my $self = shift;
172 $$self->{Output} .= uc shift;
173 }
174
176 Encoders can be plugged in to allow one to use one's favourite encoder
177 object. Presently there are two encoders: Iconv and NullEncoder, and
178 one based on "Encode" ought to be out soon. They need to implement two
179 methods, and may inherit from XML::SAX::Writer::NullConverter if they
180 wish to
181 new FROM_ENCODING, TO_ENCODING
183 Creates a new Encoder. The arguments are the chosen encodings.
184 convert STRING
186 Converts that string and returns it.
187
189 This module is generally used to write XML -- which it does most of the
190 time -- but just like the rest of SAX it can be used as a generic
191 framework to output data, the opposite of a non-XML SAX parser.
192 Of course there's only so much that one can abstract, so depending on
194 your format this may or may not be useful. If it is, you'll need to
195 know the followin API (and probably to have a look inside
196 "XML::SAX::Writer::XML", the default Writer).
197 init
199 Called before the writing starts, it's a chance for the subclass to
200 do some initialisation if it needs it.
201 setConverter
203 This is used to set the proper converter for character encodings.
204 The default implementation should suffice but you can override it.
205 It must set "$self-"{Encoder}> to an Encoder object. Subclasses
206 *should* call it.
207 setConsumer
209 Same as above, except that it is for the Consumer object, and that
210 it must set "$self-"{Consumer}>.
211 setEscaperRegex
213 Will initialise the escaping regex "$self-"{EscaperRegex}> based on
214 what is needed.
215 escape STRING
217 Takes a string and escapes it properly.
218 setCommentEscaperRegex and escapeComment STRING
220 These work exactly the same as the two above, except that they are
221 meant to operate on comment contents, which often have different
222 escaping rules than those that apply to regular content.
223
225 - proper UTF-16 handling
226 - make the quote character an option. By default it is here ', but
228 I know that a lot of people (for reasons I don't understand but
229 won't question :-) prefer to use ". (on most keyboards " is more
230 typing, on the rest it's often as much typing).
231 - the formatting options need to be developed.
233 - test, test, test (and then some tests)
235 - doc, doc, doc (actually this part is in better shape)
237 - add support for Perl 5.7's Encode module so that we can use it
239 instead of Text::Iconv. Encode is more complete and likely to be
240 better supported overall. This will be done using a pluggable
241 encoder (so that users can provide their own if they want to)
242 and detecter both in Makefile.PL requirements and in the module
243 at runtime.
244 - remove the xml_decl and replace it with intelligent logic, as
246 discussed on perl-xml
247 - make a the Consumer selecting code available in the API, to avoid
249 duplicating
250 - add an Apache output Consumer, triggered by passing $r as Output
252
254 Michael Koehne (XML::Handler::YAWriter) for much inspiration and Barrie
255 Slaymaker for the Consumer pattern idea, the coderef output option and
256 miscellaneous bugfixes and performance tweaks. Of course the usual
257 suspects (Kip Hampton and Matt Sergeant) helped in the usual ways.
258
260 Robin Berjon, robin@knowscape.com
261
263 Copyright (c) 2001-2006 Robin Berjon nad Perl XML project. All rights
264 reserved. This program is free software; you can redistribute it
265 and/or modify it under the same terms as Perl itself.
266
268 XML::SAX::*
269
271 Hey! The above document had some coding errors, which are explained
272 below:
273 Around line 417:
275 Expected '=item *'
276 Around line 433:
278 Expected '=item *'
279 Around line 445:
281 Expected '=item *'
282 Around line 452:
284 Expected '=item *'
285 Around line 457:
287 Expected '=item *'
288perl v5.10.1 2010-08-21 Writer(3)