1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
9 .de Vb \" Begin verbatim text
14 .de Ve \" End verbatim text
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD. Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
53 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear. Run. Save yourself. No user-serviceable parts.
65 . \" fudge factors for nroff and troff
74 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 . \" simple accents for nroff and troff
90 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
97 . \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 . \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 . \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
124 .\" ========================================================================
126 .IX Title "SAX::Intro 3"
127 .TH SAX::Intro 3 "2008-08-04" "perl v5.8.7" "User Contributed Perl Documentation"
128 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
133 XML::SAX::Intro \- An Introduction to SAX Parsing with Perl
135 .IX Header "Introduction"
136 \&\s-1XML::SAX\s0 is a new way to work with \s-1XML\s0 Parsers in Perl. In this article
137 we'll discuss why you should be using \s-1SAX\s0, why you should be using
138 \&\s-1XML::SAX\s0, and we'll see some of the finer implementation details. The
139 text below assumes some familiarity with callback, or push based
140 parsing, but if you are unfamiliar with these techniques then a good
141 place to start is Kip Hampton's excellent series of articles on \s-1XML\s0.com.
142 .SH "Replacing XML::Parser"
143 .IX Header "Replacing XML::Parser"
144 The de-facto way of parsing \s-1XML\s0 under perl is to use Larry Wall and
145 Clark Cooper's XML::Parser. This module is a Perl and \s-1XS\s0 wrapper around
146 the expat \s-1XML\s0 parser library by James Clark. It has been a hugely
147 successful project, but suffers from a couple of rather major flaws.
148 Firstly it is a proprietary \s-1API\s0, designed before the \s-1SAX\s0 \s-1API\s0 was
149 conceived, which means that it is not easily replaceable by other
150 streaming parsers. Secondly it's callbacks are subrefs. This doesn't
151 sound like much of an issue, but unfortunately leads to code like:
154 \& sub handle_start {
155 \& my ($e, $el, %attrs) = @_;
156 \& if ($el eq \*(Aqfoo\*(Aq) {
157 \& $e\->{inside_foo}++; # BAD! $e is an XML::Parser::Expat object.
162 As you can see, we're using the \f(CW$e\fR object to hold our state
163 information, which is a bad idea because we don't own that object \- we
164 didn't create it. It's an internal object of XML::Parser, that happens
165 to be a hashref. We could all too easily overwrite XML::Parser internal
166 state variables by using this, or Clark could change it to an array ref
167 (not that he would, because it would break so much code, but he could).
169 The only way currently with XML::Parser to safely maintain state is to
173 \& my $state = MyState\->new();
174 \& $parser\->setHandlers(Start => sub { handle_start($state, @_) });
177 This closure traps the \f(CW$state\fR variable, which now gets passed as the
178 first parameter to your callback. Unfortunately very few people use
179 this technique, as it is not documented in the XML::Parser \s-1POD\s0 files.
181 Another reason you might not want to use XML::Parser is because you
182 need some feature that it doesn't provide (such as validation), or you
183 might need to use a library that doesn't use expat, due to it not being
184 installed on your system, or due to having a restrictive \s-1ISP\s0. Using \s-1SAX\s0
185 allows you to work around these restrictions.
186 .SH "Introducing SAX"
187 .IX Header "Introducing SAX"
188 \&\s-1SAX\s0 stands for the Simple \s-1API\s0 for \s-1XML\s0. And simple it really is.
189 Constructing a \s-1SAX\s0 parser and passing events to handlers is done as
196 \& my $parser = XML::SAX::ParserFactory\->parser(
197 \& Handler => MySAXHandler\->new
200 \& $parser\->parse_uri("foo.xml");
203 The important concept to grasp here is that \s-1SAX\s0 uses a factory class
204 called XML::SAX::ParserFactory to create a new parser instance. The
205 reason for this is so that you can support other underlying
206 parser implementations for different feature sets. This is one thing
207 that XML::Parser has always sorely lacked.
209 In the code above we see the parse_uri method used, but we could
211 called parse_file, parse_string, or \fIparse()\fR. Please see XML::SAX::Base
212 for what these methods take as parameters, but don't be fooled into
213 believing parse_file takes a filename. No, it takes a file handle, a
214 glob, or a subclass of IO::Handle. Beware.
216 \&\s-1SAX\s0 works very similarly to XML::Parser's default callback method,
217 except it has one major difference: rather than setting individual
218 callbacks, you create a new class in which to recieve the callbacks.
219 Each callback is called as a method call on an instance of that handler
220 class. An example will best demonstrate this:
223 \& package MySAXHandler;
224 \& use base qw(XML::SAX::Base);
226 \& sub start_document {
227 \& my ($self, $doc) = @_;
228 \& # process document start event
231 \& sub start_element {
232 \& my ($self, $el) = @_;
233 \& # process element start event
237 Now, when we instantiate this as above, and parse some \s-1XML\s0 with this as
238 the handler, the methods start_document and start_element will be
239 called as method calls, so this would be the equivalent of directly
243 \& $object\->start_element($el);
246 Notice how this is different to XML::Parser's calling style, which
250 \& start_element($e, $name, %attribs);
253 It's the difference between function calling and method calling which
254 allows you to subclass \s-1SAX\s0 handlers which contributes to \s-1SAX\s0 being a
257 As you can see, unlike XML::Parser, we have to define a new package in
258 which to do our processing (there are hacks you can do to make this
259 uneccessary, but I'll leave figuring those out to the experts). The
260 biggest benefit of this is that you maintain your own state variable
261 ($self in the above example) thus freeing you of the concerns listed
262 above. It is also an improvement in maintainability \- you can place the
263 code in a separate file if you wish to, and your callback methods are
264 always called the same thing, rather than having to choose a suitable
265 name for them as you had to with XML::Parser. This is an obvious win.
267 \&\s-1SAX\s0 parsers are also very flexible in how you pass a handler to them.
268 You can use a constructor parameter as we saw above, or we can pass the
269 handler directly in the call to one of the parse methods:
272 \& $parser\->parse(Handler => $handler,
273 \& Source => { SystemId => "foo.xml" });
275 \& $parser\->parse_file($fh, Handler => $handler);
278 This flexibility allows for one parser to be used in many different
279 scenarios throughout your script (though one shouldn't feel pressure to
280 use this method, as parser construction is generally not a time
282 .SH "Callback Parameters"
283 .IX Header "Callback Parameters"
284 The only other thing you need to know to understand basic \s-1SAX\s0 is the
285 structure of the parameters passed to each of the callbacks. In
286 XML::Parser, all parameters are passed as multiple options to the
287 callbacks, so for example the Start callback would be called as
288 my_start($e, \f(CW$name\fR, \f(CW%attributes\fR), and the \s-1PI\s0 callback would be called
289 as my_processing_instruction($e, \f(CW$target\fR, \f(CW$data\fR). In \s-1SAX\s0, every
290 callback is passed a hash reference, containing entries that define our
291 \&\*(L"node\*(R". The key callbacks and the structures they receive are:
293 .IX Subsection "start_element"
294 The start_element handler is called whenever a parser sees an opening
295 tag. It is passed an element structure consisting of:
298 The name of the element minus any namespace prefix it may
299 have come with in the document.
301 .IX Item "NamespaceURI"
302 The \s-1URI\s0 of the namespace associated with this element,
303 or the empty string for none.
305 .IX Item "Attributes"
306 A set of attributes as described below.
309 The name of the element as it was seen in the document (i.e.
310 including any prefix associated with it)
313 The prefix used to qualify this element's namespace, or the
314 empty string if none.
316 The \fBAttributes\fR are a hash reference, keyed by what we have called
317 \&\*(L"James Clark\*(R" notation. This means that the attribute name has been
318 expanded to include any associated namespace \s-1URI\s0, and put together as
319 {ns}name, where \*(L"ns\*(R" is the expanded namespace \s-1URI\s0 of the attribute if
320 and only if the attribute had a prefix, and \*(L"name\*(R" is the LocalName of
323 The value of each entry in the attributes hash is another hash
324 structure consisting of:
327 The name of the attribute minus any namespace prefix it may have
328 come with in the document.
330 .IX Item "NamespaceURI"
331 The \s-1URI\s0 of the namespace associated with this attribute. If the
332 attribute had no prefix, then this consists of just the empty string.
335 The attribute's name as it appeared in the document, including any
339 The prefix used to qualify this attribute's namepace, or the
340 empty string if none.
343 The value of the attribute.
345 So a full example, as output by Data::Dumper might be:
351 .IX Subsection "end_element"
352 The end_element handler is called either when a parser sees a closing
353 tag, or after start_element has been called for an empty element (do
354 note however that a parser may if it is so inclined call characters
355 with an empty string when it sees an empty element. There is no simple
356 way in \s-1SAX\s0 to determine if the parser in fact saw an empty element, a
357 start and end element with no content..
359 The end_element handler receives exactly the same structure as
360 start_element, minus the Attributes entry. One must note though that it
361 should not be a reference to the same data as start_element receives,
362 so you may change the values in start_element but this will not affect
363 the values later seen by end_element.
365 .IX Subsection "characters"
366 The characters callback may be called in serveral circumstances. The
367 most obvious one is when seeing ordinary character data in the markup.
368 But it is also called for text in a \s-1CDATA\s0 section, and is also called
369 in other situations. A \s-1SAX\s0 parser has to make no guarantees whatsoever
370 about how many times it may call characters for a stretch of text in an
371 \&\s-1XML\s0 document \- it may call once, or it may call once for every
372 character in the text. In order to work around this it is often
373 important for the \s-1SAX\s0 developer to use a bundling technique, where text
374 is gathered up and processed in one of the other callbacks. This is not
375 always necessary, but it is a worthwhile technique to learn, which we
376 will cover in XML::SAX::Advanced (when I get around to writing it).
378 The characters handler is called with a very simple structure \- a hash
379 reference consisting of just one entry:
382 The text data that was received.
384 .IX Subsection "comment"
385 The comment callback is called for comment text. Unlike with
386 \&\f(CW\*(C`characters()\*(C'\fR, the comment callback *must* be invoked just once for an
387 entire comment string. It receives a single simple structure \- a hash
388 reference containing just one entry:
391 The text of the comment.
392 .SS "processing_instruction"
393 .IX Subsection "processing_instruction"
394 The processing instruction handler is called for all processing
395 instructions in the document. Note that these processing instructions
396 may appear before the document root element, or after it, or anywhere
397 where text and elements would normally appear within the document,
398 according to the \s-1XML\s0 specification.
400 The handler is passed a structure containing just two entries:
403 The target of the processing instrcution
406 The text data in the processing instruction. Can be an empty
407 string for a processing instruction that has no data element.
408 For example <?wiggle?> is a perfectly valid processing instruction.
409 .SH "Tip of the iceberg"
410 .IX Header "Tip of the iceberg"
411 What we have discussed above is really the tip of the \s-1SAX\s0 iceberg. And
412 so far it looks like there's not much of interest to \s-1SAX\s0 beyond what we
413 have seen with XML::Parser. But it does go much further than that, I
416 People who hate Object Oriented code for the sake of it may be thinking
417 here that creating a new package just to parse something is a waste
418 when they've been parsing things just fine up to now using procedural
419 code. But there's reason to all this madness. And that reason is \s-1SAX\s0
422 As you saw right at the very start, to let the parser know about our
423 class, we pass it an instance of our class as the Handler to the
424 parser. But now imagine what would happen if our class could also take
425 a Handler option, and simply do some processing and pass on our data
426 further down the line? That in a nutshell is how \s-1SAX\s0 filters work. It's
427 Unix pipes for the 21st century!
429 There are two downsides to this. Number 1 \- writing \s-1SAX\s0 filters can be
430 tricky. If you look into the future and read the advanced tutorial I'm
431 writing, you'll see that Handler can come in several shapes and sizes.
432 So making sure your filter does the right thing can be tricky.
433 Secondly, constructing complex filter chains can be difficult, and
434 simple thinking tells us that we only get one pass at our document,
435 when often we'll need more than that.
437 Luckily though, those downsides have been fixed by the release of two
438 very cool modules. What's even better is that I didn't write either of
441 The first module is XML::SAX::Base. This is a \s-1VITAL\s0 \s-1SAX\s0 module that
442 acts as a base class for all \s-1SAX\s0 parsers and filters. It provides an
443 abstraction away from calling the handler methods, that makes sure your
444 filter or parser does the right thing, and it does it \s-1FAST\s0. So, if you
445 ever need to write a \s-1SAX\s0 filter, which if you're processing \s-1XML\s0 \-> \s-1XML\s0,
446 or \s-1XML\s0 \-> \s-1HTML\s0, then you probably do, then you need to be writing it as
447 a subclass of XML::SAX::Base. Really \- this is advice not to ignore
448 lightly. I will not go into the details of writing a \s-1SAX\s0 filter here.
449 Kip Hampton, the author of XML::SAX::Base has covered this nicely in
450 his article on \s-1XML\s0.com here <\s-1URI\s0>.
452 To construct \s-1SAX\s0 pipelines, Barrie Slaymaker, a long time Perl hacker
453 whose modules you will probably have heard of or used, wrote a very
454 clever module called XML::SAX::Machines. This combines some really
455 clever \s-1SAX\s0 filter-type modules, with a construction toolkit for filters
456 that makes building pipelines easy. But before we see how it makes
457 things easy, first lets see how tricky it looks to build complex \s-1SAX\s0
461 \& use XML::SAX::ParserFactory;
462 \& use XML::Filter::Filter1;
463 \& use XML::Filter::Filter2;
464 \& use XML::SAX::Writer;
466 \& my $output_string;
467 \& my $writer = XML::SAX::Writer\->new(Output => \e$output_string);
468 \& my $filter2 = XML::SAX::Filter2\->new(Handler => $writer);
469 \& my $filter1 = XML::SAX::Filter1\->new(Handler => $filter2);
470 \& my $parser = XML::SAX::ParserFactory\->parser(Handler => $filter1);
472 \& $parser\->parse_uri("foo.xml");
475 This is a lot easier with XML::SAX::Machines:
478 \& use XML::SAX::Machines qw(Pipeline);
480 \& my $output_string;
481 \& my $parser = Pipeline(
482 \& XML::SAX::Filter1 => XML::SAX::Filter2 => \e$output_string
485 \& $parser\->parse_uri("foo.xml");
488 One of the main benefits of XML::SAX::Machines is that the pipelines
489 are constructed in natural order, rather than the reverse order we saw
490 with manual pipeline construction. XML::SAX::Machines takes care of all
491 the internals of pipe construction, providing you at the end with just
492 a parser you can use (and you can re-use the same parser as many times
495 Just a final tip. If you ever get stuck and are confused about what is
496 being passed from one \s-1SAX\s0 filter or parser to the next, then
497 Devel::TraceSAX will come to your rescue. This perl debugger plugin
498 will allow you to dump the \s-1SAX\s0 stream of events as it goes by. Usage is
499 really very simple just call your perl script that uses \s-1SAX\s0 as follows:
502 \& $ perl \-d:TraceSAX <scriptname>
505 And preferably pipe the output to a pager of some sort, such as more or
506 less. The output is extremely verbose, but should help clear some
510 Matt Sergeant, matt@sergeant.org
512 \&\f(CW$Id:\fR Intro.pod,v 1.4 2008\-08\-04 10:28:01 grant Exp $
projects / catagits/Gitalist.git / blob