1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
|
<HTML>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Created on October, 7 2003 by texi2html 1.64 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
-->
<HEAD>
<TITLE>The Ada95 XML Library: The SAX module</TITLE>
<META NAME="description" CONTENT="The Ada95 XML Library: The SAX module">
<META NAME="keywords" CONTENT="The Ada95 XML Library: The SAX module">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="texi2html 1.64">
</HEAD>
<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<A NAME="SEC9"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_3.html#SEC8"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC10"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_5.html#SEC14"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_5.html#SEC14"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1> 4. The SAX module </H1>
<!--docid::SEC9::-->
<P>
<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="xml_4.html#SEC10">4.1 Description</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="xml_4.html#SEC11">4.2 Examples</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="xml_4.html#SEC12">4.3 The SAX parser</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="xml_4.html#SEC13">4.4 The SAX handlers</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
</TABLE></BLOCKQUOTE>
<P>
<A NAME="SAX Description"></A>
<HR SIZE="6">
<A NAME="SEC10"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC9"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC11"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC9"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC9"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_5.html#SEC14"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.1 Description </H2>
<!--docid::SEC10::-->
<P>
Parsing XML streams can be done with two different methods. They each
have their pros and cons. Although the simplest, and probably most usual
way to manipulate XML files is to represent them in a tree and manipulate
it through the DOM interface (see next chapter).
</P><P>
The <B>Simple API for XML</B> is an other method that can be used for parsing.
It is based on a callbacks mechanism, and doesn't store any data in memory
(unless of course you choose to do so in your callbacks). It can thus be
more efficient to use SAX than DOM for some specialized algorithms.
In fact, this whole Ada XML library is based on such a SAX parser, then
creates the DOM tree through callbacks.
</P><P>
Note that this module supports the second release of SAX (SAX2), that fully
supports namespaces as defined in the XML standard.
</P><P>
SAX can also be used in cases where a tree would not be the most efficient
representation for you data. There is no point in building a tree with DOM,
then extracting the data and freeing the tree occupied by the tree. It is
much more efficient to directly store your data through SAX callbacks.
</P><P>
With SAX, you register a number of callback routines that the parser will
call them when certain conditions occur.
</P><P>
This documentation is in no way a full documentation on SAX. Instead,
you should refer to the standard itself, available at
<A HREF="http://www.megginson.com/SAX/">http://www.megginson.com/SAX/</A>.
</P><P>
Some of the more useful callbacks are <CODE>Start_Document</CODE>,
<CODE>End_Document</CODE>, <CODE>Start_Element</CODE>, <CODE>End_Element</CODE>,
<CODE>Get_Entity</CODE> and <CODE>Characters</CODE>. Most of these are
quite self explanatory. The characters callback is called when
characters outside a tag are parsed.
</P><P>
Consider the following XML file:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre><?xml version="1.0"?>
<body>
<h1>Title</h1>
</body>
</FONT></pre></td></tr></table></P><P>
The following events would then be generated when this file is parsed:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>Start_Document Start parsing the file
Start_Prefix_Mapping (handling of namespaces for "xml")
Start_Prefix_Mapping Parameter is "xmlns"
Processing_Instruction Parameters are "xml" and "version="1.0""
Start_Element Parameter is "body"
Characters Parameter is ASCII.LF & " "
Start_Element Parameter is "h1"
Characters Parameter is "Title"
End_Element Parameter is "h1"
Characters Parameter is ASCII.LF & " "
End_Element Parameter is "body"
End_Prefix_Mapping Parameter is "xmlns"
End_Prefix_Mapping Parameter is "xml"
End_Document End of parsing
</FONT></pre></td></tr></table></P><P>
As you can see, there is a number of events even for a very small file.
However, you can easily choose to ignore the events you don't care
about, for instance the ones related to namespace handling.
</P><P>
<A NAME="SAX Examples"></A>
<HR SIZE="6">
<A NAME="SEC11"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC10"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC12"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC12"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC9"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_5.html#SEC14"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.2 Examples </H2>
<!--docid::SEC11::-->
<P>
There are several cases where using a SAX parser rather than a DOM
parser would make sense. Here are some examples, although obvisouly
this doesn't include all the possible cases. These examples are taken
from the documentation of libxml, a GPL C toolkit for manipulating XML files.
</P><P>
<UL>
<LI>Using XML files as a database
<P>
One of the common usage for XML files is to use them as a kind of
basic database, They obviously provide a strongly structured format,
and you could for instance store a series of numbers with the following
format.
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre><array> <value>1</value> <value>2</value> ....</array>
</FONT></pre></td></tr></table></P><P>
In this case, rather than reading this file into a tree, it would obviously
be easier to manipulate it through a SAX parser, that would directly create
a standard Ada array while reading the values.
</P><P>
This can be extended to much more complex cases that would map to Ada
records for instance.
</P><P>
<LI>Large repetitive XML files
<P>
Sometimes we have XML files with many subtrees of the same format
describing different things. An example of this is an index file for a
documentation similar to this one. This contains a lot (maybe thousands)
of similar entries, each containing for instance the name of the symbol
and a list of locations.
</P><P>
If the user is looking for a specific entry, there is no point in loading
the whole file in memory and then traverse the resulting tree. The memory
usage increases very fast with the size of the file, and this might even
be unfeasible for a 35 megabytes file.
</P><P>
<LI>Simple XML files
<P>
Even for simple XML files, it might make sense to use a SAX parser. For
instance, if there are some known constraints in the input file, say
there are no attributes for elements, you can save quite a lot of memory,
and maybe time, by rebuilding your own tree rather than using the full
DOM tree.
</P><P>
</UL>
<P>
However, there are also a number of drawbacks to using SAX:
</P><P>
<UL>
<LI>SAX parsers generally require you to write a little bit more code than
the DOM interface
<LI>There is no easy way to write the XML data back to a file, unless you
build your own internal tree to save the XML.
As a result, SAX is probably not the best interface if you want to load,
modify and dump back an XML file.
<P>
Note however than in this Ada implementation, the DOM tree is built through
a set of SAX callbacks anyway, so you do not lose any power or speed by using
SAX.
</UL>
<P>
<A NAME="SAX Parser"></A>
<HR SIZE="6">
<A NAME="SEC12"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC11"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC13"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC13"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC9"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_5.html#SEC14"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.3 The SAX parser </H2>
<!--docid::SEC12::-->
<P>
The basic type in the SAX module is the <B>SAX.Readers</B> package. It
defines a tagged type, called <CODE>Reader</CODE>, that represents the SAX
parser itself.
</P><P>
Several features are define in the SAX standard for the parsers. They
indicate which behavior can be expected from the parser. The package
<CODE>SAX.Readers</CODE> defines a number of constant strings for each of
these features. Some of these features are read-only, whereas others can
be modified by the user to adapt the parser. See the <CODE>Set_Feature</CODE>
and <CODE>Get_Feature</CODE> subprograms for how to manipulate them.
</P><P>
The main primitive operation for the parser is <CODE>Parse</CODE>. It takes
an input stream for argument, associated with some XML data, and then
parses it and calls the appropriate callbacks. It returns once there are
no more characters left in the stream.
</P><P>
Several other primitive subprograms are defined for the parser, that are
called the <B>callbacks</B>. They get called automatically by the <CODE>Parse</CODE>
procedure when some events are seen.
</P><P>
As a result, you should always override at least some of these subprogram
to get something done. The default implementation for these is to do nothing,
exception for the error handler that raises Ada exceptions appropriately.
</P><P>
An example of such an implementation of a SAX parser is available in the
DOM module, and it creates a tree in memory. As you will see if you look at
the code, the callbacks are actually very short.
</P><P>
Note that internally, all the strings are encoded with a unique character
encoding scheme, that is defined in the file <TT>`sax-encodings.ads'</TT>. The input
stream is converted on the fly to this internal encoding, and all the
subprograms from then on will receive and pass parameters with this new
encoding. You can of course freely change the encoding defined in the file
<TT>`sax-encodings.ads'</TT>.
</P><P>
The encoding used for the input stream is either automatically
detected by the stream itself (see section <A HREF="xml_3.html#SEC8">3. The Input module</A>), or by parsing the
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre> <?xml version='1.0' encoding='UTF-8' ?>
</FONT></pre></td></tr></table>processing instruction at the beginning of the document. The list of
supported encodings is the same as for the Unicode module (see section <A HREF="xml_2.html#SEC2">2. The Unicode module</A>).
</P><P>
<A NAME="SAX Handlers"></A>
<HR SIZE="6">
<A NAME="SEC13"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC12"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_5.html#SEC14"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC9"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC9"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_5.html#SEC14"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.4 The SAX handlers </H2>
<!--docid::SEC13::-->
<P>
We do not intend to document the whole set of possible callbacks associated
with a SAX parser. These are all fully documented in the standard itself, and
there is little point in duplicating this information.
</P><P>
However, here is a list of the most frequently used callbacks, that you will
probably need to override in most of your applications.
</P><P>
<DL COMPACT>
<DT><CODE>Start_Document</CODE>
<DD>This callback, that doesn't receive any parameter, is called once, just before
parsing the document. It should generally be used to initialize internal
data needed later on. It is also garanteed to be called only once per input
stream.
<P>
<DT><CODE>End_Document</CODE>
<DD>This one is the reverse of the previous one, and will also be called only
once per input stream. It should be used to release the memory you have
allocated in Start_Document.
<P>
<DT><CODE>Start_Element</CODE>
<DD>This callback is called every time the parser encounters the start of an
element in the XML file. It is passed the name of the element, as well as
the relevant namespace information. The attributes defined in this element
are also passed as a list. Thus, you get all the required information for
this element in a single function call.
<P>
<DT><CODE>End_Element</CODE>
<DD>This is the opposite of the previous callback, and will be called once per
element. Calls to <CODE>Start_Element</CODE> and <CODE>End_Element</CODE> are garanteed
to be properly nested (ie you can't see the end of an element before seeing
the end of all its nested children.
<P>
<DT><CODE>Characters and Ignore_Whitespace</CODE>
<DD>This procedure will be called every time some character not part of an
element declaration are encounted. The characters themselves are passed as
an argument to the callback. Note that the white spaces (and tabulations)
are reported separately in the Ignorable_Spaces callback in case the
XML attribute <CODE>xml:space</CODE> was set to something else than <CODE>preserve</CODE>
for this element.
<P>
</DL>
<P>
You should compile and run the <TT>`testsax'</TT> executable found in this
module to visualize the SAX events that are generated for a given XML file.
</P><P>
<A NAME="The DOM module"></A>
<HR SIZE="6">
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_4.html#SEC9"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_5.html#SEC14"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="xml_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<BR>
<FONT SIZE="-1">
This document was generated
by <I>Emmanuel Briot</I> on <I>October, 7 2003</I>
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
"><I>texi2html</I></A>
</BODY>
</HTML>
|
