[JDEV] *Real* element.h usage doc

[dsmith at ai.uwf.edu]

Hey.. 

Sorry about that other unfinished email..hit the wrong button. :)
Here's the real usage doc:

--


The element.h header provides a data type <element>,  and operations (element_*)for
manipulating a parsed XML stream.

The base type <element> represent an atomic chunk of a XML stream. It
may be one of three types: 
1.) Tag 
2.) Attribute
3.) CDATA

Internally, each <element> type maintains a series of pointers that
represent the location of the element in the XML stream's
hierarchy. To understand how to use the <element> type and associated
operations, let's parse some sample XML streams.

We'll use the following notation to represent the element in-memory:

Element(type: <type>
	name: <name>, data: <data>, 
	children: <element>, 
	next: <element>,
	previous: <element>)

--------------------------------------------------------------------
Example 1: A login packet

Consider the following XML stream:
<login>
	<user>dave</user>
	<pass>dude</pass>
	<nick>mellow</nick>
</login>

Once parsed, we'll wind up with the following (in a more compact form
within memory):

Element(type: ETYPE_TAG
	name: "login", data: NULL,
	children(
		Element(type: ETYPE_TAG
			name: "user", data NULL,
			Children( 
				Element(type: ETYPE_CDATA
					name: NULL, data: "dave")))
		Element(type: ETYPE_TAG
			name: "pass", data NULL,
			Children(
				Element(type: ETYPE_CDATA
					name: NULL, data: "dude")))
		Element(type: ETYPE_TAG
			name: "nick", data NULL,
			Children(
				Element(type: ETYPE_CDATA
					name: NULL, data: "mellow")))
	))

As you can see, a hierarchy representing the stream is
formed. Assume the a variable called "root_tag" contains the root of
the hierarchy. To access the nick name CDATA element, you would make
the following calls:

	/* Retrieve element by name of "nick" */
	element nick_tag = element_get_child(root_tag, "nick"); 

	/* Retrieve first child of nick_tag (since name is not specified) */
	element nick_tag_CDATA = element_get_child(nick_tag, "");

	/* Retrieve data in CDATA element; must cast to char* since it may
	   contain any type of data */
	char* nickname = (char*)element_data(nick_tag_CDATA)

	/* nickname == "mellow" */

Obviously, this is a drawn out approach. However, it demonstrates the
way that CDATA elements are not an actual part of the tag, but rather
a full-blown sub-element. This approach is necessary since a given tag 
may have multiple CDATA sections seperated by other sub-tags. This
will be demonstrated later on.

Since it is fairly common to have tags which only have one unbroken
CDATA section, a shortcut method is provided that retrieves the CDATA
in one call:

	char* nickname = element_get_child_cdata(root_tag, "nick"); 
	/* nickname == "mellow" */

This searches the root_tag for an element by the name of "nick" and
sees if it (the element named "nick") has a CDATA as the first child. 

more later...

D.