1mxml(3) Mini-XML API mxml(3)
2
6 mxml - Mini-XML API
7
9 #include <mxml.h>
10
12 -lmxml
13
15 Mini-XML is a small XML parsing library that you can use to read XML
16 and XML-like data files in your application without requiring large
17 non-standard libraries. Mini-XML only requires an ANSI C compatible
18 compiler (GCC works, as do most vendors' ANSI C compilers) and a "make"
19 program.
20 Mini-XML provides the following functionality:
22 • Reading of UTF-8 and UTF-16 and writing of UTF-8 encoded XML files
24 and strings.
25 • Data is stored in a linked-list tree structure, preserving the XML
27 data hierarchy.
28 • Supports arbitrary element names, attributes, and attribute values
30 with no preset limits, just available memory.
31 • Supports integer, real, opaque ("CDATA"), and text data types in
33 "leaf" nodes.
34 • Functions for creating, indexing, and managing trees of data.
36 • "Find" and "walk" functions for easily locating and navigating
38 trees of data.
39 Mini-XML doesn't do validation or other types of processing on the data
41 based upon schema files or other sources of definition information, nor
42 does it support character entities other than those required by the XML
43 specification.
44
46 Mini-XML provides a single header file which you include:
47 #include <mxml.h>
49 Nodes are defined by the "mxml_node_t" structure; the "type" member de‐
51 fines the node type (element, integer, opaque, real, or text) which de‐
52 termines which value you want to look at in the "value" union. New
53 nodes can be created using the "mxmlNewElement()", "mxmlNewInteger()",
54 "mxmlNewOpaque()", "mxmlNewReal()", and "mxmlNewText()" functions.
55 Only elements can have child nodes, and the top node must be an ele‐
56 ment, usually "?xml".
57 You load an XML file using the "mxmlLoadFile()" function:
59 FILE *fp;
61 mxml_node_t *tree;
62 fp = fopen("filename.xml", "r");
64 tree = mxmlLoadFile(NULL, fp, MXML_NO_CALLBACK);
65 fclose(fp);
66 Similarly, you save an XML file using the "mxmlSaveFile()" function:
68 FILE *fp;
70 mxml_node_t *tree;
71 fp = fopen("filename.xml", "w");
73 mxmlSaveFile(tree, fp, MXML_NO_CALLBACK);
74 fclose(fp);
75 The "mxmlLoadString()", "mxmlSaveAllocString()", and "mxmlSaveString()"
77 functions load XML node trees from and save XML node trees to strings:
78 char buffer[8192];
80 char *ptr;
81 mxml_node_t *tree;
82 ...
84 tree = mxmlLoadString(NULL, buffer, MXML_NO_CALLBACK);
85 ...
87 mxmlSaveString(tree, buffer, sizeof(buffer),
88 MXML_NO_CALLBACK);
89 ...
91 ptr = mxmlSaveAllocString(tree, MXML_NO_CALLBACK);
92 You can find a named element/node using the "mxmlFindElement()" func‐
94 tion:
95 mxml_node_t *node = mxmlFindElement(tree, tree, "name",
97 "attr", "value",
98 MXML_DESCEND);
99 The "name", "attr", and "value" arguments can be passed as NULL to act
101 as wildcards, e.g.:
102 /* Find the first "a" element */
104 node = mxmlFindElement(tree, tree, "a", NULL, NULL,
105 MXML_DESCEND);
106 /* Find the first "a" element with "href" attribute */
108 node = mxmlFindElement(tree, tree, "a", "href", NULL,
109 MXML_DESCEND);
110 /* Find the first "a" element with "href" to a URL */
112 node = mxmlFindElement(tree, tree, "a", "href",
113 "http://www.easysw.com/~mike/mxml/",
114 MXML_DESCEND);
115 /* Find the first element with a "src" attribute*/
117 node = mxmlFindElement(tree, tree, NULL, "src", NULL,
118 MXML_DESCEND);
119 /* Find the first element with a "src" = "foo.jpg" */
121 node = mxmlFindElement(tree, tree, NULL, "src",
122 "foo.jpg", MXML_DESCEND);
123 You can also iterate with the same function:
125 mxml_node_t *node;
127 for (node = mxmlFindElement(tree, tree, "name", NULL,
129 NULL, MXML_DESCEND);
130 node != NULL;
131 node = mxmlFindElement(node, tree, "name", NULL,
132 NULL, MXML_DESCEND))
133 {
134 ... do something ...
135 }
136 To find the value of a specific node in the tree, use the "mxmlFind‐
138 Path()" function:
139 mxml_node_t *value = mxmlFindPath(tree, "path/to/*/foo/bar");
141 The "mxmlGetInteger()", "mxmlGetOpaque()", "mxmlGetReal()", and "mxml‐
143 GetText()" functions retrieve the value from a node:
144 mxml_node_t *node;
146 int intvalue = mxmlGetInteger(node);
148 const char *opaquevalue = mxmlGetOpaque(node);
150 double realvalue = mxmlGetReal(node);
152 int whitespacevalue;
154 const char *textvalue = mxmlGetText(node, &whitespacevalue);
155 Finally, once you are done with the XML data, use the "mxmlDelete()"
157 function to recursively free the memory that is used for a particular
158 node or the entire tree:
159 mxmlDelete(tree);
161
163 mxml_sax_event_e
164 SAX event type.
165 MXML_SAX_CDATA
167 CDATA node
168 MXML_SAX_COMMENT
170 Comment node
171 MXML_SAX_DATA
173 Data node
174 MXML_SAX_DIRECTIVE
176 Processing directive node
177 MXML_SAX_ELEMENT_CLOSE
179 Element closed
180 MXML_SAX_ELEMENT_OPEN
182 Element opened
183 mxml_type_e
185 The XML node type.
186 MXML_CUSTOM
188 Custom data
189 MXML_ELEMENT
191 XML element with attributes
192 MXML_IGNORE
194 Ignore/throw away node
195 MXML_INTEGER
197 Integer value
198 MXML_OPAQUE
200 Opaque string
201 MXML_REAL
203 Real value
204 MXML_TEXT
206 Text fragment
207
209 mxmlAdd
210 Add a node to a tree.
211 void mxmlAdd (
213 mxml_node_t *parent,
214 int where,
215 mxml_node_t *child,
216 mxml_node_t *node
217 );
218 Adds the specified node to the parent. If the child argument is not
220 NULL, puts the new node before or after the specified child depending
221 on the value of the where argument. If the child argument is NULL,
222 puts the new node at the beginning of the child list (MXML_ADD_BEFORE)
223 or at the end of the child list (MXML_ADD_AFTER). The constant
224 MXML_ADD_TO_PARENT can be used to specify a NULL child pointer.
225 mxmlDelete
227 Delete a node and all of its children.
228 void mxmlDelete (
230 mxml_node_t *node
231 );
232 If the specified node has a parent, this function first removes the
234 node from its parent using the mxmlRemove function.
235 mxmlElementDeleteAttr
237 Delete an attribute.
238 void mxmlElementDeleteAttr (
240 mxml_node_t *node,
241 const char *name
242 );
243 mxmlElementGetAttr
245 Get an attribute.
246 const char * mxmlElementGetAttr (
248 mxml_node_t *node,
249 const char *name
250 );
251 This function returns NULL if the node is not an element or the named
253 attribute does not exist.
254 mxmlElementGetAttrByIndex
256 Get an element attribute by index.
257 const char * mxmlElementGetAttrByIndex (
259 mxml_node_t *node,
260 int idx,
261 const char **name
262 );
263 The index ("idx") is 0-based. NULL is returned if the specified index
265 is out of range.
266 mxmlElementGetAttrCount
270 Get the number of element attributes.
271 int mxmlElementGetAttrCount (
273 mxml_node_t *node
274 );
275 mxmlElementSetAttr
277 Set an attribute.
278 void mxmlElementSetAttr (
280 mxml_node_t *node,
281 const char *name,
282 const char *value
283 );
284 If the named attribute already exists, the value of the attribute is
286 replaced by the new string value. The string value is copied into the
287 element node. This function does nothing if the node is not an element.
288 mxmlElementSetAttrf
290 Set an attribute with a formatted value.
291 void mxmlElementSetAttrf (
293 mxml_node_t *node,
294 const char *name,
295 const char *format,
296 ...
297 );
298 If the named attribute already exists, the value of the attribute is
300 replaced by the new formatted string. The formatted string value is
301 copied into the element node. This function does nothing if the node is
302 not an element.
303 mxmlEntityAddCallback
307 Add a callback to convert entities to Unicode.
308 int mxmlEntityAddCallback (
310 mxml_entity_cb_t cb
311 );
312 mxmlEntityGetName
314 Get the name that corresponds to the character value.
315 const char * mxmlEntityGetName (
317 int val
318 );
319 If val does not need to be represented by a named entity, NULL is re‐
321 turned.
322 mxmlEntityGetValue
324 Get the character corresponding to a named entity.
325 int mxmlEntityGetValue (
327 const char *name
328 );
329 The entity name can also be a numeric constant. -1 is returned if the
331 name is not known.
332 mxmlEntityRemoveCallback
334 Remove a callback.
335 void mxmlEntityRemoveCallback (
337 mxml_entity_cb_t cb
338 );
339 mxmlFindElement
341 Find the named element.
342 mxml_node_t * mxmlFindElement (
344 mxml_node_t *node,
345 mxml_node_t *top,
346 const char *element,
347 const char *attr,
348 const char *value,
349 int descend
350 );
351 The search is constrained by the name, attribute name, and value; any
353 NULL names or values are treated as wildcards, so different kinds of
354 searches can be implemented by looking for all elements of a given name
355 or all elements with a specific attribute. The descend argument deter‐
356 mines whether the search descends into child nodes; normally you will
357 use MXML_DESCEND_FIRST for the initial search and MXML_NO_DESCEND to
358 find additional direct descendents of the node. The top node argument
359 constrains the search to a particular node's children.
360 mxmlFindPath
362 Find a node with the given path.
363 mxml_node_t * mxmlFindPath (
365 mxml_node_t *top,
366 const char *path
367 );
368 The "path" is a slash-separated list of element names. The name "" is
370 considered a wildcard for one or more levels of elements. For example,
371 "foo/one/two", "bar/two/one", "/one", and so forth.
372 The first child node of the found node is returned if the given node
374 has children and the first child is a value node.
375 mxmlGetCDATA
379 Get the value for a CDATA node.
380 const char * mxmlGetCDATA (
382 mxml_node_t *node
383 );
384 NULL is returned if the node is not a CDATA element.
386 mxmlGetCustom
390 Get the value for a custom node.
391 const void * mxmlGetCustom (
393 mxml_node_t *node
394 );
395 NULL is returned if the node (or its first child) is not a custom value
397 node.
398 mxmlGetElement
402 Get the name for an element node.
403 const char * mxmlGetElement (
405 mxml_node_t *node
406 );
407 NULL is returned if the node is not an element node.
409 mxmlGetFirstChild
413 Get the first child of an element node.
414 mxml_node_t * mxmlGetFirstChild (
416 mxml_node_t *node
417 );
418 NULL is returned if the node is not an element node or if the node has
420 no children.
421 mxmlGetInteger
425 Get the integer value from the specified node or its first child.
426 int mxmlGetInteger (
428 mxml_node_t *node
429 );
430 0 is returned if the node (or its first child) is not an integer value
432 node.
433 mxmlGetLastChild
437 Get the last child of an element node.
438 mxml_node_t * mxmlGetLastChild (
440 mxml_node_t *node
441 );
442 NULL is returned if the node is not an element node or if the node has
444 no children.
445 mxmlGetNextSibling
449 mxml_node_t * mxmlGetNextSibling (
450 mxml_node_t *node
451 );
452 mxmlGetOpaque
454 Get an opaque string value for a node or its first child.
455 const char * mxmlGetOpaque (
457 mxml_node_t *node
458 );
459 NULL is returned if the node (or its first child) is not an opaque
461 value node.
462 mxmlGetParent
466 Get the parent node.
467 mxml_node_t * mxmlGetParent (
469 mxml_node_t *node
470 );
471 NULL is returned for a root node.
473 mxmlGetPrevSibling
477 Get the previous node for the current parent.
478 mxml_node_t * mxmlGetPrevSibling (
480 mxml_node_t *node
481 );
482 NULL is returned if this is the first child for the current parent.
484 mxmlGetReal
488 Get the real value for a node or its first child.
489 double mxmlGetReal (
491 mxml_node_t *node
492 );
493 0.0 is returned if the node (or its first child) is not a real value
495 node.
496 mxmlGetRefCount
500 Get the current reference (use) count for a node.
501 int mxmlGetRefCount (
503 mxml_node_t *node
504 );
505 The initial reference count of new nodes is 1. Use the mxmlRetain and
507 mxmlRelease functions to increment and decrement a node's reference
508 count.
509 mxmlGetText
512 Get the text value for a node or its first child.
513 const char * mxmlGetText (
515 mxml_node_t *node,
516 int *whitespace
517 );
518 NULL is returned if the node (or its first child) is not a text node.
520 The "whitespace" argument can be NULL.
521 Note: Text nodes consist of whitespace-delimited words. You will only
523 get single words of text when reading an XML file with MXML_TEXT nodes.
524 If you want the entire string between elements in the XML file, you
525 MUST read the XML file with MXML_OPAQUE nodes and get the resulting
526 strings using the mxmlGetOpaque function instead.
527 mxmlGetType
531 Get the node type.
532 mxml_type_t mxmlGetType (
534 mxml_node_t *node
535 );
536 MXML_IGNORE is returned if "node" is NULL.
538 mxmlGetUserData
542 Get the user data pointer for a node.
543 void * mxmlGetUserData (
545 mxml_node_t *node
546 );
547 mxmlIndexDelete
549 Delete an index.
550 void mxmlIndexDelete (
552 mxml_index_t *ind
553 );
554 mxmlIndexEnum
556 Return the next node in the index.
557 mxml_node_t * mxmlIndexEnum (
559 mxml_index_t *ind
560 );
561 You should call mxmlIndexReset prior to using this function to get the
563 first node in the index. Nodes are returned in the sorted order of the
564 index.
565 mxmlIndexFind
567 Find the next matching node.
568 mxml_node_t * mxmlIndexFind (
570 mxml_index_t *ind,
571 const char *element,
572 const char *value
573 );
574 You should call mxmlIndexReset prior to using this function for the
576 first time with a particular set of "element" and "value" strings.
577 Passing NULL for both "element" and "value" is equivalent to calling
578 mxmlIndexEnum.
579 mxmlIndexGetCount
581 Get the number of nodes in an index.
582 int mxmlIndexGetCount (
584 mxml_index_t *ind
585 );
586 mxmlIndexNew
588 Create a new index.
589 mxml_index_t * mxmlIndexNew (
591 mxml_node_t *node,
592 const char *element,
593 const char *attr
594 );
595 The index will contain all nodes that contain the named element and/or
597 attribute. If both "element" and "attr" are NULL, then the index will
598 contain a sorted list of the elements in the node tree. Nodes are
599 sorted by element name and optionally by attribute value if the "attr"
600 argument is not NULL.
601 mxmlIndexReset
603 Reset the enumeration/find pointer in the index and return the first
604 node in the index.
605 mxml_node_t * mxmlIndexReset (
607 mxml_index_t *ind
608 );
609 This function should be called prior to using mxmlIndexEnum or mxmlIn‐
611 dexFind for the first time.
612 mxmlLoadFd
614 Load a file descriptor into an XML node tree.
615 mxml_node_t * mxmlLoadFd (
617 mxml_node_t *top,
618 int fd,
619 mxml_load_cb_t cb
620 );
621 The nodes in the specified file are added to the specified top node.
623 If no top node is provided, the XML file MUST be well-formed with a
624 single parent node like
625 for the entire file. The callback function returns the value type that
626 should be used for child nodes. The constants MXML_INTEGER_CALLBACK,
627 MXML_OPAQUE_CALLBACK, MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are
628 defined for loading child (data) nodes of the specified type.
629 Note: The most common programming error when using the Mini-XML library
631 is to load an XML file using the MXML_TEXT_CALLBACK, which returns in‐
632 line text as a series of whitespace-delimited words, instead of using
633 the MXML_OPAQUE_CALLBACK which returns the inline text as a single
634 string (including whitespace).
635 mxmlLoadFile
637 Load a file into an XML node tree.
638 mxml_node_t * mxmlLoadFile (
640 mxml_node_t *top,
641 FILE *fp,
642 mxml_load_cb_t cb
643 );
644 The nodes in the specified file are added to the specified top node.
646 If no top node is provided, the XML file MUST be well-formed with a
647 single parent node like
648 for the entire file. The callback function returns the value type that
649 should be used for child nodes. The constants MXML_INTEGER_CALLBACK,
650 MXML_OPAQUE_CALLBACK, MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are
651 defined for loading child (data) nodes of the specified type.
652 Note: The most common programming error when using the Mini-XML library
654 is to load an XML file using the MXML_TEXT_CALLBACK, which returns in‐
655 line text as a series of whitespace-delimited words, instead of using
656 the MXML_OPAQUE_CALLBACK which returns the inline text as a single
657 string (including whitespace).
658 mxmlLoadString
660 Load a string into an XML node tree.
661 mxml_node_t * mxmlLoadString (
663 mxml_node_t *top,
664 const char *s,
665 mxml_load_cb_t cb
666 );
667 The nodes in the specified string are added to the specified top node.
669 If no top node is provided, the XML string MUST be well-formed with a
670 single parent node like
671 for the entire string. The callback function returns the value type
672 that should be used for child nodes. The constants MXML_INTEGER_CALL‐
673 BACK, MXML_OPAQUE_CALLBACK, MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK
674 are defined for loading child (data) nodes of the specified type.
675 Note: The most common programming error when using the Mini-XML library
677 is to load an XML file using the MXML_TEXT_CALLBACK, which returns in‐
678 line text as a series of whitespace-delimited words, instead of using
679 the MXML_OPAQUE_CALLBACK which returns the inline text as a single
680 string (including whitespace).
681 mxmlNewCDATA
683 Create a new CDATA node.
684 mxml_node_t * mxmlNewCDATA (
686 mxml_node_t *parent,
687 const char *data
688 );
689 The new CDATA node is added to the end of the specified parent's child
691 list. The constant MXML_NO_PARENT can be used to specify that the new
692 CDATA node has no parent. The data string must be nul-terminated and
693 is copied into the new node. CDATA nodes currently use the MXML_ELE‐
694 MENT type.
695 mxmlNewCustom
699 Create a new custom data node.
700 mxml_node_t * mxmlNewCustom (
702 mxml_node_t *parent,
703 void *data,
704 mxml_custom_destroy_cb_t destroy
705 );
706 The new custom node is added to the end of the specified parent's child
708 list. The constant MXML_NO_PARENT can be used to specify that the new
709 element node has no parent. NULL can be passed when the data in the
710 node is not dynamically allocated or is separately managed.
711 mxmlNewElement
715 Create a new element node.
716 mxml_node_t * mxmlNewElement (
718 mxml_node_t *parent,
719 const char *name
720 );
721 The new element node is added to the end of the specified parent's
723 child list. The constant MXML_NO_PARENT can be used to specify that the
724 new element node has no parent.
725 mxmlNewInteger
727 Create a new integer node.
728 mxml_node_t * mxmlNewInteger (
730 mxml_node_t *parent,
731 int integer
732 );
733 The new integer node is added to the end of the specified parent's
735 child list. The constant MXML_NO_PARENT can be used to specify that the
736 new integer node has no parent.
737 mxmlNewOpaque
739 Create a new opaque string.
740 mxml_node_t * mxmlNewOpaque (
742 mxml_node_t *parent,
743 const char *opaque
744 );
745 The new opaque string node is added to the end of the specified par‐
747 ent's child list. The constant MXML_NO_PARENT can be used to specify
748 that the new opaque string node has no parent. The opaque string must
749 be nul- terminated and is copied into the new node.
750 mxmlNewOpaquef
752 Create a new formatted opaque string node.
753 mxml_node_t * mxmlNewOpaquef (
755 mxml_node_t *parent,
756 const char *format,
757 ...
758 );
759 The new opaque string node is added to the end of the specified par‐
761 ent's child list. The constant MXML_NO_PARENT can be used to specify
762 that the new opaque string node has no parent. The format string must
763 be nul-terminated and is formatted into the new node.
764 mxmlNewReal
766 Create a new real number node.
767 mxml_node_t * mxmlNewReal (
769 mxml_node_t *parent,
770 double real
771 );
772 The new real number node is added to the end of the specified parent's
774 child list. The constant MXML_NO_PARENT can be used to specify that
775 the new real number node has no parent.
776 mxmlNewText
778 Create a new text fragment node.
779 mxml_node_t * mxmlNewText (
781 mxml_node_t *parent,
782 int whitespace,
783 const char *string
784 );
785 The new text node is added to the end of the specified parent's child
787 list. The constant MXML_NO_PARENT can be used to specify that the new
788 text node has no parent. The whitespace parameter is used to specify
789 whether leading whitespace is present before the node. The text string
790 must be nul-terminated and is copied into the new node.
791 mxmlNewTextf
793 Create a new formatted text fragment node.
794 mxml_node_t * mxmlNewTextf (
796 mxml_node_t *parent,
797 int whitespace,
798 const char *format,
799 ...
800 );
801 The new text node is added to the end of the specified parent's child
803 list. The constant MXML_NO_PARENT can be used to specify that the new
804 text node has no parent. The whitespace parameter is used to specify
805 whether leading whitespace is present before the node. The format
806 string must be nul-terminated and is formatted into the new node.
807 mxmlNewXML
809 Create a new XML document tree.
810 mxml_node_t * mxmlNewXML (
812 const char *version
813 );
814 The "version" argument specifies the version number to put in the ?xml
816 element node. If NULL, version "1.0" is assumed.
817 mxmlRelease
821 Release a node.
822 int mxmlRelease (
824 mxml_node_t *node
825 );
826 When the reference count reaches zero, the node (and any children) is
828 deleted via mxmlDelete.
829 mxmlRemove
833 Remove a node from its parent.
834 void mxmlRemove (
836 mxml_node_t *node
837 );
838 This function does not free memory used by the node - use mxmlDelete
840 for that. This function does nothing if the node has no parent.
841 mxmlRetain
843 Retain a node.
844 int mxmlRetain (
846 mxml_node_t *node
847 );
848 mxmlSAXLoadFd
850 Load a file descriptor into an XML node tree using a SAX callback.
851 mxml_node_t * mxmlSAXLoadFd (
853 mxml_node_t *top,
854 int fd,
855 mxml_load_cb_t cb,
856 mxml_sax_cb_t sax_cb,
857 void *sax_data
858 );
859 The nodes in the specified file are added to the specified top node.
861 If no top node is provided, the XML file MUST be well-formed with a
862 single parent node like
863 for the entire file. The callback function returns the value type that
864 should be used for child nodes. The constants MXML_INTEGER_CALLBACK,
865 MXML_OPAQUE_CALLBACK, MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are
866 defined for loading child nodes of the specified type.
867 The SAX callback must call mxmlRetain for any nodes that need to be
869 kept for later use. Otherwise, nodes are deleted when the parent node
870 is closed or after each data, comment, CDATA, or directive node.
871 mxmlSAXLoadFile
875 Load a file into an XML node tree using a SAX callback.
876 mxml_node_t * mxmlSAXLoadFile (
878 mxml_node_t *top,
879 FILE *fp,
880 mxml_load_cb_t cb,
881 mxml_sax_cb_t sax_cb,
882 void *sax_data
883 );
884 The nodes in the specified file are added to the specified top node.
886 If no top node is provided, the XML file MUST be well-formed with a
887 single parent node like
888 for the entire file. The callback function returns the value type that
889 should be used for child nodes. The constants MXML_INTEGER_CALLBACK,
890 MXML_OPAQUE_CALLBACK, MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK are
891 defined for loading child nodes of the specified type.
892 The SAX callback must call mxmlRetain for any nodes that need to be
894 kept for later use. Otherwise, nodes are deleted when the parent node
895 is closed or after each data, comment, CDATA, or directive node.
896 mxmlSAXLoadString
900 Load a string into an XML node tree using a SAX callback.
901 mxml_node_t * mxmlSAXLoadString (
903 mxml_node_t *top,
904 const char *s,
905 mxml_load_cb_t cb,
906 mxml_sax_cb_t sax_cb,
907 void *sax_data
908 );
909 The nodes in the specified string are added to the specified top node.
911 If no top node is provided, the XML string MUST be well-formed with a
912 single parent node like
913 for the entire string. The callback function returns the value type
914 that should be used for child nodes. The constants MXML_INTEGER_CALL‐
915 BACK, MXML_OPAQUE_CALLBACK, MXML_REAL_CALLBACK, and MXML_TEXT_CALLBACK
916 are defined for loading child nodes of the specified type.
917 The SAX callback must call mxmlRetain for any nodes that need to be
919 kept for later use. Otherwise, nodes are deleted when the parent node
920 is closed or after each data, comment, CDATA, or directive node.
921 mxmlSaveAllocString
925 Save an XML tree to an allocated string.
926 char * mxmlSaveAllocString (
928 mxml_node_t *node,
929 mxml_save_cb_t cb
930 );
931 This function returns a pointer to a string containing the textual rep‐
933 resentation of the XML node tree. The string should be freed using
934 free() when you are done with it. NULL is returned if the node would
935 produce an empty string or if the string cannot be allocated.
936 The callback argument specifies a function that returns a whitespace
938 string or NULL before and after each element. If MXML_NO_CALLBACK is
939 specified, whitespace will only be added before MXML_TEXT nodes with
940 leading whitespace and before attribute names inside opening element
941 tags.
942 mxmlSaveFd
944 Save an XML tree to a file descriptor.
945 int mxmlSaveFd (
947 mxml_node_t *node,
948 int fd,
949 mxml_save_cb_t cb
950 );
951 The callback argument specifies a function that returns a whitespace
953 string or NULL before and after each element. If MXML_NO_CALLBACK is
954 specified, whitespace will only be added before MXML_TEXT nodes with
955 leading whitespace and before attribute names inside opening element
956 tags.
957 mxmlSaveFile
959 Save an XML tree to a file.
960 int mxmlSaveFile (
962 mxml_node_t *node,
963 FILE *fp,
964 mxml_save_cb_t cb
965 );
966 The callback argument specifies a function that returns a whitespace
968 string or NULL before and after each element. If MXML_NO_CALLBACK is
969 specified, whitespace will only be added before MXML_TEXT nodes with
970 leading whitespace and before attribute names inside opening element
971 tags.
972 mxmlSaveString
974 Save an XML node tree to a string.
975 int mxmlSaveString (
977 mxml_node_t *node,
978 char *buffer,
979 int bufsize,
980 mxml_save_cb_t cb
981 );
982 This function returns the total number of bytes that would be required
984 for the string but only copies (bufsize - 1) characters into the speci‐
985 fied buffer.
986 The callback argument specifies a function that returns a whitespace
988 string or NULL before and after each element. If MXML_NO_CALLBACK is
989 specified, whitespace will only be added before MXML_TEXT nodes with
990 leading whitespace and before attribute names inside opening element
991 tags.
992 mxmlSetCDATA
994 Set the element name of a CDATA node.
995 int mxmlSetCDATA (
997 mxml_node_t *node,
998 const char *data
999 );
1000 The node is not changed if it (or its first child) is not a CDATA ele‐
1002 ment node.
1003 mxmlSetCustom
1007 Set the data and destructor of a custom data node.
1008 int mxmlSetCustom (
1010 mxml_node_t *node,
1011 void *data,
1012 mxml_custom_destroy_cb_t destroy
1013 );
1014 The node is not changed if it (or its first child) is not a custom
1016 node.
1017 mxmlSetCustomHandlers
1021 Set the handling functions for custom data.
1022 void mxmlSetCustomHandlers (
1024 mxml_custom_load_cb_t load,
1025 mxml_custom_save_cb_t save
1026 );
1027 The load function accepts a node pointer and a data string and must re‐
1029 turn 0 on success and non-zero on error.
1030 The save function accepts a node pointer and must return a malloc'd
1032 string on success and NULL on error.
1033 mxmlSetElement
1035 Set the name of an element node.
1036 int mxmlSetElement (
1038 mxml_node_t *node,
1039 const char *name
1040 );
1041 The node is not changed if it is not an element node.
1043 mxmlSetErrorCallback
1045 Set the error message callback.
1046 void mxmlSetErrorCallback (
1048 mxml_error_cb_t cb
1049 );
1050 mxmlSetInteger
1052 Set the value of an integer node.
1053 int mxmlSetInteger (
1055 mxml_node_t *node,
1056 int integer
1057 );
1058 The node is not changed if it (or its first child) is not an integer
1060 node.
1061 mxmlSetOpaque
1063 Set the value of an opaque node.
1064 int mxmlSetOpaque (
1066 mxml_node_t *node,
1067 const char *opaque
1068 );
1069 The node is not changed if it (or its first child) is not an opaque
1071 node.
1072 mxmlSetOpaquef
1074 Set the value of an opaque string node to a formatted string.
1075 int mxmlSetOpaquef (
1077 mxml_node_t *node,
1078 const char *format,
1079 ...
1080 );
1081 The node is not changed if it (or its first child) is not an opaque
1083 node.
1084 mxmlSetReal
1088 Set the value of a real number node.
1089 int mxmlSetReal (
1091 mxml_node_t *node,
1092 double real
1093 );
1094 The node is not changed if it (or its first child) is not a real number
1096 node.
1097 mxmlSetText
1099 Set the value of a text node.
1100 int mxmlSetText (
1102 mxml_node_t *node,
1103 int whitespace,
1104 const char *string
1105 );
1106 The node is not changed if it (or its first child) is not a text node.
1108 mxmlSetTextf
1110 Set the value of a text node to a formatted string.
1111 int mxmlSetTextf (
1113 mxml_node_t *node,
1114 int whitespace,
1115 const char *format,
1116 ...
1117 );
1118 The node is not changed if it (or its first child) is not a text node.
1120 mxmlSetUserData
1122 Set the user data pointer for a node.
1123 int mxmlSetUserData (
1125 mxml_node_t *node,
1126 void *data
1127 );
1128 mxmlSetWrapMargin
1130 Set the wrap margin when saving XML data.
1131 void mxmlSetWrapMargin (
1133 int column
1134 );
1135 Wrapping is disabled when "column" is 0.
1137 mxmlWalkNext
1141 Walk to the next logical node in the tree.
1142 mxml_node_t * mxmlWalkNext (
1144 mxml_node_t *node,
1145 mxml_node_t *top,
1146 int descend
1147 );
1148 The descend argument controls whether the first child is considered to
1150 be the next node. The top node argument constrains the walk to the
1151 node's children.
1152 mxmlWalkPrev
1154 Walk to the previous logical node in the tree.
1155 mxml_node_t * mxmlWalkPrev (
1157 mxml_node_t *node,
1158 mxml_node_t *top,
1159 int descend
1160 );
1161 The descend argument controls whether the previous node's last child is
1163 considered to be the previous node. The top node argument constrains
1164 the walk to the node's children.
1165
1167 mxml_custom_destroy_cb_t
1168 Custom data destructor
1169 typedef void(*)(void *) mxml_custom_destroy_cb_t;
1171 mxml_custom_load_cb_t
1173 Custom data load callback function
1174 typedef int(*)(mxml_node_t *, const char *) mxml_custom_load_cb_t;
1176 mxml_custom_save_cb_t
1178 Custom data save callback function
1179 typedef char *(*)(mxml_node_t *) mxml_custom_save_cb_t;
1181 mxml_entity_cb_t
1183 Entity callback function
1184 typedef int(*)(const char *) mxml_entity_cb_t;
1186 mxml_error_cb_t
1188 Error callback function
1189 typedef void(*)(const char *) mxml_error_cb_t;
1191 mxml_index_t
1193 An XML node index.
1194 typedef struct _mxml_index_s mxml_index_t;
1196 mxml_load_cb_t
1198 Load callback function
1199 typedef mxml_type_t(*)(mxml_node_t *) mxml_load_cb_t;
1201 mxml_node_t
1203 An XML node.
1204 typedef struct _mxml_node_s mxml_node_t;
1206 mxml_save_cb_t
1208 Save callback function
1209 typedef const char *(*)(mxml_node_t *, int) mxml_save_cb_t;
1211 mxml_sax_cb_t
1213 SAX callback function
1214 typedef void(*)(mxml_node_t *, mxml_sax_event_t, void *) mxml_sax_cb_t;
1216 mxml_sax_event_t
1218 SAX event type.
1219 typedef enum mxml_sax_event_e mxml_sax_event_t;
1221 mxml_type_t
1223 The XML node type.
1224 typedef enum mxml_type_e mxml_type_t;
1226
1228 Mini-XML Programmers Manual, https://www.msweet.org/mxml
1229
1231 Copyright © 2003-2021 by Michael R Sweet.
12322022-07-25 Mini-XML API mxml(3)