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

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