XML

Detailed Description

Typedefs
typedef int(*	xparser_callback) (xparser *parser, void *userdata, xparser_event event, const char *name, const char **attr, const char *data)
	xparser user callback. More...
typedef void *(*	xparser_alloc) (void *ud, void *ptr, size_t osize, size_t nsize)
	define XPARSER_ALLOC non-zero to enable a user memory allocator. More...

Enumerations
enum	xparser_event {   xparserNOEVENT = 0 , xparserINIT , xparserRESET , xparserTERM ,   xparserSTART , xparserXML , xparserSTART_ELEMENT , xparserEND_ELEMENT ,   xparserEMPTY_ELEMENT , xparserPI , xparserCOMMENT , xparserCDATA ,   xparserTEXT , xparserLAST }
	events for user callbacks More...
enum	xparser_textmode
	flags for text handling

Functions
xparser *	xparser_create (void)
	create a parser. More...
int	xparser_init (xparser *parser, xparser_handlers *handlers, void *userdata, unsigned int options)
	initialise a parser. More...
int	xparser_term (xparser *parser)
	destroy a parser, WITHOUT deallocating pointer. More...
void	xparser_destroy (xparser *parser)
	destroy a parser More...
int	xparser_reset (xparser *parser, int full)
	reset a parser to post-create state. More...
int	xparser_parse (xparser *parser, const char *pData, size_t datalen)
	parse a chunk of xml data. More...
const char *	xparser_errormsg (xparser *parser)
	last error message
unsigned int	xparser_line (xparser *parser)
	current source line (1-based)
unsigned int	xparser_col (xparser *parser)
	current source column (1-based)
size_t	xparser_count (xparser *parser)
	source bytes parsed
unsigned int	xparser_depth (xparser *parser)
	current tag nesting depth
unsigned int	xparser_flags (xparser *parser)
	whitespace flags
int	xparser_has_doc (xparser *parser)
	have we parsed the document node ?
void *	xparser_userdata (xparser *parser)
	user data supplied to create/init
void	xparser_setalloc (xparser_alloc pa, void *ud)
	install user memory allocator. More...

Variables
const char *const	xparser_eventname [xparserLAST]
	array lookup for event names More...

Typedef Documentation

xparser_alloc

typedef void *(* xparser_alloc) (void *ud, void *ptr, size_t osize, size_t nsize)

define XPARSER_ALLOC non-zero to enable a user memory allocator.

if XPARSER_ALLOC == 1, parser will default to internal allocator; xparser_setalloc() MAY be called to supply a replacement allocator.

if XPARSER_ALLOC == 2, parser will default to an internal stub which will always return NULL, and xparser_setalloc() MUST be called with an allocator, or xparser_create() will always return NULL.

if XPARSER_ALLOC is defined with out a value then there will be no allocation functions in the library. user memory allocator.

xparser_callback

typedef int(* xparser_callback) (xparser *parser, void *userdata, xparser_event event, const char *name, const char **attr, const char *data)

xparser user callback.

Returns

non-zero to terminate parse or return value from init handler

unused parameters will point to an empty string; they will NEVER be NULL.

Enumeration Type Documentation

xparser_event

enum xparser_event

events for user callbacks

Enumerator
xparserNOEVENT	internal flag for no event set.
xparserINIT	called from xparser_init()
xparserRESET	called from xparser_reset()
xparserTERM	called from xparser_destroy()
xparserSTART	called from xparser_parse(), on first call since init() or reset()
xparserXML	xml declaration : <?xml attrs ?>
xparserSTART_ELEMENT	start element : <name attrs >
xparserEND_ELEMENT	end element : </name>
xparserEMPTY_ELEMENT	empty element : <name attrs />
xparserPI	processing instruction : <?name data?>
xparserCOMMENT	comment : <!–data-->
xparserCDATA	cdata : data
xparserTEXT	text : data
xparserLAST	dummy for array sizing

Function Documentation

xparser_create()

xparser * xparser_create

(

void

)

create a parser.

Returns

pointer to newly-created parser, or NULL.

xparser_destroy()

void xparser_destroy

(

xparser *

parser

)

destroy a parser

the TERM handler will be called, if not already terminated.

Parameters

[in]

parser

The parser context.

xparser_init()

int xparser_init	(	xparser *	parser,
		xparser_handlers *	handlers,
		void *	userdata,
		unsigned int	options
	)

initialise a parser.

handlers is a pointer to a table of event handlers.
options is one of the textmode flags.
If the parser was previously initialised and not terminated,
its TERM handler will be called !
the INIT handler will be called, if supplied, from init()

Parameters

[in]	parser	The parser context.
[in]	handlers	pointer to handlers
[in]	userdata	opaque user data that will be returned by xparser_userdata()
[in]	options	one of the values of enum xparser_textmode

Returns

return value from the init handler, or 0.

xparser_parse()

int xparser_parse	(	xparser *	parser,
		const char *	pData,
		size_t	datalen
	)

parse a chunk of xml data.

the event handlers will be called as events occur.
parse() can be called repeatedly with successive chunks of test;
check the has_doc() function for end of parse.

Parameters

[in]	parser	The parser context.
[in]	pData	pointer to data to be parsed.
[in]	datalen	size of data in pData

Returns

returns 0 on successful parse, -1 on error, or non-zero callback return value.

xparser_reset()

int xparser_reset	(	xparser *	parser,
		int	full
	)

reset a parser to post-create state.

the RESET handler will be called, if supplied.

Parameters

[in]	parser	The parser context.
[in]	full	the 'full' flag will cause reset() to deallocate all internal buffers.

Returns

0 or reset handler return code

xparser_setalloc()

void xparser_setalloc	(	xparser_alloc	pa,
		void *	ud
	)

install user memory allocator.

IF THIS IS CALLED WITH ANY PARSER OBJECTS ALLOCATED, BEHAVIOUR IS UNDEFINED.

call with NULL allocator to revert to internal allocator.

xparser_term()

int xparser_term

(

xparser *

parser

)

destroy a parser, WITHOUT deallocating pointer.

the TERM handler will be called, if supplied This function is supplied for ease of interfacing with Lua.

Parameters

[in]

parser

The parser context.

Returns

value is 0, or TERM handler return.

Variable Documentation

xparser_eventname

const char* const xparser_eventname[xparserLAST]

extern

array lookup for event names

one of the following ordered values - "NONE", "INIT", "RESET", "TERM", "START", "XML", "START_ELEMENT", "END_ELEMENT", "EMPTY_ELEMENT", "PI", "COMMENT", "CDATA", "TEXT"

See also

xparser_event these values are the same names as xparser_event with the prefix removed