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

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