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