Blame - doc/example.html - platform/external/libxml2

blob: 21f2249d8c574731e0fc7c512cd69e9668ce9225 [file] [log] [blame]

Daniel Veillard	43d3f61	2001-11-10 11:57:23 +0000	[diff] [blame]	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	2	<html>
				3	<head>
				4	<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
Daniel Veillard	c332dab	2002-03-29 14:08:27 +0000	[diff] [blame]	5	<link rel="SHORTCUT ICON" href="/favicon.ico">
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	6	<style type="text/css"><!--
Daniel Veillard	373a475	2002-02-21 14:46:29 +0000	[diff] [blame]	7	TD {font-family: Verdana,Arial,Helvetica}
				8	BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}
				9	H1 {font-family: Verdana,Arial,Helvetica}
				10	H2 {font-family: Verdana,Arial,Helvetica}
				11	H3 {font-family: Verdana,Arial,Helvetica}
Daniel Veillard	b8cfbd1	2001-10-25 10:53:28 +0000	[diff] [blame]	12	A:link, A:visited, A:active { text-decoration: underline }
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	13	--></style>
				14	<title>A real example</title>
				15	</head>
				16	<body bgcolor="#8b7765" text="#000000" link="#000000" vlink="#000000">
				17	<table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr>
				18	<td width="180">
				19	<a href="http://www.gnome.org/"><img src="smallfootonly.gif" alt="Gnome Logo"></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo"></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo"></a>
				20	</td>
				21	<td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center">
				22	<h1>The XML C library for Gnome</h1>
				23	<h2>A real example</h2>
				24	</td></tr></table></td></tr></table></td>
				25	</tr></table>
				26	<table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr>
Daniel Veillard	594cf0b	2001-10-25 08:09:12 +0000	[diff] [blame]	27	<td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td>
				28	<table width="100%" border="0" cellspacing="1" cellpadding="3">
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	29	<tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr>
Daniel Veillard	8acca11	2002-01-21 09:52:27 +0000	[diff] [blame]	30	<tr><td bgcolor="#fffacd"><ul>
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	31	<li><a href="index.html">Home</a></li>
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	32	<li><a href="intro.html">Introduction</a></li>
Daniel Veillard	b8cfbd1	2001-10-25 10:53:28 +0000	[diff] [blame]	33	<li><a href="FAQ.html">FAQ</a></li>
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	34	<li><a href="docs.html">Documentation</a></li>
				35	<li><a href="bugs.html">Reporting bugs and getting help</a></li>
				36	<li><a href="help.html">How to help</a></li>
				37	<li><a href="downloads.html">Downloads</a></li>
				38	<li><a href="news.html">News</a></li>
Daniel Veillard	7b602b4	2002-01-08 13:26:00 +0000	[diff] [blame]	39	<li><a href="XMLinfo.html">XML</a></li>
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	40	<li><a href="XSLT.html">XSLT</a></li>
Daniel Veillard	6dbcaf8	2002-02-20 14:37:47 +0000	[diff] [blame]	41	<li><a href="python.html">Python and bindings</a></li>
Daniel Veillard	b8cfbd1	2001-10-25 10:53:28 +0000	[diff] [blame]	42	<li><a href="architecture.html">libxml architecture</a></li>
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	43	<li><a href="tree.html">The tree output</a></li>
				44	<li><a href="interface.html">The SAX interface</a></li>
Daniel Veillard	b8cfbd1	2001-10-25 10:53:28 +0000	[diff] [blame]	45	<li><a href="xmldtd.html">Validation & DTDs</a></li>
				46	<li><a href="xmlmem.html">Memory Management</a></li>
				47	<li><a href="encoding.html">Encodings support</a></li>
				48	<li><a href="xmlio.html">I/O Interfaces</a></li>
				49	<li><a href="catalog.html">Catalog support</a></li>
				50	<li><a href="library.html">The parser interfaces</a></li>
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	51	<li><a href="entities.html">Entities or no entities</a></li>
				52	<li><a href="namespaces.html">Namespaces</a></li>
Daniel Veillard	b8cfbd1	2001-10-25 10:53:28 +0000	[diff] [blame]	53	<li><a href="upgrade.html">Upgrading 1.x code</a></li>
Daniel Veillard	52dcab3	2001-10-30 12:51:17 +0000	[diff] [blame]	54	<li><a href="threads.html">Thread safety</a></li>
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	55	<li><a href="DOM.html">DOM Principles</a></li>
				56	<li><a href="example.html">A real example</a></li>
				57	<li><a href="contribs.html">Contributions</a></li>
Daniel Veillard	594cf0b	2001-10-25 08:09:12 +0000	[diff] [blame]	58	<li>
				59	<a href="xml.html">flat page</a>, <a href="site.xsl">stylesheet</a>
				60	</li>
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	61	</ul></td></tr>
Daniel Veillard	594cf0b	2001-10-25 08:09:12 +0000	[diff] [blame]	62	</table>
				63	<table width="100%" border="0" cellspacing="1" cellpadding="3">
Daniel Veillard	3bf65be	2002-01-23 12:36:34 +0000	[diff] [blame]	64	<tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>API Indexes</b></center></td></tr>
				65	<tr><td bgcolor="#fffacd"><ul>
Daniel Veillard	f859256	2002-01-23 17:58:17 +0000	[diff] [blame]	66	<li><a href="APIchunk0.html">Alphabetic</a></li>
Daniel Veillard	3bf65be	2002-01-23 12:36:34 +0000	[diff] [blame]	67	<li><a href="APIconstructors.html">Constructors</a></li>
				68	<li><a href="APIfunctions.html">Functions/Types</a></li>
				69	<li><a href="APIfiles.html">Modules</a></li>
				70	<li><a href="APIsymbols.html">Symbols</a></li>
				71	</ul></td></tr>
				72	</table>
				73	<table width="100%" border="0" cellspacing="1" cellpadding="3">
Daniel Veillard	594cf0b	2001-10-25 08:09:12 +0000	[diff] [blame]	74	<tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr>
Daniel Veillard	8acca11	2002-01-21 09:52:27 +0000	[diff] [blame]	75	<tr><td bgcolor="#fffacd"><ul>
Daniel Veillard	594cf0b	2001-10-25 08:09:12 +0000	[diff] [blame]	76	<li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li>
				77	<li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li>
Daniel Veillard	4a85920	2002-01-08 11:49:22 +0000	[diff] [blame]	78	<li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li>
Daniel Veillard	2d347fa	2002-03-17 10:34:11 +0000	[diff] [blame]	79	<li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li>
Daniel Veillard	594cf0b	2001-10-25 08:09:12 +0000	[diff] [blame]	80	<li><a href="ftp://xmlsoft.org/">FTP</a></li>
				81	<li><a href="http://www.fh-frankfurt.de/~igor/projects/libxml/">Windows binaries</a></li>
Daniel Veillard	db9dfd9	2001-11-26 17:25:02 +0000	[diff] [blame]	82	<li><a href="http://garypennington.net/libxml2/">Solaris binaries</a></li>
Daniel Veillard	2d347fa	2002-03-17 10:34:11 +0000	[diff] [blame]	83	<li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml&product=libxml2">Bug Tracker</a></li>
Daniel Veillard	594cf0b	2001-10-25 08:09:12 +0000	[diff] [blame]	84	</ul></td></tr>
				85	</table>
				86	</td></tr></table></td>
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	87	<td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd">
				88	<p>Here is a real size example, where the actual content of the application
				89	data is not kept in the DOM tree but uses internal structures. It is based on
				90	a proposal to keep a database of jobs related to Gnome, with an XML based
				91	storage structure. Here is an <a href="gjobs.xml">XML encoded jobs
				92	base</a>:</p>
				93	<pre><?xml version="1.0"?>
				94	<gjob:Helping xmlns:gjob="http://www.gnome.org/some-location">
				95	<gjob:Jobs>
				96
				97	<gjob:Job>
				98	<gjob:Project ID="3"/>
				99	<gjob:Application>GBackup</gjob:Application>
				100	<gjob:Category>Development</gjob:Category>
				101
				102	<gjob:Update>
				103	<gjob:Status>Open</gjob:Status>
				104	<gjob:Modified>Mon, 07 Jun 1999 20:27:45 -0400 MET DST</gjob:Modified>
				105	<gjob:Salary>USD 0.00</gjob:Salary>
				106	</gjob:Update>
				107
				108	<gjob:Developers>
				109	<gjob:Developer>
				110	</gjob:Developer>
				111	</gjob:Developers>
				112
				113	<gjob:Contact>
				114	<gjob:Person>Nathan Clemons</gjob:Person>
				115	<gjob:Email>nathan@windsofstorm.net</gjob:Email>
				116	<gjob:Company>
				117	</gjob:Company>
				118	<gjob:Organisation>
				119	</gjob:Organisation>
				120	<gjob:Webpage>
				121	</gjob:Webpage>
				122	<gjob:Snailmail>
				123	</gjob:Snailmail>
				124	<gjob:Phone>
				125	</gjob:Phone>
				126	</gjob:Contact>
				127
				128	<gjob:Requirements>
				129	The program should be released as free software, under the GPL.
				130	</gjob:Requirements>
				131
				132	<gjob:Skills>
				133	</gjob:Skills>
				134
				135	<gjob:Details>
				136	A GNOME based system that will allow a superuser to configure
				137	compressed and uncompressed files and/or file systems to be backed
				138	up with a supported media in the system. This should be able to
				139	perform via find commands generating a list of files that are passed
				140	to tar, dd, cpio, cp, gzip, etc., to be directed to the tape machine
				141	or via operations performed on the filesystem itself. Email
				142	notification and GUI status display very important.
				143	</gjob:Details>
				144
				145	</gjob:Job>
				146
				147	</gjob:Jobs>
				148	</gjob:Helping></pre>
				149	<p>While loading the XML file into an internal DOM tree is a matter of
MST 2002 John Fleck	823e5b2	2002-04-03 03:28:57 +0000	[diff] [blame]	150	calling only a couple of functions, browsing the tree to gather the data and
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	151	generate the internal structures is harder, and more error prone.</p>
				152	<p>The suggested principle is to be tolerant with respect to the input
				153	structure. For example, the ordering of the attributes is not significant,
				154	the XML specification is clear about it. It's also usually a good idea not to
				155	depend on the order of the children of a given node, unless it really makes
				156	things harder. Here is some code to parse the information for a person:</p>
				157	<pre>/*
				158	* A person record
				159	*/
				160	typedef struct person {
				161	char *name;
				162	char *email;
				163	char *company;
				164	char *organisation;
				165	char *smail;
				166	char *webPage;
				167	char *phone;
				168	} person, *personPtr;
				169
				170	/*
				171	* And the code needed to parse it
				172	*/
				173	personPtr parsePerson(xmlDocPtr doc, xmlNsPtr ns, xmlNodePtr cur) {
				174	personPtr ret = NULL;
				175
				176	DEBUG("parsePerson\n");
				177	/*
				178	* allocate the struct
				179	*/
				180	ret = (personPtr) malloc(sizeof(person));
				181	if (ret == NULL) {
				182	fprintf(stderr,"out of memory\n");
				183	return(NULL);
				184	}
				185	memset(ret, 0, sizeof(person));
				186
				187	/* We don't care what the top level element name is */
				188	cur = cur->xmlChildrenNode;
				189	while (cur != NULL) {
				190	if ((!strcmp(cur->name, "Person")) && (cur->ns == ns))
				191	ret->name = xmlNodeListGetString(doc, cur->xmlChildrenNode, 1);
				192	if ((!strcmp(cur->name, "Email")) && (cur->ns == ns))
				193	ret->email = xmlNodeListGetString(doc, cur->xmlChildrenNode, 1);
				194	cur = cur->next;
				195	}
				196
				197	return(ret);
				198	}</pre>
				199	<p>Here are a couple of things to notice:</p>
				200	<ul>
				201	<li>Usually a recursive parsing style is the more convenient one: XML data
				202	is by nature subject to repetitive constructs and usually exibits highly
				203	stuctured patterns.</li>
				204	<li>The two arguments of type <em>xmlDocPtr</em> and <em>xmlNsPtr</em>,
				205	i.e. the pointer to the global XML document and the namespace reserved to
				206	the application. Document wide information are needed for example to
				207	decode entities and it's a good coding practice to define a namespace for
				208	your application set of data and test that the element and attributes
				209	you're analyzing actually pertains to your application space. This is
				210	done by a simple equality test (cur->ns == ns).</li>
				211	<li>To retrieve text and attributes value, you can use the function
				212	<em>xmlNodeListGetString</em> to gather all the text and entity reference
				213	nodes generated by the DOM output and produce an single text string.</li>
				214	</ul>
				215	<p>Here is another piece of code used to parse another level of the
				216	structure:</p>
				217	<pre>#include <libxml/tree.h>
				218	/*
				219	* a Description for a Job
				220	*/
				221	typedef struct job {
				222	char *projectID;
				223	char *application;
				224	char *category;
				225	personPtr contact;
				226	int nbDevelopers;
				227	personPtr developers[100]; /* using dynamic alloc is left as an exercise */
				228	} job, *jobPtr;
				229
				230	/*
				231	* And the code needed to parse it
				232	*/
				233	jobPtr parseJob(xmlDocPtr doc, xmlNsPtr ns, xmlNodePtr cur) {
				234	jobPtr ret = NULL;
				235
				236	DEBUG("parseJob\n");
				237	/*
				238	* allocate the struct
				239	*/
				240	ret = (jobPtr) malloc(sizeof(job));
				241	if (ret == NULL) {
				242	fprintf(stderr,"out of memory\n");
				243	return(NULL);
				244	}
				245	memset(ret, 0, sizeof(job));
				246
				247	/* We don't care what the top level element name is */
				248	cur = cur->xmlChildrenNode;
				249	while (cur != NULL) {
				250
				251	if ((!strcmp(cur->name, "Project")) && (cur->ns == ns)) {
				252	ret->projectID = xmlGetProp(cur, "ID");
				253	if (ret->projectID == NULL) {
				254	fprintf(stderr, "Project has no ID\n");
				255	}
				256	}
				257	if ((!strcmp(cur->name, "Application")) && (cur->ns == ns))
				258	ret->application = xmlNodeListGetString(doc, cur->xmlChildrenNode, 1);
				259	if ((!strcmp(cur->name, "Category")) && (cur->ns == ns))
				260	ret->category = xmlNodeListGetString(doc, cur->xmlChildrenNode, 1);
				261	if ((!strcmp(cur->name, "Contact")) && (cur->ns == ns))
				262	ret->contact = parsePerson(doc, ns, cur);
				263	cur = cur->next;
				264	}
				265
				266	return(ret);
				267	}</pre>
				268	<p>Once you are used to it, writing this kind of code is quite simple, but
				269	boring. Ultimately, it could be possble to write stubbers taking either C
				270	data structure definitions, a set of XML examples or an XML DTD and produce
				271	the code needed to import and export the content between C data and XML
				272	storage. This is left as an exercise to the reader :-)</p>
				273	<p>Feel free to use <a href="example/gjobread.c">the code for the full C
				274	parsing example</a> as a template, it is also available with Makefile in the
				275	Gnome CVS base under gnome-xml/example</p>
Daniel Veillard	3f4c40f	2002-02-13 09:19:28 +0000	[diff] [blame]	276	<p><a href="bugs.html">Daniel Veillard</a></p>
Daniel Veillard	c948420	2001-10-24 12:35:52 +0000	[diff] [blame]	277	</td></tr></table></td></tr></table></td></tr></table></td>
				278	</tr></table></td></tr></table>
				279	</body>
				280	</html>