Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
mxml(3)				 Mini-XML API			       mxml(3)

NAME
       mxml - Mini-XML API

INCLUDE	FILE
       #include	<mxml.h>

LIBRARY
       -lmxml

DESCRIPTION
       Mini-XML	 is  a	small XML parsing library that you can use to read XML
       and XML-like data files in your	application  without  requiring	 large
       non-standard  libraries.	  Mini-XML  only requires an ANSI C compatible
       compiler	(GCC works, as do most vendors'	ANSI C compilers) and a	"make"
       program.

       Mini-XML	provides the following functionality:

       o   Reading  of UTF-8 and UTF-16	and writing of UTF-8 encoded XML files
	   and strings.

       o   Data	is stored in a linked-list tree	structure, preserving the  XML
	   data	hierarchy.

       o   Supports  arbitrary element names, attributes, and attribute	values
	   with	no preset limits, just available memory.

       o   Supports integer, real, opaque ("CDATA"), and text  data  types  in
	   "leaf" nodes.

       o   Functions for creating, indexing, and managing trees	of data.

       o   "Find"  and	"walk"	functions  for	easily locating	and navigating
	   trees of data.

       Mini-XML	doesn't	do validation or other types of	processing on the data
       based upon schema files or other	sources	of definition information, nor
       does it support character entities other	than those required by the XML
       specification.

USING MINI-XML
       Mini-XML	provides a single header file which you	include:

	   #include <mxml.h>

       Nodes are defined by the	"mxml_node_t" structure; the "type" member de-
       fines the node type (element, integer, opaque, real, or text) which de-
       termines	 which	value  you  want to look at in the "value" union.  New
       nodes can be created using the "mxmlNewElement()",  "mxmlNewInteger()",
       "mxmlNewOpaque()",   "mxmlNewReal()",  and  "mxmlNewText()"  functions.
       Only elements can have child nodes, and the top node must  be  an  ele-
       ment, usually "?xml".

       You load	an XML file using the "mxmlLoadFile()" function:

	   FILE	*fp;
	   mxml_node_t *tree;

	   fp =	fopen("filename.xml", "r");
	   tree	= mxmlLoadFile(NULL, fp, MXML_NO_CALLBACK);
	   fclose(fp);

       Similarly, you save an XML file using the "mxmlSaveFile()" function:

	   FILE	*fp;
	   mxml_node_t *tree;

	   fp =	fopen("filename.xml", "w");
	   mxmlSaveFile(tree, fp, MXML_NO_CALLBACK);
	   fclose(fp);

       The "mxmlLoadString()", "mxmlSaveAllocString()",	and "mxmlSaveString()"
       functions load XML node trees from and save XML node trees to strings:

	   char	buffer[8192];
	   char	*ptr;
	   mxml_node_t *tree;

	   ...
	   tree	= mxmlLoadString(NULL, buffer, MXML_NO_CALLBACK);

	   ...
	   mxmlSaveString(tree,	buffer,	sizeof(buffer),
			  MXML_NO_CALLBACK);

	   ...
	   ptr = mxmlSaveAllocString(tree, MXML_NO_CALLBACK);

       You can find a named element/node using the  "mxmlFindElement()"	 func-
       tion:

	   mxml_node_t *node = mxmlFindElement(tree, tree, "name",
					       "attr", "value",
					       MXML_DESCEND);

       The  "name", "attr", and	"value"	arguments can be passed	as NULL	to act
       as wildcards, e.g.:

	   /* Find the first "a" element */
	   node	= mxmlFindElement(tree,	tree, "a", NULL, NULL,
				  MXML_DESCEND);

	   /* Find the first "a" element with "href" attribute */
	   node	= mxmlFindElement(tree,	tree, "a", "href", NULL,
				  MXML_DESCEND);

	   /* Find the first "a" element with "href" to	a URL */
	   node	= mxmlFindElement(tree,	tree, "a", "href",
				  "http://www.easysw.com/~mike/mxml/",
				  MXML_DESCEND);

	   /* Find the first element with a "src" attribute*/
	   node	= mxmlFindElement(tree,	tree, NULL, "src", NULL,
				  MXML_DESCEND);

	   /* Find the first element with a "src" = "foo.jpg" */
	   node	= mxmlFindElement(tree,	tree, NULL, "src",
				  "foo.jpg", MXML_DESCEND);

       You can also iterate with the same function:

	   mxml_node_t *node;

	   for (node = mxmlFindElement(tree, tree, "name", NULL,
				       NULL, MXML_DESCEND);
		node !=	NULL;
		node = mxmlFindElement(node, tree, "name", NULL,
				       NULL, MXML_DESCEND))
	   {
	     ... do something ...
	   }

       To find the value of a specific node in the tree,  use  the  "mxmlFind-
       Path()" function:

	   mxml_node_t *value =	mxmlFindPath(tree, "path/to/*/foo/bar");

       The  "mxmlGetInteger()",	"mxmlGetOpaque()", "mxmlGetReal()", and	"mxml-
       GetText()" functions retrieve the value from a node:

	   mxml_node_t *node;

	   int intvalue	= mxmlGetInteger(node);

	   const char *opaquevalue = mxmlGetOpaque(node);

	   double realvalue = mxmlGetReal(node);

	   int whitespacevalue;
	   const char *textvalue = mxmlGetText(node, &whitespacevalue);

       Finally,	once you are done with the XML data,  use  the	"mxmlDelete()"
       function	 to  recursively free the memory that is used for a particular
       node or the entire tree:

	   mxmlDelete(tree);

ENUMERATIONS
   mxml_sax_event_e
       SAX event type.

       MXML_SAX_CDATA
	    CDATA node

       MXML_SAX_COMMENT
	    Comment node

       MXML_SAX_DATA
	    Data node

       MXML_SAX_DIRECTIVE
	    Processing directive node

       MXML_SAX_ELEMENT_CLOSE
	    Element closed

       MXML_SAX_ELEMENT_OPEN
	    Element opened

   mxml_type_e
       The XML node type.

       MXML_CUSTOM
	    Custom data

       MXML_ELEMENT
	    XML	element	with attributes

       MXML_IGNORE
	    Ignore/throw away node

       MXML_INTEGER
	    Integer value

       MXML_OPAQUE
	    Opaque string

       MXML_REAL
	    Real value

       MXML_TEXT
	    Text fragment

FUNCTIONS
   mxmlAdd
       Add a node to a tree.

       void mxmlAdd (
	   mxml_node_t *parent,
	   int where,
	   mxml_node_t *child,
	   mxml_node_t *node
       );

       Adds the	specified node to the parent.  If the child  argument  is  not
       NULL,  puts  the	new node before	or after the specified child depending
       on the value of the where argument.  If the  child  argument  is	 NULL,
       puts  the new node at the beginning of the child	list (MXML_ADD_BEFORE)
       or at the  end  of  the	child  list  (MXML_ADD_AFTER).	 The  constant
       MXML_ADD_TO_PARENT can be used to specify a NULL	child pointer.

   mxmlDelete
       Delete a	node and all of	its children.

       void mxmlDelete (
	   mxml_node_t *node
       );

       If  the	specified  node	 has a parent, this function first removes the
       node from its parent using the mxmlRemove function.

   mxmlElementDeleteAttr
       Delete an attribute.

       void mxmlElementDeleteAttr (
	   mxml_node_t *node,
	   const char *name
       );

   mxmlElementGetAttr
       Get an attribute.

       const char * mxmlElementGetAttr (
	   mxml_node_t *node,
	   const char *name
       );

       This function returns NULL if the node is not an	element	or  the	 named
       attribute does not exist.

   mxmlElementGetAttrByIndex
       Get an element attribute	by index.

       const char * mxmlElementGetAttrByIndex (
	   mxml_node_t *node,
	   int idx,
	   const char **name
       );

       The  index ("idx") is 0-based.  NULL is returned	if the specified index
       is out of range.

   mxmlElementGetAttrCount
       Get the number of element attributes.

       int  mxmlElementGetAttrCount (
	   mxml_node_t *node
       );

   mxmlElementSetAttr
       Set an attribute.

       void mxmlElementSetAttr (
	   mxml_node_t *node,
	   const char *name,
	   const char *value
       );

       If the named attribute already exists, the value	of  the	 attribute  is
       replaced	 by  the new string value. The string value is copied into the
       element node. This function does	nothing	if the node is not an element.

   mxmlElementSetAttrf
       Set an attribute	with a formatted value.

       void mxmlElementSetAttrf	(
	   mxml_node_t *node,
	   const char *name,
	   const char *format,
	   ...
       );

       If the named attribute already exists, the value	of  the	 attribute  is
       replaced	 by  the  new  formatted string. The formatted string value is
       copied into the element node. This function does	nothing	if the node is
       not an element.

   mxmlEntityAddCallback
       Add a callback to convert entities to Unicode.

       int  mxmlEntityAddCallback (
	   mxml_entity_cb_t cb
       );

   mxmlEntityGetName
       Get the name that corresponds to	the character value.

       const char * mxmlEntityGetName (
	   int val
       );

       If  val	does not need to be represented	by a named entity, NULL	is re-
       turned.

   mxmlEntityGetValue
       Get the character corresponding to a named entity.

       int  mxmlEntityGetValue (
	   const char *name
       );

       The entity name can also	be a numeric constant. -1 is returned  if  the
       name is not known.

   mxmlEntityRemoveCallback
       Remove a	callback.

       void mxmlEntityRemoveCallback (
	   mxml_entity_cb_t cb
       );

   mxmlFindElement
       Find the	named element.

       mxml_node_t * mxmlFindElement (
	   mxml_node_t *node,
	   mxml_node_t *top,
	   const char *element,
	   const char *attr,
	   const char *value,
	   int descend
       );

       The  search  is constrained by the name,	attribute name,	and value; any
       NULL names or values are	treated	as wildcards, so  different  kinds  of
       searches	can be implemented by looking for all elements of a given name
       or all elements with a specific attribute. The descend argument	deter-
       mines  whether  the search descends into	child nodes; normally you will
       use MXML_DESCEND_FIRST for the initial search  and  MXML_NO_DESCEND  to
       find  additional	 direct	descendents of the node. The top node argument
       constrains the search to	a particular node's children.

   mxmlFindPath
       Find a node with	the given path.

       mxml_node_t * mxmlFindPath (
	   mxml_node_t *top,
	   const char *path
       );

       The "path" is a slash-separated list of element names. The name "*"  is
       considered a wildcard for one or	more levels of elements.  For example,
       "foo/one/two", "bar/two/one", "*/one", and so forth.

       The first child node of the found node is returned if  the  given  node
       has children and	the first child	is a value node.

   mxmlGetCDATA
       Get the value for a CDATA node.

       const char * mxmlGetCDATA (
	   mxml_node_t *node
       );

       NULL is returned	if the node is not a CDATA element.

   mxmlGetCustom
       Get the value for a custom node.

       const void * mxmlGetCustom (
	   mxml_node_t *node
       );

       NULL is returned	if the node (or	its first child) is not	a custom value
       node.

   mxmlGetElement
       Get the name for	an element node.

       const char * mxmlGetElement (
	   mxml_node_t *node
       );

       NULL is returned	if the node is not an element node.

   mxmlGetFirstChild
       Get the first child of an element node.

       mxml_node_t * mxmlGetFirstChild (
	   mxml_node_t *node
       );

       NULL is returned	if the node is not an element node or if the node  has
       no children.

   mxmlGetInteger
       Get the integer value from the specified	node or	its first child.

       int  mxmlGetInteger (
	   mxml_node_t *node
       );

       0  is returned if the node (or its first	child) is not an integer value
       node.

   mxmlGetLastChild
       Get the last child of an	element	node.

       mxml_node_t * mxmlGetLastChild (
	   mxml_node_t *node
       );

       NULL is returned	if the node is not an element node or if the node  has
       no children.

   mxmlGetNextSibling
       mxml_node_t * mxmlGetNextSibling	(
	   mxml_node_t *node
       );

   mxmlGetOpaque
       Get an opaque string value for a	node or	its first child.

       const char * mxmlGetOpaque (
	   mxml_node_t *node
       );

       NULL  is	 returned  if  the  node (or its first child) is not an	opaque
       value node.

   mxmlGetParent
       Get the parent node.

       mxml_node_t * mxmlGetParent (
	   mxml_node_t *node
       );

       NULL is returned	for a root node.

   mxmlGetPrevSibling
       Get the previous	node for the current parent.

       mxml_node_t * mxmlGetPrevSibling	(
	   mxml_node_t *node
       );

       NULL is returned	if this	is the first child for the current parent.

   mxmlGetReal
       Get the real value for a	node or	its first child.

       double  mxmlGetReal (
	   mxml_node_t *node
       );

       0.0 is returned if the node (or its first child)	is not	a  real	 value
       node.

   mxmlGetRefCount
       Get the current reference (use) count for a node.

       int  mxmlGetRefCount (
	   mxml_node_t *node
       );

       The  initial  reference count of	new nodes is 1.	Use the	mxmlRetain and
       mxmlRelease functions to	increment and  decrement  a  node's  reference
       count.

   mxmlGetText
       Get the text value for a	node or	its first child.

       const char * mxmlGetText	(
	   mxml_node_t *node,
	   int *whitespace
       );

       NULL  is	 returned if the node (or its first child) is not a text node.
       The "whitespace"	argument can be	NULL.

       Note: Text nodes	consist	of whitespace-delimited	words. You  will  only
       get single words	of text	when reading an	XML file with MXML_TEXT	nodes.
       If you want the entire string between elements in  the  XML  file,  you
       MUST  read  the	XML  file with MXML_OPAQUE nodes and get the resulting
       strings using the mxmlGetOpaque function	instead.

   mxmlGetType
       Get the node type.

       mxml_type_t  mxmlGetType	(
	   mxml_node_t *node
       );

       MXML_IGNORE is returned if "node" is NULL.

   mxmlGetUserData
       Get the user data pointer for a node.

       void * mxmlGetUserData (
	   mxml_node_t *node
       );

   mxmlIndexDelete
       Delete an index.

       void mxmlIndexDelete (
	   mxml_index_t	*ind
       );

   mxmlIndexEnum
       Return the next node in the index.

       mxml_node_t * mxmlIndexEnum (
	   mxml_index_t	*ind
       );

       You should call mxmlIndexReset prior to using this function to get  the
       first node in the index.	 Nodes are returned in the sorted order	of the
       index.

   mxmlIndexFind
       Find the	next matching node.

       mxml_node_t * mxmlIndexFind (
	   mxml_index_t	*ind,
	   const char *element,
	   const char *value
       );

       You should call mxmlIndexReset prior to using  this  function  for  the
       first  time  with  a  particular	 set of	"element" and "value" strings.
       Passing NULL for	both "element" and "value" is  equivalent  to  calling
       mxmlIndexEnum.

   mxmlIndexGetCount
       Get the number of nodes in an index.

       int  mxmlIndexGetCount (
	   mxml_index_t	*ind
       );

   mxmlIndexNew
       Create a	new index.

       mxml_index_t * mxmlIndexNew (
	   mxml_node_t *node,
	   const char *element,
	   const char *attr
       );

       The  index will contain all nodes that contain the named	element	and/or
       attribute.  If both "element" and "attr"	are NULL, then the index  will
       contain	a  sorted  list	 of  the elements in the node tree.  Nodes are
       sorted by element name and optionally by	attribute value	if the	"attr"
       argument	is not NULL.

   mxmlIndexReset
       Reset  the  enumeration/find  pointer in	the index and return the first
       node in the index.

       mxml_node_t * mxmlIndexReset (
	   mxml_index_t	*ind
       );

       This function should be called prior to using mxmlIndexEnum or  mxmlIn-
       dexFind for the first time.

   mxmlLoadFd
       Load a file descriptor into an XML node tree.

       mxml_node_t * mxmlLoadFd	(
	   mxml_node_t *top,
	   int fd,
	   mxml_load_cb_t cb
       );

       The  nodes  in  the specified file are added to the specified top node.
       If no top node is provided, the XML file	MUST  be  well-formed  with  a
       single  parent node like	<?xml> for the entire file. The	callback func-
       tion returns the	value type that	should be used for child  nodes.   The
       constants  MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, MXML_REAL_CALL-
       BACK, and MXML_TEXT_CALLBACK are	defined	for loading child (data) nodes
       of the specified	type.

       Note: The most common programming error when using the Mini-XML library
       is to load an XML file using the	MXML_TEXT_CALLBACK, which returns  in-
       line  text  as a	series of whitespace-delimited words, instead of using
       the MXML_OPAQUE_CALLBACK	which returns the  inline  text	 as  a	single
       string (including whitespace).

   mxmlLoadFile
       Load a file into	an XML node tree.

       mxml_node_t * mxmlLoadFile (
	   mxml_node_t *top,
	   FILE	*fp,
	   mxml_load_cb_t cb
       );

       The  nodes  in  the specified file are added to the specified top node.
       If no top node is provided, the XML file	MUST  be  well-formed  with  a
       single  parent node like	<?xml> for the entire file. The	callback func-
       tion returns the	value type that	should be used for child  nodes.   The
       constants  MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, MXML_REAL_CALL-
       BACK, and MXML_TEXT_CALLBACK are	defined	for loading child (data) nodes
       of the specified	type.

       Note: The most common programming error when using the Mini-XML library
       is to load an XML file using the	MXML_TEXT_CALLBACK, which returns  in-
       line  text  as a	series of whitespace-delimited words, instead of using
       the MXML_OPAQUE_CALLBACK	which returns the  inline  text	 as  a	single
       string (including whitespace).

   mxmlLoadString
       Load a string into an XML node tree.

       mxml_node_t * mxmlLoadString (
	   mxml_node_t *top,
	   const char *s,
	   mxml_load_cb_t cb
       );

       The  nodes in the specified string are added to the specified top node.
       If no top node is provided, the XML string MUST be well-formed  with  a
       single  parent  node  like  <?xml>  for the entire string. The callback
       function	returns	the value type that should be used  for	 child	nodes.
       The	constants     MXML_INTEGER_CALLBACK,	 MXML_OPAQUE_CALLBACK,
       MXML_REAL_CALLBACK, and	MXML_TEXT_CALLBACK  are	 defined  for  loading
       child (data) nodes of the specified type.

       Note: The most common programming error when using the Mini-XML library
       is to load an XML file using the	MXML_TEXT_CALLBACK, which returns  in-
       line  text  as a	series of whitespace-delimited words, instead of using
       the MXML_OPAQUE_CALLBACK	which returns the  inline  text	 as  a	single
       string (including whitespace).

   mxmlNewCDATA
       Create a	new CDATA node.

       mxml_node_t * mxmlNewCDATA (
	   mxml_node_t *parent,
	   const char *data
       );

       The  new	CDATA node is added to the end of the specified	parent's child
       list.  The constant MXML_NO_PARENT can be used to specify that the  new
       CDATA  node  has	no parent.  The	data string must be nul-terminated and
       is copied into the new node.  CDATA nodes currently use	the  MXML_ELE-
       MENT type.

   mxmlNewCustom
       Create a	new custom data	node.

       mxml_node_t * mxmlNewCustom (
	   mxml_node_t *parent,
	   void	*data,
	   mxml_custom_destroy_cb_t destroy
       );

       The new custom node is added to the end of the specified	parent's child
       list. The constant MXML_NO_PARENT can be	used to	specify	that  the  new
       element	node  has  no  parent. NULL can	be passed when the data	in the
       node is not dynamically allocated or is separately managed.

   mxmlNewElement
       Create a	new element node.

       mxml_node_t * mxmlNewElement (
	   mxml_node_t *parent,
	   const char *name
       );

       The new element node is added to	the  end  of  the  specified  parent's
       child list. The constant	MXML_NO_PARENT can be used to specify that the
       new element node	has no parent.

   mxmlNewInteger
       Create a	new integer node.

       mxml_node_t * mxmlNewInteger (
	   mxml_node_t *parent,
	   int integer
       );

       The new integer node is added to	the  end  of  the  specified  parent's
       child list. The constant	MXML_NO_PARENT can be used to specify that the
       new integer node	has no parent.

   mxmlNewOpaque
       Create a	new opaque string.

       mxml_node_t * mxmlNewOpaque (
	   mxml_node_t *parent,
	   const char *opaque
       );

       The new opaque string node is added to the end of  the  specified  par-
       ent's  child  list.  The	constant MXML_NO_PARENT	can be used to specify
       that the	new opaque string node has no parent.  The opaque string  must
       be nul- terminated and is copied	into the new node.

   mxmlNewOpaquef
       Create a	new formatted opaque string node.

       mxml_node_t * mxmlNewOpaquef (
	   mxml_node_t *parent,
	   const char *format,
	   ...
       );

       The  new	 opaque	 string	node is	added to the end of the	specified par-
       ent's child list.  The constant MXML_NO_PARENT can be used  to  specify
       that  the new opaque string node	has no parent.	The format string must
       be nul-terminated and is	formatted into the new node.

   mxmlNewReal
       Create a	new real number	node.

       mxml_node_t * mxmlNewReal (
	   mxml_node_t *parent,
	   double real
       );

       The new real number node	is added to the	end of the specified  parent's
       child  list.   The  constant MXML_NO_PARENT can be used to specify that
       the new real number node	has no parent.

   mxmlNewText
       Create a	new text fragment node.

       mxml_node_t * mxmlNewText (
	   mxml_node_t *parent,
	   int whitespace,
	   const char *string
       );

       The new text node is added to the end of	the specified  parent's	 child
       list.   The constant MXML_NO_PARENT can be used to specify that the new
       text node has no	parent.	 The whitespace	parameter is used  to  specify
       whether leading whitespace is present before the	node.  The text	string
       must be nul-terminated and is copied into the new node.

   mxmlNewTextf
       Create a	new formatted text fragment node.

       mxml_node_t * mxmlNewTextf (
	   mxml_node_t *parent,
	   int whitespace,
	   const char *format,
	   ...
       );

       The new text node is added to the end of	the specified  parent's	 child
       list.   The constant MXML_NO_PARENT can be used to specify that the new
       text node has no	parent.	 The whitespace	parameter is used  to  specify
       whether	leading	 whitespace  is	 present  before the node.  The	format
       string must be nul-terminated and is formatted into the new node.

   mxmlNewXML
       Create a	new XML	document tree.

       mxml_node_t * mxmlNewXML	(
	   const char *version
       );

       The "version" argument specifies	the version number to put in the  ?xml
       element node. If	NULL, version "1.0" is assumed.

   mxmlRelease
       Release a node.

       int  mxmlRelease	(
	   mxml_node_t *node
       );

       When  the  reference count reaches zero,	the node (and any children) is
       deleted via mxmlDelete.

   mxmlRemove
       Remove a	node from its parent.

       void mxmlRemove (
	   mxml_node_t *node
       );

       This function does not free memory used by the node  -  use  mxmlDelete
       for that.  This function	does nothing if	the node has no	parent.

   mxmlRetain
       Retain a	node.

       int  mxmlRetain (
	   mxml_node_t *node
       );

   mxmlSAXLoadFd
       Load a file descriptor into an XML node tree using a SAX	callback.

       mxml_node_t * mxmlSAXLoadFd (
	   mxml_node_t *top,
	   int fd,
	   mxml_load_cb_t cb,
	   mxml_sax_cb_t sax_cb,
	   void	*sax_data
       );

       The  nodes  in  the specified file are added to the specified top node.
       If no top node is provided, the XML file	MUST  be  well-formed  with  a
       single  parent node like	<?xml> for the entire file. The	callback func-
       tion returns the	value type that	should be used for child  nodes.   The
       constants  MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, MXML_REAL_CALL-
       BACK, and MXML_TEXT_CALLBACK are	defined	for loading child nodes	of the
       specified type.

       The  SAX	 callback  must	 call mxmlRetain for any nodes that need to be
       kept for	later use. Otherwise, nodes are	deleted	when the  parent  node
       is closed or after each data, comment, CDATA, or	directive node.

   mxmlSAXLoadFile
       Load a file into	an XML node tree using a SAX callback.

       mxml_node_t * mxmlSAXLoadFile (
	   mxml_node_t *top,
	   FILE	*fp,
	   mxml_load_cb_t cb,
	   mxml_sax_cb_t sax_cb,
	   void	*sax_data
       );

       The  nodes  in  the specified file are added to the specified top node.
       If no top node is provided, the XML file	MUST  be  well-formed  with  a
       single  parent node like	<?xml> for the entire file. The	callback func-
       tion returns the	value type that	should be used for child  nodes.   The
       constants  MXML_INTEGER_CALLBACK, MXML_OPAQUE_CALLBACK, MXML_REAL_CALL-
       BACK, and MXML_TEXT_CALLBACK are	defined	for loading child nodes	of the
       specified type.

       The  SAX	 callback  must	 call mxmlRetain for any nodes that need to be
       kept for	later use. Otherwise, nodes are	deleted	when the  parent  node
       is closed or after each data, comment, CDATA, or	directive node.

   mxmlSAXLoadString
       Load a string into an XML node tree using a SAX callback.

       mxml_node_t * mxmlSAXLoadString (
	   mxml_node_t *top,
	   const char *s,
	   mxml_load_cb_t cb,
	   mxml_sax_cb_t sax_cb,
	   void	*sax_data
       );

       The  nodes in the specified string are added to the specified top node.
       If no top node is provided, the XML string MUST be well-formed  with  a
       single  parent  node  like  <?xml>  for the entire string. The callback
       function	returns	the value type that should be used  for	 child	nodes.
       The	constants     MXML_INTEGER_CALLBACK,	 MXML_OPAQUE_CALLBACK,
       MXML_REAL_CALLBACK, and	MXML_TEXT_CALLBACK  are	 defined  for  loading
       child nodes of the specified type.

       The  SAX	 callback  must	 call mxmlRetain for any nodes that need to be
       kept for	later use. Otherwise, nodes are	deleted	when the  parent  node
       is closed or after each data, comment, CDATA, or	directive node.

   mxmlSaveAllocString
       Save an XML tree	to an allocated	string.

       char * mxmlSaveAllocString (
	   mxml_node_t *node,
	   mxml_save_cb_t cb
       );

       This function returns a pointer to a string containing the textual rep-
       resentation of the XML node tree.  The string should be freed using the
       free()  function	 when  you  are	done with it.  NULL is returned	if the
       node would produce an empty string or if	the  string  cannot  be	 allo-
       cated.

       The  callback  argument	specifies a function that returns a whitespace
       string or NULL before and after each element.  If  MXML_NO_CALLBACK  is
       specified,  whitespace  will  only be added before MXML_TEXT nodes with
       leading whitespace and before attribute names  inside  opening  element
       tags.

   mxmlSaveFd
       Save an XML tree	to a file descriptor.

       int  mxmlSaveFd (
	   mxml_node_t *node,
	   int fd,
	   mxml_save_cb_t cb
       );

       The  callback  argument	specifies a function that returns a whitespace
       string or NULL before and after each element.  If  MXML_NO_CALLBACK  is
       specified,  whitespace  will  only be added before MXML_TEXT nodes with
       leading whitespace and before attribute names  inside  opening  element
       tags.

   mxmlSaveFile
       Save an XML tree	to a file.

       int  mxmlSaveFile (
	   mxml_node_t *node,
	   FILE	*fp,
	   mxml_save_cb_t cb
       );

       The  callback  argument	specifies a function that returns a whitespace
       string or NULL before and after each element.  If  MXML_NO_CALLBACK  is
       specified,  whitespace  will  only be added before MXML_TEXT nodes with
       leading whitespace and before attribute names  inside  opening  element
       tags.

   mxmlSaveString
       Save an XML node	tree to	a string.

       int  mxmlSaveString (
	   mxml_node_t *node,
	   char	*buffer,
	   int bufsize,
	   mxml_save_cb_t cb
       );

       This  function returns the total	number of bytes	that would be required
       for the string but only copies (bufsize - 1) characters into the	speci-
       fied buffer.

       The  callback  argument	specifies a function that returns a whitespace
       string or NULL before and after each element.  If  MXML_NO_CALLBACK  is
       specified,  whitespace  will  only be added before MXML_TEXT nodes with
       leading whitespace and before attribute names  inside  opening  element
       tags.

   mxmlSetCDATA
       Set the element name of a CDATA node.

       int  mxmlSetCDATA (
	   mxml_node_t *node,
	   const char *data
       );

       The  node is not	changed	if it (or its first child) is not a CDATA ele-
       ment node.

   mxmlSetCustom
       Set the data and	destructor of a	custom data node.

       int  mxmlSetCustom (
	   mxml_node_t *node,
	   void	*data,
	   mxml_custom_destroy_cb_t destroy
       );

       The node	is not changed if it (or its first  child)  is	not  a	custom
       node.

   mxmlSetCustomHandlers
       Set the handling	functions for custom data.

       void mxmlSetCustomHandlers (
	   mxml_custom_load_cb_t load,
	   mxml_custom_save_cb_t save
       );

       The load	function accepts a node	pointer	and a data string and must re-
       turn 0 on success and non-zero on error.

       The save	function accepts a node	pointer	and  must  return  a  malloc'd
       string on success and NULL on error.

   mxmlSetElement
       Set the name of an element node.

       int  mxmlSetElement (
	   mxml_node_t *node,
	   const char *name
       );

       The node	is not changed if it is	not an element node.

   mxmlSetErrorCallback
       Set the error message callback.

       void mxmlSetErrorCallback (
	   mxml_error_cb_t cb
       );

   mxmlSetInteger
       Set the value of	an integer node.

       int  mxmlSetInteger (
	   mxml_node_t *node,
	   int integer
       );

       The  node  is  not changed if it	(or its	first child) is	not an integer
       node.

   mxmlSetOpaque
       Set the value of	an opaque node.

       int  mxmlSetOpaque (
	   mxml_node_t *node,
	   const char *opaque
       );

       The node	is not changed if it (or its first child)  is  not  an	opaque
       node.

   mxmlSetOpaquef
       Set the value of	an opaque string node to a formatted string.

       int  mxmlSetOpaquef (
	   mxml_node_t *node,
	   const char *format,
	   ...
       );

       The  node  is  not  changed if it (or its first child) is not an	opaque
       node.

   mxmlSetReal
       Set the value of	a real number node.

       int  mxmlSetReal	(
	   mxml_node_t *node,
	   double real
       );

       The node	is not changed if it (or its first child) is not a real	number
       node.

   mxmlSetText
       Set the value of	a text node.

       int  mxmlSetText	(
	   mxml_node_t *node,
	   int whitespace,
	   const char *string
       );

       The node	is not changed if it (or its first child) is not a text	node.

   mxmlSetTextf
       Set the value of	a text node to a formatted string.

       int  mxmlSetTextf (
	   mxml_node_t *node,
	   int whitespace,
	   const char *format,
	   ...
       );

       The node	is not changed if it (or its first child) is not a text	node.

   mxmlSetUserData
       Set the user data pointer for a node.

       int  mxmlSetUserData (
	   mxml_node_t *node,
	   void	*data
       );

   mxmlSetWrapMargin
       Set the wrap margin when	saving XML data.

       void mxmlSetWrapMargin (
	   int column
       );

       Wrapping	is disabled when "column" is 0.

   mxmlWalkNext
       Walk to the next	logical	node in	the tree.

       mxml_node_t * mxmlWalkNext (
	   mxml_node_t *node,
	   mxml_node_t *top,
	   int descend
       );

       The  descend argument controls whether the first	child is considered to
       be the next node.  The top node argument	constrains  the	 walk  to  the
       node's children.

   mxmlWalkPrev
       Walk to the previous logical node in the	tree.

       mxml_node_t * mxmlWalkPrev (
	   mxml_node_t *node,
	   mxml_node_t *top,
	   int descend
       );

       The descend argument controls whether the previous node's last child is
       considered to be	the previous node.  The	top node  argument  constrains
       the walk	to the node's children.

TYPES
   mxml_custom_destroy_cb_t
       Custom data destructor

       typedef void(*)(void *) mxml_custom_destroy_cb_t;

   mxml_custom_load_cb_t
       Custom data load	callback function

       typedef int(*)(mxml_node_t *, const char	*) mxml_custom_load_cb_t;

   mxml_custom_save_cb_t
       Custom data save	callback function

       typedef char *(*)(mxml_node_t *)	mxml_custom_save_cb_t;

   mxml_entity_cb_t
       Entity callback function

       typedef int(*)(const char *) mxml_entity_cb_t;

   mxml_error_cb_t
       Error callback function

       typedef void(*)(const char *) mxml_error_cb_t;

   mxml_index_t
       An XML node index.

       typedef struct _mxml_index_s mxml_index_t;

   mxml_load_cb_t
       Load callback function

       typedef mxml_type_t(*)(mxml_node_t *) mxml_load_cb_t;

   mxml_node_t
       An XML node.

       typedef struct _mxml_node_s mxml_node_t;

   mxml_save_cb_t
       Save callback function

       typedef const char *(*)(mxml_node_t *, int) mxml_save_cb_t;

   mxml_sax_cb_t
       SAX callback function

       typedef void(*)(mxml_node_t *, mxml_sax_event_t,	void *)	mxml_sax_cb_t;

   mxml_sax_event_t
       SAX event type.

       typedef enum mxml_sax_event_e mxml_sax_event_t;

   mxml_type_t
       The XML node type.

       typedef enum mxml_type_e	mxml_type_t;

SEE ALSO
       Mini-XML	Programmers Manual, https://www.msweet.org/mxml

COPYRIGHT
       Copyright (C) 2003-2019 by Michael R Sweet.

2019-07-03			 Mini-XML API			       mxml(3)

NAME | INCLUDE FILE | LIBRARY | DESCRIPTION | USING MINI-XML | ENUMERATIONS | FUNCTIONS | TYPES | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mxml&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help