% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\usepackage[utf8]{inputenc}
\DeclareUnicodeCharacter{00A0}{\nobreakspace}
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage{longtable}
\usepackage{sphinx}
\usepackage{multirow}



\title{XML/Ada: the XML Library for Ada Documentation}
\date{May 16, 2016}
\release{2016}
\author{AdaCore}
\newcommand{\sphinxlogo}{}
\renewcommand{\releasename}{Release}
\makeindex

\makeatletter
\def\PYG@reset{\let\PYG@it=\relax \let\PYG@bf=\relax%
    \let\PYG@ul=\relax \let\PYG@tc=\relax%
    \let\PYG@bc=\relax \let\PYG@ff=\relax}
\def\PYG@tok#1{\csname PYG@tok@#1\endcsname}
\def\PYG@toks#1+{\ifx\relax#1\empty\else%
    \PYG@tok{#1}\expandafter\PYG@toks\fi}
\def\PYG@do#1{\PYG@bc{\PYG@tc{\PYG@ul{%
    \PYG@it{\PYG@bf{\PYG@ff{#1}}}}}}}
\def\PYG#1#2{\PYG@reset\PYG@toks#1+\relax+\PYG@do{#2}}

\expandafter\def\csname PYG@tok@gd\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.63,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gu\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@gt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.27,0.87}{##1}}}
\expandafter\def\csname PYG@tok@gs\endcsname{\let\PYG@bf=\textbf}
\expandafter\def\csname PYG@tok@gr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{1.00,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@cm\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@vg\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@m\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@mh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@cs\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}
\expandafter\def\csname PYG@tok@ge\endcsname{\let\PYG@it=\textit}
\expandafter\def\csname PYG@tok@vc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@il\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@go\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.20,0.20,0.20}{##1}}}
\expandafter\def\csname PYG@tok@cp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@gi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.63,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gh\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@ni\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.84,0.33,0.22}{##1}}}
\expandafter\def\csname PYG@tok@nl\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.13,0.44}{##1}}}
\expandafter\def\csname PYG@tok@nn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@no\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.38,0.68,0.84}{##1}}}
\expandafter\def\csname PYG@tok@na\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@nb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@nd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.33,0.33,0.33}{##1}}}
\expandafter\def\csname PYG@tok@ne\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.49}{##1}}}
\expandafter\def\csname PYG@tok@si\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.44,0.63,0.82}{##1}}}
\expandafter\def\csname PYG@tok@s2\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@vi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@nt\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.45}{##1}}}
\expandafter\def\csname PYG@tok@nv\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@s1\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@gp\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@sh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@ow\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@sx\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@bp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c1\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@kc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@mf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@err\endcsname{\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}
\expandafter\def\csname PYG@tok@mb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@ss\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.32,0.47,0.09}{##1}}}
\expandafter\def\csname PYG@tok@sr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.14,0.33,0.53}{##1}}}
\expandafter\def\csname PYG@tok@mo\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@kd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@mi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@kn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@o\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.40,0.40,0.40}{##1}}}
\expandafter\def\csname PYG@tok@kr\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@s\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@kp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@w\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.73,0.73}{##1}}}
\expandafter\def\csname PYG@tok@kt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.56,0.13,0.00}{##1}}}
\expandafter\def\csname PYG@tok@sc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@k\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@se\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sd\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}

\def\PYGZbs{\char`\\}
\def\PYGZus{\char`\_}
\def\PYGZob{\char`\{}
\def\PYGZcb{\char`\}}
\def\PYGZca{\char`\^}
\def\PYGZam{\char`\&}
\def\PYGZlt{\char`\<}
\def\PYGZgt{\char`\>}
\def\PYGZsh{\char`\#}
\def\PYGZpc{\char`\%}
\def\PYGZdl{\char`\$}
\def\PYGZhy{\char`\-}
\def\PYGZsq{\char`\'}
\def\PYGZdq{\char`\"}
\def\PYGZti{\char`\~}
% for compatibility with earlier versions
\def\PYGZat{@}
\def\PYGZlb{[}
\def\PYGZrb{]}
\makeatother

\renewcommand\PYGZsq{\textquotesingle}

\begin{document}

\maketitle
\tableofcontents
\phantomsection\label{index::doc}



\chapter{Introduction}
\label{intro:introduction}\label{intro::doc}\label{intro:xml-ada-the-unicode-and-xml-library-for-ada}
The Extensible Markup Language (XML) is a subset of SGML Its goal is to enable
generic SGML to be served, received, and processed on the Web in the way that
is now possible with HTML. XML has been designed for ease of implementation and
for interoperability with both SGML and HTML.

This library includes a set of Ada95 packages to manipulate XML input. It
implements the XML 1.0 standard (see the references at the end of this
document), as well as support for namespaces and a number of other optional
standards related to XML.

We have tried to follow as closely as possible the XML standard, so that you
can easily analyze and reuse languages produced for other languages.

This document isn't a tutorial on what XML is, nor on the various standards
like DOM and SAX. Although we will try and give a few examples, we refer the
reader to the standards themselves, which are all easily readable.


\chapter{The Unicode module}
\label{unicode:the-unicode-module}\label{unicode::doc}\label{unicode:id1}
Unicode provides a unique number for every character, no matter what the
platform, no matter what the program, no matter what the language.

Fundamentally, computers just deal with numbers. They store letters and other
characters by assigning a number for each one. Before Unicode was invented,
there were hundreds of different encoding systems for assigning these numbers.
No single encoding could contain enough characters: for example, the European
Union alone requires several different encodings to cover all its languages.
Even for a single language like English no single encoding was adequate for all
the letters, punctuation, and technical symbols in common use.

These encoding systems also conflict with one another. That is, two encodings
can use the same number for two different characters, or use different numbers
for the same character. Any given computer (especially servers) needs to
support many different encodings; yet whenever data is passed between different
encodings or platforms, that data always runs the risk of corruption.

Unicode provides a unique number for every character, no matter what the
platform, no matter what the program, no matter what the language. The Unicode
Standard has been adopted by such industry leaders as Apple, HP, IBM,
JustSystem, Microsoft, Oracle, SAP, Sun, Sybase, Unisys and many others.
Unicode is required by modern standards such as XML, Java, ECMAScript
(JavaScript), LDAP, CORBA 3.0, WML, etc., and is the official way to implement
ISO/IEC 10646. It is supported in many operating systems, all modern browsers,
and many other products. The emergence of the Unicode Standard, and the
availability of tools supporting it, are among the most significant recent
global software technology trends.

The following sections explain the basic vocabulary and concepts associated
with Unicode and encodings.

Most of the information comes from the official Unicode Web site, at
\href{http://www.unicode.org/unicode/reports/tr17}{http://www.unicode.org/unicode/reports/tr17}.

Part of this documentation comes from \href{http://www.unicode.org}{http://www.unicode.org}, the official web site for Unicode.


\section{Glyphs}
\label{unicode:glyphs}\label{unicode:id2}
A glyph is a particular representation of a character or part of a character.

Several representations are possible, mostly depending on the exact font used
at that time. A single glyph can correspond to a sequence of characters, or a
single character to a sequence of glyphs.

The Unicode standard doesn't deal with glyphs, although a suggested
representation is given for each character in the standard. Likewise, this
module doesn't provide any graphical support for Unicode, and will just deal
with textual memory representation and encodings.

Take a look at the \textbf{GtkAda} library that provides the graphical interface for
unicode in the upcoming 2.0 version.


\section{Repertoires and subsets}
\label{unicode:repertoires-and-subsets}
A repertoire is a set of abstract characters to be encoded, normally a familiar
alphabet or symbol set. For instance, the alphabet used to spell English words,
or the one used for the Russian alphabet are two such repertoires.

There exist two types of repertoires, close and open ones. The former is the
most common one, and the two examples above are such repertoires.  No character
is ever added to them.

Unicode is also a repertoire, but an open one. New entries are added to it.
However, it is guaranteed that none will ever be deleted from it.  Unicode
intends to be a universal repertoire, with all possible characters currently
used in the world. It currently contains all the alphabets, including a number
of alphabets associated with dead languages like hieroglyphs. It also contains
a number of often used symbols, like mathematical signs.

The goal of this Unicode module is to convert all characters to entries in the
Unicode repertoire, so that any applications can communicate with each other in
a portable manner.

Given its size, most applications will only support a subset of Unicode.  Some
of the scripts, most notably Arabic and Asian languages, require a special
support in the application (right-to-left writing,...), and thus will not be
supported by some applications.

The Unicode standard includes a set of internal catalogs, called collections.
Each character in these collections is given a special name, in addition to its
code, to improve readability.

Several child packages (\textbf{Unicode.Names.*}) define those names. For instance:
\begin{description}
\item[{\emph{Unicode.Names.Basic\_Latin}}] \leavevmode
This contains the basic characters used in most western European languages,
including the standard ASCII subset.

\item[{\emph{Unicode.Names.Cyrillic}}] \leavevmode
This contains the Russian alphabet.

\item[{\emph{Unicode.Names.Mathematical\_Operators}}] \leavevmode
This contains several mathematical symbols

\end{description}

More than 80 such packages exist.


\section{Character sets}
\label{unicode:character-sets}
A character set is a mapping from a set of abstract characters to some
non-negative integers. The integer associated with a character is called its
code point, and the character itself is called the encoded character.

There exist a number of standard character sets, unfortunately not compatible
with each other. For instance, ASCII is one of these character sets, and
contains 128 characters. A super-set of it is the ISO/8859-1 character set.
Another character set is the JIS X 0208, used to encode Japanese characters.

Note that a character set is different from a repertoire. For instance, the
same character C with cedilla doesn't have the same integer value in the
ISO/8859-1 character set and the ISO/8859-2 character set.

Unicode is also such a character set, that contains all the possible characters
and associate a standard integer with them. A similar and fully compatible
character set is ISO/10646. The only addition that Unicode does to ISO/10646 is
that it also specifies algorithms for rendering presentation forms of some
scripts (say Arabic), handling of bi-directional texts that mix for instance
Latin and Hebrew, algorithms for sorting and string comparison, and much more.

Currently, our Unicode package doesn't include any support for these
algorithms.

Unicode and ISO 10646 define formally a 31-bit character set. However, of this
huge code space, so far characters have been assigned only to the first 65534
positions (0x0000 to 0xFFFD). The characters that are expected to be encoded
outside the 16-bit range belong all to rather exotic scripts (e.g.,
Hieroglyphics) that are only used by specialists for historic and scientific
purposes

The Unicode module contains a set of packages to provide conversion from some
of the most common character sets to and from Unicode. These are the
\textbf{Unicode.CCS.*} packages.

All these packages have a common structure:
\begin{itemize}
\item {} 
They define a global variable of type \emph{Character\_Set} with two fields, ie the
two conversion functions between the given character set and Unicode.

These functions convert one character (actually its code point) at a time.

\item {} 
They also define a number of standard names associated with this character
set. For instance, the ISO/8859-1 set is also known as Latin1.

The function \emph{Unicode.CCS.Get\_Character\_Set} can be used to find a character
set by its standard name.

\end{itemize}

Currently, the following sets are supported:

\emph{ISO/8859-1 aka Latin1}
\begin{quote}

This is the standard character set used to represent most Western European
languages including: Albanian, Catalan, Danish, Dutch, English, Faroese,
Finnish, French, Galician, German, Irish, Icelandic, Italian, Norwegian,
Portuguese, Spanish and Swedish.
\end{quote}

\emph{ISO/8859-2 aka Latin2}
\begin{quote}

This character set supports the Slavic languages of Central Europe which use
the Latin alphabet. The ISO-8859-2 set is used for the following languages:
Czech, Croat, German, Hungarian, Polish, Romanian, Slovak and Slovenian.
\end{quote}

\emph{ISO/8859-3}
\begin{quote}

This character set is used for Esperanto, Galician, Maltese and Turkish
\end{quote}

\emph{ISO/8859-4}
\begin{quote}

Some letters were added to the ISO-8859-4 to support languages such as
Estonian, Latvian and Lithuanian. It is an incomplete precursor of the Latin
6 set.
\end{quote}


\section{Character encoding schemes}
\label{unicode:character-encoding-schemes}
We now know how each encoded character can be represented by an integer value
(code point) depending on the character set.

Character encoding schemes deal with the representation of a sequence of
integers to a sequence of code units. A code unit is a sequence of bytes on a
computer architecture.

There exists a number of possible encoding schemes. Some of them encode all
integers on the same number of bytes. They are called fixed-width encoding
forms, and include the standard encoding for Internet emails (\textbf{7bits}, but it
can't encode all characters), as well as the simple \textbf{8bits} scheme, or the
\textbf{EBCDIC} scheme. Among them is also the \textbf{UTF-32} scheme which is defined in
the Unicode standard.

Another set of encoding schemes encode integers on a variable number of bytes.
These include two schemes that are also defined in the Unicode standard, namely
\textbf{Utf-8} and \textbf{Utf-16}.

Unicode doesn't impose any specific encoding. However, it is most often
associated with one of the Utf encodings. They each have their own properties
and advantages:

\emph{Utf32}
\begin{quote}

This is the simplest of all these encodings. It simply encodes all the
characters on 32 bits (4 bytes). This encodes all the possible characters in
Unicode, and is obviously straightforward to manipulate. However, given that
the first 65535 characters in Unicode are enough to encode all known
languages currently in use, Utf32 is also a waste of space in most cases.
\end{quote}

\emph{Utf16}
\begin{quote}

For the above reason, Utf16 was defined. Most characters are only encoded on
two bytes (which is enough for the first 65535 and most current characters).
In addition, a number of special code points have been defined, known as
\emph{surrogate pairs}, that make the encoding of integers greater than 65535
possible. The integers are then encoded on four bytes.  As a result, Utf16 is
thus much more memory-efficient and requires less space than Utf32 to encode
sequences of characters. However, it is also more complex to decode.
\end{quote}

\emph{Utf8}
\begin{quote}

This is an even more space-efficient encoding, but is also more complex to
decode. More important, it is compatible with the most currently used simple
8bit encoding.

Utf8 has the following properties:
\begin{itemize}
\item {} 
Characters 0 to 127 (ASCII) are encoded simply as a single byte.
This means that files and strings which contain only 7-bit ASCII
characters have the same encoding under both ASCII and UTF-8.

\item {} 
Characters greater than 127 are encoded as a sequence of several
bytes, each of which has the most significant bit set. Therefore,
no ASCII byte can appear as part of any other character.

\item {} 
The first byte of a multibyte sequence that represents a non-ASCII
character is always in the range 0xC0 to 0xFD and it indicates how
many bytes follow for this character. All further bytes in a
multibyte sequence are in the range 0x80 to 0xBF. This allows easy
resynchronization and makes the encoding stateless and robust
against missing bytes.

\item {} 
UTF-8 encoded characters may theoretically be up to six bytes
long, however the first 16-bit characters are only up to three bytes
long.

\end{itemize}
\end{quote}

Note that the encodings above, except for Utf8, have two versions, depending on
the chosen byte order on the machine.

The Ada95 Unicode module provides a set of packages that provide an easy
conversion between all the encoding schemes, as well as basic manipulations of
these byte sequences. These are the \textbf{Unicode.CES.*} packages.  Currently,
four encoding schemes are supported, the three Utf schemes and the basic 8bit
encoding which corresponds to the standard Ada strings.

It also supports some routines to convert from one byte-order to another.

The following examples show a possible use of these packages:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
Converting a latin1 string coded on 8 bits to a Utf8 latin2 file
involves the following steps:

   Latin1 string  (bytes associated with code points in Latin1)
     \textbar{}    \PYGZdq{}use Unicode.CES.Basic\PYGZus{}8bit.To\PYGZus{}Utf32\PYGZdq{}
     v
   Utf32 latin1 string (contains code points in Latin1)
     \textbar{}    \PYGZdq{}Convert argument to To\PYGZus{}Utf32 should be
     v         Unicode.CCS.Iso\PYGZus{}8859\PYGZus{}1.Convert\PYGZdq{}
   Utf32 Unicode string (contains code points in Unicode)
     \textbar{}    \PYGZdq{}use Unicode.CES.Utf8.From\PYGZus{}Utf32\PYGZdq{}
     v
   Utf8 Unicode string (contains code points in Unicode)
     \textbar{}    \PYGZdq{}Convert argument to From\PYGZus{}Utf32 should be
     v         Unicode.CCS.Iso\PYGZus{}8859\PYGZus{}2.Convert\PYGZdq{}
   Utf8 Latin2 string (contains code points in Latin2)
\end{Verbatim}


\section{Unicode\_Encoding}
\label{unicode:unicode-encoding}
XML/Ada groups the two notions of character sets and encoding schemes into a
single type, \emph{Unicode.Encodings.Unicode\_Encoding}.

This package provides additional functions to manipulate these encodings, for
instance to retrieve them by the common name that is associated with them (for
instance ``utf-8'', ``iso-8859-15'',...), since very often the encoding scheme is
implicit. If you are speaking of utf-8 string, most people always assume you
also use the unicode character set. Likewise, if you are speaking of
``iso-8859-1'', most people will assume you string is encoded as 8 byte
characters.

The goal of the \emph{Unicode.Encodings} package is to make these implicit
associations more obvious.

It also provides one additional function \emph{Convert}, which can be used to
convert a sequence of bytes from one encoding to another. This is a convenience
function that you can use when for instance creating DOM trees directly through
Ada calls, since XML/Ada excepts all its strings to be in utf-8 by default.


\section{Misc. functions}
\label{unicode:misc-functions}
The package \textbf{Unicode} contains a series of \emph{Is\_*} functions, matching the
Unicode standard.

\emph{Is\_White\_Space}
\begin{quote}

Return True if the character argument is a space character, ie a space,
horizontal tab, line feed or carriage return.
\end{quote}

\emph{Is\_Letter}
\begin{quote}

Return True if the character argument is a letter. This includes the
standard English letters, as well as some less current cases defined in the
standard.
\end{quote}
\begin{description}
\item[{\emph{Is\_Base\_Char}}] \leavevmode
Return True if the character is a base character, ie a character whose
meaning can be modified with a combining character.

\item[{\emph{Is\_Digit}}] \leavevmode
Return True if the character is a digit (numeric character)

\item[{\emph{Is\_Combining\_Char}}] \leavevmode
Return True if the character is a combining character. Combining characters
are accents or other diacritical marks that are added to the previous
character.

The most important accented characters, like those used in the orthographies
of common languages, have codes of their own in Unicode to ensure backwards
compatibility with older character sets. Accented characters that have their
own code position, but could also be represented as a pair of another
character followed by a combining character, are known as precomposed
characters. Precomposed characters are available in Unicode for backwards
compatibility with older encodings such as ISO 8859 that had no combining
characters. The combining character mechanism allows to add accents and other
diacritical marks to any character

Note however that your application must provide specific support for
combining characters, at least if you want to represent them visually.

\item[{\emph{Is\_Extender}}] \leavevmode
True if Char is an extender character.

\item[{\emph{Is\_Ideographic}}] \leavevmode
True if Char is an ideographic character. This is defined only for
Asian languages.

\end{description}


\chapter{The Input module}
\label{input:the-input-module}\label{input::doc}\label{input:id1}
This module provides a set of packages with a common interface to access the
characters contained in a stream. Various implementations are provided to
access files and manipulate standard Ada strings.

A top-level tagged type is provided that must be extended for the various
streams. It is assumed that the pointer to the current character in the stream
can only go forward, and never backward. As a result, it is possible to
implement this package for sockets or other strings where it isn't even
possible to go backward. This also means that one doesn't have to provide
buffers in such cases, and thus that it is possible to provide memory-efficient
readers.

Two predefined readers are available, namely \emph{String\_Input} to read characters
from a standard Ada string, and \emph{File\_Input} to read characters from a standard
text file.

They all provide the following primite operations:

\emph{Open}
\begin{quote}

Although this operation isn't exactly overriden, since its parameters
depend on the type of stream you want to read from, it is nice to
use a standard name for this constructor.
\end{quote}
\begin{description}
\item[{\emph{Close}}] \leavevmode
This terminates the stream reader and free any associated memory. It
is no longer possible to read from the stream afterwards.

\item[{\emph{Next\_Char}}] \leavevmode
Return the next Unicode character in the stream. Note this character doesn't
have to be associated specifically with a single byte, but that it depends on
the encoding chosen for the stream (see the unicode module documentation for
more information).

The next time this function is called, it returns the following character
from the stream.

\item[{\emph{Eof}}] \leavevmode
This function should return True when the reader has already returned the
last character from the stream. Note that it is not guarantee that a second
call to Eof will also return True.

\end{description}

It is the responsability of this stream reader to correctly call the decoding
functions in the unicode module so as to return one single valid unicode
character. No further processing is done on the result of \emph{Next\_Char}. Note
that the standard \emph{File\_Input} and \emph{String\_Input} streams can automatically
detect the encoding to use for a file, based on a header read directly from the
file.

Based on the first four bytes of the stream (assuming this is valid XML), they
will automatically detect whether the file was encoded as Utf8, Utf16,... If
you are writing your own input streams, consider adding this automatic
detection as well.

However, it is always possible to override the default through a call to
\emph{Set\_Encoding}. This allows you to specify both the character set (Latin1, ...)
and the character encoding scheme (Utf8,...).

The user is also encouraged to set the identifiers for the stream they are
parsing, through calls to \emph{Set\_System\_Id} and \emph{Set\_Public\_Id}. These are used
when reporting error messages.


\chapter{The SAX module}
\label{sax:the-sax-module}\label{sax::doc}\label{sax:id1}

\section{Description}
\label{sax:description}
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).

The \textbf{Simple API for XML} 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.

Note that this module supports the second release of SAX (SAX2), that fully
supports namespaces as defined in the XML standard.

SAX can also be used in cases where a tree would not be the most efficient
representation for your 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.

With SAX, you register a number of callback routines that the parser will call
them when certain conditions occur.

This documentation is in no way a full documentation on SAX. Instead, you
should refer to the standard itself, available at \href{http://sax.sourceforge.net}{http://sax.sourceforge.net}.

Some of the more useful callbacks are \emph{Start\_Document}, \emph{End\_Document},
\emph{Start\_Element}, \emph{End\_Element}, \emph{Get\_Entity} and \emph{Characters}. Most of these
are quite self explanatory. The characters callback is called when characters
outside a tag are parsed.

Consider the following XML file:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{c+cp}{\PYGZlt{}?xml version=\PYGZdq{}1.0\PYGZdq{}?\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}body}\PYG{n+nt}{\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}h1}\PYG{n+nt}{\PYGZgt{}}Title\PYG{n+nt}{\PYGZlt{}/h1\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}/body\PYGZgt{}}
\end{Verbatim}

The following events would then be generated when this file is parsed:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
Start\PYGZus{}Document           Start parsing the file
Start\PYGZus{}Prefix\PYGZus{}Mapping     (handling of namespaces for \PYGZdq{}xml\PYGZdq{})
Start\PYGZus{}Prefix\PYGZus{}Mapping     Parameter is \PYGZdq{}xmlns\PYGZdq{}
Processing\PYGZus{}Instruction   Parameters are \PYGZdq{}xml\PYGZdq{} and \PYGZdq{}version=\PYGZdq{}1.0\PYGZdq{}\PYGZdq{}
Start\PYGZus{}Element            Parameter is \PYGZdq{}body\PYGZdq{}
Characters               Parameter is ASCII.LF \PYGZam{} \PYGZdq{}  \PYGZdq{}
Start\PYGZus{}Element            Parameter is \PYGZdq{}h1\PYGZdq{}
Characters               Parameter is \PYGZdq{}Title\PYGZdq{}
End\PYGZus{}Element              Parameter is \PYGZdq{}h1\PYGZdq{}
Characters               Parameter is ASCII.LF \PYGZam{} \PYGZdq{}  \PYGZdq{}
End\PYGZus{}Element              Parameter is \PYGZdq{}body\PYGZdq{}
End\PYGZus{}Prefix\PYGZus{}Mapping       Parameter is \PYGZdq{}xmlns\PYGZdq{}
End\PYGZus{}Prefix\PYGZus{}Mapping       Parameter is \PYGZdq{}xml\PYGZdq{}
End\PYGZus{}Document             End of parsing
\end{Verbatim}

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.


\section{Examples}
\label{sax:examples}
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.
\begin{itemize}
\item {} 
Using XML files as a database

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:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{n+nt}{\PYGZlt{}array}\PYG{n+nt}{\PYGZgt{}} \PYG{n+nt}{\PYGZlt{}value}\PYG{n+nt}{\PYGZgt{}}1\PYG{n+nt}{\PYGZlt{}/value\PYGZgt{}} \PYG{n+nt}{\PYGZlt{}value}\PYG{n+nt}{\PYGZgt{}}2\PYG{n+nt}{\PYGZlt{}/value\PYGZgt{}} ....\PYG{n+nt}{\PYGZlt{}/array\PYGZgt{}}
\end{Verbatim}

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.

This can be extended to much more complex cases that would map to Ada records
for instance.

\item {} 
Large repetitive XML files

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.

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.

\item {} 
Simple XML files

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.

\end{itemize}

However, there are also a number of drawbacks to using SAX:
\begin{itemize}
\item {} 
SAX parsers generally require you to write a little bit more code than the
DOM interface

\item {} 
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.

Note however that 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
DOM instead of SAX.

\end{itemize}


\section{The SAX parser}
\label{sax:the-sax-parser}
The basic type in the SAX module is the \textbf{SAX.Readers} package. It defines a
tagged type, called \emph{Reader}, that represents the SAX parser itself.

Several features are define in the SAX standard for the parsers. They indicate
which behavior can be expected from the parser. The package \emph{SAX.Readers}
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 \emph{Set\_Feature} and \emph{Get\_Feature} subprograms for how to
manipulate them.

The main primitive operation for the parser is \emph{Parse}. 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.

Several other primitive subprograms are defined for the parser, that are called
the \textbf{callbacks}. They get called automatically by the \emph{Parse} procedure when
some events are seen.

As a result, you should always override at least some of these subprograms to
get something done. The default implementation for these is to do nothing,
except for the error handler that raises Ada exceptions appropriately.

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.

Note that internally, all the strings are encoded with a unique character
encoding scheme, that is defined in the file \code{sax-encodings.ads}. 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
\code{sax-encodings.ads}.

The encoding used for the input stream is either automatically detected by the
stream itself ({\hyperref[input:the-input-module]{\emph{The Input module}}}), or by parsing the:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{c+cp}{\PYGZlt{}?xml version=\PYGZsq{}1.0\PYGZsq{} encoding=\PYGZsq{}UTF\PYGZhy{}8\PYGZsq{} ?\PYGZgt{}}
\end{Verbatim}

processing instruction at the beginning of the document. The list of supported
encodings is the same as for the Unicode module ({\hyperref[unicode:the-unicode-module]{\emph{The Unicode module}}}).


\section{The SAX handlers}
\label{sax:the-sax-handlers}
We do not intend to document the whole set of possible callbacks associated
with a SAX parser. These are all fully documented in the file
\code{sax-readers.ads}.

here is a list of the most frequently used callbacks, that you will probably
need to override in most of your applications.
\begin{description}
\item[{\emph{Start\_Document}}] \leavevmode
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.

\item[{\emph{End\_Document}}] \leavevmode
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.

\item[{\emph{Start\_Element}}] \leavevmode
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.

\item[{\emph{End\_Element}}] \leavevmode
This is the opposite of the previous callback, and will be called once per
element. Calls to \emph{Start\_Element} and \emph{End\_Element} 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.

\item[{\emph{Characters and Ignore\_Whitespace}}] \leavevmode
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 \emph{xml:space} was set to something else than \emph{preserve} for this
element.

\end{description}

You should compile and run the \code{testsax} executable found in this
module to visualize the SAX events that are generated for a given XML file.


\section{Using SAX}
\label{sax:using-sax}\label{sax:id2}
This section will guide you through the creation of a small SAX application.
This application will read an XML file, assumed to be a configuration file, and
setup some preferences according to the contents of the file.

The XML file is the following:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{c+cp}{\PYGZlt{}?xml version=\PYGZdq{}1.0\PYGZdq{} ?\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}preferences}\PYG{n+nt}{\PYGZgt{}}
   \PYG{n+nt}{\PYGZlt{}pref} \PYG{n+na}{name=}\PYG{l+s}{\PYGZdq{}pref1\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}Value1\PYG{n+nt}{\PYGZlt{}/pref\PYGZgt{}}
   \PYG{n+nt}{\PYGZlt{}pref} \PYG{n+na}{name=}\PYG{l+s}{\PYGZdq{}pref2\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}Value2\PYG{n+nt}{\PYGZlt{}/pref\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}/preferences\PYGZgt{}}
\end{Verbatim}

This is a very simple example which doesn't use namespaces, and has a very
limited nesting of nodes. However, that should help demonstrate the basics of
using SAX.


\subsection{Parsing the file}
\label{sax:parsing-the-file}
The first thing to do is to declare a parser, and parse the file. No callback
is put in place in this first version, and as a result nothing happens.

The main program is the following:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kn}{with} \PYG{n+nn}{Sax.Readers}\PYG{p}{;}        \PYG{k+kn}{use} \PYG{n+nn}{Sax.Readers}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Input\PYGZus{}Sources.File}\PYG{p}{;} \PYG{k+kn}{use} \PYG{n+nn}{Input\PYGZus{}Sources.File}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{SaxExample}\PYG{p}{;}         \PYG{k+kn}{use} \PYG{n+nn}{SaxExample}\PYG{p}{;}

\PYG{k+kd}{procedure} \PYG{n+nf}{SaxExample\PYGZus{}Main} \PYG{k+kr}{is}
   \PYG{n}{My\PYGZus{}Reader} \PYG{p}{:} \PYG{n}{SaxExample}\PYG{p}{.}\PYG{n}{Reader}\PYG{p}{;}
   \PYG{n}{Input}     \PYG{p}{:} \PYG{n}{File\PYGZus{}Input}\PYG{p}{;}
\PYG{k+kr}{begin}
   \PYG{n}{Set\PYGZus{}Public\PYGZus{}Id} \PYG{p}{(}\PYG{n}{Input}\PYG{p}{,} \PYG{l+s}{\PYGZdq{}Preferences file\PYGZdq{}}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Set\PYGZus{}System\PYGZus{}Id} \PYG{p}{(}\PYG{n}{Input}\PYG{p}{,} \PYG{l+s}{\PYGZdq{}pref.xml\PYGZdq{}}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Open} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}pref.xml\PYGZdq{}}\PYG{p}{,} \PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Set\PYGZus{}Feature} \PYG{p}{(}\PYG{n}{My\PYGZus{}Reader}\PYG{p}{,} \PYG{n}{Namespace\PYGZus{}Prefixes\PYGZus{}Feature}\PYG{p}{,} \PYG{k+kc}{False}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Set\PYGZus{}Feature} \PYG{p}{(}\PYG{n}{My\PYGZus{}Reader}\PYG{p}{,} \PYG{n}{Namespace\PYGZus{}Feature}\PYG{p}{,} \PYG{k+kc}{False}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Set\PYGZus{}Feature} \PYG{p}{(}\PYG{n}{My\PYGZus{}Reader}\PYG{p}{,} \PYG{n}{Validation\PYGZus{}Feature}\PYG{p}{,} \PYG{k+kc}{False}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Parse} \PYG{p}{(}\PYG{n}{My\PYGZus{}Reader}\PYG{p}{,} \PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Close} \PYG{p}{(}\PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}
\PYG{k+kr}{end} \PYG{n+nf}{SaxExample\PYGZus{}Main}\PYG{p}{;}
\end{Verbatim}

A separate package is provided that contain our implementation of an XML
parser:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kn}{with} \PYG{n+nn}{Sax.Readers}\PYG{p}{;}

\PYG{k+kd}{package} \PYG{n+nc}{SaxExample} \PYG{k+kr}{is}

   \PYG{k+kd}{type} \PYG{k+kt}{Reader} \PYG{k+kr}{is} \PYG{k+kr}{new} \PYG{n}{Sax}\PYG{p}{.}\PYG{n}{Readers}\PYG{p}{.}\PYG{n}{Reader} \PYG{k+kr}{with} \PYG{k+kr}{null record}\PYG{p}{;}

\PYG{k+kr}{end} \PYG{n+nf}{SaxExample}\PYG{p}{;}
\end{Verbatim}

There are two steps in setting up an XML parser:
\begin{itemize}
\item {} 
Create an input stream

This input stream is in charge of providing the XML input to the parser.
Several input streams are provided by XML/Ada, including the one we use in
this example to read the XML data from a file on the disk. The file is called
\code{pref.xml}.

It has two properties, that should generally be set: the public id will be
used by XML/Ada in its error message to reference locations in that file; the
system id should be the location of the file on the system. It is used to
resolve relative paths found in the XML document.

\item {} 
Setup the parser

The behavior of an XML parser can be changed in several ways by activating or
deactivating some features. In the example above, we have specified that the
XML document doesn't contain namespaces, and that we do not intend to
validate the XML file against a grammar.

\end{itemize}

Once the two steps above are done, we can simply call the procedure \emph{Parse} to
perform the actual parsing. Since we are using SAX, XML/Ada will call the
primitive operations of \emph{My\_Reader}, which, so far, are inherited form the
default ones provided by XML, and do nothing.


\subsection{Reacting to events}
\label{sax:reacting-to-events}
We are now going to enhance the example a little, and make it react to the
contents of the XML file.

We are only interested in two particular type of events, which are the opening
and closing of an XML tag, and finding the value of each preference.

The way to react to these events is to override some of the primitive
subprograms in the package \code{saxexample.ads} as follows:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kn}{with} \PYG{n+nn}{Sax.Readers}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Unicode.CES}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Sax.Attributes}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Ada.Strings.Unbounded}\PYG{p}{;} \PYG{k+kn}{use} \PYG{n+nn}{Ada.Strings.Unbounded}\PYG{p}{;}

\PYG{k+kd}{package} \PYG{n+nc}{SaxExample} \PYG{k+kr}{is}

   \PYG{k+kd}{type} \PYG{k+kt}{String\PYGZus{}Access} \PYG{k+kr}{is} \PYG{k+kr}{access} \PYG{k+kt}{String}\PYG{p}{;}

   \PYG{k+kd}{type} \PYG{k+kt}{Reader} \PYG{k+kr}{is} \PYG{k+kr}{new} \PYG{n}{Sax}\PYG{p}{.}\PYG{n}{Readers}\PYG{p}{.}\PYG{n}{Reader} \PYG{k+kr}{with} \PYG{k+kr}{record}
       \PYG{n}{Current\PYGZus{}Pref}  \PYG{p}{:} \PYG{n}{Unbounded\PYGZus{}String}\PYG{p}{;}
       \PYG{n}{Current\PYGZus{}Value} \PYG{p}{:} \PYG{n}{Unbounded\PYGZus{}String}\PYG{p}{;}
   \PYG{k+kr}{end record}\PYG{p}{;}

   \PYG{k+kd}{procedure} \PYG{n+nf}{Start\PYGZus{}Element}
     \PYG{p}{(}\PYG{n+nv}{Handler}       \PYG{p}{: }\PYG{n+nv}{in} \PYG{n+nv}{out} \PYG{n+nv}{Reader}\PYG{p}{;}
      \PYG{n+nv}{Namespace\PYGZus{}URI} \PYG{p}{: }\PYG{n+nv}{Unicode}\PYG{p}{.}\PYG{n+nv}{CES}\PYG{p}{.}\PYG{n+nv}{Byte\PYGZus{}Sequence} \PYG{p}{:=} \PYG{l+s}{\PYGZdq{}\PYGZdq{}}\PYG{p}{;}
      \PYG{n+nv}{Local\PYGZus{}Name}    \PYG{p}{: }\PYG{n+nv}{Unicode}\PYG{p}{.}\PYG{n+nv}{CES}\PYG{p}{.}\PYG{n+nv}{Byte\PYGZus{}Sequence} \PYG{p}{:=} \PYG{l+s}{\PYGZdq{}\PYGZdq{}}\PYG{p}{;}
      \PYG{n+nv}{Qname}         \PYG{p}{: }\PYG{n+nv}{Unicode}\PYG{p}{.}\PYG{n+nv}{CES}\PYG{p}{.}\PYG{n+nv}{Byte\PYGZus{}Sequence} \PYG{p}{:=} \PYG{l+s}{\PYGZdq{}\PYGZdq{}}\PYG{p}{;}
      \PYG{n+nv}{Atts}          \PYG{p}{: }\PYG{n+nv}{Sax}\PYG{p}{.}\PYG{n+nv}{Attributes}\PYG{p}{.}\PYG{n+nv}{Attributes}\PYG{p}{\PYGZsq{}}\PYG{n+na}{Class}\PYG{p}{)}\PYG{p}{;}

   \PYG{k+kd}{procedure} \PYG{n+nf}{End\PYGZus{}Element}
     \PYG{p}{(}\PYG{n+nv}{Handler} \PYG{p}{: }\PYG{n+nv}{in} \PYG{n+nv}{out} \PYG{n+nv}{Reader}\PYG{p}{;}
      \PYG{n+nv}{Namespace\PYGZus{}URI} \PYG{p}{: }\PYG{n+nv}{Unicode}\PYG{p}{.}\PYG{n+nv}{CES}\PYG{p}{.}\PYG{n+nv}{Byte\PYGZus{}Sequence} \PYG{p}{:=} \PYG{l+s}{\PYGZdq{}\PYGZdq{}}\PYG{p}{;}
      \PYG{n+nv}{Local\PYGZus{}Name}    \PYG{p}{: }\PYG{n+nv}{Unicode}\PYG{p}{.}\PYG{n+nv}{CES}\PYG{p}{.}\PYG{n+nv}{Byte\PYGZus{}Sequence} \PYG{p}{:=} \PYG{l+s}{\PYGZdq{}\PYGZdq{}}\PYG{p}{;}
      \PYG{n+nv}{Qname}         \PYG{p}{: }\PYG{n+nv}{Unicode}\PYG{p}{.}\PYG{n+nv}{CES}\PYG{p}{.}\PYG{n+nv}{Byte\PYGZus{}Sequence} \PYG{p}{:=} \PYG{l+s}{\PYGZdq{}\PYGZdq{}}\PYG{p}{)}\PYG{p}{;}

   \PYG{k+kd}{procedure} \PYG{n+nf}{Characters}
     \PYG{p}{(}\PYG{n+nv}{Handler} \PYG{p}{: }\PYG{n+nv}{in} \PYG{n+nv}{out} \PYG{n+nv}{Reader}\PYG{p}{;}
      \PYG{n+nv}{Ch}      \PYG{p}{: }\PYG{n+nv}{Unicode}\PYG{p}{.}\PYG{n+nv}{CES}\PYG{p}{.}\PYG{n+nv}{Byte\PYGZus{}Sequence}\PYG{p}{)}\PYG{p}{;}

\PYG{k+kr}{end} \PYG{n+nf}{SaxExample}\PYG{p}{;}
\end{Verbatim}

The primitive operations will be called automatically when the corresponding
events are detected in the XML file.

The implementation for these subprograms is detailed below.


\subsubsection{Start of XML tags}
\label{sax:start-of-xml-tags}
When an XML tag is started, we need to check whether it corresponds to the
definition of a preference value. If that is the case, we get the value of the
\emph{name} attribute, which specifies the name of a preference:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kn}{with} \PYG{n+nn}{Unicode.CES}\PYG{p}{;}    \PYG{k+kn}{use} \PYG{n+nn}{Unicode.CES}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Sax.Attributes}\PYG{p}{;} \PYG{k+kn}{use} \PYG{n+nn}{Sax.Attributes}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Ada.Text\PYGZus{}IO}\PYG{p}{;}    \PYG{k+kn}{use} \PYG{n+nn}{Ada.Text\PYGZus{}IO}\PYG{p}{;}

\PYG{k+kd}{package} \PYG{k+kd}{body} \PYG{n+nc}{SaxExample} \PYG{k+kr}{is}

   \PYG{k+kd}{procedure} \PYG{n+nf}{Start\PYGZus{}Element}
     \PYG{p}{(}\PYG{n+nv}{Handler}       \PYG{p}{: }\PYG{n+nv}{in} \PYG{n+nv}{out} \PYG{n+nv}{Reader}\PYG{p}{;}
      \PYG{n+nv}{Namespace\PYGZus{}URI} \PYG{p}{: }\PYG{n+nv}{Unicode}\PYG{p}{.}\PYG{n+nv}{CES}\PYG{p}{.}\PYG{n+nv}{Byte\PYGZus{}Sequence} \PYG{p}{:=} \PYG{l+s}{\PYGZdq{}\PYGZdq{}}\PYG{p}{;}
      \PYG{n+nv}{Local\PYGZus{}Name}    \PYG{p}{: }\PYG{n+nv}{Unicode}\PYG{p}{.}\PYG{n+nv}{CES}\PYG{p}{.}\PYG{n+nv}{Byte\PYGZus{}Sequence} \PYG{p}{:=} \PYG{l+s}{\PYGZdq{}\PYGZdq{}}\PYG{p}{;}
      \PYG{n+nv}{Qname}         \PYG{p}{: }\PYG{n+nv}{Unicode}\PYG{p}{.}\PYG{n+nv}{CES}\PYG{p}{.}\PYG{n+nv}{Byte\PYGZus{}Sequence} \PYG{p}{:=} \PYG{l+s}{\PYGZdq{}\PYGZdq{}}\PYG{p}{;}
      \PYG{n+nv}{Atts}          \PYG{p}{: }\PYG{n+nv}{Sax}\PYG{p}{.}\PYG{n+nv}{Attributes}\PYG{p}{.}\PYG{n+nv}{Attributes}\PYG{p}{\PYGZsq{}}\PYG{n+na}{Class}\PYG{p}{)}
   \PYG{k+kr}{is}
   \PYG{k+kr}{begin}
      \PYG{n}{Handler}\PYG{p}{.}\PYG{n}{Current\PYGZus{}Pref}  \PYG{p}{:=} \PYG{n}{Null\PYGZus{}Unbounded\PYGZus{}String}\PYG{p}{;}
      \PYG{n}{Handler}\PYG{p}{.}\PYG{n}{Current\PYGZus{}Value} \PYG{p}{:=} \PYG{n}{Null\PYGZus{}Unbounded\PYGZus{}String}\PYG{p}{;}

      \PYG{k+kr}{if} \PYG{n}{Local\PYGZus{}Name} \PYG{o}{=} \PYG{l+s}{\PYGZdq{}pref\PYGZdq{}} \PYG{k+kr}{then}
         \PYG{n}{Handler}\PYG{p}{.}\PYG{n}{Current\PYGZus{}Pref} \PYG{p}{:=}
           \PYG{n}{To\PYGZus{}Unbounded\PYGZus{}String} \PYG{p}{(}\PYG{n}{Get\PYGZus{}Value} \PYG{p}{(}\PYG{n}{Atts}\PYG{p}{,} \PYG{l+s}{\PYGZdq{}name\PYGZdq{}}\PYG{p}{)}\PYG{p}{)}\PYG{p}{;}
      \PYG{k+kr}{end} \PYG{k+kr}{if}\PYG{p}{;}
   \PYG{k+kr}{end} \PYG{n+nf}{Start\PYGZus{}Element}\PYG{p}{;}
\end{Verbatim}


\subsubsection{Characters}
\label{sax:characters}
XML/Ada will report the textual contents of an XML tag through one or more
calls to the \emph{Characters} primitive operation. An XML parser is free to
divide the contents into as many calls to \emph{Characters} as it needs, and
we must be prepared to handle this properly. Therefore, we concatenate the
characters with the current value:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kd}{procedure} \PYG{n+nf}{Characters}
  \PYG{p}{(}\PYG{n+nv}{Handler} \PYG{p}{: }\PYG{n+nv}{in} \PYG{n+nv}{out} \PYG{n+nv}{Reader}\PYG{p}{;}
   \PYG{n+nv}{Ch}      \PYG{p}{: }\PYG{n+nv}{Unicode}\PYG{p}{.}\PYG{n+nv}{CES}\PYG{p}{.}\PYG{n+nv}{Byte\PYGZus{}Sequence}\PYG{p}{)} \PYG{k+kr}{is}
\PYG{k+kr}{begin}
   \PYG{k+kr}{if} \PYG{n}{Handler}\PYG{p}{.}\PYG{n}{Current\PYGZus{}Pref} \PYG{o}{/}\PYG{o}{=} \PYG{n}{Null\PYGZus{}Unbounded\PYGZus{}String} \PYG{k+kr}{then}
      \PYG{n}{Handler}\PYG{p}{.}\PYG{n}{Current\PYGZus{}Value} \PYG{p}{:=} \PYG{n}{Handler}\PYG{p}{.}\PYG{n}{Current\PYGZus{}Value} \PYG{o}{\PYGZam{}} \PYG{n}{Ch}\PYG{p}{;}
   \PYG{k+kr}{end} \PYG{k+kr}{if}\PYG{p}{;}
\PYG{k+kr}{end} \PYG{n+nf}{Characters}\PYG{p}{;}
\end{Verbatim}


\subsubsection{End of tag}
\label{sax:end-of-tag}
Once we meet the end of a tag, we know there will be no more addition to
the value, and we can now set the value of the preference. In this example,
we simply display the value on the standard output:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kd}{procedure} \PYG{n+nf}{End\PYGZus{}Element}
  \PYG{p}{(}\PYG{n+nv}{Handler} \PYG{p}{: }\PYG{n+nv}{in} \PYG{n+nv}{out} \PYG{n+nv}{Reader}\PYG{p}{;}
   \PYG{n+nv}{Namespace\PYGZus{}URI} \PYG{p}{: }\PYG{n+nv}{Unicode}\PYG{p}{.}\PYG{n+nv}{CES}\PYG{p}{.}\PYG{n+nv}{Byte\PYGZus{}Sequence} \PYG{p}{:=} \PYG{l+s}{\PYGZdq{}\PYGZdq{}}\PYG{p}{;}
   \PYG{n+nv}{Local\PYGZus{}Name}    \PYG{p}{: }\PYG{n+nv}{Unicode}\PYG{p}{.}\PYG{n+nv}{CES}\PYG{p}{.}\PYG{n+nv}{Byte\PYGZus{}Sequence} \PYG{p}{:=} \PYG{l+s}{\PYGZdq{}\PYGZdq{}}\PYG{p}{;}
   \PYG{n+nv}{Qname}         \PYG{p}{: }\PYG{n+nv}{Unicode}\PYG{p}{.}\PYG{n+nv}{CES}\PYG{p}{.}\PYG{n+nv}{Byte\PYGZus{}Sequence} \PYG{p}{:=} \PYG{l+s}{\PYGZdq{}\PYGZdq{}}\PYG{p}{)}
\PYG{k+kr}{is}
\PYG{k+kr}{begin}
   \PYG{k+kr}{if} \PYG{n}{Local\PYGZus{}Name} \PYG{o}{=} \PYG{l+s}{\PYGZdq{}pref\PYGZdq{}} \PYG{k+kr}{then}
      \PYG{n}{Put\PYGZus{}Line} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}Value for \PYGZdq{}}\PYG{l+s}{\PYGZdq{}\PYGZdq{}} \PYG{o}{\PYGZam{}} \PYG{n}{To\PYGZus{}String} \PYG{p}{(}\PYG{n}{Handler}\PYG{p}{.}\PYG{n}{Current\PYGZus{}Pref}\PYG{p}{)}
                \PYG{o}{\PYGZam{}} \PYG{l+s}{\PYGZdq{}\PYGZdq{}}\PYG{l+s}{\PYGZdq{} is \PYGZdq{}} \PYG{o}{\PYGZam{}} \PYG{n}{To\PYGZus{}String} \PYG{p}{(}\PYG{n}{Handler}\PYG{p}{.}\PYG{n}{Current\PYGZus{}Value}\PYG{p}{)}\PYG{p}{)}\PYG{p}{;}
   \PYG{k+kr}{end} \PYG{k+kr}{if}\PYG{p}{;}
\PYG{k+kr}{end} \PYG{n+nf}{End\PYGZus{}Element}\PYG{p}{;}
\end{Verbatim}

In a real application, we would need to handle error cases in the XML file.
Thankfully, most of the work is already done by XML/Ada, and the errors will be
reported as calls to the primitive operation \emph{Fatal\_Error}, which by default
raises an exception.


\section{Understanding SAX error messages}
\label{sax:understanding-sax-error-messages}
XML/Ada error messages try to be as explicit as possible. They are not,
however, meant to be understood by someone who doesn't know XML.

In addition to the location of the error (line and column in the file),
they might contain one of the following abbreviations:
\begin{itemize}
\item {} 
\emph{{[}WF{]}}
.. index:: WF

This abbreviation indicates that the error message is related to a
well-formedness issue, as defined in the XML standard. Basically, the
structure of the XML document is invalid, for instance because an
open tag has never been closed. Some of the error messages also indicate
a more precise section in the XML standard.

\item {} 
\emph{{[}VC{]}}
.. index:: VC
.. index:: DTD

This abbreviation indicates that the error message is related to an
unsatisfied validity-constraint, as defined in the XML standard. The XML
document is well formed, although it doesn't match the semantic rules
that the grammar defines. For instance, if you are trying to validate an
XML document against a DTD, the document must contain a DTD that defines the
name of the root element.

\end{itemize}


\chapter{The DOM module}
\label{dom::doc}\label{dom:the-dom-module}\label{dom:id1}
DOM is another standard associated with XML, in which the XML stream is
represented as a tree in memory. This tree can be manipulated at will, to add
new nodes, remove existing nodes, change attributes,...

Since it contains the whole XML information, it can then in turn be dump to a
stream.

As an example, most modern web browsers provide a DOM interface to the document
currently loaded in the browser. Using javascript, one can thus modify
dynamically the document. The calls to do so are similar to the ones provided
by XML/Ada for manipulating a DOM tree, and all are defined in the DOM
standard.

The W3C commitee (\href{http://www.w3c.org}{http://www.w3c.org}) has defined
several version of the DOM, each building on the previous one and adding
several enhancements.

XML/Ada currently supports the second revision of DOM (DOM 2.0), which mostly
adds namespaces over the first revision. The third revision is not supported at
this point, and it adds support for loading and saving XML streams in a
standardized fashion.

Although it doesn't support DOM 3.0, XML/Ada provides subprograms for doing
similar things.

Only the Core module of the DOM standard is currently implemented, other
modules will follow.

Note that the \code{encodings.ads} file specifies the encoding to use to store
the tree in memory. Full compatibility with the XML standard requires that this
be UTF16, however, it is generally much more memory-efficient for European
languages to use UTF8. You can freely change this and recompile.


\section{Using DOM}
\label{dom:using-dom}\label{dom:id2}
In XML/Ada, the DOM tree is build through a special implementation of a
SAX parser, provided in the \emph{DOM.Readers} package.

Using DOM to read an XML document is similar to using SAX: one must setup an
input stream, then parse the document and get the tree. This is done with a
code similar to the following:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kn}{with} \PYG{n+nn}{Input\PYGZus{}Sources.File}\PYG{p}{;} \PYG{k+kn}{use} \PYG{n+nn}{Input\PYGZus{}Sources.File}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Sax.Readers}\PYG{p}{;}        \PYG{k+kn}{use} \PYG{n+nn}{Sax.Readers}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{DOM.Readers}\PYG{p}{;}        \PYG{k+kn}{use} \PYG{n+nn}{DOM.Readers}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{DOM.Core}\PYG{p}{;}           \PYG{k+kn}{use} \PYG{n+nn}{DOM.Core}\PYG{p}{;}

\PYG{k+kd}{procedure} \PYG{n+nf}{DomExample} \PYG{k+kr}{is}
   \PYG{n}{Input}  \PYG{p}{:} \PYG{n}{File\PYGZus{}Input}\PYG{p}{;}
   \PYG{n}{Reader} \PYG{p}{:} \PYG{n}{Tree\PYGZus{}Reader}\PYG{p}{;}
   \PYG{n}{Doc}    \PYG{p}{:} \PYG{n}{Document}\PYG{p}{;}
\PYG{k+kr}{begin}
   \PYG{n}{Set\PYGZus{}Public\PYGZus{}Id} \PYG{p}{(}\PYG{n}{Input}\PYG{p}{,} \PYG{l+s}{\PYGZdq{}Preferences file\PYGZdq{}}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Open} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}pref.xml\PYGZdq{}}\PYG{p}{,} \PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Set\PYGZus{}Feature} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{,} \PYG{n}{Validation\PYGZus{}Feature}\PYG{p}{,} \PYG{k+kc}{False}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Set\PYGZus{}Feature} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{,} \PYG{n}{Namespace\PYGZus{}Feature}\PYG{p}{,} \PYG{k+kc}{False}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Parse} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{,} \PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Close} \PYG{p}{(}\PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Doc} \PYG{p}{:=} \PYG{n}{Get\PYGZus{}Tree} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{)}\PYG{p}{;} 

   \PYG{n}{Free} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{)}\PYG{p}{;}
\PYG{k+kr}{end} \PYG{n+nf}{DomExample}\PYG{p}{;}
\end{Verbatim}

This code is almost exactly the same as the code that was used when
demonstrating the use of SAX ({\hyperref[sax:using-sax]{\emph{Using SAX}}}).

The main two differences are:
\begin{itemize}
\item {} 
We no longer need to define our own XML reader, and we simply use the
one provided in \emph{DOM.Readers}.

\item {} 
We therefore do not add our own callbacks to react to the XML events.
Instead, the last instruction of the program gets a handle on the tree that
was created in memory.

\end{itemize}

The tree can now be manipulated to get access to the value stored.
If we want to implement the same thing we did for SAX, the code would look
like:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kn}{with} \PYG{n+nn}{Input\PYGZus{}Sources.File}\PYG{p}{;} \PYG{k+kn}{use} \PYG{n+nn}{Input\PYGZus{}Sources.File}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Sax.Readers}\PYG{p}{;}        \PYG{k+kn}{use} \PYG{n+nn}{Sax.Readers}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{DOM.Readers}\PYG{p}{;}        \PYG{k+kn}{use} \PYG{n+nn}{DOM.Readers}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{DOM.Core}\PYG{p}{;}           \PYG{k+kn}{use} \PYG{n+nn}{DOM.Core}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{DOM.Core.Documents}\PYG{p}{;} \PYG{k+kn}{use} \PYG{n+nn}{DOM.Core.Documents}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{DOM.Core.Nodes}\PYG{p}{;}     \PYG{k+kn}{use} \PYG{n+nn}{DOM.Core.Nodes}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{DOM.Core.Attrs}\PYG{p}{;}     \PYG{k+kn}{use} \PYG{n+nn}{DOM.Core.Attrs}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Ada.Text\PYGZus{}IO}\PYG{p}{;}        \PYG{k+kn}{use} \PYG{n+nn}{Ada.Text\PYGZus{}IO}\PYG{p}{;}

\PYG{k+kd}{procedure} \PYG{n+nf}{DomExample2} \PYG{k+kr}{is}
   \PYG{n}{Input}  \PYG{p}{:} \PYG{n}{File\PYGZus{}Input}\PYG{p}{;}
   \PYG{n}{Reader} \PYG{p}{:} \PYG{n}{Tree\PYGZus{}Reader}\PYG{p}{;}
   \PYG{n}{Doc}    \PYG{p}{:} \PYG{n}{Document}\PYG{p}{;}
   \PYG{n}{List}   \PYG{p}{:} \PYG{n}{Node\PYGZus{}List}\PYG{p}{;}
   \PYG{n}{N}      \PYG{p}{:} \PYG{n}{Node}\PYG{p}{;}
   \PYG{n}{A}      \PYG{p}{:} \PYG{n}{Attr}\PYG{p}{;}
\PYG{k+kr}{begin}
   \PYG{n}{Set\PYGZus{}Public\PYGZus{}Id} \PYG{p}{(}\PYG{n}{Input}\PYG{p}{,} \PYG{l+s}{\PYGZdq{}Preferences file\PYGZdq{}}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Open} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}pref.xml\PYGZdq{}}\PYG{p}{,} \PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Set\PYGZus{}Feature} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{,} \PYG{n}{Validation\PYGZus{}Feature}\PYG{p}{,} \PYG{k+kc}{False}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Set\PYGZus{}Feature} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{,} \PYG{n}{Namespace\PYGZus{}Feature}\PYG{p}{,} \PYG{k+kc}{False}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Parse} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{,} \PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Close} \PYG{p}{(}\PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Doc} \PYG{p}{:=} \PYG{n}{Get\PYGZus{}Tree} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{)}\PYG{p}{;} 

   \PYG{n}{List} \PYG{p}{:=} \PYG{n}{Get\PYGZus{}Elements\PYGZus{}By\PYGZus{}Tag\PYGZus{}Name} \PYG{p}{(}\PYG{n}{Doc}\PYG{p}{,} \PYG{l+s}{\PYGZdq{}pref\PYGZdq{}}\PYG{p}{)}\PYG{p}{;}

   \PYG{k+kr}{for} \PYG{n}{Index} \PYG{o+ow}{in} \PYG{l+m+mi}{1} \PYG{p}{.}\PYG{p}{.} \PYG{n}{Length} \PYG{p}{(}\PYG{n}{List}\PYG{p}{)} \PYG{k+kr}{loop}
       \PYG{n}{N} \PYG{p}{:=} \PYG{n}{Item} \PYG{p}{(}\PYG{n}{List}\PYG{p}{,} \PYG{n}{Index} \PYG{o}{\PYGZhy{}} \PYG{l+m+mi}{1}\PYG{p}{)}\PYG{p}{;}
       \PYG{n}{A} \PYG{p}{:=} \PYG{n}{Get\PYGZus{}Named\PYGZus{}Item} \PYG{p}{(}\PYG{n}{Attributes} \PYG{p}{(}\PYG{n}{N}\PYG{p}{)}\PYG{p}{,} \PYG{l+s}{\PYGZdq{}name\PYGZdq{}}\PYG{p}{)}\PYG{p}{;}
       \PYG{n}{Put\PYGZus{}Line} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}Value of \PYGZdq{}}\PYG{l+s}{\PYGZdq{}\PYGZdq{}} \PYG{o}{\PYGZam{}} \PYG{n}{Value} \PYG{p}{(}\PYG{n}{A}\PYG{p}{)} \PYG{o}{\PYGZam{}} \PYG{l+s}{\PYGZdq{}\PYGZdq{}}\PYG{l+s}{\PYGZdq{} is \PYGZdq{}}
                 \PYG{o}{\PYGZam{}} \PYG{n}{Node\PYGZus{}Value} \PYG{p}{(}\PYG{n}{First\PYGZus{}Child} \PYG{p}{(}\PYG{n}{N}\PYG{p}{)}\PYG{p}{)}\PYG{p}{)}\PYG{p}{;}
   \PYG{k+kr}{end} \PYG{k+kr}{loop}\PYG{p}{;} 

   \PYG{n}{Free} \PYG{p}{(}\PYG{n}{List}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Free} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{)}\PYG{p}{;}
\PYG{k+kr}{end} \PYG{n+nf}{DomExample2}\PYG{p}{;}
\end{Verbatim}

The code is much simpler than with SAX, since most of the work is done
internally by XML/Ada. In particular, for SAX we had to take into account the
fact that the textual contents of a node could be reported in several events.
For DOM, the tree is initially normalized, ie all text nodes are collapsed
together when possible.

This added simplicity has one drawback, which is the amount of memory required
to represent even a simple tree.

XML/Ada optimizes the memory necessary to represent a tree by sharing the
strings as much as possible (this is under control of constants at the
beginning of \code{dom-core.ads}). Still, DOM requires a significant amount of
information to be kept for each node.

For really big XML streams, it might prove impossible to keep the whole tree in
memory, in which case ad hoc storage might be implemented through the use of a
SAX parser. The implementation of \emph{dom-readers.adb} will prove helpful in
creating such a parser.


\section{Editing DOM trees}
\label{dom:editing-dom-trees}
Once in memory, DOM trees can be manipulated through subprograms provides by
the DOM API.

Each of these subprograms is fully documented both in the Ada specs (the
\code{*.ads} files) and in the DOM standard itself, which XML/Ada follows
fully.

One important note however is related to the use of strings. Various
subprograms allows you to set the textual content of a node, modify its
attributes,.... Such subprograms take a Byte\_Sequence as a parameter.

This Byte\_Sequence must always be encoded in the encoding defined in the
package \emph{Sax.Encoding} (as described earlier, changing this package requires
recompiling XML/Ada). By default, this is UTF-8.

Therefore, if you need to set an attribute to a string encoded for
instance in iso-8859-15, you should use the subprogram
\emph{Unicode.Encodings.Convert} to convert it appropriately.
The code would thus look as follows:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{n}{Set\PYGZus{}Attribute} \PYG{p}{(}\PYG{n}{N}\PYG{p}{,} \PYG{n}{Convert} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}å\PYGZdq{}}\PYG{p}{,} \PYG{n}{From} \PYG{p}{=\PYGZgt{}} \PYG{n}{Get\PYGZus{}By\PYGZus{}Name} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}iso\PYGZhy{}8859\PYGZhy{}15\PYGZdq{}}\PYG{p}{)}\PYG{p}{)}\PYG{p}{)}\PYG{p}{;}
\end{Verbatim}


\section{Printing DOM tress}
\label{dom:printing-dom-tress}
The standard DOM 2.0 does not define a common way to read DOM trees from
input sources, nor how to write them back to output sources. This was
added in later revision of the standard (DOM 3.0), which is not yet
supported by XML/Ada.

However, the package \code{DOM.Core.Nodes} provides a \emph{Write}
procedure that can be used for that purpose. It outputs a given DOM tree
to an Ada stream. This stream can then be connected to a standard file
on the disk, to a socket, or be used to transform the tree into a string
in memory.

An example is provided in the XML/Ada distribution, called
\code{dom/test/tostring.adb} which shows how you can create a stream to
convert the tree in memory, without going through a file on the disk


\section{Adding information to the tree}
\label{dom:adding-information-to-the-tree}
The DOM standard does not mandate each node to have a pointer to the
location it was read from (for instance \emph{file:line:column}). In fact,
storing that for each node would increase the size of the DOM tree
(not small by any means already) significantly.

But depending on your application, this might be a useful information
to have, for instance if you want to report error messages with a
correct location.

Fortunately, this can be done relatively easily by extending the
type \emph{DOM.Readers.Tree\_Reader}, and override the \emph{Start\_Element}.
You would then add a custom attribute to all the nodes that contain
the location for this node. Here is an example.

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kn}{with} \PYG{n+nn}{DOM.Readers}\PYG{p}{;}       \PYG{k+kn}{use} \PYG{n+nn}{DOM.Readers}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Sax.Utils}\PYG{p}{;}         \PYG{k+kn}{use} \PYG{n+nn}{Sax.Utils}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Sax.Readers}\PYG{p}{;}       \PYG{k+kn}{use} \PYG{n+nn}{Sax.Readers}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Sax.Symbols}\PYG{p}{;}       \PYG{k+kn}{use} \PYG{n+nn}{Sax.Symbols}\PYG{p}{;}

\PYG{k+kd}{package} \PYG{n+nc}{DOM\PYGZus{}With\PYGZus{}Location} \PYG{k+kr}{is}

   \PYG{k+kd}{type} \PYG{k+kt}{Tree\PYGZus{}Reader\PYGZus{}With\PYGZus{}Location} \PYG{k+kr}{is} \PYG{k+kr}{new} \PYG{n}{Tree\PYGZus{}Reader} \PYG{k+kr}{with} \PYG{k+kr}{null record}\PYG{p}{;}
   \PYG{k+kr}{overriding} \PYG{k+kd}{procedure} \PYG{n+nf}{Start\PYGZus{}Element}
      \PYG{p}{(}\PYG{n+nv}{Handler}     \PYG{p}{: }\PYG{n+nv}{in} \PYG{n+nv}{out} \PYG{n+nv}{Tree\PYGZus{}Reader\PYGZus{}With\PYGZus{}Location}\PYG{p}{;}
       \PYG{n+nv}{NS}          \PYG{p}{: }\PYG{n+nv}{Sax}\PYG{p}{.}\PYG{n+nv}{Utils}\PYG{p}{.}\PYG{n+nv}{XML\PYGZus{}NS}\PYG{p}{;}
       \PYG{n+nv}{Local\PYGZus{}Name}  \PYG{p}{: }\PYG{n+nv}{Sax}\PYG{p}{.}\PYG{n+nv}{Symbols}\PYG{p}{.}\PYG{n+nv}{Symbol}\PYG{p}{;}
       \PYG{n+nv}{Atts}        \PYG{p}{: }\PYG{n+nv}{Sax}\PYG{p}{.}\PYG{n+nv}{Readers}\PYG{p}{.}\PYG{n+nv}{Sax\PYGZus{}Attribute\PYGZus{}List}\PYG{p}{)}\PYG{p}{;}

\PYG{k+kr}{end} \PYG{n+nf}{DOM\PYGZus{}With\PYGZus{}Location}\PYG{p}{;}
\end{Verbatim}

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kn}{with} \PYG{n+nn}{DOM.Core}\PYG{p}{;}            \PYG{k+kn}{use} \PYG{n+nn}{DOM.Core}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{DOM.Core.Attrs}\PYG{p}{;}      \PYG{k+kn}{use} \PYG{n+nn}{DOM.Core.Attrs}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{DOM.Core.Documents}\PYG{p}{;}  \PYG{k+kn}{use} \PYG{n+nn}{DOM.Core.Documents}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{DOM.Core.Elements}\PYG{p}{;}   \PYG{k+kn}{use} \PYG{n+nn}{DOM.Core.Elements}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Sax.Locators}\PYG{p}{;}        \PYG{k+kn}{use} \PYG{n+nn}{Sax.Locators}\PYG{p}{;}

\PYG{k+kd}{package} \PYG{k+kd}{body} \PYG{n+nc}{DOM\PYGZus{}With\PYGZus{}Location} \PYG{k+kr}{is}

   \PYG{k+kr}{overriding} \PYG{k+kd}{procedure} \PYG{n+nf}{Start\PYGZus{}Element}
      \PYG{p}{(}\PYG{n+nv}{Handler}     \PYG{p}{: }\PYG{n+nv}{in} \PYG{n+nv}{out} \PYG{n+nv}{Tree\PYGZus{}Reader\PYGZus{}With\PYGZus{}Location}\PYG{p}{;}
       \PYG{n+nv}{NS}          \PYG{p}{: }\PYG{n+nv}{Sax}\PYG{p}{.}\PYG{n+nv}{Utils}\PYG{p}{.}\PYG{n+nv}{XML\PYGZus{}NS}\PYG{p}{;}
       \PYG{n+nv}{Local\PYGZus{}Name}  \PYG{p}{: }\PYG{n+nv}{Sax}\PYG{p}{.}\PYG{n+nv}{Symbols}\PYG{p}{.}\PYG{n+nv}{Symbol}\PYG{p}{;}
       \PYG{n+nv}{Atts}        \PYG{p}{: }\PYG{n+nv}{Sax\PYGZus{}Attribute\PYGZus{}List}\PYG{p}{)}
   \PYG{k+kr}{is}
      \PYG{n}{Att}\PYG{p}{,} \PYG{n}{Att2} \PYG{p}{:} \PYG{n}{Attr}\PYG{p}{;}
   \PYG{k+kr}{begin}
      \PYG{c+c1}{\PYGZhy{}\PYGZhy{}  First create the node as usual}
      \PYG{n}{Start\PYGZus{}Element} \PYG{p}{(}\PYG{n}{Tree\PYGZus{}Reader} \PYG{p}{(}\PYG{n}{Handler}\PYG{p}{)}\PYG{p}{,} \PYG{n}{NS}\PYG{p}{,} \PYG{n}{Local\PYGZus{}Name}\PYG{p}{,} \PYG{n}{Atts}\PYG{p}{)}\PYG{p}{;}

      \PYG{c+c1}{\PYGZhy{}\PYGZhy{}  Then add the new attribute}
      \PYG{n}{Att} \PYG{p}{:=} \PYG{n}{Create\PYGZus{}Attribute\PYGZus{}NS}
         \PYG{p}{(}\PYG{n}{Get\PYGZus{}Tree} \PYG{p}{(}\PYG{n}{Handler}\PYG{p}{)}\PYG{p}{,}
          \PYG{n}{Namespace\PYGZus{}URI}  \PYG{p}{=\PYGZgt{}} \PYG{l+s}{\PYGZdq{}http://mydomain.com\PYGZdq{}}\PYG{p}{,}
          \PYG{n}{Qualified\PYGZus{}Name} \PYG{p}{=\PYGZgt{}} \PYG{l+s}{\PYGZdq{}mydomain:location\PYGZdq{}}\PYG{p}{)}\PYG{p}{;}
      \PYG{n}{Set\PYGZus{}Value} \PYG{p}{(}\PYG{n}{Att}\PYG{p}{,} \PYG{n}{To\PYGZus{}String} \PYG{p}{(}\PYG{n}{Current\PYGZus{}Location} \PYG{p}{(}\PYG{n}{Handler}\PYG{p}{)}\PYG{p}{)}\PYG{p}{)}\PYG{p}{;}

      \PYG{n}{Att2} \PYG{p}{:=} \PYG{n}{Set\PYGZus{}Attribute\PYGZus{}Node} \PYG{p}{(}\PYG{n}{Handler}\PYG{p}{.}\PYG{n}{Current\PYGZus{}Node}\PYG{p}{,} \PYG{n}{Att}\PYG{p}{)}\PYG{p}{;}
   \PYG{k+kr}{end} \PYG{n+nf}{Start\PYGZus{}Element}\PYG{p}{;}

\PYG{k+kr}{end} \PYG{n+nf}{DOM\PYGZus{}With\PYGZus{}Location}\PYG{p}{;}
\end{Verbatim}


\chapter{The Schema module}
\label{schema:the-schema-module}\label{schema::doc}\label{schema:id1}

\section{XML Grammars}
\label{schema:xml-grammars}
There are several steps that applications must go through when they have to use
XML files:
\begin{itemize}
\item {} 
Make sure the XML file is well-formed.

This is a basic step where we ensure that XML tags are correctly nested, that
closing tags have the same names as the matching opening tags, that attribute
values are quoted,.... This corresponds to a syntactic parser in a compiler.

This step does not depend on the application domain. One file that is
well-formed will always be so, no matter in what context you use it.

\item {} 
Make sure the contents of the XML file is semantically valid.

Depending on the application domain, we must ensure that the content of the
file makes sense. This step is highly application dependent, and a file that
is usable in one application might not be usable in another one.

This is the phase in which the application needs to check whether a given XML
file has all its required attributes, whether the children of an XML tag are
the expected ones, whether the type of the attributes is valid,....

\item {} 
Use the XML file in the application.

This is done through the already-described SAX or DOM parsers

\end{itemize}

The first phase is mandatory, and necessarily enforced by XML/Ada. You will not
be able to access the contents of the XML file if it isn't well-formed.

The second phase is provided by the Schema module in XML/Ada. Although such
constraints can be checked at the application level, with ad hoc code, it is
generally easier to maintain a separate file that describes the valid semantic
contents of the file, that maintain specific code when the semantic changes. It
is also difficult not to forget special cases when doing the validating through
a set of \emph{if} statements in the Ada core.

XML provides two ways to describe additional constraints that a file must
satisfy in order to be considered as valid.
\begin{itemize}
\item {} 
DTD

The Document Type Description is the original way to do this. They come
directly from the ancestor of XML, SGML. All XML parsers must parse the DTD,
and report events if the user is using SAX. However, not all parsers are able
to validate the document against a DTD (XML/Ada doesn't).

Their use tend to greatly diminish. Among their limitation are a limit
capability to express constraints on the order of tag children, the fact they
the DTD themselves are written in a separate language totally different from
XML, and that users must learn as a result.

\item {} 
XML Schema

The XML schemas are replacing the DTDs. They are written in XML, and provide
an extensive capability to describe what the XML document should look like.
In fact, almost all Ada types can be described in an XML schema, including
range constraints, arrays, records, type inheritance, abstract types,....

It is for instance possible to indicate that the value of a preference, in
our example, must be a string of length 6. Any other length will result in a
validation error.

\end{itemize}


\section{XML Schema Syntax}
\label{schema:xml-schema-syntax}
The Schema modules provides subprograms and types to parse an XML schema and
validate an XML document with this schema.

This document does not provide a full documentation on the format of XML
Schemas. This is extensive, has several obscure features, which, although
supported by XML/Ada, are of little use in most pratical uses. We refer the
reader to the first part of the XML Schema specification, which is designed as
a tutorial (\href{http://www.w3.org/TR/xmlschema-0/}{http://www.w3.org/TR/xmlschema-0/}).

The typical extension for a schema file is \code{.xsd}.

A schema file must be a valid XML file, and thus start with the usual \emph{\textless{}?xml
version=''1.0'' ?\textgreater{}} line. The root node must be named \emph{schema}, and belong to the
namespace (\href{http://www.w3.org/2001/XMLSchema/}{http://www.w3.org/2001/XMLSchema/}). The handling of namespaces is fairly
powerful, but also complex. A given XML document might have nodes belonging to
several namespaces, and thus several schema files might have to be loaded, each
defining one of the namespaces.

In the following simple example, we will not define our schema for a specific
namespace, and thus no special attribute is needed for the root node.  Thus,
our document will be organized as:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{c+cp}{\PYGZlt{}?xml version=\PYGZdq{}1.0\PYGZdq{} ?\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}xsd:schema} \PYG{n+na}{xmlns:xsd=}\PYG{l+s}{\PYGZdq{}http://www.w3.org/2001/XMLSchema\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
    ... rest of the description goes here ...
\PYG{n+nt}{\PYGZlt{}/xsd:schema\PYGZgt{}}
\end{Verbatim}

An XML schema does not enforce a specific root node in the XML documents it
validates. However, it must define all the valid elements that can be used in
the XML file. This is done through the \emph{\textless{}element\textgreater{}} tag, which takes
one mandatory attribute, the name of the element we are defining.

The contents of the element is then defined in one of two ways:
\begin{itemize}
\item {} 
Through a \emph{type} attribute.

Schemas come with a number of predefined simple types. A simple type is
such that an element of that type accepts no child node, and that its
contents must satisfy additional constraints (be an integer, a date,
...).

Among the predefined simple type (which are all defined in the namespace
\href{http://www.w3.org/2001/XMLSchema/}{http://www.w3.org/2001/XMLSchema/}),
one can find: \emph{string}, \emph{integer}, \emph{byte}, \emph{date}, \emph{time}, \emph{dateTime},
\emph{boolean},...

If no additional constraint should be enforced on this simple type when
applied to the element, the type of the element is given through a \emph{type}
attribute, as in:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{n+nt}{\PYGZlt{}xsd:element} \PYG{n+na}{name=}\PYG{l+s}{\PYGZdq{}tag1\PYGZdq{}} \PYG{n+na}{type=}\PYG{l+s}{\PYGZdq{}xsd:string\PYGZdq{}}  \PYG{n+nt}{/\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}xsd:element} \PYG{n+na}{name=}\PYG{l+s}{\PYGZdq{}tag2\PYGZdq{}} \PYG{n+na}{type=}\PYG{l+s}{\PYGZdq{}xsd:boolean\PYGZdq{}} \PYG{n+nt}{/\PYGZgt{}}
\end{Verbatim}

which would accept the following XML files:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{n+nt}{\PYGZlt{}tag1}\PYG{n+nt}{\PYGZgt{}}Any string is valid here\PYG{n+nt}{\PYGZlt{}/tag1\PYGZgt{}}
\end{Verbatim}

and:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{n+nt}{\PYGZlt{}tag2}\PYG{n+nt}{\PYGZgt{}}true\PYG{n+nt}{\PYGZlt{}/tag2\PYGZgt{}}
\end{Verbatim}

but not:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{n+nt}{\PYGZlt{}tag2}\PYG{n+nt}{\PYGZgt{}}String\PYG{n+nt}{\PYGZlt{}/tag2\PYGZgt{}}
\end{Verbatim}

As will be described later, it is possible to create new types in XML schema,
which are created with a name. Such new types can also be associated with the
element through the \emph{type} attribute.

\item {} 
Through an inline type definition

If the element must accept child elements, or if a further constraint needs
to be enforced on the list of valid values, one must create the type. As
mentioned above, this can be done by creating a type separately and
referencing it by name, or through an inline type definition.

The syntax is mostly the same in both cases. Schemas distinguish between the
notion of simple types (that accept no child element) and complex types (that
accept child elements, and possibly text value).

To define a simple type, based on string, but that only allows a limited set
of value (similar to an Ada enumeration), one would create a restriction of
the standard string type, as in:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{n+nt}{\PYGZlt{}xsd:element} \PYG{n+na}{name=}\PYG{l+s}{\PYGZdq{}tag3\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
 \PYG{n+nt}{\PYGZlt{}xsd:simpleType}\PYG{n+nt}{\PYGZgt{}}
   \PYG{n+nt}{\PYGZlt{}xsd:restriction} \PYG{n+na}{base=}\PYG{l+s}{\PYGZdq{}xsd:string\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
     \PYG{n+nt}{\PYGZlt{}xsd:enumeration} \PYG{n+na}{value=}\PYG{l+s}{\PYGZdq{}value1\PYGZdq{}} \PYG{n+nt}{/\PYGZgt{}}
     \PYG{n+nt}{\PYGZlt{}xsd:enumeration} \PYG{n+na}{value=}\PYG{l+s}{\PYGZdq{}value2\PYGZdq{}} \PYG{n+nt}{/\PYGZgt{}}
   \PYG{n+nt}{\PYGZlt{}/xsd:restriction\PYGZgt{}}
 \PYG{n+nt}{\PYGZlt{}/xsd:simpleType\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}/xsd:element\PYGZgt{}}
\end{Verbatim}

Similarly, we could create an integer type whose valid range of values
is between 10 and 20, as in:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{n+nt}{\PYGZlt{}xsd:element} \PYG{n+na}{name=}\PYG{l+s}{\PYGZdq{}tag4\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
 \PYG{n+nt}{\PYGZlt{}xsd:simpleType}\PYG{n+nt}{\PYGZgt{}}
   \PYG{n+nt}{\PYGZlt{}xsd:restriction} \PYG{n+na}{base=}\PYG{l+s}{\PYGZdq{}xsd:byte\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
     \PYG{n+nt}{\PYGZlt{}xsd:minInclusive} \PYG{n+na}{value=}\PYG{l+s}{\PYGZdq{}10\PYGZdq{}} \PYG{n+nt}{/\PYGZgt{}}
     \PYG{n+nt}{\PYGZlt{}xsd:maxInclusive} \PYG{n+na}{value=}\PYG{l+s}{\PYGZdq{}20\PYGZdq{}} \PYG{n+nt}{/\PYGZgt{}}
   \PYG{n+nt}{\PYGZlt{}/xsd:restriction\PYGZgt{}}
 \PYG{n+nt}{\PYGZlt{}/xsd:simpleType\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}/xsd:element\PYGZgt{}}
\end{Verbatim}

Complex types allow elements to have child nodes, as well as attributes. The
list of valid attributes is created by a set of \emph{\textless{}xsd:attribute\textgreater{}} tags, and
the list of valid child nodes is generally defined either through a
\emph{\textless{}xsd:choice\textgreater{}} or a \emph{\textless{}xsd:sequence\textgreater{}} node (although it is possible to
indicate that any child node is authorized, among other things).

\emph{\textless{}xsd:choice\textgreater{}} indicate the children can appear in any order, whereas
\emph{\textless{}xsd:sequence\textgreater{}} enforces a specific order on children.

In both cases, extra attributes can be specified to indicate the number of
times the sequence or choice itself can be repeated, or that each child node
can appear.

For instance, we can indicate that \emph{tag5} accepts between 1 and 4 child
nodes, chosen among \emph{tag6} and \emph{tag7}, but that the latter, if
present, can only appear once. In addition, tag5 accepts one optional
attribute. Note that the type of tag6 and tag7 is here specified through a
\emph{type} attribute, although it could in turn be defined inline:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYGZlt{}xsd:element name=\PYGZdq{}tag5\PYGZdq{}\PYGZgt{}
  \PYGZlt{}xsd:complexType\PYGZgt{}
    \PYGZlt{}xsd:choice\PYGZgt{}
      \PYGZlt{}xsd:element name=\PYGZdq{}tag6\PYGZdq{} type=\PYGZdq{}xsd:string\PYGZdq{}
                   minOccurs=\PYGZdq{}1\PYGZdq{} maxOccurs=\PYGZdq{}3/\PYGZgt{}
      \PYGZlt{}xsd:element name=\PYGZdq{}tag7\PYGZdq{} type=\PYGZdq{}xsd:string\PYGZdq{} maxOccurs=\PYGZdq{}1\PYGZdq{} /\PYGZgt{}
    \PYGZlt{}/xsd:choice\PYGZgt{}
    \PYGZlt{}xsd:attribute name=\PYGZdq{}attr\PYGZdq{} type=\PYGZdq{}xsd:boolean\PYGZdq{} use=\PYGZdq{}optional\PYGZdq{} /\PYGZgt{}
  \PYGZlt{}/xsd:complexType\PYGZgt{}
\PYGZlt{}/xsd:element\PYGZgt{}
\end{Verbatim}

In the example above, if \emph{tag6} was defined elsewhere in the
schema, we could use a reference to it, instead of duplicating its
type definition, as in:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{n+nt}{\PYGZlt{}xsd:element} \PYG{n+na}{ref=}\PYG{l+s}{\PYGZdq{}tag6\PYGZdq{}} \PYG{n+nt}{/\PYGZgt{}}
\end{Verbatim}

If you need an element with no child element (just a string value),
but that accepts attributes, this also must be defined through a
complex type, as in:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{n+nt}{\PYGZlt{}xsd:element} \PYG{n+na}{name=}\PYG{l+s}{\PYGZdq{}tag8\PYGZdq{}} \PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}xsd:complexType}\PYG{n+nt}{\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}xsd:simpleContent}\PYG{n+nt}{\PYGZgt{}}
      \PYG{n+nt}{\PYGZlt{}xsd:extension} \PYG{n+na}{base=}\PYG{l+s}{\PYGZdq{}xsd:string\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
         \PYG{n+nt}{\PYGZlt{}xsd:attribute} \PYG{n+na}{name=}\PYG{l+s}{\PYGZdq{}attr\PYGZdq{}} \PYG{n+na}{type=}\PYG{l+s}{\PYGZdq{}xsd:boolean\PYGZdq{}} \PYG{n+nt}{/\PYGZgt{}}
      \PYG{n+nt}{\PYGZlt{}/xsd:extension\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}/xsd:simpleContent\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/xsd:complexType\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}/xsd:element\PYGZgt{}}
\end{Verbatim}

\end{itemize}

As mentioned before, instead of defining inline types, we could explicitly
declare them, and reference them in the element declaration later on:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{n+nt}{\PYGZlt{}xsd:simpleType} \PYG{n+na}{name=}\PYG{l+s}{\PYGZdq{}string\PYGZus{}of\PYGZus{}length\PYGZus{}10\PYGZdq{}}\PYG{n+nt}{\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}xsd:restriction} \PYG{n+na}{base=}\PYG{l+s}{\PYGZdq{}xsd:string\PYGZdq{}} \PYG{n+nt}{/\PYGZgt{}}
    \PYG{n+nt}{\PYGZlt{}xsd:length} \PYG{n+na}{value=}\PYG{l+s}{\PYGZdq{}10\PYGZdq{}}\PYG{n+nt}{/\PYGZgt{}}
  \PYG{n+nt}{\PYGZlt{}/xsd:restriction\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}/xsd:simpleType\PYGZgt{}}
\PYG{n+nt}{\PYGZlt{}xsd:element} \PYG{n+na}{name=}\PYG{l+s}{\PYGZdq{}tag9\PYGZdq{}} \PYG{n+na}{type=}\PYG{l+s}{\PYGZdq{}string\PYGZus{}of\PYGZus{}length\PYGZus{}10\PYGZdq{}} \PYG{n+nt}{/\PYGZgt{}}
\end{Verbatim}


\section{Connecting XML documents and schemas}
\label{schema:connecting-xml-documents-and-schemas}
There are several ways that XML/Ada uses to find what schema to use when
validating a file.
\begin{itemize}
\item {} 
Manually creating the grammar.

The schema module contains the package \emph{Schema.Validators} which
allows you to create a grammar by hand. It is very low-level, and it is
likely that you will never need to use it. It is used internally mostly,
and when creating the schema which is used to validate schema files
themselves.

\item {} 
Explicitly parsing a schema file

Parsing a schema file can be done through a call to parse for a reader
derived from \emph{Schema.Schema\_Readers.Schema\_reader}.  As usual, you
call \emph{Parse}, and pass it an input source. As output, you get
access to a grammar, that can then be given to another instance of a
\emph{Schema.Readers.Validating\_Reader}.

This technique will generally be used when you need to validate several
XML files with the same grammar: you parse the grammar only once, and
then reuse its instance, instead of reparsing the \code{.xsd} file every
time:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kn}{with} \PYG{n+nn}{Ada.Text\PYGZus{}IO}\PYG{p}{;}   \PYG{k+kn}{use} \PYG{n+nn}{Ada.Text\PYGZus{}IO}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Schema.Schema\PYGZus{}Readers}\PYG{p}{,} \PYG{n}{Schema}\PYG{p}{.}\PYG{n}{Validators}\PYG{p}{,} \PYG{n}{Input\PYGZus{}Sources}\PYG{p}{.}\PYG{n}{File}\PYG{p}{;}
\PYG{k+kn}{use}  \PYG{n+nn}{Schema.Schema\PYGZus{}Readers}\PYG{p}{,} \PYG{n}{Schema}\PYG{p}{.}\PYG{n}{Validators}\PYG{p}{,} \PYG{n}{Input\PYGZus{}Sources}\PYG{p}{.}\PYG{n}{File}\PYG{p}{;}

\PYG{k+kd}{procedure} \PYG{n+nf}{SchemaExample2} \PYG{k+kr}{is}
   \PYG{n}{Grammar} \PYG{p}{:} \PYG{n}{XML\PYGZus{}Grammar}\PYG{p}{;}
   \PYG{n}{Schema}  \PYG{p}{:} \PYG{n}{Schema\PYGZus{}Reader}\PYG{p}{;}
   \PYG{n}{Read}    \PYG{p}{:} \PYG{n}{File\PYGZus{}Input}\PYG{p}{;}
\PYG{k+kr}{begin}
   \PYG{n}{Open} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}file.xsd\PYGZdq{}}\PYG{p}{,} \PYG{n}{Read}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Parse} \PYG{p}{(}\PYG{n}{Schema}\PYG{p}{,} \PYG{n}{Read}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Close} \PYG{p}{(}\PYG{n}{Read}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Grammar} \PYG{p}{:=} \PYG{n}{Get\PYGZus{}Grammar} \PYG{p}{(}\PYG{n}{Schema}\PYG{p}{)}\PYG{p}{;}

 \PYG{k+kr}{exception}
    \PYG{k+kr}{when} \PYG{n}{XML\PYGZus{}Validation\PYGZus{}Error} \PYG{p}{\textbar{}} \PYG{n}{XML\PYGZus{}Not\PYGZus{}Implemented} \PYG{p}{=\PYGZgt{}}
       \PYG{n}{Put\PYGZus{}Line} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}ERROR: \PYGZdq{}} \PYG{o}{\PYGZam{}} \PYG{n}{Get\PYGZus{}Error\PYGZus{}Message} \PYG{p}{(}\PYG{n}{Schema}\PYG{p}{)}\PYG{p}{)}\PYG{p}{;}
\PYG{k+kr}{end} \PYG{n+nf}{SchemaExample2}\PYG{p}{;}
\end{Verbatim}

In the example above, the schema file itself is validated against the
official schema for schema files.

The resulting grammar object is in fact a collection of parsed schema
files, each associated with its own namespace. It can be kept as long as
you need it in your application. Memory will automatically be reclaimed
when no longer needed.

Every time you parse an XML file later on, you must associated the
Grammar with the parser:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kr}{declare}
   \PYG{n}{Read}      \PYG{p}{:} \PYG{n}{File\PYGZus{}Input}\PYG{p}{;}
   \PYG{n}{My\PYGZus{}Reader} \PYG{p}{:} \PYG{n}{Validating\PYGZus{}Reader}\PYG{p}{;}
\PYG{k+kr}{begin}
   \PYG{n}{Set\PYGZus{}Grammar} \PYG{p}{(}\PYG{n}{My\PYGZus{}Reader}\PYG{p}{,} \PYG{n}{Grammar}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Set\PYGZus{}Feature} \PYG{p}{(}\PYG{n}{My\PYGZus{}Reader}\PYG{p}{,} \PYG{n}{Schema\PYGZus{}Validation\PYGZus{}Feature}\PYG{p}{,} \PYG{k+kc}{True}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Open} \PYG{p}{(}\PYG{n}{Xml\PYGZus{}File}\PYG{p}{.}\PYG{k+kr}{all}\PYG{p}{,} \PYG{n}{Read}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Parse} \PYG{p}{(}\PYG{n}{My\PYGZus{}Reader}\PYG{p}{,} \PYG{n}{Read}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Close} \PYG{p}{(}\PYG{n}{Read}\PYG{p}{)}\PYG{p}{;}

\PYG{k+kr}{exception}
   \PYG{k+kr}{when} \PYG{n}{XML\PYGZus{}Validation\PYGZus{}Error} \PYG{p}{\textbar{}} \PYG{n}{XML\PYGZus{}Not\PYGZus{}Implemented} \PYG{p}{=\PYGZgt{}}
      \PYG{n}{Put\PYGZus{}Line} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}ERROR: \PYGZdq{}} \PYG{o}{\PYGZam{}} \PYG{n}{Get\PYGZus{}Error\PYGZus{}Message} \PYG{p}{(}\PYG{n}{My\PYGZus{}reader}\PYG{p}{)}\PYG{p}{)}\PYG{p}{;}
\PYG{k+kr}{end}\PYG{p}{;}
\end{Verbatim}

\item {} 
Implicitly parsing the schema

Two special attributes, defined in the Schema standard, can be used to
indicate, in an XML document itself, that it should be validated with
a specific schema.

These attributes are both defined in a special namespace,
\href{http://www.w3.org/2001/XMLSchema-instance}{http://www.w3.org/2001/XMLSchema-instance}.
\begin{itemize}
\item {} 
\emph{xsi:noNamespaceSchemaLocation}

The value of this attribute is the name of a file that contains
the schema to use for elements that are not associated with a
specific namespace.

\item {} 
\emph{xsi:schemaLocation}

This attribute is a list of strings, alternatively the prefix of
a namespace and the name of an xsd file to use for that
namespace. For instance, \emph{``ns1 file1.xsd ns2 file2.xsd''}.

\end{itemize}

When it encounters any of these two attributes, XML/Ada will
automatically parse the corresponding schema files, and use the result
to validate the file.

See the section below on optimizing the parsing of the grammars, as a
way to avoid parsing the same grammar multiple times.

\end{itemize}


\section{Validating documents with SAX}
\label{schema:validating-documents-with-sax}
XML/Ada is quite unique in the category of XML parsers, since it allows the
validation of XML files when you are using an event-based parser with SAX.
Most other XML parsers only work on DOM trees.

Basing the validation on SAX is more efficient, since there is no need to read
the whole XML stream (or even the grammar) in memory before starting the
validation, and errors can be reported immediatly.

It also requires less memory to run, and thus can validate large XML
documents.

It also means that even if you are using SAX, and not DOM, you still have
access to the validation features.

Validating a XML document while parsing it is basically done the same as when
using SAX itself. Instead of inheriting from \emph{Sax.Readers.Reader}, your tagged
type must inherit from \emph{Schema.Readers.Validating\_Reader}.

As usual, you can still override the predefined primitive operations like
\emph{Start\_Element}, \emph{End\_Element}, ...

Note the activation of the \emph{Schema\_Validation\_Feature} feature, without which
no validation takes place:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kn}{with} \PYG{n+nn}{Ada.Text\PYGZus{}IO}\PYG{p}{;}        \PYG{k+kn}{use} \PYG{n+nn}{Ada.Text\PYGZus{}IO}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Sax.Readers}\PYG{p}{;}        \PYG{k+kn}{use} \PYG{n+nn}{Sax.Readers}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Schema.Readers}\PYG{p}{;}     \PYG{k+kn}{use} \PYG{n+nn}{Schema.Readers}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Schema.Validators}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Input\PYGZus{}Sources.File}\PYG{p}{;} \PYG{k+kn}{use} \PYG{n+nn}{Input\PYGZus{}Sources.File}\PYG{p}{;}

\PYG{k+kd}{procedure} \PYG{n+nf}{SchemaExample} \PYG{k+kr}{is}
   \PYG{n}{Input} \PYG{p}{:} \PYG{n}{File\PYGZus{}Input}\PYG{p}{;}
   \PYG{n}{My\PYGZus{}Reader} \PYG{p}{:} \PYG{n}{Validating\PYGZus{}Reader}\PYG{p}{;}
\PYG{k+kr}{begin}
   \PYG{n}{Set\PYGZus{}Public\PYGZus{}Id} \PYG{p}{(}\PYG{n}{Input}\PYG{p}{,} \PYG{l+s}{\PYGZdq{}Preferences file\PYGZdq{}}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Open} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}pref.xml\PYGZdq{}}\PYG{p}{,} \PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Set\PYGZus{}Feature} \PYG{p}{(}\PYG{n}{My\PYGZus{}Reader}\PYG{p}{,} \PYG{n}{Schema\PYGZus{}Validation\PYGZus{}Feature}\PYG{p}{,} \PYG{k+kc}{True}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Parse} \PYG{p}{(}\PYG{n}{My\PYGZus{}Reader}\PYG{p}{,} \PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Close} \PYG{p}{(}\PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}

\PYG{k+kr}{exception}
   \PYG{k+kr}{when} \PYG{n}{Schema}\PYG{p}{.}\PYG{n}{Validators}\PYG{p}{.}\PYG{n}{XML\PYGZus{}Validation\PYGZus{}Error} \PYG{p}{=\PYGZgt{}}
      \PYG{n}{Put\PYGZus{}Line} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}ERROR: \PYGZdq{}} \PYG{o}{\PYGZam{}} \PYG{n}{Get\PYGZus{}Error\PYGZus{}Message} \PYG{p}{(}\PYG{n}{My\PYGZus{}Reader}\PYG{p}{)}\PYG{p}{)}\PYG{p}{;}
\PYG{k+kr}{end} \PYG{n+nf}{SchemaExample}\PYG{p}{;}
\end{Verbatim}


\section{Validating documents with DOM}
\label{schema:validating-documents-with-dom}
This is very similar to using DOM itself, except the base class of your
reader should be \emph{Schema.Dom\_Readers.Tree\_Reader}. Going back to the
example described in {\hyperref[dom:using-dom]{\emph{Using DOM}}}, you would use the following to
validate XML streams before generating the DOM tree.

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kn}{with} \PYG{n+nn}{Input\PYGZus{}Sources.File}\PYG{p}{;} \PYG{k+kn}{use} \PYG{n+nn}{Input\PYGZus{}Sources.File}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Sax.Readers}\PYG{p}{;}        \PYG{k+kn}{use} \PYG{n+nn}{Sax.Readers}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{DOM.Core}\PYG{p}{;}           \PYG{k+kn}{use} \PYG{n+nn}{DOM.Core}\PYG{p}{;}
\PYG{k+kn}{with} \PYG{n+nn}{Schema.Dom\PYGZus{}Readers}\PYG{p}{;} \PYG{k+kn}{use} \PYG{n+nn}{Schema.Dom\PYGZus{}Readers}\PYG{p}{;}

\PYG{k+kd}{procedure} \PYG{n+nf}{DomSchemaExample} \PYG{k+kr}{is}
   \PYG{n}{Input}  \PYG{p}{:} \PYG{n}{File\PYGZus{}Input}\PYG{p}{;}
   \PYG{n}{Reader} \PYG{p}{:} \PYG{n}{Schema}\PYG{p}{.}\PYG{n}{Dom\PYGZus{}Readers}\PYG{p}{.}\PYG{n}{Tree\PYGZus{}Reader}\PYG{p}{;}
   \PYG{n}{Doc}    \PYG{p}{:} \PYG{n}{Document}\PYG{p}{;}
\PYG{k+kr}{begin}
   \PYG{n}{Set\PYGZus{}Public\PYGZus{}Id} \PYG{p}{(}\PYG{n}{Input}\PYG{p}{,} \PYG{l+s}{\PYGZdq{}Preferences file\PYGZdq{}}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Open} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}pref\PYGZus{}with\PYGZus{}xsd.xml\PYGZdq{}}\PYG{p}{,} \PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Set\PYGZus{}Feature} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{,} \PYG{n}{Validation\PYGZus{}Feature}\PYG{p}{,} \PYG{k+kc}{False}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Set\PYGZus{}Feature} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{,} \PYG{n}{Namespace\PYGZus{}Feature}\PYG{p}{,} \PYG{k+kc}{False}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Parse} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{,} \PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Close} \PYG{p}{(}\PYG{n}{Input}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Doc} \PYG{p}{:=} \PYG{n}{Get\PYGZus{}Tree} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{)}\PYG{p}{;} 

   \PYG{n}{Free} \PYG{p}{(}\PYG{n}{Reader}\PYG{p}{)}\PYG{p}{;}
\PYG{k+kr}{end} \PYG{n+nf}{DomSchemaExample}\PYG{p}{;}
\end{Verbatim}


\section{Unsupported schema elements}
\label{schema:unsupported-schema-elements}
Not all aspects of XML schemas are supported by XML/Ada.
In particular, it does not currently support XPath, so any part of the
schema that is related to XPath expressions (for instance \emph{\textless{}xsd:key\textgreater{}}
and \emph{\textless{}xsd:unique\textgreater{}}) are not supported currently.


\section{Optimizing the parsing of grammars}
\label{schema:optimizing-the-parsing-of-grammars}
It is often the case that a given \code{.xsd} file will be reused multiple
times to validate XML documents. In such case, you do not want to parse the
file multiple times, but instead reuse an already existing \emph{XML\_Grammar}
object. Of course, this is a tradeoff between memory used to keep the
grammar in memory, and the time it would take to reparse the grammar.

This is easily done when you have a single \code{.xsd} file to reuse
for all the XML files. Simply call \emph{Set\_Grammar} on the parser before
you parse the file, as in:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kr}{declare}
   \PYG{n+no}{G} \PYG{p}{:} \PYG{k+kr}{constant} \PYG{n}{XML\PYGZus{}Grammar} \PYG{p}{:=} \PYG{p}{.}\PYG{p}{.}\PYG{p}{.}\PYG{p}{;}  \PYG{c+c1}{\PYGZhy{}\PYGZhy{}  parsed earlier}
   \PYG{n}{R} \PYG{p}{:} \PYG{n}{Validating\PYGZus{}Reader}\PYG{p}{;}
   \PYG{n}{F} \PYG{p}{:} \PYG{n}{File\PYGZus{}Input}\PYG{p}{;}
\PYG{k+kr}{begin}
   \PYG{n}{R}\PYG{p}{.}\PYG{n}{Set\PYGZus{}Grammar} \PYG{p}{(}\PYG{n}{G}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Open} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}file.xml\PYGZdq{}}\PYG{p}{,} \PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{R}\PYG{p}{.}\PYG{n}{Parse} \PYG{p}{(}\PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Close} \PYG{p}{(}\PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{p}{.}\PYG{p}{.}\PYG{p}{.}\PYG{p}{;}  \PYG{c+c1}{\PYGZhy{}\PYGZhy{}  Do something with the resulting tree}
\PYG{k+kr}{end}\PYG{p}{;}
\end{Verbatim}

The second use case is a bit more complex: you have several XSD files to
parse, and the XML files will need either of these. If you are using
namespaces, there is nothing special to do, and the same code as above
applies: you can simply parse each of the XSD file into the same
XML\_Grammar, and then use that grammar to parse all the XML files,
as in:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kr}{declare}
   \PYG{n}{G} \PYG{p}{:} \PYG{n}{XML\PYGZus{}Grammar}\PYG{p}{;}
   \PYG{n}{S} \PYG{p}{:} \PYG{n}{Schema\PYGZus{}Reader}\PYG{p}{;}
   \PYG{n}{F} \PYG{p}{:} \PYG{n}{File\PYGZus{}Input}\PYG{p}{;}
   \PYG{n}{R} \PYG{p}{:} \PYG{n}{Validating\PYGZus{}Reader}\PYG{p}{;}
\PYG{k+kr}{begin}
   \PYG{n}{Open} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}grammar1.xsd\PYGZdq{}}\PYG{p}{,} \PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{S}\PYG{p}{.}\PYG{n}{Parse} \PYG{p}{(}\PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{F}\PYG{p}{.}\PYG{n}{Close}\PYG{p}{;}

   \PYG{n}{Open} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}grammar2.xsd\PYGZdq{}}\PYG{p}{,} \PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{S}\PYG{p}{.}\PYG{n}{Parse} \PYG{p}{(}\PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{F}\PYG{p}{.}\PYG{n}{Close}\PYG{p}{;}

   \PYG{n}{G} \PYG{p}{:=} \PYG{n}{S}\PYG{p}{.}\PYG{n}{Get\PYGZus{}Grammar}\PYG{p}{;}

   \PYG{n}{R}\PYG{p}{.}\PYG{n}{Set\PYGZus{}Grammar} \PYG{p}{(}\PYG{n}{G}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{Open} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}file.xml\PYGZdq{}}\PYG{p}{,} \PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{R}\PYG{p}{.}\PYG{n}{Parse} \PYG{p}{(}\PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{F}\PYG{p}{.}\PYG{n}{Close}\PYG{p}{;}
\PYG{k+kr}{end}\PYG{p}{;}
\end{Verbatim}

If however you are not using namespaces, you cannot use this technics, since
the grammar from the various XSD files would end up mixed up, and validation
will most likely fail. So instead you need to have one \emph{XML\_Grammar} per
XSD file, and then set the grammar on the reader dynamically. A full
example is given in the XML/Ada source distribution, in
\code{tests/schema/multiple\_xsd}. Here is an overview.

We first need to parse each of the XSD files into its own grammar:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kr}{declare}
   \PYG{n}{Symbols} \PYG{p}{:} \PYG{n}{Symbol\PYGZus{}Table}\PYG{p}{;}
   \PYG{n}{G1}\PYG{p}{,} \PYG{n}{G2} \PYG{p}{:} \PYG{n}{XML\PYGZus{}Grammar}\PYG{p}{;}
   \PYG{n}{S}      \PYG{p}{:} \PYG{n}{Schema\PYGZus{}Grammar}\PYG{p}{;}
   \PYG{n}{F}      \PYG{p}{:} \PYG{n}{File\PYGZus{}Input}\PYG{p}{;}
\PYG{k+kr}{begin}
   \PYG{c+c1}{\PYGZhy{}\PYGZhy{}  Since we are going to reuse grammars, we need to ensure their}
   \PYG{c+c1}{\PYGZhy{}\PYGZhy{}  symbol tables (where internal strings are stored) across all}
   \PYG{c+c1}{\PYGZhy{}\PYGZhy{}  involved parsers).}
   \PYG{n}{Symbols} \PYG{p}{:=} \PYG{n}{Allocate}\PYG{p}{;}
   \PYG{n}{S}\PYG{p}{.}\PYG{n}{Set\PYGZus{}Symbol\PYGZus{}Table} \PYG{p}{(}\PYG{n}{Symbols}\PYG{p}{)}\PYG{p}{;}

   \PYG{c+c1}{\PYGZhy{}\PYGZhy{}  Now we can parse each of the XSD file}
   \PYG{n}{Open} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}algo1.xsd\PYGZdq{}}\PYG{p}{,} \PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{S}\PYG{p}{.}\PYG{n}{Parse} \PYG{p}{(}\PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{F}\PYG{p}{.}\PYG{n}{Close}\PYG{p}{;}
   \PYG{n}{G1} \PYG{p}{:=} \PYG{n}{S}\PYG{p}{.}\PYG{n}{Get\PYGZus{}Grammar}\PYG{p}{;}

   \PYG{n}{S}\PYG{p}{.}\PYG{n}{Set\PYGZus{}Grammar} \PYG{p}{(}\PYG{n}{No\PYGZus{}Grammar}\PYG{p}{)}\PYG{p}{;}  \PYG{c+c1}{\PYGZhy{}\PYGZhy{}  reset}
   \PYG{n}{Open} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}algo2.xsd\PYGZdq{}}\PYG{p}{,} \PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{S}\PYG{p}{.}\PYG{n}{Parse} \PYG{p}{(}\PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{F}\PYG{p}{.}\PYG{n}{Close}\PYG{p}{;}
   \PYG{n}{G2} \PYG{p}{:=} \PYG{n}{S}\PYG{p}{.}\PYG{n}{Get\PYGZus{}Grammar}\PYG{p}{;}
\PYG{k+kr}{end}\PYG{p}{;}
\end{Verbatim}

We then need to create a custom validating reader, which knows how to set
the grammar based on its name. This is done by overriding one of the
primitive operations of the parser:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYG{k+kr}{declare}
   \PYG{k+kd}{type} \PYG{k+kt}{My\PYGZus{}Reader} \PYG{k+kr}{is} \PYG{k+kr}{new} \PYG{n}{Validating\PYGZus{}Reader} \PYG{k+kr}{with} \PYG{k+kr}{null record}\PYG{p}{;}
   \PYG{k+kr}{overriding} \PYG{k+kd}{procedure} \PYG{n+nf}{Parse\PYGZus{}Grammar}
      \PYG{p}{(}\PYG{n+nv}{Self}          \PYG{p}{: }\PYG{n+nv}{not} \PYG{n+nv}{null} \PYG{n+nv}{access} \PYG{n+nv}{Reader\PYGZus{}With\PYGZus{}Preloaded\PYGZus{}XSD}\PYG{p}{;}
       \PYG{n+nv}{URI}\PYG{p}{,} \PYG{n+nv}{Xsd\PYGZus{}File} \PYG{p}{: }\PYG{n+nv}{Sax}\PYG{p}{.}\PYG{n+nv}{Symbols}\PYG{p}{.}\PYG{n+nv}{Symbol}\PYG{p}{;}
       \PYG{n+nv}{Do\PYGZus{}Create\PYGZus{}NFA} \PYG{p}{: }\PYG{n+nv}{Boolean} \PYG{p}{:=} \PYG{n+nv}{True}\PYG{p}{)} \PYG{k+kr}{is}
   \PYG{k+kr}{begin}
      \PYG{k+kr}{if} \PYG{n}{Xsd\PYGZus{}File} \PYG{o}{=} \PYG{l+s}{\PYGZdq{}algo1.xsd\PYGZdq{}} \PYG{k+kr}{then}
         \PYG{n}{Self}\PYG{p}{.}\PYG{n}{Set\PYGZus{}Grammar} \PYG{p}{(}\PYG{n}{G1}\PYG{p}{)}\PYG{p}{;}
      \PYG{k+kr}{elsif} \PYG{n}{Xsd\PYGZus{}File} \PYG{o}{=} \PYG{l+s}{\PYGZdq{}algo2.xsd\PYGZdq{}} \PYG{k+kr}{then}
         \PYG{n}{Self}\PYG{p}{.}\PYG{n}{Set\PYGZus{}Grammar} \PYG{p}{(}\PYG{n}{G2}\PYG{p}{)}\PYG{p}{;}
      \PYG{k+kr}{end} \PYG{k+kr}{if}\PYG{p}{;}
   \PYG{k+kr}{end} \PYG{n+nf}{Parse\PYGZus{}Grammar}\PYG{p}{;}

   \PYG{n}{R} \PYG{p}{:} \PYG{n}{My\PYGZus{}Reader}\PYG{p}{;}
\PYG{k+kr}{begin}
   \PYG{c+c1}{\PYGZhy{}\PYGZhy{}  Also share the same symbol table}
   \PYG{n}{R}\PYG{p}{.}\PYG{n}{Set\PYGZus{}Symbol\PYGZus{}Table} \PYG{p}{(}\PYG{n}{Symbols}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{R}\PYG{p}{.}\PYG{n}{Set\PYGZus{}Feature} \PYG{p}{(}\PYG{n}{Schema\PYGZus{}Validation\PYGZus{}Feature}\PYG{p}{,} \PYG{k+kc}{True}\PYG{p}{)}\PYG{p}{;}

   \PYG{n}{Open} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}test1.xml\PYGZdq{}}\PYG{p}{,} \PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{R}\PYG{p}{.}\PYG{n}{Parse} \PYG{p}{(}\PYG{n}{F}\PYG{p}{)}\PYG{p}{;}
   \PYG{n}{F}\PYG{p}{.}\PYG{n}{Close}\PYG{p}{;}
\PYG{k+kr}{end}\PYG{p}{;}
\end{Verbatim}

Where for instance \code{test1.xml} contains:

\begin{Verbatim}[frame=single,commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1]
\PYGZlt{}?xml version=\PYGZdq{}1.0\PYGZdq{} encoding=\PYGZdq{}UTF\PYGZhy{}8\PYGZdq{}?\PYGZgt{}
\PYGZlt{}root xmlns:xsi=\PYGZdq{}http://www.w3.org/2001/XMLSchema\PYGZhy{}instance\PYGZdq{}
      xsi:noNamespaceSchemaLocation=\PYGZdq{}algo1.xsd\PYGZdq{}\PYGZgt{}
   \PYGZlt{}child\PYGZgt{}102\PYGZlt{}/child\PYGZgt{}
\PYGZlt{}/root\PYGZgt{}
\end{Verbatim}


\chapter{Using the library}
\label{using::doc}\label{using:using-the-library}\label{using:id1}
XML/Ada is a library. When compiling an application that uses it, you
thus need to specify where the spec files are to be found, as well
as where the libraries are installed.

There are several ways to do it:

\index{xmlada-config}\begin{itemize}
\item {} 
The simplest is to use the \emph{xmlada-config} script, and let it
provide the list of switches for \emph{gnatmake}. This is more
convenient on Unix systems, where you can simply compile your application
with:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
gnatmake main.adb {}`xmlada\PYGZhy{}config{}`
\end{Verbatim}

Note the use of backticks. This means that \emph{xmlada-config} is
first executed, and then the command line is replaced with the output of
the script, thus finally executing something like:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
gnatmake main.adb \PYGZhy{}Iprefix/include/xmlada \PYGZhy{}largs \PYGZhy{}Lprefix/lib \PYGZbs{}\PYGZbs{}
  \PYGZhy{}lxmlada\PYGZus{}input\PYGZus{}sources \PYGZhy{}lxmlada\PYGZus{}sax \PYGZhy{}lxmlada\PYGZus{}unicode \PYGZhy{}lxmlada\PYGZus{}dom
\end{Verbatim}

Unfortunately, this behavior is not available on Windows (unless of course
you use a Unix shell). The simplest in that case is to create a
\code{Makefile}, to be used with the \emph{make} command, and copy-paste
the output of \emph{xmlada-config} into it.

\emph{xmlada-config} has several switches that might be useful:
\begin{itemize}
\item {} 
\emph{--sax}: If you this flag, your application will not be
linked against the DOM module. This might save some space, particularly
if linking statically.

\item {} 
\emph{--static}: Return the list of flags to use to link your
application statically against Xml/Ada. Your application is then
standalone, and you don't need to distribute XMl/Ada at the same time.

\item {} 
\emph{--static\_sax}: Combines both of the above flags.

\end{itemize}

If you are working on a big project, particularly one that includes
sources in languages other than Ada, you generally have to run the three
steps of the compilation process separately (compile, bind and then link).
\emph{xmlada-config} can also be used, provided you use one of the
following switches:
\begin{itemize}
\item {} 
\emph{--cflags}: This returns the compiler flags only, to be used
for instance with \emph{gcc}.

\item {} 
\emph{--libs}: This returns the linker flags only, to be used for
instance with \emph{gnatlink}.

\end{itemize}

This \emph{xmlada-config} method doesn't provide access to the
\code{xml\_gtk} module, which is only available when using project files
(see below).

\index{project files}
\index{xmlada.gpr}
\item {} 
The preferred method, however, is to use the GNAT project files.
See the GNAT user's guide for more information on the project files and
how to create them for your application.

Basically, a project file contains the description of your build
environment (source directories, object directories, libraries,...).

The very simple case is when you have all your sources in the same
directory (say \code{src/}), and the object files are all generated in the
\code{obj/} directory.

In this case, your project file would look like:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{k+kn}{with} \PYG{l+s}{\PYGZdq{}xmlada\PYGZdq{}}\PYG{p}{;}
\PYG{n}{project} \PYG{n}{Default} \PYG{k+kr}{is}
   \PYG{k+kr}{for} \PYG{n}{Source\PYGZus{}Dirs} \PYG{k+kn}{use} \PYG{p}{(}\PYG{l+s}{\PYGZdq{}src/\PYGZdq{}}\PYG{p}{)}\PYG{p}{;}
   \PYG{k+kr}{for} \PYG{n}{Object\PYGZus{}Dir} \PYG{k+kn}{use} \PYG{l+s}{\PYGZdq{}obj/\PYGZdq{}}\PYG{p}{;}
\PYG{k+kr}{end} \PYG{n+nf}{Default}\PYG{p}{;}
\end{Verbatim}

and you build your application with:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{n}{gprbuild} \PYG{o}{\PYGZhy{}}\PYG{n}{Pdefault} \PYG{n}{main}\PYG{p}{.}\PYG{n}{adb}
\end{Verbatim}

Note in the project file the first line, which indicates that your
application requires XML/Ada to build. This will automatically set the
appropriate compiler and linker switches to use XML/Ada. Your application
will be linker against all modules of XML/Ada (DOM, SAX, ...).

If your application doesn't use DOM, you can replace the first line with
something like:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{k+kn}{with} \PYG{l+s}{\PYGZdq{}xmlada\PYGZus{}sax\PYGZdq{}}\PYG{p}{;}
\end{Verbatim}

which will reduce the number of libraries that your application is
linked with.

WHen you are using project files, you need to let GNAT know where to find
the project files. This is done by setting the \emph{ADA\_PROJECT\_PATH}
environment variable, by adding to it the installation directory of
XML/Ada, ie the one that contains xmlada.gpr

If the installation prefix is the same as your GNAT installation, and you
are using GNAT more recent than 5.03a, then it will automatically find
XML/Ada's project files.

Check the \code{dom/test} directory in the XML/Ada package, which contains
both code examples and project files that you can use as a basic for your
own code.

\end{itemize}

The default type of library depends on the way you installed XML/Ada. In all
cases, and assuming you installed both static and shared libraries, you can
choose among the two by setting the environment variable:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{n}{LIBRARY\PYGZus{}TYPE}\PYG{o}{=}\PYG{n}{static}
\end{Verbatim}

or:

\begin{Verbatim}[frame=single,commandchars=\\\{\}]
\PYG{n}{LIBRARY\PYGZus{}TYPE}\PYG{o}{=}\PYG{n}{relocatable}
\end{Verbatim}

Whatever method you used to build your application, you might have to change,
at least one UNIX systems, the environment variable \emph{LD\_LIBRARY\_PATH} so that
it contains the \code{lib/} directory in the XML/Ada installation, so that the
dynamic libraries are correctly found.

This is not needed if you build XML/Ada as a static directory.


\section{Running on VxWorks}
\label{using:running-on-vxworks}
On VxWorks, XML Ada processing might require more stack space than what is
typically available from the VxWorks shell, the tasks spawned from there with
``sp'', or Ada tasks with no or a too small Storage\_Size value attached.

Such stack overflow conditions are typically characterized by non-deterministic
erratic behavior and can be cured by allocating more stack space for the tasks
involved.

Copyright (C) 2000-2002, Emmanuel Briot

Copyright (C) 2003-2011, AdaCore

This document may be copied, in whole or in part, in any form or by any
means, as is or with alterations, provided that (1) alterations are clearly
marked as alterations and (2) this copyright notice is included
unmodified in any copy.



\renewcommand{\indexname}{Index}
\printindex
\end{document}
