Typedefs
typedef struct M_xml_node	M_xml_node_t

Enumerations
enum	M_xml_node_type_t { M_XML_NODE_TYPE_UNKNOWN = 0 , M_XML_NODE_TYPE_DOC = 1 , M_XML_NODE_TYPE_ELEMENT = 2 , M_XML_NODE_TYPE_TEXT = 3 , M_XML_NODE_TYPE_PROCESSING_INSTRUCTION = 4 , M_XML_NODE_TYPE_DECLARATION = 5 , M_XML_NODE_TYPE_COMMENT = 6 }

enum	M_xml_reader_flags_t { M_XML_READER_NONE = 0 , M_XML_READER_IGNORE_COMMENTS = 1 << 0 , M_XML_READER_TAG_CASECMP = 1 << 1 , M_XML_READER_DONT_DECODE_TEXT = 1 << 2 , M_XML_READER_DONT_DECODE_ATTRS = 1 << 3 }

enum	M_xml_writer_flags_t { M_XML_WRITER_NONE = 0 , M_XML_WRITER_IGNORE_COMMENTS = 1 << 0 , M_XML_WRITER_LOWER_TAGS = 1 << 1 , M_XML_WRITER_LOWER_ATTRS = 1 << 2 , M_XML_WRITER_DONT_ENCODE_TEXT = 1 << 3 , M_XML_WRITER_DONT_ENCODE_ATTRS = 1 << 4 , M_XML_WRITER_PRETTYPRINT_SPACE = 1 << 5 , M_XML_WRITER_PRETTYPRINT_TAB = 1 << 6 , M_XML_WRITER_SELFCLOSE_SPACE = 1 << 7 }

enum	M_xml_error_t { M_XML_ERROR_SUCCESS = 0 , M_XML_ERROR_GENERIC , M_XML_ERROR_MISUSE , M_XML_ERROR_ATTR_EXISTS , M_XML_ERROR_NO_ELEMENTS , M_XML_ERROR_INVALID_START_TAG , M_XML_ERROR_INVALID_CHAR_IN_START_TAG , M_XML_ERROR_EMPTY_START_TAG , M_XML_ERROR_MISSING_DECLARATION_NAME , M_XML_ERROR_INELIGIBLE_FOR_CLOSE , M_XML_ERROR_UNEXPECTED_CLOSE , M_XML_ERROR_MISSING_CLOSE_TAG , M_XML_ERROR_MISSING_PROCESSING_INSTRUCTION_END , M_XML_ERROR_EXPECTED_END }

Functions
M_xml_node_t *	M_xml_create_doc (void) M_MALLOC

M_xml_node_t *	M_xml_create_element (const char name, M_xml_node_t parent) M_MALLOC

M_xml_node_t *	M_xml_create_element_with_text (const char name, const char text, size_t max_len, M_xml_node_t *parent) M_MALLOC

M_xml_node_t *	M_xml_create_element_with_num (const char name, M_int64 num, size_t max_len, M_xml_node_t parent) M_MALLOC

M_xml_node_t *	M_xml_create_text (const char text, size_t max_len, M_xml_node_t parent) M_MALLOC

M_xml_node_t *	M_xml_create_xml_declaration (const char encoding, M_xml_node_t parent) M_MALLOC

M_xml_node_t *	M_xml_create_declaration (const char name, M_xml_node_t parent) M_MALLOC

M_xml_node_t *	M_xml_create_declaration_with_tag_data (const char name, const char data, M_xml_node_t *parent) M_MALLOC

M_xml_node_t *	M_xml_create_processing_instruction (const char name, M_xml_node_t parent) M_MALLOC

M_xml_node_t *	M_xml_create_comment (const char comment, M_xml_node_t parent) M_MALLOC

void	M_xml_node_destroy (M_xml_node_t *node) M_FREE(1)

M_xml_node_t *	M_xml_read (const char data, size_t data_len, M_uint32 flags, size_t processed_len, M_xml_error_t error, size_t error_line, size_t *error_pos) M_MALLOC

M_xml_node_t *	M_xml_read_file (const char path, M_uint32 flags, size_t max_read, M_xml_error_t error, size_t error_line, size_t error_pos) M_MALLOC

char *	M_xml_write (const M_xml_node_t node, M_uint32 flags, size_t len) M_WARN_UNUSED_RESULT M_MALLOC

M_bool	M_xml_write_buf (M_buf_t buf, const M_xml_node_t node, M_uint32 flags)

M_fs_error_t	M_xml_write_file (const M_xml_node_t node, const char path, M_uint32 flags)

const char *	M_xml_errcode_to_str (M_xml_error_t err)

M_xml_node_type_t	M_xml_node_type (const M_xml_node_t *node)

M_xml_node_t **	M_xml_xpath (M_xml_node_t node, const char search, M_uint32 flags, size_t *num_matches) M_MALLOC

const char *	M_xml_xpath_text_first (M_xml_node_t node, const char search)

M_xml_node_t *	M_xml_node_parent (const M_xml_node_t *node)

void	M_xml_take_from_parent (M_xml_node_t *node)

M_bool	M_xml_node_insert_node (M_xml_node_t parent, M_xml_node_t child)

M_bool	M_xml_node_insert_node_at (M_xml_node_t parent, M_xml_node_t child, size_t idx)

size_t	M_xml_node_num_children (const M_xml_node_t *node)

M_xml_node_t *	M_xml_node_child (const M_xml_node_t *node, size_t idx)

M_xml_node_t *	M_xml_node_sibling (const M_xml_node_t *node, M_bool after)

M_bool	M_xml_node_set_name (M_xml_node_t node, const char name)

const char *	M_xml_node_name (const M_xml_node_t *node)

M_bool	M_xml_node_set_text (M_xml_node_t node, const char text, size_t max_len)

const char *	M_xml_node_text (const M_xml_node_t *node)

M_bool	M_xml_node_set_tag_data (M_xml_node_t node, const char data)

const char *	M_xml_node_tag_data (const M_xml_node_t *node)

M_bool	M_xml_node_insert_attribute (M_xml_node_t node, const char key, const char *val, size_t max_len, M_bool overwrite)

M_bool	M_xml_node_remove_attribute (M_xml_node_t node, const char key)

M_list_str_t *	M_xml_node_attribute_keys (const M_xml_node_t *node) M_MALLOC

const M_hash_dict_t *	M_xml_node_attributes (const M_xml_node_t *node)

const char *	M_xml_node_attribute (const M_xml_node_t node, const char key)

Detailed Description

DOM based XML data processing.

This is a simple API for reading, creating, manipulating, searching, and writing XML data.

It is possible to construct an invalid XML document. It is also possible that an invalid XML document created with M_xml will not be readable by M_xml. Specifically, when dealing with attribute and text encoding options for M_xml_read and M_xml_write. Also, attribute keys and tag names are not validated to ensure they are valid XML names. This must happen outside of M_xml.

M_xml is not susceptible to common XML entity expansion attaches such as billion laughs, quadratic blowup, and external entity expansion. Only basic XML entities are expanded and only one level is expanded. Further external entity references are not downloaded. Neither are external DTDs. This will mitigate against network based attacks relying on retrieval.

Example:

#include <mstdlib/mstdlib.h>
#include <mstdlib/mstdlib_formats.h>
 
int main(int argc, char** argv)
{
    M_xml_node_t *xml;
    const char   *data = "<r><tag1>abc</tag1><tag2>123</tag2><tag3>xyz</tag3></r>";
    char         *out;
 
    xml = M_xml_read(data, M_str_len(data), M_XML_READER_NONE, NULL, NULL, NULL, NULL);
    if (xml == NULL) {
        M_printf("xml parse error\n");
        return M_FALSE;
    }
 
    M_xml_create_element_with_text("AbCd", "blah blah blah", 0, xml);
 
    out = M_xml_write(xml, M_XML_WRITER_LOWER_TAGS|M_XML_WRITER_LOWER_ATTRS|M_XML_WRITER_PRETTYPRINT_SPACE, NULL);
    M_printf("out=\n%s\n", out);
    M_free(out);
    return 0;
}

Typedef Documentation

◆ M_xml_node_t

typedef struct M_xml_node M_xml_node_t

Enumeration Type Documentation

◆ M_xml_node_type_t

enum M_xml_node_type_t

Node types in our XML tree structure

Enumerator
M_XML_NODE_TYPE_UNKNOWN	An invalid node type.
M_XML_NODE_TYPE_DOC	The base of every XML tree and provides access to the documents data. Supports: Nodes. Does not support: Name, Attributes, Text, Tag data.
M_XML_NODE_TYPE_ELEMENT	Element (tag). E.g: <name key="val" />, <name>...</name> . Supports: Attributes, Nodes, Name. Does not support: Text, Tag data.
M_XML_NODE_TYPE_TEXT	Text. E.g: abc. Supports: Text. Does not support: Nodes, Name, Attributes, Tag data.
M_XML_NODE_TYPE_PROCESSING_INSTRUCTION	Conveys information. E.g: <?xml version="1.0" encoding="UTF-8" ?> Supports: Name, Attributes, Tag data. Does not support: Nodes, Text.
M_XML_NODE_TYPE_DECLARATION	HTML/DTD declaration. E.g: <!DOCTYPE html>, <!ELEMENT element-name category>, <!ATTLIST payment type CDATA "check"> Supports: Name, Tag data. Does not support: Nodes, Attributes, text.
M_XML_NODE_TYPE_COMMENT	Comment. E.g: <!-- comment --> Supports: Tag data. Does not support: Nodes, Name, Attributes, Text.

◆ M_xml_reader_flags_t

enum M_xml_reader_flags_t

Flags to control the behavior of the XML writer.

Enumerator
M_XML_READER_NONE	Normal operation.
M_XML_READER_IGNORE_COMMENTS	Don't include comments as part of the output during parse.
M_XML_READER_TAG_CASECMP	Compare open and close tags case insensitive.
M_XML_READER_DONT_DECODE_TEXT	By default text data will be xml entity decoded. This prevents the decode from taking place. It should be paired with the equivalent don't encode option when writing.
M_XML_READER_DONT_DECODE_ATTRS	By default attribute values will be attribute entity decoded. This prevents the decode from taking place. It should be paired with the equivalent don't encode option when writing.

◆ M_xml_writer_flags_t

enum M_xml_writer_flags_t

Flags to control the behavior of the XML reader.

Enumerator
M_XML_WRITER_NONE	No indent. All data on a single line.
M_XML_WRITER_IGNORE_COMMENTS	Comments are not included.
M_XML_WRITER_LOWER_TAGS	All tags are written lower case.
M_XML_WRITER_LOWER_ATTRS	All attribute keys are written lower case.
M_XML_WRITER_DONT_ENCODE_TEXT	By default text data will be xml entity encoded. This prevents the encode from taking place. It should be paired with the equivalent don't decode option when reading.
M_XML_WRITER_DONT_ENCODE_ATTRS	By default attribute values will be attribute entity encoded. This prevents the encode from taking place. It should be paired with the equivalent don't decode option when reading.
M_XML_WRITER_PRETTYPRINT_SPACE	2 space indent.
M_XML_WRITER_PRETTYPRINT_TAB	Tab indent.
M_XML_WRITER_SELFCLOSE_SPACE	Add a space before the closing slash for self closing tags.

◆ M_xml_error_t

enum M_xml_error_t

Error codes.

Enumerator
M_XML_ERROR_SUCCESS	success
M_XML_ERROR_GENERIC	generic error
M_XML_ERROR_MISUSE	API misuse
M_XML_ERROR_ATTR_EXISTS	the attribute already exists on the node
M_XML_ERROR_NO_ELEMENTS	unexpected end of XML, no elements in data
M_XML_ERROR_INVALID_START_TAG	invalid tag start character
M_XML_ERROR_INVALID_CHAR_IN_START_TAG	invalid character '<' found in tag
M_XML_ERROR_EMPTY_START_TAG	only whitespace after tag start
M_XML_ERROR_MISSING_DECLARATION_NAME	missing name after !
M_XML_ERROR_INELIGIBLE_FOR_CLOSE	cannot close element of this type
M_XML_ERROR_UNEXPECTED_CLOSE	cannot close element with the given tag
M_XML_ERROR_MISSING_CLOSE_TAG	missing closing element statement(s)
M_XML_ERROR_MISSING_PROCESSING_INSTRUCTION_END	missing processing instruction close
M_XML_ERROR_EXPECTED_END	expected end but more data found

Function Documentation

◆ M_xml_create_doc()

M_xml_node_t * M_xml_create_doc ( void )

Create an XML document.

Returns: An XML node on success. NULL on failure.

See also: M_xml_node_destroy

◆ M_xml_create_element()

M_xml_node_t * M_xml_create_element	(	const char *	name,
		M_xml_node_t *	parent
	)

Create an XML element node.

Parameters

[in]	name	The tag name for the element.
[in,out]	parent	The parent this node should be inserted into. Optional, pass NULL if the node should be created without a parent.

Returns: An XML node on success. NULL on failure.

See also: M_xml_node_destroy

◆ M_xml_create_element_with_text()

M_xml_node_t * M_xml_create_element_with_text	(	const char *	name,
		const char *	text,
		size_t	max_len,
		M_xml_node_t *	parent
	)

Create an XML element with text node.

Parameters

[in]	name	The tag name for the element.
[in]	text	The text for the element.
[in]	max_len	The maximum length the text is allowed to be when xml encoded. If the encoded length is greater an error will result. Use 0 to specify that the text length should not be checked and any length is allowed.
[in,out]	parent	The parent this node should be inserted into. Optional, pass NULL if the node should be created without a parent.

Returns: An XML node on success. NULL on failure.

See also: M_xml_node_destroy

◆ M_xml_create_element_with_num()

M_xml_node_t * M_xml_create_element_with_num	(	const char *	name,
		M_int64	num,
		size_t	max_len,
		M_xml_node_t *	parent
	)

Create an XML element with text set from num.

Parameters

[in]	name	The tag name for the element.
[in]	num	The number to be inserted as the text for the element.
[in]	max_len	The maximum length the text is allowed to be when xml encoded. If the encoded length is greater an error will result. Use 0 to specify that the text length should not be checked and any length is allowed.
[in,out]	parent	The parent this node should be inserted into. Optional, pass NULL if the node should be created without a parent.

Returns: A XML node on success. NULL on failure.

See also: M_xml_node_destroy

◆ M_xml_create_text()

M_xml_node_t * M_xml_create_text	(	const char *	text,
		size_t	max_len,
		M_xml_node_t *	parent
	)

Create an XML text node.

Parameters

[in]	text	The text.
[in]	max_len	The maximum length the text is allowed to be when xml encoded. If the encoded length is greater an error will result. Use 0 to specify that the text length should not be checked and any length is allowed.
[in,out]	parent	The parent this node should be inserted into. Optional, pass NULL if the node should be created without a parent.

Returns: An XML node on success. NULL on failure.

See also: M_xml_node_destroy

◆ M_xml_create_xml_declaration()

M_xml_node_t * M_xml_create_xml_declaration	(	const char *	encoding,
		M_xml_node_t *	parent
	)

Create an XML declaration node.

E.g:

<?xml version="1.0" encoding="UTF-8" ?>

Parameters

[in]	encoding	The encoding.
[in,out]	parent	The parent this node should be inserted into. Optional, pass NULL if the node should be created without a parent.

Returns: An XML node on success. NULL on failure.

See also: M_xml_node_destroy

◆ M_xml_create_declaration()

M_xml_node_t * M_xml_create_declaration	(	const char *	name,
		M_xml_node_t *	parent
	)

Create a declaration node.

E.g:

<!DOCTYPE html>
<!ELEMENT element-name category>
<!ATTLIST payment type CDATA "check">

Parameters

[in]	name	The tag name for the declaration.
[in,out]	parent	The parent this node should be inserted into. Optional, pass NULL if the node should be created without a parent.

Returns: An XML node on success. NULL on failure.

See also: M_xml_node_destroy

◆ M_xml_create_declaration_with_tag_data()

M_xml_node_t * M_xml_create_declaration_with_tag_data	(	const char *	name,
		const char *	data,
		M_xml_node_t *	parent
	)

Create a declaration node.

E.g:

<!DOCTYPE html>
<!ELEMENT element-name category>
<!ATTLIST payment type CDATA "check">

Parameters

[in]	name	The tag name for the declaration.
[in]	data	The tag data.
[in,out]	parent	The parent this node should be inserted into. Optional, pass NULL if the node should be created without a parent.

Returns: An XML node on success. NULL on failure.

See also: M_xml_node_destroy

◆ M_xml_create_processing_instruction()

M_xml_node_t * M_xml_create_processing_instruction	(	const char *	name,
		M_xml_node_t *	parent
	)

Create an XML processing instruction node.

Parameters

[in]	name	The instruction name for the node.
[in,out]	parent	The parent this node should be inserted into. Optional, pass NULL if the node should be created without a parent.

Returns: An XML node on success. NULL on failure.

See also: M_xml_node_destroy

◆ M_xml_create_comment()

M_xml_node_t * M_xml_create_comment	(	const char *	comment,
		M_xml_node_t *	parent
	)

Create an XML comment node.

Parameters

[in]	comment	The comment.
[in,out]	parent	The parent this node should be inserted into. Optional, pass NULL if the node should be created without a parent.

Returns: An XML node on success. NULL on failure.

See also: M_xml_node_destroy

◆ M_xml_node_destroy()

void M_xml_node_destroy ( M_xml_node_t * node )

Destroy an XML node.

Destroying a node will destroy every node under it and remove it from it's parent node if it is a child.

Parameters

[in] node The node to destroy.

◆ M_xml_read()

M_xml_node_t * M_xml_read	(	const char *	data,
		size_t	data_len,
		M_uint32	flags,
		size_t *	processed_len,
		M_xml_error_t *	error,
		size_t *	error_line,
		size_t *	error_pos
	)

Parse a string into an XML object.

Parameters

[in]	data	The data to parse.
[in]	data_len	The length of the data to parse.
[in]	flags	M_xml_reader_flags_t flags to control the behavior of the reader.
[out]	processed_len	Length of data processed. Useful if you could have multiple XML documents in a stream. Optional pass NULL if not needed.
[out]	error	Error code if creation failed. Optional, Pass NULL if not needed.
[out]	error_line	The line the error occurred. Optional, pass NULL if not needed.
[out]	error_pos	The column the error occurred if error_line is not NULL, otherwise the position in the stream the error occurred. Optional, pass NULL if not needed.

Returns: The XML doc node of the parsed data, or NULL on error.

◆ M_xml_read_file()

M_xml_node_t * M_xml_read_file	(	const char *	path,
		M_uint32	flags,
		size_t	max_read,
		M_xml_error_t *	error,
		size_t *	error_line,
		size_t *	error_pos
	)

Parse a file into an XML object.

Parameters

[in]	path	The file to read.
[in]	flags	M_xml_reader_flags_t flags to control the behavior of the reader.
[in]	max_read	The maximum amount of data to read from the file. If the data in the file is larger than max_read an error will most likely result. Optional pass 0 to read all data.
[out]	error	Error code if creation failed. Optional, Pass NULL if not needed.
[out]	error_line	The line the error occurred. Optional, pass NULL if not needed.
[out]	error_pos	The column the error occurred if error_line is not NULL, otherwise the position in the stream the error occurred. Optional, pass NULL if not needed.

Returns: The XML doc node of the parsed data, or NULL on error.

◆ M_xml_write()

char * M_xml_write	(	const M_xml_node_t *	node,
		M_uint32	flags,
		size_t *	len
	)

Write XML to a string.

This writes nodes to a string. The string may not be directly usable by M_xml_read. E.g. If you are only writing a string node.

Parameters

[in]	node	The node to write. This will write the node and any nodes under it.
[in]	flags	M_xml_writer_flags_t flags to control writing.
[out]	len	The length of the string that was returned. Optional, pass NULL if not needed.

Returns: A string with data or NULL on error.

◆ M_xml_write_buf()

M_bool M_xml_write_buf	(	M_buf_t *	buf,
		const M_xml_node_t *	node,
		M_uint32	flags
	)

Write XML to a buffer.

This writes nodes out to a buffer. The resulting string may not be directly usable by M_xml_read - for example, you can write out a string node or other component of an XML document, without writing the whole thing.

Parameters

[out]	buf	buffer to write XML to
[in]	node	the node to write (children of this node are also included in output)
[in]	flags	OR'd combo of M_xml_write_flags_t values (to control writing)

Returns: M_TRUE if successful, M_FALSE otherwise.

◆ M_xml_write_file()

M_fs_error_t M_xml_write_file	(	const M_xml_node_t *	node,
		const char *	path,
		M_uint32	flags
	)

Write XML to a file.

This writes nodes to a string. The string may not be directly usable by M_xml_read_file. E.g. If you are only writing a string node.

Parameters

[in]	node	The node to write. This will write the node and any nodes under it.
[in]	path	The filename and path to write the data to.
[in]	flags	M_xml_writer_flags_t flags to control writing.

Returns: Result.

◆ M_xml_errcode_to_str()

const char * M_xml_errcode_to_str ( M_xml_error_t err )

Convert an XML error code to a string.

Parameters

[in] err error code

Returns: name of error code (not a description, just the enum name, like M_XML_ERROR_SUCCESS)

◆ M_xml_node_type()

M_xml_node_type_t M_xml_node_type ( const M_xml_node_t * node )

Get the type of node.

Parameters

[in] node The node.

Returns: The type.

◆ M_xml_xpath()

M_xml_node_t ** M_xml_xpath	(	M_xml_node_t *	node,
		const char *	search,
		M_uint32	flags,
		size_t *	num_matches
	)

Using XPath expressions, scan for matches.

Note that full XPath support does not yet exist. Also only element nodes are currently returned unless text() is used to return text nodes.

This will return an array of nodes within the tree. The nodes in the return are not copies, they are references. Changing a node in the xpath return will modify the node in the tree.

Supports:

Syntax	Meaning
tag	Selects children of the current element node with the given tag name.
*:tag	Selects children of the current element node with the given tag name ignoring any namespace on the tag. Also matches tags without a namespace.
*	Selects all children of the current element node.
/	Selects children one level below the current element node.
//	Selects children on all levels bellow the current element node.
.	Selects the current element node.
..	Selects the parent of the current element node.
text()	Selects all text nodes.
[@attrib]	Selects elements which have an attribute attrib.
[@attrib=val]	Selects elements which have an attribute attrib with a value of val.
[@attrib="val"]	Selects elements which have an attribute attrib with a value of val.
[@attrib='val']	Selects elements which have an attribute attrib with a value of val.
[@*]	Selects elements which have an (any) attribute set.
[idx]	Select an element at a given position.
[position() ? idx]	Select an element at a given position.

More information about [idx]:

Index matching can either be an integer (starting from 1) or the expression "last()". "last()" can be followed by a negative integer in order to count backwards from the last elements. For example: "last()-1" is the second to last element. The idx is not the index within the parent the node but the index of the matching nodes. idx must be preceded by either a tag or text().

More information about [position() ? idx]:

Position matching can use the equality modifiers '=', '<=', '>=', '<', '>'. These will select one or more nodes that match the given criteria. "last()" can be used as the index.

E.g: "a/b[2]" for <a><b/><c/><b/></a> will select the second "b" after "c".

Parameters

[in]	node	The node.
[in]	search	search expression
[in]	flags	M_xml_reader_flags_t flags to control the behavior of the search. valid flags are: M_XML_READER_NONE M_XML_READER_TAG_CASECMP
[out]	num_matches	Number of matches found

Returns: array of M_xml_node_t pointers on success (must free array, but not internal pointers), NULL on failure

◆ M_xml_xpath_text_first()

const char * M_xml_xpath_text_first	(	M_xml_node_t *	node,
		const char *	search
	)

Using XPath expressions, scan for matches and return the first text value.

This will only return the first text node. Meaning if multiple text nodes are inserted in a row only the text from the first will be returned. If the XML tree was created using M_xml_read or M_xml_read_file then the fist text node will contain all of the text.

See also: M_xml_xpath for information about supported XPath features.

Parameters

[in]	node	The node.
[in]	search	search expression

Returns: Text on success otherwise NULL.

◆ M_xml_node_parent()

M_xml_node_t * M_xml_node_parent ( const M_xml_node_t * node )

Get the parent node of a given node.

Parameters

[in] node The node.

Returns: The parent node or NULL if there is no parent.

◆ M_xml_take_from_parent()

void M_xml_take_from_parent ( M_xml_node_t * node )

Take a node from its parent but does not destroy the node.

This allows a node to be moved between different parents.

Parameters

[in,out] node The node.

◆ M_xml_node_insert_node()

M_bool M_xml_node_insert_node	(	M_xml_node_t *	parent,
		M_xml_node_t *	child
	)

Insert a node into a doc or element node.

The parent node will take ownership of the child node.

Only parentless nodes can be insert into other nodes. You must use M_xml_take_from_parent first if you are moving nodes from one parent to another.

Parameters

[in,out]	parent	The parent node.
[in]	child	The child node.

Returns: M_TRUE on success otherwise M_FALSE.

◆ M_xml_node_insert_node_at()

M_bool M_xml_node_insert_node_at	(	M_xml_node_t *	parent,
		M_xml_node_t *	child,
		size_t	idx
	)

Insert a node into a doc or element node at a given position.

The parent node will take ownership of the child node.

Parameters

[in,out]	parent	The parent node.
[in]	child	The child node.
[in]	idx	The location where the node should be inserted.

Returns: M_TRUE on success otherwise M_FALSE.

◆ M_xml_node_num_children()

size_t M_xml_node_num_children ( const M_xml_node_t * node )

Get the number of child nodes for a doc or element node.

Parameters

[in] node The node.

Returns: The number of children.

See also: M_xml_node_child

◆ M_xml_node_child()

M_xml_node_t * M_xml_node_child	(	const M_xml_node_t *	node,
		size_t	idx
	)

Get the child node at the given position for a doc or element node.

Parameters

[in]	node	The node.
[in]	idx	The position for the child to retrieve.

Returns: The child node or NULL if a child does not exist at the given position.

See also: M_xml_node_num_children

◆ M_xml_node_sibling()

M_xml_node_t * M_xml_node_sibling	(	const M_xml_node_t *	node,
		M_bool	after
	)

Get the sibling for the node.

The sibling is the node at the same level as the current node which is either before or after the node.

Parameters

[in]	node	The node.
[in]	after	M_TRUE to return the node after. M_FALSE to return the one before.

Returns: The sibling node. NULL if there is no sibling in the given direction.

◆ M_xml_node_set_name()

M_bool M_xml_node_set_name	(	M_xml_node_t *	node,
		const char *	name
	)

Set the tag name for an element or processing instruction node.

The name is the tag name. E.g. "<name>". This will change the name of the node.

Parameters

[in,out]	node	The node.
[in]	name	The name.

Returns: M_TRUE on sucess otherwise M_FALSE.

◆ M_xml_node_name()

const char * M_xml_node_name ( const M_xml_node_t * node )

Get the tag name for node an element or processing instruction node.

Parameters

[in] node The node.

Returns: The name.

◆ M_xml_node_set_text()

M_bool M_xml_node_set_text	(	M_xml_node_t *	node,
		const char *	text,
		size_t	max_len
	)

Set the text for a text node.

Parameters

[in,out]	node	The node.
[in]	text	The text.
[in]	max_len	The maximum length the text is allowed to be when xml encoded. If the encoded length is greater an error will result. Use 0 to specify that the text length should not be checked and any length is allowed.

Returns: M_TRUE on success, otherwise M_FALSE.

◆ M_xml_node_text()

const char * M_xml_node_text ( const M_xml_node_t * node )

Get the text for a text node.

Parameters

[in] node The node

Returns: The node's text.

◆ M_xml_node_set_tag_data()

M_bool M_xml_node_set_tag_data	(	M_xml_node_t *	node,
		const char *	data
	)

Set the tag data for a node.

Parameters

[in,out]	node	The node.
[in]	data	The tag data.

Returns: M_TRUE on success, otherwise M_FALSE.

◆ M_xml_node_tag_data()

const char * M_xml_node_tag_data ( const M_xml_node_t * node )

Get the tag data for a node.

Parameters

[in] node The node

Returns: The node's tag data.

◆ M_xml_node_insert_attribute()

M_bool M_xml_node_insert_attribute	(	M_xml_node_t *	node,
		const char *	key,
		const char *	val,
		size_t	max_len,
		M_bool	overwrite
	)

Insert an attribute into an element or processing instruction node.

Parameters

[in,out]	node	The node.
[in]	key	The attribute key.
[in]	val	The attribute value.
[in]	max_len	The maximum length the text is allowed to be when xml encoded. If the encoded length is greater an error will result. Use 0 to specify that the text length should not be checked and any length is allowed.
[in]	overwrite	Action to take when the given key exists. If M_TRUE the value will be overwritten when with the given value. If M_FALSE the attribute will not be written. This will be treated as an error condition.

Returns: M_TRUE on success, otherwise M_FALSE.

◆ M_xml_node_remove_attribute()

M_bool M_xml_node_remove_attribute	(	M_xml_node_t *	node,
		const char *	key
	)

Remove an attribute from an element or processing instruction node.

Parameters

[in,out]	node	The node.
[in]	key	The attribute key.

Returns: M_TRUE on success, otherwise M_FALSE.

◆ M_xml_node_attribute_keys()

M_list_str_t * M_xml_node_attribute_keys ( const M_xml_node_t * node )

Get a list of all attribute keys set for an element or processing instruction node.

Parameters

[in] node The node.

Returns: A list of keys.

◆ M_xml_node_attributes()

const M_hash_dict_t * M_xml_node_attributes ( const M_xml_node_t * node )

Get a dictionary of all attribute set for an element or processing instruction node.

Parameters

[in] node The node.

Returns: A dictionary with attributes.

◆ M_xml_node_attribute()

const char * M_xml_node_attribute	(	const M_xml_node_t *	node,
		const char *	key
	)

Get the value of a given attribute for an element or processing instruction node.

Parameters

[in]	node	The node.
[in]	key	The attribute key.

Returns: The value of the attribute. NULL if the key does not exist.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ M_xml_node_t

Enumeration Type Documentation

◆ M_xml_node_type_t

◆ M_xml_reader_flags_t

◆ M_xml_writer_flags_t

◆ M_xml_error_t

Function Documentation

◆ M_xml_create_doc()

◆ M_xml_create_element()

◆ M_xml_create_element_with_text()

◆ M_xml_create_element_with_num()

◆ M_xml_create_text()

◆ M_xml_create_xml_declaration()

◆ M_xml_create_declaration()

◆ M_xml_create_declaration_with_tag_data()

◆ M_xml_create_processing_instruction()

◆ M_xml_create_comment()

◆ M_xml_node_destroy()

◆ M_xml_read()

◆ M_xml_read_file()

◆ M_xml_write()

◆ M_xml_write_buf()

◆ M_xml_write_file()

◆ M_xml_errcode_to_str()

◆ M_xml_node_type()

◆ M_xml_xpath()

◆ M_xml_xpath_text_first()

◆ M_xml_node_parent()

◆ M_xml_take_from_parent()

◆ M_xml_node_insert_node()

◆ M_xml_node_insert_node_at()

◆ M_xml_node_num_children()

◆ M_xml_node_child()

◆ M_xml_node_sibling()

◆ M_xml_node_set_name()

◆ M_xml_node_name()

◆ M_xml_node_set_text()

◆ M_xml_node_text()

◆ M_xml_node_set_tag_data()

◆ M_xml_node_tag_data()

◆ M_xml_node_insert_attribute()

◆ M_xml_node_remove_attribute()

◆ M_xml_node_attribute_keys()

◆ M_xml_node_attributes()

◆ M_xml_node_attribute()