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

NAME

6       XML::SAX::Writer - SAX2 Writer
7

SYNOPSIS

9         use XML::SAX::Writer;
10         use XML::SAX::SomeDriver;
11
12         my $w = XML::SAX::Writer->new;
13         my $d = XML::SAX::SomeDriver->new(Handler => $w);
14
15         $d->parse('some options...');
16

DESCRIPTION

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
24       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
33       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

METHODS

37       ·   new(%hash)
38
39           This is the constructor for this object. A It takes a number of
40           parameters, all of which are optional.
41
42       ·   -- Output
43
44           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
51           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
55           If this parameter is not provided, then output is sent to STDOUT.
56
57       ·   -- Escape
58
59           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           &apos; escape used for apostrophes so that you should be careful
65           when outputting XHTML.
66
67           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
70       ·   -- CommentEscape
71
72           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
77       ·   -- EncodeFrom
78
79           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
82       ·   -- EncodeTo
83
84           The character set encoding in which output should be encoded.
85           A Again, this defaults to UTF-8.
86

THE CONSUMER INTERFACE

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
95       If you don't understand this, don't worry. You don't need it most of
96       the time.
97
98       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
104       The two methods that it needs to implement are:
105
106       ·   output STRING
107
108           (Required)
109
110           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
115       ·   finalize()
116
117           (Optional)
118
119           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
125       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
130           package MyConsumer;
131
132           @ISA = qw( XML::SAX::Writer::ConsumerInterface );
133
134           use strict;
135
136           sub new {
137               my $self = shift->SUPER::new( my $output );
138
139               $$self = '';      # Note the extra '$'
140
141               return $self;
142           }
143
144           sub output {
145               my $self = shift;
146               $$self .= uc shift;
147           }
148
149           sub get_output {
150               my $self = shift;
151               return $$self;
152           }
153
154       And here's one way to use it:
155
156           my $c = MyConsumer->new;
157           my $w = XML::SAX::Writer->new( Output => $c );
158
159           ## ... send events to $w ...
160
161           print $c->get_output;
162
163       If you need to store more that one data member, pass in an array or
164       hash reference:
165
166               my $self = shift->SUPER::new( {} );
167
168       and access it like:
169
170           sub output {
171               my $self = shift;
172               $$self->{Output} .= uc shift;
173           }
174

THE ENCODER INTERFACE

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
182       new FROM_ENCODING, TO_ENCODING
183           Creates a new Encoder. The arguments are the chosen encodings.
184
185       convert STRING
186           Converts that string and returns it.
187

CUSTOM OUTPUT

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
193       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
198       init
199           Called before the writing starts, it's a chance for the subclass to
200           do some initialisation if it needs it.
201
202       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
208       setConsumer
209           Same as above, except that it is for the Consumer object, and that
210           it must set "$self-"{Consumer}>.
211
212       setEscaperRegex
213           Will initialise the escaping regex "$self-"{EscaperRegex}> based on
214           what is needed.
215
216       escape STRING
217           Takes a string and escapes it properly.
218
219       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

TODO

225           - proper UTF-16 handling
226
227           - 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
232           - the formatting options need to be developed.
233
234           - test, test, test (and then some tests)
235
236           - doc, doc, doc (actually this part is in better shape)
237
238           - 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
245           - remove the xml_decl and replace it with intelligent logic, as
246           discussed on perl-xml
247
248           - make a the Consumer selecting code available in the API, to avoid
249           duplicating
250
251           - add an Apache output Consumer, triggered by passing $r as Output
252

CREDITS

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

AUTHOR

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

SEE ALSO

268       XML::SAX::*
269

POD ERRORS

271       Hey! The above document had some coding errors, which are explained
272       below:
273
274       Around line 417:
275           Expected '=item *'
276
277       Around line 433:
278           Expected '=item *'
279
280       Around line 445:
281           Expected '=item *'
282
283       Around line 452:
284           Expected '=item *'
285
286       Around line 457:
287           Expected '=item *'
288
289
290
291perl v5.12.0                      2010-05-07                         Writer(3)
Impressum