Load XML documents from different sources. More...

Files
file	parser.h
	SCEW parser handling routines.

Typedefs
typedef scew_bool(*	scew_parser_load_hook )(scew_parser , void , void *)
	SCEW parser hooks might be used as notifications to know when XML elements or trees are parsed. More...

Functions
SCEW_API scew_tree *	scew_parser_load (scew_parser parser, scew_reader reader)
	Loads an XML tree from the specified reader. More...

SCEW_API scew_bool	scew_parser_load_stream (scew_parser parser, scew_reader reader)
	Loads multiple XML trees from the specified stream reader. More...

SCEW_API void	scew_parser_reset (scew_parser *parser)
	Resets the given parser for further uses. More...

SCEW_API void	scew_parser_set_element_hook (scew_parser parser, scew_parser_load_hook hook, void user_data)
	Registers a hook to be called once an XML element is successfully parsed. More...

SCEW_API void	scew_parser_set_tree_hook (scew_parser parser, scew_parser_load_hook hook, void user_data)
	Registers a hook to be called once an XML tree is successfully parsed. More...

SCEW_API void	scew_parser_ignore_whitespaces (scew_parser *parser, scew_bool ignore)
	Tells the parser how to treat white spaces. More...

Detailed Description

Load XML documents from different sources.

Typedef Documentation

typedef scew_bool(* scew_parser_load_hook)(scew_parser *, void *, void *)

SCEW parser hooks might be used as notifications to know when XML elements or trees are parsed.

Two types of hooks might be registered, one for elements (scew_parser_set_element_hook) and one for trees (scew_parser_set_tree_hook) . Whenever the parser loads a complete element (when the end of tag is found) the user will be notified via the registered hook, and the same for XML trees.

Parameters

parser	the parser that is loading the XML contents.
data	this is the pointer to an SCEW element or tree.
user_data	an optional user data pointer to be used by the hook (might be NULL).

Returns: true if the hook call had no errors, false otherwise.

Function Documentation

SCEW_API scew_tree* scew_parser_load	(	scew_parser *	parser,
		scew_reader *	reader
	)

Loads an XML tree from the specified reader.

This will get data from the reader and it will try to parse it. The reader might be of any type. Once the parser loads elements or the complete XML tree, the appropiate registered hooks will be called.

Note that this function can only load one XML tree. Concatenated XML documents might be loaded via scew_parser_load_stream.

XML declarations are not mandatory, and if none is found, the SCEW tree will still be created with a default one.

At startup, the parser is reset (via scew_parser_reset).

Precondition: parser != NULL; reader != NULL

Parameters

parser	the SCEW parser that parses the reader contents.
reader	the reader from where to load the XML.

Returns: the XML parsed tree or NULL if an error was found.

SCEW_API scew_bool scew_parser_load_stream	(	scew_parser *	parser,
		scew_reader *	reader
	)

Loads multiple XML trees from the specified stream reader.

This will get data from the reader and it will try to parse it. The difference between scew_parser_load and this function is that, here, at some point the reader might not have any more data to be read, so the function will return. Once more data becomes available subsequent calls to this function are needed to continue parsing.

Another important difference is that concatenated XML documents are allowed. Once the parser loads elements or complete XML trees, the appropiate registered hooks will be called.

It is necessary to register an XML tree hook, otherwise it will not be possible to get a reference to parsed XML trees, causing a memory leak.

Precondition: parser != NULL; reader != NULL; tree hook registered (scew_parser_set_tree_hook)

Parameters

parser	the SCEW parser that parses the reader contents.
reader	the stream reader from where to load XML information.

Returns: true if the parsing is being successful, false if an error is found.

SCEW_API void scew_parser_reset ( scew_parser * parser )

Resets the given parser for further uses.

Resetting a parser allows the parser to be re-used. This function is automatically called in scew_parser_load, but needs to be called when loading streams, as scew_parser_load_stream does not reset the parser.

Precondition: parser != NULL

Parameters

parser the parser to reset.

SCEW_API void scew_parser_set_element_hook	(	scew_parser *	parser,
		scew_parser_load_hook	hook,
		void *	user_data
	)

Registers a hook to be called once an XML element is successfully parsed.

The hook will only be called once the complete element is parsed, that is, when the end tag is found.

This hook might be useful as a notification mechanism when parsing big XML documents.

Note that no modification or deletion should be performed on the elements as they might still be needed by the parser.

Precondition: parser != NULL; hook != NULL

Parameters

parser	the parser that is loading the XML contents.
hook	this is the hook to be called once an XML element is parsed.
user_data	an optional user data pointer to be used by the hook (might be NULL).

SCEW_API void scew_parser_set_tree_hook	(	scew_parser *	parser,
		scew_parser_load_hook	hook,
		void *	user_data
	)

Registers a hook to be called once an XML tree is successfully parsed.

The hook will only be called once the complete XML tree is parsed.

This hook is necessary when loading streams (via scew_parser_load_stream), as no XML tree is returned there.

Precondition: parser != NULL; hook != NULL

Parameters

parser	the parser that is loading the XML contents.
hook	this is the hook to be called once an XML tree is parsed.
user_data	an optional user data pointer to be used by the hook (might be NULL).

SCEW_API void scew_parser_ignore_whitespaces	(	scew_parser *	parser,
		scew_bool	ignore
	)

Tells the parser how to treat white spaces.

The default is to ignore heading and trailing white spaces.

There is a new section in XML specification which talks about how to handle white spaces in XML. One can set an optional attribtue to an element which is called xml:space, and it can be set to default or preserve, and it inherits its value from parent elements.

preserve: leave white spaces as their are found.
default: white spaces are handled by the XML processor (Expat in our case) the way it wants to.

This function gives the possibility to change the XML processor behaviour.

Parameters

parser	the parser to set the option to.
ignore	whether the parser should ignore white spaces, false otherwise.

Files

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation