XLX.h File Reference

Public definitions for the XLX (XML parser) package. More...

Classes
struct	_XLX_basic_tag
	Structure descibing a basic XML tag with a name and a pointer to a function used to parse PCDATA. More...
struct	_XLX_parent_tag
	Tag structure specifying the possible contents of this tag and any additional actions to be performed when the tag is entered. More...
struct	_XLX_stack
	Structure to hold stack control information. More...
struct	_XLX_state
	Current state of the parsing - stack pointing to current element and address of leaf on the configuration tree. More...
Typedefs
typedef struct _XLX_state	XLX_state
	Forward declaration of the state structure.
typedef void(*	XLX_pDoctype )(XLX_state *state, const char *type, const char *sysId, const char *pubId, int intSubset)
	Pointer to function called to process a doctype declaration.
typedef void(*	XLX_pChar )(XLX_state *state, const char *data, int leng)
	Pointer to function called to perform unique actions on character data.
typedef void(*	XLX_pEnter )(XLX_state *state, const char **attr)
	Pointer to function called to perform additional (attribute parsing) actions on entry to a tag.
typedef void(*	XLX_pExit )(XLX_state *state)
	Pointer to function called to perform additional actions on exit from a tag.
typedef void(*	XLX_pDelete )(void *user)
	Pointer to function to use to destroy elements on the stack.
typedef struct _XLX_basic_tag	XLX_basic_tag
	Structure descibing a basic XML tag with a name and a pointer to a function used to parse PCDATA.
typedef struct _XLX_parent_tag	XLX_parent_tag
	Tag structure specifying the possible contents of this tag and any additional actions to be performed when the tag is entered.
typedef struct _XLX_stack	XLX_stack
	Structure to hold stack control information.
Enumerations
enum	xlxType {   XLX_BASIC = 0,   XLX_PARENT = 1,   N_XTYPES = 2 }
	Enumeration used to extend the types of tag available.
enum	xlxSelf {   XLX_NON_RECURSIVE = 0,   XLX_RECURSIVE = 1 }
	Enumeration used to indicate if the tag can contain itself.
Functions
void	XLX_attrError (XLX_state *state, const char *func, const char *name)
	Report missing attribute error.
void	XLX_attrValError (XLX_state *state, const char *func, const char *name)
	Report invalid attribute value error.
void	XLX_character_noop (XLX_state *state, const char *element, int len)
	No-op character element handler.
void	XLX_character_tag (XLX_state *state, const char *element, int len)
	Handle a character element inside a parent tag by delegating the work to the first child.
void	XLX_destroyStack (XLX_stack *stack, XLX_pDelete dFn)
	Free the memory allocated to a stack and its elements.
void	XLX_dispFileName (XLX_state *state, const char *func)
	Display the name of the current file being parsed.
void	XLX_dump (XLX_stack *stack)
	Print out the stack information.
void	XLX_endStack (XLX_stack *stack)
	Free the memory allocated to a stack.
void	XLX_enter_noop (XLX_state *state, const char **attribute)
	No-op enter element handler.
void	XLX_exit_noop (XLX_state *state)
	No-op exit element handler.
int	XLX_getAttribute (const char **attribute, const char *name, int *value)
	Find a named attribute in an attribute list.
int	XLX_getLineNum (XLX_state *state)
	Get the current line number.
int	XLX_initStack (XLX_stack *stack, unsigned int limit)
	Initialise a stack.
int	XLX_initState (XLX_state *state, unsigned int stackLimit, void *stackSeed, XLX_pDoctype doctype, XLX_pEnter enter, XLX_pExit exit, XLX_pChar character, int verbose)
	Initialise the state of the parser.
int	XLX_ischar (const char *string, unsigned int len)
	Test a string for valid characters.
int	XLX_isEnabled (const char **attribute, int *enabled)
	Reads the attribute list and sets enabled accordingly.
int	XLX_parse (const char *filename, XLX_state *pState)
	Parse an XML file.
void *	XLX_peek (XLX_stack *stack, unsigned int depth)
	Look at an item on a stack without removing it.
void *	XLX_pop (XLX_stack *stack)
	Remove and return the top item on a stack.
int	XLX_push (XLX_stack *stack, void *ptr)
	Put a new item on the top of a stack.
int	XLX_strtoi (const char *string, unsigned int len, int *value)
	Convert a string to a signed 32-bit integer.
int	XLX_strtoll (const char *string, unsigned int len, long long *value)
	Convert a string to a signed 64-bit integer.
int	XLX_strtou (const char *string, unsigned int len, unsigned int *value)
	Convert a string to an unsigned 32-bit integer.
int	XLX_strtoull (const char *string, unsigned int len, unsigned long long *value)
	Convert a string to an unsigned 64-bit integer.
void	XLX_valError (XLX_state *state, const char *func, const char *string, unsigned int len)
	Report value string to be in error.

---

Detailed Description

Public definitions for the XLX (XML parser) package.

Author:

James Swain & Owen Saxton

Id

XLX.h,v 1.5 2007/10/08 19:27:31 saxton Exp

---

Function Documentation

void XLX_attrError	(	XLX_state *	state,
		const char *	func,
		const char *	name
	)

Report missing attribute error.

This routine displays the name of the missing attribute, along with the line number in and the name of the file being parsed.

Parameters:

	state	Current parse state
	func	Name of function reporting the error
	name	Attribute name

References _XLX_state::parser, _XLX_state::verbose, and XLX_dispFileName().

void XLX_attrValError	(	XLX_state *	state,
		const char *	func,
		const char *	name
	)

Report invalid attribute value error.

This routine displays the name of the attribute, along with the line number in and the name of the file being parsed.

Parameters:

	state	Current parse state
	func	Name of function reporting the error
	name	Attribute name

References _XLX_state::parser, _XLX_state::verbose, and XLX_dispFileName().

void XLX_character_noop	(	XLX_state *	state,
		const char *	element,
		int	len
	)

No-op character element handler.

Parameters:

	state	Pointer to the current state of the parser
	element	The text string from the current element
	len	Length of element

void XLX_character_tag	(	XLX_state *	state,
		const char *	element,
		int	len
	)

Handle a character element inside a parent tag by delegating the work to the first child.

If there are valid characters in the character element then the first child of the current tag is pushed onto the stack and then XLX_character is called to handle the character parsing. After the parsing is complete the child is popped off the stack.

Parameters:

	state	Pointer to the current state of the parser
	element	Character element
	len	Length of the character element

References _XLX_parent_tag::child, _XLX_state::st, XLX_character(), XLX_ischar(), XLX_peek(), XLX_pop(), and XLX_push().

void XLX_destroyStack	(	XLX_stack *	stack,
		XLX_pDelete	dFn
	)

Free the memory allocated to a stack and its elements.

Parameters:

	stack	Stack to end
	dFn	Function to call to delete objects on the stack

References XLX_endStack(), and XLX_pop().

void XLX_dispFileName	(	XLX_state *	state,
		const char *	func
	)

Display the name of the current file being parsed.

This routine is used when reporting errors during the parsing.

Parameters:

	state	Current parse state
	func	Name of function reporting the error

References _XLX_state::fName.

Referenced by XLX_attrError(), XLX_attrValError(), XLX_end(), XLX_parse(), XLX_start(), and XLX_valError().

void XLX_dump

(

XLX_stack *

stack

)

Print out the stack information.

Parameters:

stack

Stack to dump

References _XLX_stack::base, _XLX_stack::limit, and _XLX_stack::used.

void XLX_endStack

(

XLX_stack *

stack

)

Free the memory allocated to a stack.

Parameters:

stack

Stack to free

References _XLX_stack::base, _XLX_stack::limit, and _XLX_stack::used.

Referenced by XLX_destroyStack().

void XLX_enter_noop	(	XLX_state *	state,
		const char **	attribute
	)

No-op enter element handler.

Parameters:

	state	Pointer to the current state of the parser
	attribute	Attribute list for the current element

void XLX_exit_noop

(

XLX_state *

state

)

No-op exit element handler.

Parameters:

state

Pointer to the current state of the parser

int XLX_getAttribute	(	const char **	attribute,
		const char *	name,
		int *	value
	)

Find a named attribute in an attribute list.

This routine looks for the attribute in the attribute list and returns its associated value (signed decimal or hexadecimal string) converted to an integer.

Parameters:

	attribute	Attribute list from the start tag of the element
	name	Attribute to find and return
	value	Location to put value of attribute

Return values:

	0	If the name is found and its value is valid
	-1	If the value is not a valid number
	-2	If the name is missing from the attribute list

References XLX_strtoi().

int XLX_getLineNum

(

XLX_state *

state

)

Get the current line number.

This routine obtains the current line number in the file being parsed.

Parameters:

state

Current parse state

Returns:

The current line number

References _XLX_state::parser.

int XLX_initStack	(	XLX_stack *	stack,
		unsigned int	limit
	)

Initialise a stack.

This routine allocates memory to hold the stack contents and sets the limit and used values.

Parameters:

	stack	Stack to initialise
	limit	Size of the stack

Return values:

	0	If the stack was successfully initialised
	-1	If there was an error allocating memory for the stack

References _XLX_stack::base, _XLX_stack::limit, and _XLX_stack::used.

Referenced by XLX_initState().

int XLX_initState	(	XLX_state *	state,
		unsigned int	stackLimit,
		void *	stackSeed,
		XLX_pDoctype	doctype,
		XLX_pEnter	enter,
		XLX_pExit	exit,
		XLX_pChar	character,
		int	verbose
	)

Initialise the state of the parser.

Parameters:

	state	Pointer to the state information
	stackLimit	Initial depth of the stack
	stackSeed	Initial item on the stack
	doctype	Action on encountering a doctype declaration
	enter	Parser default action on encountering an enter tag
	exit	Parser default action on encountering an exit tag
	character	Parser default action on encountering a character tag
	verbose	Verbosity level of the parser: 0 is quiet, 1 displays file name after error messages, > 1 displays information messages

Return values:

	0	Success
	-1	Insufficient memory

References _XLX_state::character, _XLX_state::doctype, _XLX_state::enter, _XLX_state::error, _XLX_state::exit, _XLX_state::fName, _XLX_state::parser, _XLX_state::st, _XLX_state::verbose, XLX_initStack(), and XLX_push().

int XLX_ischar	(	const char *	string,
		unsigned int	len
	)

Test a string for valid characters.

Checks that the string has valid graphic characters after any leading whitespace and before the start of the next tag.

Parameters:

	string	Address of string to test
	len	Max length of the string (including whitespace)

Return values:

	1	If the string has valid characters before the start of the next tag
	0	If the string does not have valid characters before the start of the next tag

Referenced by XLX_character_tag().

int XLX_isEnabled	(	const char **	attribute,
		int *	enabled
	)

Reads the attribute list and sets enabled accordingly.

Parameters:

	attribute	Attribute list from the start tag of the element
	enabled	Location to write 0 (FALSE) or 1 (TRUE)

Return values:

	0	If the attribute list was read correctly
	-1	If there was a bad value for the 'enabled' attribute
	-2	If there was no 'enabled' attribute

int XLX_parse	(	const char *	filename,
		XLX_state *	pState
	)

Parse an XML file.

Parameters:

	filename	XML file to parse
	pState	State of the parser.

Return values:

	0	If the file is successfully parsed
	-1	If the file cannot be opened
	-1	If there is an error creating the parser control structure
	-1	If there is an error reading the file
	-1	If there is an error parsing the XML

References _XLX_state::error, _XLX_state::fName, _XLX_state::parser, _XLX_state::verbose, XLX_character(), XLX_dispFileName(), XLX_doctype(), XLX_end(), and XLX_start().

void* XLX_peek	(	XLX_stack *	stack,
		unsigned int	depth
	)

Look at an item on a stack without removing it.

Parameters:

	stack	Stack to peek at
	depth	Depth from the top of the stack of item to peek at

Returns:

Item on the top of the stack

References _XLX_stack::base, and _XLX_stack::used.

Referenced by XLX_character(), XLX_character_tag(), and XLX_start().

void* XLX_pop

(

XLX_stack *

stack

)

Remove and return the top item on a stack.

Parameters:

stack

Stack to pop item off

Returns:

Item popped off the top of the stack

References _XLX_stack::base, and _XLX_stack::used.

Referenced by XLX_character_tag(), XLX_destroyStack(), and XLX_end().

int XLX_push	(	XLX_stack *	stack,
		void *	ptr
	)

Put a new item on the top of a stack.

If the stack is already full, its size is doubled.

Parameters:

	stack	Stack to push item onto
	ptr	Pointer to push onto stack

Return values:

	0	If the item is added successfully
	-1	If the stack needs to be extended to accomodate the new item and the memory allocation failed

References _XLX_stack::base, _XLX_stack::limit, and _XLX_stack::used.

Referenced by XLX_character_tag(), XLX_initState(), and XLX_start().

int XLX_strtoi	(	const char *	string,
		unsigned int	len,
		int *	value
	)

Convert a string to a signed 32-bit integer.

Parameters:

	string	String to convert
	len	Maximum length of the string (including whitespace)
	value	Address of the converted value

Return values:

	0	If the string represents a valid integer
	-1	If the string contains invalid characters

References strtobin().

Referenced by XLX_getAttribute().

int XLX_strtoll	(	const char *	string,
		unsigned int	len,
		long long *	value
	)

Convert a string to a signed 64-bit integer.

Parameters:

	string	String to convert
	len	Maximum length of the string (including whitespace)
	value	Address of the converted value

Return values:

	0	If the string represents a valid integer
	-1	If the string contains invalid characters

References strtobin().

int XLX_strtou	(	const char *	string,
		unsigned int	len,
		unsigned int *	value
	)

Convert a string to an unsigned 32-bit integer.

Parameters:

	string	String to convert
	len	Maximum length of the string (including whitespace)
	value	Address of the converted value

Return values:

	0	If the string represents a valid integer
	-1	If the string contains invalid characters

References strtobin().

int XLX_strtoull	(	const char *	string,
		unsigned int	len,
		unsigned long long *	value
	)

Convert a string to an unsigned 64-bit integer.

Parameters:

	string	String to convert
	len	Maximum length of the string (including whitespace)
	value	Address of the converted value

Return values:

	0	If the string represents a valid integer
	-1	If the string contains invalid characters

References strtobin().

void XLX_valError	(	XLX_state *	state,
		const char *	func,
		const char *	string,
		unsigned int	len
	)

Report value string to be in error.

This routine displays the contents of the string, along with the line number in and the name of the file being parsed.

Parameters:

	state	Current parse state
	func	Name of function reporting the error
	string	String to report
	len	Max length of the string (including whitespace)

References _XLX_state::parser, _XLX_state::verbose, and XLX_dispFileName().