Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / libxml2 / 0142b84bbfd75ae0696604f4f12a1f6383205185 / . / doc / xml.html
blob: a9d91da6030836013e8494b1be790d730c342408 [file] [log] [blame]
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]2 "http://www.w3.org/TR/REC-html40/loose.dtd">
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]3<html>
4<head>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]5 <title>The XML library for Gnome</title>
Daniel Veillardb24054a1999-12-18 15:32:46 +0000[diff] [blame]6 <meta name="GENERATOR" content="amaya V2.4">
7 <meta http-equiv="Content-Type" content="text/html">
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]8</head>
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]9
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]10<body bgcolor="#ffffff">
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]11<h1 align="center">The XML library for Gnome</h1>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]12
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]13<h2 style="text-align: center">libxml, a.k.a. gnome-xml</h2>
14
15<p></p>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]16<ul>
17 <li><a href="#Introducti">Introduction</a></li>
18 <li><a href="#Documentat">Documentation</a></li>
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]19 <li><a href="#Downloads">Downloads</a></li>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]20 <li><a href="#News">News</a></li>
21 <li><a href="#XML">XML</a></li>
22 <li><a href="#tree">The tree output</a></li>
23 <li><a href="#interface">The SAX interface</a></li>
24 <li><a href="#library">The XML library interfaces</a>
25 <ul>
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]26 <li><a href="#Invoking">Invoking the parser: the pull way</a></li>
27 <li><a href="#Invoking">Invoking the parser: the push way</a></li>
28 <li><a href="#Invoking2">Invoking the parser: the SAX interface</a></li>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]29 <li><a href="#Building">Building a tree from scratch</a></li>
30 <li><a href="#Traversing">Traversing the tree</a></li>
31 <li><a href="#Modifying">Modifying the tree</a></li>
32 <li><a href="#Saving">Saving the tree</a></li>
33 <li><a href="#Compressio">Compression</a></li>
34 </ul>
35 </li>
36 <li><a href="#Entities">Entities or no entities</a></li>
37 <li><a href="#Namespaces">Namespaces</a></li>
38 <li><a href="#Validation">Validation</a></li>
39 <li><a href="#Principles">DOM principles</a></li>
40 <li><a href="#real">A real example</a></li>
41</ul>
42
43<h2><a name="Introducti">Introduction</a></h2>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]44
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]45<p>This document describes the <a href="http://www.w3.org/XML/">XML</a>
46library provideed in the <a href="http://www.gnome.org/">Gnome</a> framework.
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]47XML is a standard to build tag based structured documents/data.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]48
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]49<p>Here are some key points about libxml:</p>
50<ul>
51 <li>The internal document repesentation is as close as possible to the <a
52 href="http://www.w3.org/DOM/">DOM</a> interfaces.</li>
53 <li>Libxml also has a <a href="http://www.megginson.com/SAX/index.html">SAX
54 like interface</a>, the interface is designed to be compatible with <a
55 href="http://www.jclark.com/xml/expat.html">Expat</a> one.</li>
56 <li>Libxml now include a nearly complete <a
57 href="http://www.w3.org/TR/xpath">XPath</a> implementation.</li>
58 <li>Libxml export Push and Pull type parser interface for both XML and
59 HTML.</li>
60 <li>This library is released both under the W3C Copyright and the GNU LGPL,
61 basically everybody should be happy, if not, drop me a mail.</li>
62</ul>
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]63
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]64<h2><a name="Documentat">Documentation</a></h2>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]65
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]66<p>There is some on-line resources about using libxml :</p>
67<ol>
68 <li>The code is commented in a way which allow <a
69 href="http://xmlsoft.org/libxml.html">extensive documentation</a> to be
70 automatically extracted.</li>
71 <li>This page provides a global overview and <a href="#real">some
72 examples</a> on how to use libxml</li>
73 <li><a href="mailto:james@daa.com.au">James Henstridge</a> made <a
74 href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">a nice
75 documentation</a> expaining how to use the SAX interface of libxml</li>
76 <li>George Lebl wrote <a
77 href="http://www-4.ibm.com/software/developer/library/gnome3/">an article
78 for IBM developperWorks</a> about using libxml</li>
79 <li>It is also a good idea to check to <a href="mailto:raph@levien.com">Raph
80 Levien</a> <a href="http://levien.com/gnome/">web site</a> since he is
81 building the <a href="http://levien.com/gnome/gdome.html">DOM interface
82 gdome</a> on top of libxml result tree and an implementation of <a
83 href="http://www.w3.org/Graphics/SVG/">SVG</a> called <a
84 href="http://www.levien.com/svg/">gill</a>. Check his <a
85 href="http://www.levien.com/gnome/domination.html">DOMination
86 paper</a>.</li>
87 <li>And don't forget to look at the <a href="/messages/">mailing-list
88 archive</a> too.</li>
89</ol>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]90
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]91<h3>Reporting bugs and getting help</h3>
Daniel Veillard4c3a2031999-11-19 17:46:26 +0000[diff] [blame]92
93<p>Well bugs or missing features are always possible, and I will make a point
94of fixing them in a timely fashion. The best way it to <a
95href="http://bugs.gnome.org/db/pa/lgnome-xml.html">use the Gnome bug tracking
96database</a>. I look at reports there regulary and it's good to have a
97reminder when a bug is still open. Check the <a
98href="http://bugs.gnome.org/Reporting.html">instructions on reporting bugs</a>
99and be sure to specify thatthe bug is for the package gnome-xml.</p>
100
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]101<p>There is also a mailing-list <a
102href="mailto:xml@rufus.w3.org">xml@rufus.w3.org</a> for libxml, with an <a
103href="http://xmlsoft.org/messages">on-line archive</a>. To subscribe to this
104majordomo based list, send a mail to <a
105href="mailto:majordomo@rufus.w3.org">majordomo@rufus.w3.org</a> with
106"subscribe xml" in the <strong>content</strong> of the message.</p>
107
Daniel Veillard4c3a2031999-11-19 17:46:26 +0000[diff] [blame]108<p>Alternately you can just send the bug to the <a
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]109href="mailto:xml@rufus.w3.org">xml@rufus.w3.org</a> list.</p>
Daniel Veillard4c3a2031999-11-19 17:46:26 +0000[diff] [blame]110
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]111<h2><a name="Downloads">Downloads</a></h2>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]112
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]113<p>Latest versions can be found on <a
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]114href="ftp://rpmfind.net/pub/veillard/">rpmfind.net</a> or on the <a
115href="ftp://ftp.gnome.org/pub/GNOME/MIRRORS.html">Gnome FTP server</a> either
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]116as a <a href="ftp://ftp.gnome.org/pub/GNOME/stable/sources/libxml/">source
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]117archive</a> or <a href="ftp://ftp.gnome.org/pub/GNOME/contrib/rpms/">RPMs
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]118packages</a> (NOTE that you need both the <a
119href="http://rpmfind.net/linux/RPM/libxml.html">libxml</a> and <a
120href="http://rpmfind.net/linux/RPM/libxml-devel.html">libxml-devel</a>
121packages installed to compile applications using libxml).</p>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]122
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]123<p>Libxml is also available from 2 CVs bases:</p>
124<ul>
125 <li><p>The <a href="http://dev.w3.org/cvsweb/XML/">W3C CVS base</a>,
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]126 available read-only using the CVS pserver authentification (I tend to use
127 this base for my own developements so it's updated more regulary, but
128 content may not be as stable):</p>
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]129 <pre>CVSROOT=:pserver:anonymous@dev.w3.org:/sources/public
130password: anonymous
131module: XML</pre>
132 </li>
133 <li><p>The <a
134 href="http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&amp;dir=gnome-xml">Gnome
135 CVS base</a>, Check the <a
136 href="http://developer.gnome.org/tools/cvs.html">Gnome CVS Tools</a> page,
137 the CVS module is <b>gnome-xml</b></p>
138 </li>
139</ul>
140
141<h2><a name="News">News</a></h2>
142
Daniel Veillard944b5ff1999-12-15 19:08:24 +0000[diff] [blame]143<h3>CVS only : check the <a
144href="http://cvs.gnome.org/lxr/source/gnome-xml/ChangeLog">Changelog</a> file
145for really accurate description</h3>
Daniel Veillard4c3a2031999-11-19 17:46:26 +0000[diff] [blame]146<ul>
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]147 <li>working on HTML and XML links recognition layers, get in touch with me
Daniel Veillard944b5ff1999-12-15 19:08:24 +0000[diff] [blame]148 if you want to test those.</li>
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]149 <li>adding APIs to parse a well balanced chunk of XML (production <a
150 href="http://www.w3.org/TR/REC-xml#NT-content">[43] content</a> of the XML
151 spec)</li>
152</ul>
153
154<h3>1.8.4: Jan 13 2000</h3>
155<ul>
156 <li>bug fixes, reintroduced xmlNewGlobalNs(), fixed xmlNewNs()</li>
157 <li>all exit() call should have been removed from libxml</li>
158 <li>fixed a problem with INCLUDE_WINSOCK on WIN32 platform</li>
159 <li>added newDocFragment()</li>
Daniel Veillardf84f71f2000-01-05 19:54:23 +0000[diff] [blame]160</ul>
161
162<h3>1.8.3: Jan 5 2000</h3>
163<ul>
164 <li>a Push interface for the XML and HTML parsers</li>
Daniel Veillard437b87b2000-01-03 17:30:46 +0000[diff] [blame]165 <li>an shell like interface to the document tree (try tester --shell
166 :-)</li>
Daniel Veillarddbfd6411999-12-28 16:35:14 +0000[diff] [blame]167 <li>lots of bug fixes and improvement added over XMas hollidays</li>
Daniel Veillard437b87b2000-01-03 17:30:46 +0000[diff] [blame]168 <li>fixed the DTD parsing code to work with the xhtml DTD</li>
Daniel Veillardf84f71f2000-01-05 19:54:23 +0000[diff] [blame]169 <li>added xmlRemoveProp(), xmlRemoveID() and xmlRemoveRef()</li>
170 <li>Fixed bugs in xmlNewNs()</li>
Daniel Veillard437b87b2000-01-03 17:30:46 +0000[diff] [blame]171 <li>External entity loading code has been revamped, now it uses
Daniel Veillardf84f71f2000-01-05 19:54:23 +0000[diff] [blame]172 xmlLoadExternalEntity(), some fix on entities processing were added</li>
Daniel Veillard437b87b2000-01-03 17:30:46 +0000[diff] [blame]173 <li>cleaned up WIN32 includes of socket stuff</li>
Daniel Veillard5cb5ab81999-12-21 15:35:29 +0000[diff] [blame]174</ul>
175
176<h3>1.8.2: Dec 21 1999</h3>
177<ul>
Daniel Veillardb24054a1999-12-18 15:32:46 +0000[diff] [blame]178 <li>I got another problem with includes and C++, I hope this issue is fixed
179 for good this time</li>
Daniel Veillard5cb5ab81999-12-21 15:35:29 +0000[diff] [blame]180 <li>Added a few tree modification functions: xmlReplaceNode,
181 xmlAddPrevSibling, xmlAddNextSibling, xmlNodeSetName and
182 xmlDocSetRootElement</li>
183 <li>Tried to improve the HTML output with help from <a
184 href="mailto:clahey@umich.edu">Chris Lahey</a></li>
Daniel Veillarde4e51311999-12-18 15:32:46 +0000[diff] [blame]185</ul>
Daniel Veillardb24054a1999-12-18 15:32:46 +0000[diff] [blame]186
Daniel Veillarde4e51311999-12-18 15:32:46 +0000[diff] [blame]187<h3>1.8.1: Dec 18 1999</h3>
188<ul>
189 <li>various patches to avoid troubles when using libxml with C++ compilers
190 the "namespace" keyword and C escaping in include files</li>
191 <li>a problem in one of the core macros IS_CHAR was corrected</li>
192 <li>fixed a bug introduced in 1.8.0 breaking default namespace processing,
193 and more specifically the Dia application</li>
Daniel Veillard944b5ff1999-12-15 19:08:24 +0000[diff] [blame]194 <li>fixed a posteriori validation (validation after parsing, or by using a
195 Dtd not specified in the original document)</li>
Daniel Veillardb24054a1999-12-18 15:32:46 +0000[diff] [blame]196 <li>fixed a bug in</li>
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]197</ul>
198
199<h3>1.8.0: Dec 12 1999</h3>
200<ul>
201 <li>cleanup, especially memory wise</li>
202 <li>the parser should be more reliable, especially the HTML one, it should
203 not crash, whatever the input !</li>
204 <li>Integrated various patches, especially a speedup improvement for large
205 dataset from <a href="mailto:cnygard@bellatlantic.net">Carl Nygard</a>,
206 configure with --with-buffers to enable them.</li>
207 <li>attribute normalization, oops should have been added long ago !</li>
208 <li>attributes defaulted from Dtds should be available, xmlSetProp() now
209 does entities escapting by default.</li>
Daniel Veillard4c3a2031999-11-19 17:46:26 +0000[diff] [blame]210</ul>
Daniel Veillard35008381999-10-25 13:15:52 +0000[diff] [blame]211
212<h3>1.7.4: Oct 25 1999</h3>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]213<ul>
Daniel Veillard35008381999-10-25 13:15:52 +0000[diff] [blame]214 <li>Lots of HTML improvement</li>
215 <li>Fixed some errors when saving both XML and HTML</li>
216 <li>More examples, the regression tests should now look clean</li>
217 <li>Fixed a bug with contiguous charref</li>
218</ul>
219
220<h3>1.7.3: Sep 29 1999</h3>
221<ul>
222 <li>portability problems fixed</li>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]223 <li>snprintf was used unconditionnally, leading to link problems on system
Daniel Veillard35008381999-10-25 13:15:52 +0000[diff] [blame]224 were it's not available, fixed</li>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]225</ul>
226
227<h3>1.7.1: Sep 24 1999</h3>
228<ul>
229 <li>The basic type for strings manipulated by libxml has been renamed in
230 1.7.1 from <strong>CHAR</strong> to <strong>xmlChar</strong>. The reason
231 is that CHAR was conflicting with a predefined type on Windows. However on
232 non WIN32 environment, compatibility is provided by the way of a
233 <strong>#define </strong>.</li>
234 <li>Changed another error : the use of a structure field called errno, and
235 leading to troubles on platforms where it's a macro</li>
236</ul>
237
238<h3>1.7.0: sep 23 1999</h3>
239<ul>
240 <li>Added the ability to fetch remote DTD or parsed entities, see the <a
241 href="gnome-xml-nanohttp.html">nanohttp</a> module.</li>
242 <li>Added an errno to report errors by another mean than a simple printf
243 like callback</li>
244 <li>Finished ID/IDREF support and checking when validation</li>
245 <li>Serious memory leaks fixed (there is now a <a
246 href="gnome-xml-xmlmemory.html">memory wrapper</a> module)</li>
247 <li>Improvement of <a href="http://www.w3.org/TR/xpath">XPath</a>
248 implementation</li>
249 <li>Added an HTML parser front-end</li>
250</ul>
251
252<h2><a name="XML">XML</a></h2>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]253
254<p><a href="http://www.w3.org/TR/REC-xml">XML is a standard</a> for markup
255based structured documents, here is <a name="example">an example</a>:</p>
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]256<pre>&lt;?xml version="1.0"?>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]257&lt;EXAMPLE prop1="gnome is great" prop2="&amp;amp; linux too">
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]258 &lt;head>
259 &lt;title>Welcome to Gnome&lt;/title>
260 &lt;/head>
261 &lt;chapter>
262 &lt;title>The Linux adventure&lt;/title>
263 &lt;p>bla bla bla ...&lt;/p>
264 &lt;image href="linus.gif"/>
265 &lt;p>...&lt;/p>
266 &lt;/chapter>
267&lt;/EXAMPLE></pre>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]268
269<p>The first line specify that it's an XML document and gives useful
270informations about it's encoding. Then the document is a text format whose
271structure is specified by tags between brackets. <strong>Each tag opened have
272to be closed</strong> XML is pedantic about this, not that for example the
273image tag has no content (just an attribute) and is closed by ending up the
274tag with <code>/></code>.</p>
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]275
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]276<p>XML can be applied sucessfully to a wide range or usage from long term
277structured document maintenance where it follows the steps of SGML to simple
278data encoding mechanism like configuration file format (glade), spreadsheets
279(gnumeric), or even shorter lived document like in WebDAV where it is used to
280encode remote call between a client and a server.</p>
281
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]282<h2><a name="tree">The tree output</a></h2>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]283
284<p>The parser returns a tree built during the document analysis. The value
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]285returned is an <strong>xmlDocPtr</strong> (i.e. a pointer to an
286<strong>xmlDoc</strong> structure). This structure contains informations like
287the file name, the document type, and a <strong>root</strong> pointer which
288is the root of the document (or more exactly the first child under the root
289which is the document). The tree is made of <strong>xmlNode</strong>s, chained
290in double linked lists of siblings and with childs&lt;->parent relationship.
291An xmlNode can also carry properties (a chain of xmlAttr structures). An
292attribute may have a value which is a list of TEXT or ENTITY_REF nodes.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]293
294<p>Here is an example (erroneous w.r.t. the XML spec since there should be
295only one ELEMENT under the root):</p>
296
297<p><img src="structure.gif" alt=" structure.gif "></p>
298
299<p>In the source package there is a small program (not installed by default)
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]300called <strong>tester</strong> which parses XML files given as argument and
301prints them back as parsed, this is useful to detect errors both in XML code
302and in the XML parser itself. It has an option <strong>--debug</strong> which
303prints the actual in-memory structure of the document, here is the result with
304the <a href="#example">example</a> given before:</p>
305<pre>DOCUMENT
306version=1.0
307standalone=true
308 ELEMENT EXAMPLE
309 ATTRIBUTE prop1
310 TEXT
311 content=gnome is great
312 ATTRIBUTE prop2
313 ENTITY_REF
314 TEXT
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]315 content= linux too
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]316 ELEMENT title
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]317 TEXT
318 content=Welcome to Gnome
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]319 ELEMENT chapter
320 ELEMENT title
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]321 TEXT
322 content=The Linux adventure
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]323 ELEMENT p
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]324 TEXT
325 content=bla bla bla ...
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]326 ELEMENT image
327 ATTRIBUTE href
328 TEXT
329 content=linus.gif
330 ELEMENT p
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]331 TEXT
332 content=...</pre>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]333
334<p>This should be useful to learn the internal representation model.</p>
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]335
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]336<h2><a name="interface">The SAX interface</a></h2>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]337
338<p>Sometimes the DOM tree output is just to large to fit reasonably into
339memory. In that case and if you don't expect to save back the XML document
340loaded using libxml, it's better to use the SAX interface of libxml. SAX is a
341<strong>callback based interface</strong> to the parser. Before parsing, the
342application layer register a customized set of callbacks which will be called
343by the library as it progresses through the XML input.</p>
344
345<p>To get a more detailed step-by-step guidance on using the SAX interface of
346libxml, <a href="mailto:james@daa.com.au">James Henstridge</a> made <a
347href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">a nice
348documentation.</a></p>
349
350<p>You can debug the SAX behaviour by using the <strong>testSAX</strong>
351program located in the gnome-xml module (it's usually not shipped in the
352binary packages of libxml, but you can also find it in the tar source
353distribution). Here is the sequence of callback that would be generated when
354parsing the example given before as reported by testSAX:</p>
355<pre>SAX.setDocumentLocator()
356SAX.startDocument()
357SAX.getEntity(amp)
358SAX.startElement(EXAMPLE, prop1='gnome is great', prop2='&amp;amp; linux too')
359SAX.characters( , 3)
360SAX.startElement(head)
361SAX.characters( , 4)
362SAX.startElement(title)
363SAX.characters(Welcome to Gnome, 16)
364SAX.endElement(title)
365SAX.characters( , 3)
366SAX.endElement(head)
367SAX.characters( , 3)
368SAX.startElement(chapter)
369SAX.characters( , 4)
370SAX.startElement(title)
371SAX.characters(The Linux adventure, 19)
372SAX.endElement(title)
373SAX.characters( , 4)
374SAX.startElement(p)
375SAX.characters(bla bla bla ..., 15)
376SAX.endElement(p)
377SAX.characters( , 4)
378SAX.startElement(image, href='linus.gif')
379SAX.endElement(image)
380SAX.characters( , 4)
381SAX.startElement(p)
382SAX.characters(..., 3)
383SAX.endElement(p)
384SAX.characters( , 3)
385SAX.endElement(chapter)
386SAX.characters( , 1)
387SAX.endElement(EXAMPLE)
388SAX.endDocument()</pre>
389
390<p>Most of the other functionnalities of libxml are based on the DOM tree
391building facility, so nearly everything up to the end of this document
392presuppose the use of the standard DOM tree build. Note that the DOM tree
393itself is built by a set of registered default callbacks, without internal
394specific interface.</p>
395
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]396<h2><a name="library">The XML library interfaces</a></h2>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]397
398<p>This section is directly intended to help programmers getting bootstrapped
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]399using the XML library from the C language. It doesn't intent to be extensive,
400I hope the automatically generated docs will provide the completeness
401required, but as a separated set of documents. The interfaces of the XML
402library are by principle low level, there is nearly zero abstration. Those
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]403interested in a higher level API should <a href="#DOM">look at DOM</a>.</p>
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]404
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]405<p>The <a href="gnome-xml-parser.html">parser interfaces for XML</a> are
406separated from the <a href="gnome-xml-htmlparser.html">HTML parser ones</a>,
407let's have a look at how it can be called:</p>
408
409<h3><a name="Invoking">Invoking the parser : the pull way</a></h3>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]410
411<p>Usually, the first thing to do is to read an XML input, the parser accepts
412to parse both memory mapped documents or direct files. The functions are
413defined in "parser.h":</p>
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]414<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]415 <dt><code>xmlDocPtr xmlParseMemory(char *buffer, int size);</code></dt>
416 <dd><p>parse a zero terminated string containing the document</p>
417 </dd>
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]418</dl>
419<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]420 <dt><code>xmlDocPtr xmlParseFile(const char *filename);</code></dt>
421 <dd><p>parse an XML document contained in a file (possibly compressed)</p>
422 </dd>
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]423</dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]424
425<p>This returns a pointer to the document structure (or NULL in case of
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]426failure).</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]427
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]428<h3 id="Invoking1">Invoking the parser: the push way</h3>
429
430<p>In order for the application to keep the control when the document is been
431fetched (common for GUI based programs) the libxml, as of version 1.8.3
432provides a push interface too, here are the interfaces:</p>
433<pre>xmlParserCtxtPtr xmlCreatePushParserCtxt(xmlSAXHandlerPtr sax,
434 void *user_data,
435 const char *chunk,
436 int size,
437 const char *filename);
438int xmlParseChunk (xmlParserCtxtPtr ctxt,
439 const char *chunk,
440 int size,
441 int terminate);</pre>
442
443<p>and here is a simple use example:</p>
444<pre> FILE *f;
445
446 f = fopen(filename, "r");
447 if (f != NULL) {
448 int res, size = 1024;
449 char chars[1024];
450 xmlParserCtxtPtr ctxt;
451
452 res = fread(chars, 1, 4, f);
453 if (res > 0) {
454 ctxt = xmlCreatePushParserCtxt(NULL, NULL,
455 chars, res, filename);
456 while ((res = fread(chars, 1, size, f)) > 0) {
457 xmlParseChunk(ctxt, chars, res, 0);
458 }
459 xmlParseChunk(ctxt, chars, 0, 1);
460 doc = ctxt->myDoc;
461 xmlFreeParserCtxt(ctxt);
462 }
463 }</pre>
464
465<p>Also note that the HTML parser embedded into libxml also have a push
466interface they are just prefixed by "html" instead of "xml"</p>
467
468<h3 id="Invoking2">Invoking the parser: the SAX interface</h3>
469
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]470<p>A couple of comments can be made, first this mean that the parser is
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]471memory-hungry, first to load the document in memory, second to build the tree.
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]472Reading a document without building the tree is possible using the SAX
473interfaces (see SAX.h and <a
474href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">James
475Henstridge documentation</a>), not also that the push interface can be limited
476to SAX, just use the two first arguments of
477<code>xmlCreatePushParserCtxt()</code>.</p>
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]478
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]479<h3><a name="Building">Building a tree from scratch</a></h3>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]480
481<p>The other way to get an XML tree in memory is by building it. Basically
482there is a set of functions dedicated to building new elements, those are also
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]483described in "tree.h", here is for example the piece of code producing the
484example used before:</p>
485<pre> xmlDocPtr doc;
486 xmlNodePtr tree, subtree;
487
488 doc = xmlNewDoc("1.0");
489 doc->root = xmlNewDocNode(doc, NULL, "EXAMPLE", NULL);
490 xmlSetProp(doc->root, "prop1", "gnome is great");
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]491 xmlSetProp(doc->root, "prop2", "&amp; linux too");
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]492 tree = xmlNewChild(doc->root, NULL, "head", NULL);
493 subtree = xmlNewChild(tree, NULL, "title", "Welcome to Gnome");
494 tree = xmlNewChild(doc->root, NULL, "chapter", NULL);
495 subtree = xmlNewChild(tree, NULL, "title", "The Linux adventure");
496 subtree = xmlNewChild(tree, NULL, "p", "bla bla bla ...");
497 subtree = xmlNewChild(tree, NULL, "image", NULL);
498 xmlSetProp(subtree, "href", "linus.gif");</pre>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]499
500<p>Not really rocket science ...</p>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]501
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]502<h3><a name="Traversing">Traversing the tree</a></h3>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]503
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]504<p>Basically by <a href="gnome-xml-tree.html">including "tree.h"</a> your code
505has access to the internal structure of all the element of the tree. The names
506should be somewhat simple like <strong>parent</strong>,
507<strong>childs</strong>, <strong>next</strong>, <strong>prev</strong>,
508<strong>properties</strong>, etc... For example still with the previous
509example:</p>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]510<pre><code>doc->root->childs->childs</code></pre>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]511
512<p>points to the title element,</p>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]513<pre>doc->root->childs->next->child->child</pre>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]514
515<p>points to the text node containing the chapter titlle "The Linux adventure"
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]516and</p>
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]517
Daniel Veillardb24054a1999-12-18 15:32:46 +0000[diff] [blame]518<p><strong>NOTE</strong>: XML allows <em>PI</em>s and <em>comments</em> to be
519present before the document root, so doc->root may point to an element which
520is not the document Root Element, a function
Daniel Veillard5cb5ab81999-12-21 15:35:29 +0000[diff] [blame]521<code>xmlDocGetRootElement()</code> was added for this purpose.</p>
Daniel Veillardb24054a1999-12-18 15:32:46 +0000[diff] [blame]522
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]523<h3><a name="Modifying">Modifying the tree</a></h3>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]524
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]525<p>functions are provided to read and write the document content, here is an
526excerpt from the <a href="gnome-xml-tree.html">tree API</a>:</p>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]527<dl>
Daniel Veillarddd6b3671999-09-23 22:19:22 +0000[diff] [blame]528 <dt><code>xmlAttrPtr xmlSetProp(xmlNodePtr node, const xmlChar *name, const
529 xmlChar *value);</code></dt>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]530 <dd><p>This set (or change) an attribute carried by an ELEMENT node the
531 value can be NULL</p>
532 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]533</dl>
534<dl>
Daniel Veillarddd6b3671999-09-23 22:19:22 +0000[diff] [blame]535 <dt><code>const xmlChar *xmlGetProp(xmlNodePtr node, const xmlChar
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]536 *name);</code></dt>
537 <dd><p>This function returns a pointer to the property content, note that
538 no extra copy is made</p>
539 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]540</dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]541
542<p>Two functions must be used to read an write the text associated to
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]543elements:</p>
544<dl>
Daniel Veillarddd6b3671999-09-23 22:19:22 +0000[diff] [blame]545 <dt><code>xmlNodePtr xmlStringGetNodeList(xmlDocPtr doc, const xmlChar
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]546 *value);</code></dt>
547 <dd><p>This function takes an "external" string and convert it to one text
548 node or possibly to a list of entity and text nodes. All non-predefined
549 entity references like &amp;Gnome; will be stored internally as an
550 entity node, hence the result of the function may not be a single
551 node.</p>
552 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]553</dl>
554<dl>
Daniel Veillarddd6b3671999-09-23 22:19:22 +0000[diff] [blame]555 <dt><code>xmlChar *xmlNodeListGetString(xmlDocPtr doc, xmlNodePtr list, int
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]556 inLine);</code></dt>
557 <dd><p>this is the dual function, which generate a new string containing
558 the content of the text and entity nodes. Note the extra argument
559 inLine, if set to 1 instead of returning the &amp;Gnome; XML encoding in
560 the string it will substitute it with it's value say "GNU Network Object
561 Model Environment". Set it if you want to use the string for non XML
562 usage like User Interface.</p>
563 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]564</dl>
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]565
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]566<h3><a name="Saving">Saving a tree</a></h3>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]567
568<p>Basically 3 options are possible:</p>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]569<dl>
Daniel Veillarddd6b3671999-09-23 22:19:22 +0000[diff] [blame]570 <dt><code>void xmlDocDumpMemory(xmlDocPtr cur, xmlChar**mem, int
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]571 *size);</code></dt>
572 <dd><p>returns a buffer where the document has been saved</p>
573 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]574</dl>
575<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]576 <dt><code>extern void xmlDocDump(FILE *f, xmlDocPtr doc);</code></dt>
577 <dd><p>dumps a buffer to an open file descriptor</p>
578 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]579</dl>
580<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]581 <dt><code>int xmlSaveFile(const char *filename, xmlDocPtr cur);</code></dt>
582 <dd><p>save the document ot a file. In that case the compression interface
583 is triggered if turned on</p>
584 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]585</dl>
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]586
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]587<h3><a name="Compressio">Compression</a></h3>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]588
589<p>The library handle transparently compression when doing file based
590accesses, the level of compression on saves can be tuned either globally or
591individually for one file:</p>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]592<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]593 <dt><code>int xmlGetDocCompressMode (xmlDocPtr doc);</code></dt>
594 <dd><p>Get the document compression ratio (0-9)</p>
595 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]596</dl>
597<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]598 <dt><code>void xmlSetDocCompressMode (xmlDocPtr doc, int mode);</code></dt>
599 <dd><p>Set the document compression ratio</p>
600 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]601</dl>
602<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]603 <dt><code>int xmlGetCompressMode(void);</code></dt>
604 <dd><p>Get the default compression ratio</p>
605 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]606</dl>
607<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]608 <dt><code>void xmlSetCompressMode(int mode);</code></dt>
609 <dd><p>set the default compression ratio</p>
610 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]611</dl>
612
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]613<h2><a name="Entities">Entities or no entities</a></h2>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]614
615<p>Entities principle is similar to simple C macros. They define an
616abbreviation for a given string that you can reuse many time through the
617content of your document. They are especially useful when frequent occurrences
618of a given string may occur within a document or to confine the change needed
619to a document to a restricted area in the internal subset of the document (at
620the beginning). Example:</p>
621<pre>1 &lt;?xml version="1.0"?>
6222 &lt;!DOCTYPE EXAMPLE SYSTEM "example.dtd" [
6233 &lt;!ENTITY xml "Extensible Markup Language">
6244 ]>
6255 &lt;EXAMPLE>
6266 &amp;xml;
Daniel Veillard35008381999-10-25 13:15:52 +0000[diff] [blame]6277 &lt;/EXAMPLE></pre>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]628
629<p>Line 3 declares the xml entity. Line 6 uses the xml entity, by prefixing
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]630it's name with '&amp;' and following it by ';' without any spaces added. There
631are 5 predefined entities in libxml allowing to escape charaters with
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]632predefined meaning in some parts of the xml document content:
633<strong>&amp;lt;</strong> for the letter '&lt;', <strong>&amp;gt;</strong> for
634the letter '>', <strong>&amp;apos;</strong> for the letter ''',
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]635<strong>&amp;quot;</strong> for the letter '"', and <strong>&amp;amp;</strong>
636for the letter '&amp;'.</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]637
638<p>One of the problems related to entities is that you may want the parser to
639substitute entities content to see the replacement text in your application,
640or you may prefer keeping entities references as such in the content to be
641able to save the document back without loosing this usually precious
642information (if the user went through the pain of explicitley defining
643entities, he may have a a rather negative attitude if you blindly susbtitute
644them as saving time). The function <a
645href="gnome-xml-parser.html#XMLSUBSTITUTEENTITIESDEFAULT">xmlSubstituteEntitiesDefault()</a>
646allows to check and change the behaviour, which is to not substitute entities
647by default.</p>
648
649<p>Here is the DOM tree built by libxml for the previous document in the
650default case:</p>
651<pre>/gnome/src/gnome-xml -> ./tester --debug test/ent1
652DOCUMENT
653version=1.0
654 ELEMENT EXAMPLE
655 TEXT
656 content=
657 ENTITY_REF
658 INTERNAL_GENERAL_ENTITY xml
659 content=Extensible Markup Language
660 TEXT
661 content=</pre>
662
663<p>And here is the result when substituting entities:</p>
664<pre>/gnome/src/gnome-xml -> ./tester --debug --noent test/ent1
665DOCUMENT
666version=1.0
667 ELEMENT EXAMPLE
668 TEXT
669 content= Extensible Markup Language</pre>
670
671<p>So entities or no entities ? Basically it depends on your use case, I
672suggest to keep the non-substituting default behaviour and avoid using
673entities in your XML document or data if you are not willing to handle the
674entity references elements in the DOM tree.</p>
675
676<p>Note that at save time libxml enforce the conversion of the predefined
677entities where necessary to prevent well-formedness problems, and will also
678transparently replace those with chars (i.e. will not generate entity
679reference elements in the DOM tree nor call the reference() SAX callback when
680finding them in the input).</p>
681
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]682<h2><a name="Namespaces">Namespaces</a></h2>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]683
684<p>The libxml library implement namespace @@ support by recognizing namespace
685contructs in the input, and does namespace lookup automatically when building
686the DOM tree. A namespace declaration is associated with an in-memory
687structure and all elements or attributes within that namespace point to it.
688Hence testing the namespace is a simple and fast equality operation at the
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]689user level.</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]690
691<p>I suggest it that people using libxml use a namespace, and declare it on
692the root element of their document as the default namespace. Then they dont
693need to happend the prefix in the content but we will have a basis for future
694semantic refinement and merging of data from different sources. This doesn't
695augment significantly the size of the XML output, but significantly increase
696it's value in the long-term.</p>
697
698<p>Concerning the namespace value, this has to be an URL, but this doesn't
699have to point to any existing resource on the Web. I suggest using an URL
700within a domain you control, which makes sense and if possible holding some
701kind of versionning informations. For example
702<code>"http://www.gnome.org/gnumeric/1.0"</code> is a good namespace scheme.
703Then when you load a file, make sure that a namespace carrying the
704version-independant prefix is installed on the root element of your document,
705and if the version information don't match something you know, warn the user
706and be liberal in what you accept as the input. Also do *not* try to base
707namespace checking on the prefix value &lt;foo:text> may be exactly the same
708as &lt;bar:text> in another document, what really matter is the URI
709associated with the element or the attribute, not the prefix string which is
710just a shortcut for the full URI.</p>
711
712<p>@@Interfaces@@</p>
713
714<p>@@Examples@@</p>
715
716<p>Usually people object using namespace in the case of validation, I object
717this and will make sure that using namespaces won't break validity checking,
718so even is you plan or are using validation I strongly suggest to add
719namespaces to your document. A default namespace scheme
720<code>xmlns="http://...."</code> should not break validity even on less
721flexible parsers. Now using namespace to mix and differenciate content coming
722from mutliple Dtd will certainly break current validation schemes, I will try
723to provide ways to do this, but this may not be portable or standardized.</p>
724
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]725<h2><a name="Validation">Validation, or are you afraid of DTDs ?</a></h2>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]726
727<p>Well what is validation and what is a DTD ?</p>
728
729<p>Validation is the process of checking a document against a set of
730construction rules, a <strong>DTD</strong> (Document Type Definition) is such
731a set of rules.</p>
732
733<p>The validation process and building DTDs are the two most difficult parts
734of XML life cycle. Briefly a DTD defines all the possibles element to be
735found within your document, what is the formal shape of your document tree (by
736defining the allowed content of an element, either text, a regular expression
737for the allowed list of children, or mixed content i.e. both text and childs).
738The DTD also defines the allowed attributes for all elements and the types of
739the attributes. For more detailed informations, I suggest to read the related
740parts of the XML specification, the examples found under
741gnome-xml/test/valid/dtd and the large amount of books available on XML. The
742dia example in gnome-xml/test/valid should be both simple and complete enough
743to allow you to build your own.</p>
744
745<p>A word of warning, building a good DTD which will fit your needs of your
746application in the long-term is far from trivial, however the extra level of
747quality it can insure is well worth the price for some sets of applications or
748if you already have already a DTD defined for your application field.</p>
749
750<p>The validation is not completely finished but in a (very IMHO) usable
751state. Until a real validation interface is defined the way to do it is to
752define and set the <strong>xmlDoValidityCheckingDefaultValue</strong> external
753variable to 1, this will of course be changed at some point:</p>
754
755<p>extern int xmlDoValidityCheckingDefaultValue;</p>
756
757<p>...</p>
758
759<p>xmlDoValidityCheckingDefaultValue = 1;</p>
760
761<p></p>
762
763<p>To handle external entities, use the function
764<strong>xmlSetExternalEntityLoader</strong>(xmlExternalEntityLoader f); to
765link in you HTTP/FTP/Entities database library to the standard libxml
766core.</p>
767
768<p>@@interfaces@@</p>
769
Daniel Veillard35008381999-10-25 13:15:52 +0000[diff] [blame]770<h2><a name="DOM"></a><a name="Principles">DOM Principles</a></h2>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]771
772<p><a href="http://www.w3.org/DOM/">DOM</a> stands for the <em>Document Object
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]773Model</em> this is an API for accessing XML or HTML structured documents.
774Native support for DOM in Gnome is on the way (module gnome-dom), and it will
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]775be based on gnome-xml. This will be a far cleaner interface to manipulate XML
Daniel Veillardc08a2c61999-09-08 21:35:25 +0000[diff] [blame]776files within Gnome since it won't expose the internal structure. DOM defines a
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]777set of IDL (or Java) interfaces allowing to traverse and manipulate a
778document. The DOM library will allow accessing and modifying "live" documents
779presents on other programs like this:</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]780
781<p><img src="DOM.gif" alt=" DOM.gif "></p>
782
783<p>This should help greatly doing things like modifying a gnumeric spreadsheet
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]784embedded in a GWP document for example.</p>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]785
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]786<p>The current DOM implementation on top of libxml is the <a
787href="http://cvs.gnome.org/lxr/source/gdome/">gdome Gnome module</a>, this is
788a full DOM interface, thanks to <a href="mailto:raph@levien.com">Raph
789Levien</a>.</p>
790
791<p>The gnome-dom module in the Gnome CVS base is obsolete</p>
792
Daniel Veillard35008381999-10-25 13:15:52 +0000[diff] [blame]793<h2><a name="Example"></a><a name="real">A real example</a></h2>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]794
795<p>Here is a real size example, where the actual content of the application
796data is not kept in the DOM tree but uses internal structures. It is based on
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]797a proposal to keep a database of jobs related to Gnome, with an XML based
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]798storage structure. Here is an <a href="gjobs.xml">XML encoded jobs
799base</a>:</p>
800<pre>&lt;?xml version="1.0"?>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]801&lt;gjob:Helping xmlns:gjob="http://www.gnome.org/some-location">
802 &lt;gjob:Jobs>
803
804 &lt;gjob:Job>
805 &lt;gjob:Project ID="3"/>
806 &lt;gjob:Application>GBackup&lt;/gjob:Application>
807 &lt;gjob:Category>Development&lt;/gjob:Category>
808
809 &lt;gjob:Update>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]810 &lt;gjob:Status>Open&lt;/gjob:Status>
811 &lt;gjob:Modified>Mon, 07 Jun 1999 20:27:45 -0400 MET DST&lt;/gjob:Modified>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]812 &lt;gjob:Salary>USD 0.00&lt;/gjob:Salary>
813 &lt;/gjob:Update>
814
815 &lt;gjob:Developers>
816 &lt;gjob:Developer>
817 &lt;/gjob:Developer>
818 &lt;/gjob:Developers>
819
820 &lt;gjob:Contact>
821 &lt;gjob:Person>Nathan Clemons&lt;/gjob:Person>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]822 &lt;gjob:Email>nathan@windsofstorm.net&lt;/gjob:Email>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]823 &lt;gjob:Company>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]824 &lt;/gjob:Company>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]825 &lt;gjob:Organisation>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]826 &lt;/gjob:Organisation>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]827 &lt;gjob:Webpage>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]828 &lt;/gjob:Webpage>
829 &lt;gjob:Snailmail>
830 &lt;/gjob:Snailmail>
831 &lt;gjob:Phone>
832 &lt;/gjob:Phone>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]833 &lt;/gjob:Contact>
834
835 &lt;gjob:Requirements>
836 The program should be released as free software, under the GPL.
837 &lt;/gjob:Requirements>
838
839 &lt;gjob:Skills>
840 &lt;/gjob:Skills>
841
842 &lt;gjob:Details>
843 A GNOME based system that will allow a superuser to configure
844 compressed and uncompressed files and/or file systems to be backed
845 up with a supported media in the system. This should be able to
846 perform via find commands generating a list of files that are passed
847 to tar, dd, cpio, cp, gzip, etc., to be directed to the tape machine
848 or via operations performed on the filesystem itself. Email
849 notification and GUI status display very important.
850 &lt;/gjob:Details>
851
852 &lt;/gjob:Job>
853
854 &lt;/gjob:Jobs>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]855&lt;/gjob:Helping></pre>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]856
857<p>While loading the XML file into an internal DOM tree is a matter of calling
858only a couple of functions, browsing the tree to gather the informations and
859generate the internals structures is harder, and more error prone.</p>
860
861<p>The suggested principle is to be tolerant with respect to the input
862structure. For example the ordering of the attributes is not significant, Cthe
863XML specification is clear about it. It's also usually a good idea to not be
864dependant of the orders of the childs of a given node, unless it really makes
865things harder. Here is some code to parse the informations for a person:</p>
866<pre>/*
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]867 * A person record
868 */
869typedef struct person {
870 char *name;
871 char *email;
872 char *company;
873 char *organisation;
874 char *smail;
875 char *webPage;
876 char *phone;
877} person, *personPtr;
878
879/*
880 * And the code needed to parse it
881 */
882personPtr parsePerson(xmlDocPtr doc, xmlNsPtr ns, xmlNodePtr cur) {
883 personPtr ret = NULL;
884
885DEBUG("parsePerson\n");
886 /*
887 * allocate the struct
888 */
889 ret = (personPtr) malloc(sizeof(person));
890 if (ret == NULL) {
891 fprintf(stderr,"out of memory\n");
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]892 return(NULL);
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]893 }
894 memset(ret, 0, sizeof(person));
895
896 /* We don't care what the top level element name is */
897 cur = cur->childs;
898 while (cur != NULL) {
899 if ((!strcmp(cur->name, "Person")) &amp;&amp; (cur->ns == ns))
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]900 ret->name = xmlNodeListGetString(doc, cur->childs, 1);
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]901 if ((!strcmp(cur->name, "Email")) &amp;&amp; (cur->ns == ns))
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]902 ret->email = xmlNodeListGetString(doc, cur->childs, 1);
903 cur = cur->next;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]904 }
905
906 return(ret);
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]907}</pre>
908
909<p>Here is a couple of things to notice:</p>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]910<ul>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]911 <li>Usually a recursive parsing style is the more convenient one, XML data
912 being by nature subject to repetitive constructs and usualy exibit highly
913 stuctured patterns.</li>
914 <li>The two arguments of type <em>xmlDocPtr</em> and <em>xmlNsPtr</em>, i.e.
915 the pointer to the global XML document and the namespace reserved to the
916 application. Document wide information are needed for example to decode
917 entities and it's a good coding practice to define a namespace for your
918 application set of data and test that the element and attributes you're
919 analyzing actually pertains to your application space. This is done by a
920 simple equality test (cur->ns == ns).</li>
921 <li>To retrieve text and attributes value, it is suggested to use the
922 function <em>xmlNodeListGetString</em> to gather all the text and entity
923 reference nodes generated by the DOM output and produce an single text
924 string.</li>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]925</ul>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]926
927<p>Here is another piece of code used to parse another level of the
928structure:</p>
929<pre>/*
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]930 * a Description for a Job
931 */
932typedef struct job {
933 char *projectID;
934 char *application;
935 char *category;
936 personPtr contact;
937 int nbDevelopers;
938 personPtr developers[100]; /* using dynamic alloc is left as an exercise */
939} job, *jobPtr;
940
941/*
942 * And the code needed to parse it
943 */
944jobPtr parseJob(xmlDocPtr doc, xmlNsPtr ns, xmlNodePtr cur) {
945 jobPtr ret = NULL;
946
947DEBUG("parseJob\n");
948 /*
949 * allocate the struct
950 */
951 ret = (jobPtr) malloc(sizeof(job));
952 if (ret == NULL) {
953 fprintf(stderr,"out of memory\n");
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]954 return(NULL);
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]955 }
956 memset(ret, 0, sizeof(job));
957
958 /* We don't care what the top level element name is */
959 cur = cur->childs;
960 while (cur != NULL) {
961
962 if ((!strcmp(cur->name, "Project")) &amp;&amp; (cur->ns == ns)) {
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]963 ret->projectID = xmlGetProp(cur, "ID");
964 if (ret->projectID == NULL) {
965 fprintf(stderr, "Project has no ID\n");
966 }
967 }
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]968 if ((!strcmp(cur->name, "Application")) &amp;&amp; (cur->ns == ns))
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]969 ret->application = xmlNodeListGetString(doc, cur->childs, 1);
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]970 if ((!strcmp(cur->name, "Category")) &amp;&amp; (cur->ns == ns))
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]971 ret->category = xmlNodeListGetString(doc, cur->childs, 1);
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]972 if ((!strcmp(cur->name, "Contact")) &amp;&amp; (cur->ns == ns))
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]973 ret->contact = parsePerson(doc, ns, cur);
974 cur = cur->next;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]975 }
976
977 return(ret);
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]978}</pre>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]979
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]980<p>One can notice that once used to it, writing this kind of code is quite
981simple, but boring. Ultimately, it could be possble to write stubbers taking
982either C data structure definitions, a set of XML examples or an XML DTD and
983produce the code needed to import and export the content between C data and
984XML storage. This is left as an exercise to the reader :-)</p>
985
986<p>Feel free to use <a href="gjobread.c">the code for the full C parsing
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]987example</a> as a template, it is also available with Makefile in the Gnome CVS
988base under gnome-xml/example</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]989
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]990<p></p>
991
992<p><a href="mailto:Daniel.Veillard@w3.org">Daniel Veillard</a></p>
993
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame^]994<p>$Id: xml.html,v 1.20 2000/01/05 19:54:23 veillard Exp $</p>
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]995</body>
996</html>