cgi/html_tree.h File Reference

HTML DOM tree support functions. More...

#include <stdio.h>

Functions
TAG *	createElement ()
	Create empty DOM node.
TAG *	createTextNode ()
	Create empty text DOM node.
TAG *	appendChild (TAG *, TAG *)
	Append child.
TAG *	appendSibling (TAG *, TAG *)
	Append sibling.
void	removeSibling (TAG *, TAG *)
	Remove sibling.
void	removeChild (TAG *, TAG *)
	Remove b from a's children list.
void	deleteNode (TAG *)
	Delete node.
void	deleteTree (TAG *)
	Delete tree.
TAG *	findBack (TAG *, char *)
	Reverse find tree node.
TAG *	findBackPlain (TAG *, char *)
	Reverse find tree node.
TAG *	findPrev (TAG *)
	Find tree node.
TAG *	copyTree (TAG *a)
	Copy tree.
TAG *	copyBranch (TAG *a)
	Copy branch.
TAG *	copyNode (TAG *a)
	Copy node.
void	dumpTree (TAG *, FILE *)
	Construct document from tree.
TAG *	findNode (TAG *a, char *name)
	Find tree node.
TAG *	findNext (TAG *a)
	Find tree node.
TAG *	findNextPlain (TAG *a)
	Find tree node.
TAG *	insertAfter (TAG *, TAG *)
	Insert node after given node.
TAG *	insertBefore (TAG *, TAG *)
	Insert node before given node.
TAG *	extractFrom (TAG *)
	Extract tree.
TAG *	replaceNode (TAG *, TAG *)
	Replace node.
TAG *	recurseNodes (TAG *)
	Recursively walk through all nodes.
TAG *	getElementById (TAG *, char *)
	Find element with given ID.
char *	getAttribute (TAG *, char *)
	Get element's attribute with given name.
void	setAttribute (TAG *, char *, char *)
	Set element's attribute with given name.
void	removeAttribute (TAG *, char *)
	Remove element's attribute with given name.

---

Detailed Description

HTML DOM tree support functions.

Author:

Vladimir Pavluk, 2006-2007

HTML DOM tree is an object model of the document, where each tag is represented by corresponding tree node. HTML DOM is widely used to access document elements in JavaScript in client-side scripting.

However, I thought it would be convenient sometimes to have access to the document's DOM tree on the server side. This file contains functions and structures to enable one to access HTML DOM tree from CGI script.

---

Function Documentation

TAG* appendChild	(	TAG *	a,
		TAG *	b
	)

Append child.

Appends child node to the DOM node. The child is appended into the end of list of children.

Parameters:

	a	parent node.
	b	node to attach.

Returns:

attached node.

TAG* appendSibling	(	TAG *	a,
		TAG *	b
	)

Append sibling.

Appends sibling node to the DOM node. The child is appended into the end of list of children.

Parameters:

	a	node to attach to.
	b	node to attach.

Returns:

attached node.

TAG* copyBranch

(

TAG *

a

)

Copy branch.

Acts the same way as copyTree, but copies only tree without siblings.

Parameters:

a

starting node to copy.

Returns:

copied branch on success, or NULL if failed.

TAG* copyNode

(

TAG *

a

)

Copy node.

Creates and returns full copy of given node.

Parameters:

a

node to copy.

Returns:

node copy.

TAG* copyTree

(

TAG *

a

)

Copy tree.

Acts the same way as copyNode, but copies the whole tree along with siblings.

Parameters:

a

starting node to copy.

Returns:

copied tree on success, or NULL if failed.

TAG* createElement

(

)

Create empty DOM node.

Creates empty DOM node.

Returns:

empty DOM node (TAG *).

TAG* createTextNode

(

)

Create empty text DOM node.

Creates empty text DOM node.

Returns:

empty DOM text node (TAG *).

void deleteNode

(

TAG *

a

)

Delete node.

Deletes node and frees associated memory.

Parameters:

a

node to delete.

void deleteTree

(

TAG *

a

)

Delete tree.

Deletes the whole tree and frees associated memory.

Parameters:

a

starting tree node.

void dumpTree	(	TAG *	root,
		FILE *	out
	)

Construct document from tree.

Constructs document from tree and dumps it to the output stream.

Parameters:

	root	tree root node.
	out	output stream.

TAG* extractFrom

(

TAG *

a

)

Extract tree.

Extracts tree/child nodes from given node.

Parameters:

a

node to extract from.

Returns:

extracted node.

TAG* findBack	(	TAG *	a,
		char *	name
	)

Reverse find tree node.

Searches for the first node with given tag name in reverse direction.

Parameters:

	a	node to start search from.
	name	tag name.

Returns:

found node on success, or NULL if failed.

TAG* findBackPlain	(	TAG *	a,
		char *	name
	)

Reverse find tree node.

Searches current level for the first node with given tag name in reverse direction. Processes only siblings, but not child nodes.

Parameters:

	a	node to start search from.
	name	tag name.

Returns:

found node on success, or NULL if failed.

TAG* findNext

(

TAG *

a

)

Find tree node.

Searches tree for the next node with given tag name.

Parameters:

a

previous found node with given tag name.

Returns:

found node on success, or NULL if failed.

TAG* findNextPlain

(

TAG *

a

)

Find tree node.

Searches current level for the next node with given tag name. Processes only siblings, but not child nodes.

Parameters:

a

previous found node with given tag name.

Returns:

found node on success, or NULL if failed.

TAG* findNode	(	TAG *	a,
		char *	name
	)

Find tree node.

Searches tree for the first node with given tag name.

Parameters:

	a	node to start search from.
	name	tag name.

Returns:

found node on success, or NULL if failed.

TAG* findPrev

(

TAG *

a

)

Find tree node.

Searches tree for the previous node with given tag name.

Parameters:

a

previous found node with given tag name.

Returns:

found node on success, or NULL if failed.

char* getAttribute	(	TAG *	a,
		char *	name
	)

Get element's attribute with given name.

Returns element's attribute with given name.

Parameters:

	a	node.
	name	attribute name.

Returns:

attribute string on success, NULL if not found.

TAG* getElementById	(	TAG *	node,
		char *	id
	)

Find element with given ID.

Searches document for the element with given ID attribute.

Parameters:

	node	tree root node.
	id	id to search for.

Returns:

found node upon success, NULL if failed.

TAG* insertAfter	(	TAG *	a,
		TAG *	b
	)

Insert node after given node.

Inserts node after given node.

Parameters:

	a	node after which to insert.
	b	node to insert.

Returns:

inserted node on success, or NULL if failed.

TAG* insertBefore	(	TAG *	a,
		TAG *	b
	)

Insert node before given node.

Inserts node before given node.

Parameters:

	a	node before which to insert.
	b	node to insert.

Returns:

inserted node on success, or NULL if failed.

TAG* recurseNodes

(

TAG *

a

)

Recursively walk through all nodes.

Subsequently returns nodes as they appear in tree. When there are no more nodes, NULL is returned.

Parameters:

a

node to start.

Returns:

next node, or NULL if there are no more nodes.

void removeAttribute	(	TAG *	a,
		char *	name
	)

Remove element's attribute with given name.

Removes element's attribute with given name.

Parameters:

	a	node.
	name	attribute name.

void removeChild	(	TAG *	a,
		TAG *	b
	)

Remove b from a's children list.

Remove element b from a's children list.

Parameters:

	a	node to delete from.
	b	node to delete.

void removeSibling	(	TAG *	a,
		TAG *	b
	)

Remove sibling.

Removes sibling node from the DOM node.

Parameters:

	a	node for which the sibling is deleted.
	b	node to delete.

TAG* replaceNode	(	TAG *	a,
		TAG *	b
	)

Replace node.

Replaces node with another node.

Parameters:

	a	node to replace.
	b	node to replace with.

Returns:

new node.

void setAttribute	(	TAG *	a,
		char *	name,
		char *	value
	)

Set element's attribute with given name.

Sets element's attribute with given name. If attribute does not exist, it is created first.

Parameters:

	a	node.
	name	attribute name.
	value	attribute value.