parse.h File Reference

#include <stdlib.h>
#include <string.h>
#include <stdbool.h>
#include "lex.h"
#include <libadt/lptr.h>
#include <libadt/vector.h>

Include dependency graph for parse.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef void	descent_xml_parse_text_fn(struct libadt_const_lptr text, bool is_cdata, void *context)
	Type signature for a user-passed text node parsing function. Used by descent_xml_parse().
typedef void	descent_xml_parse_text_cstr_fn(char *text, bool is_cdata, void *context)
	Type signature for a user-passed text node parsing function. Used by descent_xml_parse_cstr().

Functions
struct descent_xml_lex	descent_xml_parse_element_fn (struct descent_xml_lex token, struct libadt_const_lptr element_name, struct libadt_const_lptr attributes, bool empty, void *context)
	Type signature for a user-passed element parsing function. Used by descent_xml_parse().
struct descent_xml_lex	descent_xml_parse_element_cstr_fn (struct descent_xml_lex token, char *element_name, char **attributes, bool empty, void *context)
	Type signature for a user-passed element parsing function. Used by descent_xml_parse_cstr().
struct descent_xml_lex	descent_xml_parse (struct descent_xml_lex xml, descent_xml_parse_element_fn *element_handler, descent_xml_parse_text_fn *text_handler, void *context)
	Function for parsing an XML document.
struct descent_xml_lex	descent_xml_parse_cstr (struct descent_xml_lex xml, descent_xml_parse_element_cstr_fn *element_handler, descent_xml_parse_text_cstr_fn *text_handler, void *context)
	Function for parsing an XML document.

Typedef Documentation

descent_xml_parse_text_cstr_fn

typedef void descent_xml_parse_text_cstr_fn(char *text, bool is_cdata, void *context)

Type signature for a user-passed text node parsing function. Used by descent_xml_parse_cstr().

Parameters

token	The last token encountered by the parser. This can be returned directly, iterated over with descent_xml_lex_next_raw(), or passed to a recursive call to descent_xml_parse_cstr().
text	A pointer to a null-terminated string containing the text.
context	The pointer provided to descent_xml_parse_cstr() by the user.

descent_xml_parse_text_fn

typedef void descent_xml_parse_text_fn(struct libadt_const_lptr text, bool is_cdata, void *context)

Type signature for a user-passed text node parsing function. Used by descent_xml_parse().

Parameters

token	The last token encountered by the parser. This can be returned directly, iterated over with descent_xml_lex_next_raw(), or passed to a recursive call to descent_xml_parse().
text	A length-pointer containing the text.
context	The pointer provided to descent_xml_parse() by the user.

Returns

The last token processed. This can be the token passed in as an argument, or a token generated as a result of further processing inside the function.

Function Documentation

descent_xml_parse()

struct descent_xml_lex descent_xml_parse ( struct descent_xml_lex  xml, descent_xml_parse_element_fn *  element_handler, descent_xml_parse_text_fn *  text_handler, void *  context  )

inline

Function for parsing an XML document.

descent_xml_parse() is the version of the parser that does not allocate new memory and does not copy strings. Instead, it uses the length-pointer implementation from libadt to point into the original XML file for the element names, attributes and text. This also means that entities are not converted, and the text passed to the callbacks is not null-terminated.

This function will only parse a single entity. If the entity is an opening XML element, it will be parsed and passed to the given element_handler. If the entity is a text node, it will be parsed and passed to the text_handler. The return value will be the token returned by a handler if called, or the next token to process if neither were called.

Parameters

xml	A token into an XML document. Can be created on a full XML document using descent_xml_lex_init().
element_handler	A callback to call when encountering an opening element tag. Pass a NULL pointer to disable.
text_handler	A callback to call when encountering a text node. Pass a NULL pointer to disable.
context	A user-provided pointer that will be passed to the callbacks.

Returns

The last token encountered while parsing. If the return value's type property is descent_xml_classifier_unexpected, an error was encountered. If the type property is descent_xml_classifier_eof, then the end of the XML was encountered in an expected way.

See also

descent_xml_parse_cstr() An interface for C-style strings.

descent_xml_parse_cstr()

struct descent_xml_lex descent_xml_parse_cstr ( struct descent_xml_lex  xml, descent_xml_parse_element_cstr_fn *  element_handler, descent_xml_parse_text_cstr_fn *  text_handler, void *  context  )

inline

Function for parsing an XML document.

descent_xml_parse_cstr() is the version of the parser that allocates memory to copy values into. The strings are null-terminated char arrays, and are freed by the parser after the relevant callback is finished running.

Entities are not converted.

This function will only parse a single entity. If the entity is an opening XML element, it will be parsed and passed to the given element_handler. If the entity is a text node, it will be parsed and passed to text_handler. The return value will be the token returned by a handler if called, or the next token to process if neither were called.

Parameters

xml	A token into an XML document. Can be created on a full XML document using descent_xml_lex_init().
element_handler	A callback to call when encountering an opening element tag. Pass a NULL pointer to disable.
text_handler	A callback to call when encountering a text node. Pass a NULL pointer to disable.
context	A user-provided void pointer that will be passed to the callbacks.

Returns

The last token encountered while parsing. If the return value's type property is descent_xml_classifier_unexpected, a lex error occurred. If the type property is descent_xml_parse_error, there was an error allocating memory for a value. If the type property is descent_xml_classifier_eof, the end of the XML was encountered in an expected way.

See also

descent_xml_parse() An interface using pointer-length structs, using no allocation or copying logic.

descent_xml_parse_element_cstr_fn()

struct descent_xml_lex descent_xml_parse_element_cstr_fn	(	struct descent_xml_lex	token,
		char *	element_name,
		char **	attributes,
		bool	empty,
		void *	context
	)

Type signature for a user-passed element parsing function. Used by descent_xml_parse_cstr().

Parameters

token	The last token encountered by the parser. This can be returned directly, iterated over with descent_xml_lex_next_raw(), or passed to a recursive call to descent_xml_parse().
element_name	A null-terminated string containing the element name.
attributes	A null-terminated array of null-terminated strings. The zeroth string will be the zeroth attribute name, the first string will be its value; the second will be the first attribute name, the third its value, and so on.
empty	True if the element is an empty element, of the format <element-name />. False if the element is terminated with a closing tag. Note that elements with no content between an opening and closing tag are not considered empty elements.
context	The pointer provided to descent_xml_parse_cstr() by the user.

descent_xml_parse_element_fn()

struct descent_xml_lex descent_xml_parse_element_fn	(	struct descent_xml_lex	token,
		struct libadt_const_lptr	element_name,
		struct libadt_const_lptr	attributes,
		bool	empty,
		void *	context
	)

Type signature for a user-passed element parsing function. Used by descent_xml_parse().

Parameters

token	The last token encountered by the parser. This can be returned directly, iterated over with descent_xml_lex_next_raw(), or passed to a recursive call to descent_xml_parse().
element_name	An libadt_const_lptr to the byte array of the element name. element_name.length contains the number of bytes for the name and the pointer can be retrieved with libadt_const_lptr_raw(element_name).
attributes	An libadt_const_lptr of libadt_const_lptrs to attribute strings. attributes.length contains the number of strings. The zeroth string will be the zeroth attribute name, the first string will be its value; the second string will be the first attribute name, the third its value, and so on.
empty	True if the element is an empty element, of the format <element-name />. False if the element is terminated with a closing tag. Note that elements with no content between an opening and closing tag are not considered empty elements.
context	The pointer provided to descent_xml_parse() by the user.

Returns

The last token processed. This can be the token passed in as an argument, or a token generated as a result of further processing inside the function.