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 the
934 free() function when you are done with it. NULL is returned if the
935 node would produce an empty string or if the string cannot be allo‐
936 cated.
937 The callback argument specifies a function that returns a whitespace
939 string or NULL before and after each element. If MXML_NO_CALLBACK is
940 specified, whitespace will only be added before MXML_TEXT nodes with
941 leading whitespace and before attribute names inside opening element
942 tags.
943 mxmlSaveFd
945 Save an XML tree to a file descriptor.
946 int mxmlSaveFd (
948 mxml_node_t *node,
949 int fd,
950 mxml_save_cb_t cb
951 );
952 The callback argument specifies a function that returns a whitespace
954 string or NULL before and after each element. If MXML_NO_CALLBACK is
955 specified, whitespace will only be added before MXML_TEXT nodes with
956 leading whitespace and before attribute names inside opening element
957 tags.
958 mxmlSaveFile
960 Save an XML tree to a file.
961 int mxmlSaveFile (
963 mxml_node_t *node,
964 FILE *fp,
965 mxml_save_cb_t cb
966 );
967 The callback argument specifies a function that returns a whitespace
969 string or NULL before and after each element. If MXML_NO_CALLBACK is
970 specified, whitespace will only be added before MXML_TEXT nodes with
971 leading whitespace and before attribute names inside opening element
972 tags.
973 mxmlSaveString
975 Save an XML node tree to a string.
976 int mxmlSaveString (
978 mxml_node_t *node,
979 char *buffer,
980 int bufsize,
981 mxml_save_cb_t cb
982 );
983 This function returns the total number of bytes that would be required
985 for the string but only copies (bufsize - 1) characters into the speci‐
986 fied buffer.
987 The callback argument specifies a function that returns a whitespace
989 string or NULL before and after each element. If MXML_NO_CALLBACK is
990 specified, whitespace will only be added before MXML_TEXT nodes with
991 leading whitespace and before attribute names inside opening element
992 tags.
993 mxmlSetCDATA
995 Set the element name of a CDATA node.
996 int mxmlSetCDATA (
998 mxml_node_t *node,
999 const char *data
1000 );
1001 The node is not changed if it (or its first child) is not a CDATA ele‐
1003 ment node.
1004 mxmlSetCustom
1008 Set the data and destructor of a custom data node.
1009 int mxmlSetCustom (
1011 mxml_node_t *node,
1012 void *data,
1013 mxml_custom_destroy_cb_t destroy
1014 );
1015 The node is not changed if it (or its first child) is not a custom
1017 node.
1018 mxmlSetCustomHandlers
1022 Set the handling functions for custom data.
1023 void mxmlSetCustomHandlers (
1025 mxml_custom_load_cb_t load,
1026 mxml_custom_save_cb_t save
1027 );
1028 The load function accepts a node pointer and a data string and must re‐
1030 turn 0 on success and non-zero on error.
1031 The save function accepts a node pointer and must return a malloc'd
1033 string on success and NULL on error.
1034 mxmlSetElement
1036 Set the name of an element node.
1037 int mxmlSetElement (
1039 mxml_node_t *node,
1040 const char *name
1041 );
1042 The node is not changed if it is not an element node.
1044 mxmlSetErrorCallback
1046 Set the error message callback.
1047 void mxmlSetErrorCallback (
1049 mxml_error_cb_t cb
1050 );
1051 mxmlSetInteger
1053 Set the value of an integer node.
1054 int mxmlSetInteger (
1056 mxml_node_t *node,
1057 int integer
1058 );
1059 The node is not changed if it (or its first child) is not an integer
1061 node.
1062 mxmlSetOpaque
1064 Set the value of an opaque node.
1065 int mxmlSetOpaque (
1067 mxml_node_t *node,
1068 const char *opaque
1069 );
1070 The node is not changed if it (or its first child) is not an opaque
1072 node.
1073 mxmlSetOpaquef
1075 Set the value of an opaque string node to a formatted string.
1076 int mxmlSetOpaquef (
1078 mxml_node_t *node,
1079 const char *format,
1080 ...
1081 );
1082 The node is not changed if it (or its first child) is not an opaque
1084 node.
1085 mxmlSetReal
1089 Set the value of a real number node.
1090 int mxmlSetReal (
1092 mxml_node_t *node,
1093 double real
1094 );
1095 The node is not changed if it (or its first child) is not a real number
1097 node.
1098 mxmlSetText
1100 Set the value of a text node.
1101 int mxmlSetText (
1103 mxml_node_t *node,
1104 int whitespace,
1105 const char *string
1106 );
1107 The node is not changed if it (or its first child) is not a text node.
1109 mxmlSetTextf
1111 Set the value of a text node to a formatted string.
1112 int mxmlSetTextf (
1114 mxml_node_t *node,
1115 int whitespace,
1116 const char *format,
1117 ...
1118 );
1119 The node is not changed if it (or its first child) is not a text node.
1121 mxmlSetUserData
1123 Set the user data pointer for a node.
1124 int mxmlSetUserData (
1126 mxml_node_t *node,
1127 void *data
1128 );
1129 mxmlSetWrapMargin
1131 Set the wrap margin when saving XML data.
1132 void mxmlSetWrapMargin (
1134 int column
1135 );
1136 Wrapping is disabled when "column" is 0.
1138 mxmlWalkNext
1142 Walk to the next logical node in the tree.
1143 mxml_node_t * mxmlWalkNext (
1145 mxml_node_t *node,
1146 mxml_node_t *top,
1147 int descend
1148 );
1149 The descend argument controls whether the first child is considered to
1151 be the next node. The top node argument constrains the walk to the
1152 node's children.
1153 mxmlWalkPrev
1155 Walk to the previous logical node in the tree.
1156 mxml_node_t * mxmlWalkPrev (
1158 mxml_node_t *node,
1159 mxml_node_t *top,
1160 int descend
1161 );
1162 The descend argument controls whether the previous node's last child is
1164 considered to be the previous node. The top node argument constrains
1165 the walk to the node's children.
1166
1168 mxml_custom_destroy_cb_t
1169 Custom data destructor
1170 typedef void(*)(void *) mxml_custom_destroy_cb_t;
1172 mxml_custom_load_cb_t
1174 Custom data load callback function
1175 typedef int(*)(mxml_node_t *, const char *) mxml_custom_load_cb_t;
1177 mxml_custom_save_cb_t
1179 Custom data save callback function
1180 typedef char *(*)(mxml_node_t *) mxml_custom_save_cb_t;
1182 mxml_entity_cb_t
1184 Entity callback function
1185 typedef int(*)(const char *) mxml_entity_cb_t;
1187 mxml_error_cb_t
1189 Error callback function
1190 typedef void(*)(const char *) mxml_error_cb_t;
1192 mxml_index_t
1194 An XML node index.
1195 typedef struct _mxml_index_s mxml_index_t;
1197 mxml_load_cb_t
1199 Load callback function
1200 typedef mxml_type_t(*)(mxml_node_t *) mxml_load_cb_t;
1202 mxml_node_t
1204 An XML node.
1205 typedef struct _mxml_node_s mxml_node_t;
1207 mxml_save_cb_t
1209 Save callback function
1210 typedef const char *(*)(mxml_node_t *, int) mxml_save_cb_t;
1212 mxml_sax_cb_t
1214 SAX callback function
1215 typedef void(*)(mxml_node_t *, mxml_sax_event_t, void *) mxml_sax_cb_t;
1217 mxml_sax_event_t
1219 SAX event type.
1220 typedef enum mxml_sax_event_e mxml_sax_event_t;
1222 mxml_type_t
1224 The XML node type.
1225 typedef enum mxml_type_e mxml_type_t;
1227
1229 Mini-XML Programmers Manual, https://www.msweet.org/mxml
1230
1232 Copyright © 2003-2019 by Michael R Sweet.
12332020-10-09 Mini-XML API mxml(3)