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

blob: ff49607a54f4fff41ef7b4b0e6f755437885ff94 [file] [log] [blame]

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