xml.html revision 10c6a8fdde3006c509fa4573bfc4af49a0b2c0a7
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" 2 "http://www.w3.org/TR/REC-html40/loose.dtd"> 3<html> 4<head> 5<title>No title</title> 6<meta name="GENERATOR" content="amaya V1.3b"> 7</head> 8<body bgcolor="#ffffff"> 9 10<h1 align="center">The XML library for Gnome</h1> 11<p> 12This document describes the <a href="http://www.w3.org/XML/">XML</a> library 13provideed in the <a href="http://www.gnome.org/">Gnome</a> framework. XML is a 14standard to build tag based structured documents. The internal document 15repesentation is as close as possible to the <a 16href="http://www.w3.org/DOM/">DOM</a> interfaces.</p> 17 18<h2>xml</h2> 19<p> 20XML is a standard for markup based structured documents, here is <a 21name="example">an example</a>:</p> 22<pre><?xml version="1.0"?> 23<EXAMPLE prop1="gnome is great" prop2="&linux; too"> 24 <head> 25 <title>Welcome to Gnome</title> 26 </head> 27 <chapter> 28 <title>The Linux adventure</title> 29 <p>bla bla bla ...</p> 30 <image href="linus.gif"/> 31 <p>...</p> 32 </chapter> 33</EXAMPLE></pre> 34<p> 35The first line specify that it's an XML document and gives useful informations 36about it's encoding. Then the document is a text format whose structure is 37specified by tags between brackets. <strong>Each tag opened have to be 38closed</strong> XML is pedantic about this, not that for example the image 39tage has no content (just an attribute) and is closed by ending up the tag 40with <code>/></code>.</p> 41 42<h2>The tree output</h2> 43<p> 44The parser returns a tree built during the document analysis. The value 45returned is an <strong>xmlDocPtr</strong> (i.e. a pointer to an 46<strong>xmlDoc</strong> structure). This structure contains informations like 47the file name, the document type, and a <strong>root</strong> pointer which 48is the root of the document (or more exactly the first child under the root 49which is the document). The tree is made of <strong>xmlNode</strong>s, chained 50in double linked lists of siblings and with childs<->parent relationship. 51An xmlNode can also carry properties (a chain of xmlAttr structures). An 52attribute may have a value which is a list of TEXT or ENTITY_REF nodes.</p> 53<p> 54Here is an example (erroneous w.r.t. the XML spec since there should be only 55one ELEMENT under the root):</p> 56<p> 57<img src="structure.gif" alt=" structure.gif "></p> 58<p> 59In the source package there is a small program (not installed by default) 60called <strong>tester</strong> which parses XML files given as argument and 61prints them back as parsed, this is useful to detect errors both in XML code 62and in the XML parser itself. It has an option <strong>--debug</strong> which 63prints the actual in-memory structure of the document, here is the result with 64the <a href="#example">example</a> given before:</p> 65<pre>DOCUMENT 66version=1.0 67standalone=true 68 ELEMENT EXAMPLE 69 ATTRIBUTE prop1 70 TEXT 71 content=gnome is great 72 ATTRIBUTE prop2 73 ENTITY_REF 74 TEXT 75 content= too 76 ELEMENT head 77 ELEMENT title 78 content=Welcome to Gnome 79 ELEMENT chapter 80 ELEMENT title 81 content=The Linux adventure 82 ELEMENT p 83 content=bla bla bla ... 84 ELEMENT image 85 ATTRIBUTE href 86 TEXT 87 content=linus.gif 88 ELEMENT p 89 content=...</pre> 90<p> 91This should be useful to learn the internal representation model.</p> 92 93<h2>The XML library interfaces</h2> 94<p> 95This section is directly intended to help programmers getting bootstrapped 96using the XML library from the C language. It doesn't intent to be extensive, 97I hope the automatically generated docs will provide the completeness 98required, but as a separated set of documents. The interfaces of the XML 99library are by principle low level, there is nearly zero abstration. Those 100interested in a higher level API should <a href="#DOM">look at DOM</a> 101(unfortunately not completed).</p> 102 103<h3>Invoking the parser</h3> 104<p> 105Usually, the first thing to do is to read an XML input, the parser accepts to 106parse both memory mapped documents or direct files. The functions are defined 107in "parser.h":</p> 108<dl> 109<dt>xmlDocPtr xmlParseMemory(char *buffer, int size);</dt> 110<dd><p> 111parse a zero terminated string containing the document</p> 112</dd> 113</dl> 114<dl> 115<dt>xmlDocPtr xmlParseFile(const char *filename);</dt> 116<dd><p> 117parse an XML document contained in a file (possibly compressed)</p> 118</dd> 119</dl> 120<p> 121 This returns a pointer to the document structure (or NULL in case of 122failure).</p> 123<p> 124A couple of comments can be made, first this mean that the parser is 125memory-hungry, first to load the document in memory, second to build the tree. 126Reading a document without building the tree will be possible in the future by 127pluggin the code to the SAX interface (see SAX.c).</p> 128 129<h3>Traversing the tree</h3> 130<p> 131Basically by including "tree.h" your code has access to the internal structure 132of all the element of the tree. The names should be somewhat simple like 133<strong>parent</strong>, <strong>childs</strong>, <strong>next</strong>, 134<strong>prev</strong>, <strong>properties</strong>, etc... </p> 135 136<h3>Modifying the tree</h3> 137 138<h3>Saving a tree</h3> 139 140<h2><a name="DOM">DOM interfaces</a></h2> 141<p> 142<a href="http://www.w3.org/DOM/">DOM</a> stands for the <em>Document Object 143Model</em> this is an API for accessing XML or HTML structured documents. 144Native support for DOM in Gnome is on the way (module gnome-dom), and it will 145be based on gnome-xml. DOM defiles a set of IDL (or Java) interfaces allowing 146to traverse and manipulate a document. The DOM library will allow accessing 147and modifying "live" documents presents on other programs like this:</p> 148<p> 149<img src="DOM.gif" alt=" DOM.gif "></p> 150<p> 151This should help greatly doing things like modifying a gnumeric spreadsheet 152embedded in a GWP document for example.</p> 153<p> 154</p> 155</body> 156</html> 157
