1mxml(3)                          Mini-XML API                          mxml(3)
2
3
4

NAME

6       mxml - Mini-XML API
7

INCLUDE FILE

9       #include <mxml.h>
10

LIBRARY

12       -lmxml
13

DESCRIPTION

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
21       Mini-XML provides the following functionality:
22
23       •   Reading  of UTF-8 and UTF-16 and writing of UTF-8 encoded XML files
24           and strings.
25
26       •   Data is stored in a linked-list tree structure, preserving the  XML
27           data hierarchy.
28
29       •   Supports  arbitrary element names, attributes, and attribute values
30           with no preset limits, just available memory.
31
32       •   Supports integer, real, opaque ("CDATA"), and text  data  types  in
33           "leaf" nodes.
34
35       •   Functions for creating, indexing, and managing trees of data.
36
37       •   "Find"  and  "walk"  functions  for  easily locating and navigating
38           trees of data.
39
40       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

USING MINI-XML

46       Mini-XML provides a single header file which you include:
47
48           #include <mxml.h>
49
50       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
58       You load an XML file using the "mxmlLoadFile()" function:
59
60           FILE *fp;
61           mxml_node_t *tree;
62
63           fp = fopen("filename.xml", "r");
64           tree = mxmlLoadFile(NULL, fp, MXML_NO_CALLBACK);
65           fclose(fp);
66
67       Similarly, you save an XML file using the "mxmlSaveFile()" function:
68
69           FILE *fp;
70           mxml_node_t *tree;
71
72           fp = fopen("filename.xml", "w");
73           mxmlSaveFile(tree, fp, MXML_NO_CALLBACK);
74           fclose(fp);
75
76       The "mxmlLoadString()", "mxmlSaveAllocString()", and "mxmlSaveString()"
77       functions load XML node trees from and save XML node trees to strings:
78
79           char buffer[8192];
80           char *ptr;
81           mxml_node_t *tree;
82
83           ...
84           tree = mxmlLoadString(NULL, buffer, MXML_NO_CALLBACK);
85
86           ...
87           mxmlSaveString(tree, buffer, sizeof(buffer),
88                          MXML_NO_CALLBACK);
89
90           ...
91           ptr = mxmlSaveAllocString(tree, MXML_NO_CALLBACK);
92
93       You can find a named element/node using the  "mxmlFindElement()"  func‐
94       tion:
95
96           mxml_node_t *node = mxmlFindElement(tree, tree, "name",
97                                               "attr", "value",
98                                               MXML_DESCEND);
99
100       The  "name", "attr", and "value" arguments can be passed as NULL to act
101       as wildcards, e.g.:
102
103           /* Find the first "a" element */
104           node = mxmlFindElement(tree, tree, "a", NULL, NULL,
105                                  MXML_DESCEND);
106
107           /* Find the first "a" element with "href" attribute */
108           node = mxmlFindElement(tree, tree, "a", "href", NULL,
109                                  MXML_DESCEND);
110
111           /* 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
116           /* Find the first element with a "src" attribute*/
117           node = mxmlFindElement(tree, tree, NULL, "src", NULL,
118                                  MXML_DESCEND);
119
120           /* Find the first element with a "src" = "foo.jpg" */
121           node = mxmlFindElement(tree, tree, NULL, "src",
122                                  "foo.jpg", MXML_DESCEND);
123
124       You can also iterate with the same function:
125
126           mxml_node_t *node;
127
128           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
137       To find the value of a specific node in the tree,  use  the  "mxmlFind‐
138       Path()" function:
139
140           mxml_node_t *value = mxmlFindPath(tree, "path/to/*/foo/bar");
141
142       The  "mxmlGetInteger()", "mxmlGetOpaque()", "mxmlGetReal()", and "mxml‐
143       GetText()" functions retrieve the value from a node:
144
145           mxml_node_t *node;
146
147           int intvalue = mxmlGetInteger(node);
148
149           const char *opaquevalue = mxmlGetOpaque(node);
150
151           double realvalue = mxmlGetReal(node);
152
153           int whitespacevalue;
154           const char *textvalue = mxmlGetText(node, &whitespacevalue);
155
156       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
160           mxmlDelete(tree);
161

ENUMERATIONS

163   mxml_sax_event_e
164       SAX event type.
165
166       MXML_SAX_CDATA
167            CDATA node
168
169       MXML_SAX_COMMENT
170            Comment node
171
172       MXML_SAX_DATA
173            Data node
174
175       MXML_SAX_DIRECTIVE
176            Processing directive node
177
178       MXML_SAX_ELEMENT_CLOSE
179            Element closed
180
181       MXML_SAX_ELEMENT_OPEN
182            Element opened
183
184   mxml_type_e
185       The XML node type.
186
187       MXML_CUSTOM
188            Custom data
189
190       MXML_ELEMENT
191            XML element with attributes
192
193       MXML_IGNORE
194            Ignore/throw away node
195
196       MXML_INTEGER
197            Integer value
198
199       MXML_OPAQUE
200            Opaque string
201
202       MXML_REAL
203            Real value
204
205       MXML_TEXT
206            Text fragment
207

FUNCTIONS

209   mxmlAdd
210       Add a node to a tree.
211
212       void mxmlAdd (
213           mxml_node_t *parent,
214           int where,
215           mxml_node_t *child,
216           mxml_node_t *node
217       );
218
219       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
226   mxmlDelete
227       Delete a node and all of its children.
228
229       void mxmlDelete (
230           mxml_node_t *node
231       );
232
233       If  the  specified  node  has a parent, this function first removes the
234       node from its parent using the mxmlRemove function.
235
236   mxmlElementDeleteAttr
237       Delete an attribute.
238
239       void mxmlElementDeleteAttr (
240           mxml_node_t *node,
241           const char *name
242       );
243
244   mxmlElementGetAttr
245       Get an attribute.
246
247       const char * mxmlElementGetAttr (
248           mxml_node_t *node,
249           const char *name
250       );
251
252       This function returns NULL if the node is not an element or  the  named
253       attribute does not exist.
254
255   mxmlElementGetAttrByIndex
256       Get an element attribute by index.
257
258       const char * mxmlElementGetAttrByIndex (
259           mxml_node_t *node,
260           int idx,
261           const char **name
262       );
263
264       The  index ("idx") is 0-based.  NULL is returned if the specified index
265       is out of range.
266
267
268
269   mxmlElementGetAttrCount
270       Get the number of element attributes.
271
272       int  mxmlElementGetAttrCount (
273           mxml_node_t *node
274       );
275
276   mxmlElementSetAttr
277       Set an attribute.
278
279       void mxmlElementSetAttr (
280           mxml_node_t *node,
281           const char *name,
282           const char *value
283       );
284
285       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
289   mxmlElementSetAttrf
290       Set an attribute with a formatted value.
291
292       void mxmlElementSetAttrf (
293           mxml_node_t *node,
294           const char *name,
295           const char *format,
296           ...
297       );
298
299       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
304
305
306   mxmlEntityAddCallback
307       Add a callback to convert entities to Unicode.
308
309       int  mxmlEntityAddCallback (
310           mxml_entity_cb_t cb
311       );
312
313   mxmlEntityGetName
314       Get the name that corresponds to the character value.
315
316       const char * mxmlEntityGetName (
317           int val
318       );
319
320       If  val  does not need to be represented by a named entity, NULL is re‐
321       turned.
322
323   mxmlEntityGetValue
324       Get the character corresponding to a named entity.
325
326       int  mxmlEntityGetValue (
327           const char *name
328       );
329
330       The entity name can also be a numeric constant. -1 is returned  if  the
331       name is not known.
332
333   mxmlEntityRemoveCallback
334       Remove a callback.
335
336       void mxmlEntityRemoveCallback (
337           mxml_entity_cb_t cb
338       );
339
340   mxmlFindElement
341       Find the named element.
342
343       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
352       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
361   mxmlFindPath
362       Find a node with the given path.
363
364       mxml_node_t * mxmlFindPath (
365           mxml_node_t *top,
366           const char *path
367       );
368
369       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
373       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
376
377
378   mxmlGetCDATA
379       Get the value for a CDATA node.
380
381       const char * mxmlGetCDATA (
382           mxml_node_t *node
383       );
384
385       NULL is returned if the node is not a CDATA element.
386
387
388
389   mxmlGetCustom
390       Get the value for a custom node.
391
392       const void * mxmlGetCustom (
393           mxml_node_t *node
394       );
395
396       NULL is returned if the node (or its first child) is not a custom value
397       node.
398
399
400
401   mxmlGetElement
402       Get the name for an element node.
403
404       const char * mxmlGetElement (
405           mxml_node_t *node
406       );
407
408       NULL is returned if the node is not an element node.
409
410
411
412   mxmlGetFirstChild
413       Get the first child of an element node.
414
415       mxml_node_t * mxmlGetFirstChild (
416           mxml_node_t *node
417       );
418
419       NULL is returned if the node is not an element node or if the node  has
420       no children.
421
422
423
424   mxmlGetInteger
425       Get the integer value from the specified node or its first child.
426
427       int  mxmlGetInteger (
428           mxml_node_t *node
429       );
430
431       0  is returned if the node (or its first child) is not an integer value
432       node.
433
434
435
436   mxmlGetLastChild
437       Get the last child of an element node.
438
439       mxml_node_t * mxmlGetLastChild (
440           mxml_node_t *node
441       );
442
443       NULL is returned if the node is not an element node or if the node  has
444       no children.
445
446
447
448   mxmlGetNextSibling
449       mxml_node_t * mxmlGetNextSibling (
450           mxml_node_t *node
451       );
452
453   mxmlGetOpaque
454       Get an opaque string value for a node or its first child.
455
456       const char * mxmlGetOpaque (
457           mxml_node_t *node
458       );
459
460       NULL  is  returned  if  the  node (or its first child) is not an opaque
461       value node.
462
463
464
465   mxmlGetParent
466       Get the parent node.
467
468       mxml_node_t * mxmlGetParent (
469           mxml_node_t *node
470       );
471
472       NULL is returned for a root node.
473
474
475
476   mxmlGetPrevSibling
477       Get the previous node for the current parent.
478
479       mxml_node_t * mxmlGetPrevSibling (
480           mxml_node_t *node
481       );
482
483       NULL is returned if this is the first child for the current parent.
484
485
486
487   mxmlGetReal
488       Get the real value for a node or its first child.
489
490       double  mxmlGetReal (
491           mxml_node_t *node
492       );
493
494       0.0 is returned if the node (or its first child) is not  a  real  value
495       node.
496
497
498
499   mxmlGetRefCount
500       Get the current reference (use) count for a node.
501
502       int  mxmlGetRefCount (
503           mxml_node_t *node
504       );
505
506       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
510
511   mxmlGetText
512       Get the text value for a node or its first child.
513
514       const char * mxmlGetText (
515           mxml_node_t *node,
516           int *whitespace
517       );
518
519       NULL  is  returned if the node (or its first child) is not a text node.
520       The "whitespace" argument can be NULL.
521
522       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
528
529
530   mxmlGetType
531       Get the node type.
532
533       mxml_type_t  mxmlGetType (
534           mxml_node_t *node
535       );
536
537       MXML_IGNORE is returned if "node" is NULL.
538
539
540
541   mxmlGetUserData
542       Get the user data pointer for a node.
543
544       void * mxmlGetUserData (
545           mxml_node_t *node
546       );
547
548   mxmlIndexDelete
549       Delete an index.
550
551       void mxmlIndexDelete (
552           mxml_index_t *ind
553       );
554
555   mxmlIndexEnum
556       Return the next node in the index.
557
558       mxml_node_t * mxmlIndexEnum (
559           mxml_index_t *ind
560       );
561
562       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
566   mxmlIndexFind
567       Find the next matching node.
568
569       mxml_node_t * mxmlIndexFind (
570           mxml_index_t *ind,
571           const char *element,
572           const char *value
573       );
574
575       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
580   mxmlIndexGetCount
581       Get the number of nodes in an index.
582
583       int  mxmlIndexGetCount (
584           mxml_index_t *ind
585       );
586
587   mxmlIndexNew
588       Create a new index.
589
590       mxml_index_t * mxmlIndexNew (
591           mxml_node_t *node,
592           const char *element,
593           const char *attr
594       );
595
596       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
602   mxmlIndexReset
603       Reset  the  enumeration/find  pointer in the index and return the first
604       node in the index.
605
606       mxml_node_t * mxmlIndexReset (
607           mxml_index_t *ind
608       );
609
610       This function should be called prior to using mxmlIndexEnum or  mxmlIn‐
611       dexFind for the first time.
612
613   mxmlLoadFd
614       Load a file descriptor into an XML node tree.
615
616       mxml_node_t * mxmlLoadFd (
617           mxml_node_t *top,
618           int fd,
619           mxml_load_cb_t cb
620       );
621
622       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
630       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
636   mxmlLoadFile
637       Load a file into an XML node tree.
638
639       mxml_node_t * mxmlLoadFile (
640           mxml_node_t *top,
641           FILE *fp,
642           mxml_load_cb_t cb
643       );
644
645       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
653       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
659   mxmlLoadString
660       Load a string into an XML node tree.
661
662       mxml_node_t * mxmlLoadString (
663           mxml_node_t *top,
664           const char *s,
665           mxml_load_cb_t cb
666       );
667
668       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
676       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
682   mxmlNewCDATA
683       Create a new CDATA node.
684
685       mxml_node_t * mxmlNewCDATA (
686           mxml_node_t *parent,
687           const char *data
688       );
689
690       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
696
697
698   mxmlNewCustom
699       Create a new custom data node.
700
701       mxml_node_t * mxmlNewCustom (
702           mxml_node_t *parent,
703           void *data,
704           mxml_custom_destroy_cb_t destroy
705       );
706
707       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
712
713
714   mxmlNewElement
715       Create a new element node.
716
717       mxml_node_t * mxmlNewElement (
718           mxml_node_t *parent,
719           const char *name
720       );
721
722       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
726   mxmlNewInteger
727       Create a new integer node.
728
729       mxml_node_t * mxmlNewInteger (
730           mxml_node_t *parent,
731           int integer
732       );
733
734       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
738   mxmlNewOpaque
739       Create a new opaque string.
740
741       mxml_node_t * mxmlNewOpaque (
742           mxml_node_t *parent,
743           const char *opaque
744       );
745
746       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
751   mxmlNewOpaquef
752       Create a new formatted opaque string node.
753
754       mxml_node_t * mxmlNewOpaquef (
755           mxml_node_t *parent,
756           const char *format,
757           ...
758       );
759
760       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
765   mxmlNewReal
766       Create a new real number node.
767
768       mxml_node_t * mxmlNewReal (
769           mxml_node_t *parent,
770           double real
771       );
772
773       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
777   mxmlNewText
778       Create a new text fragment node.
779
780       mxml_node_t * mxmlNewText (
781           mxml_node_t *parent,
782           int whitespace,
783           const char *string
784       );
785
786       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
792   mxmlNewTextf
793       Create a new formatted text fragment node.
794
795       mxml_node_t * mxmlNewTextf (
796           mxml_node_t *parent,
797           int whitespace,
798           const char *format,
799           ...
800       );
801
802       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
808   mxmlNewXML
809       Create a new XML document tree.
810
811       mxml_node_t * mxmlNewXML (
812           const char *version
813       );
814
815       The  "version" argument specifies the version number to put in the ?xml
816       element node. If NULL, version "1.0" is assumed.
817
818
819
820   mxmlRelease
821       Release a node.
822
823       int  mxmlRelease (
824           mxml_node_t *node
825       );
826
827       When the reference count reaches zero, the node (and any  children)  is
828       deleted via mxmlDelete.
829
830
831
832   mxmlRemove
833       Remove a node from its parent.
834
835       void mxmlRemove (
836           mxml_node_t *node
837       );
838
839       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
842   mxmlRetain
843       Retain a node.
844
845       int  mxmlRetain (
846           mxml_node_t *node
847       );
848
849   mxmlSAXLoadFd
850       Load a file descriptor into an XML node tree using a SAX callback.
851
852       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
860       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
868       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
872
873
874   mxmlSAXLoadFile
875       Load a file into an XML node tree using a SAX callback.
876
877       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
885       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
893       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
897
898
899   mxmlSAXLoadString
900       Load a string into an XML node tree using a SAX callback.
901
902       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
910       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
918       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
922
923
924   mxmlSaveAllocString
925       Save an XML tree to an allocated string.
926
927       char * mxmlSaveAllocString (
928           mxml_node_t *node,
929           mxml_save_cb_t cb
930       );
931
932       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
937       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
943   mxmlSaveFd
944       Save an XML tree to a file descriptor.
945
946       int  mxmlSaveFd (
947           mxml_node_t *node,
948           int fd,
949           mxml_save_cb_t cb
950       );
951
952       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
958   mxmlSaveFile
959       Save an XML tree to a file.
960
961       int  mxmlSaveFile (
962           mxml_node_t *node,
963           FILE *fp,
964           mxml_save_cb_t cb
965       );
966
967       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
973   mxmlSaveString
974       Save an XML node tree to a string.
975
976       int  mxmlSaveString (
977           mxml_node_t *node,
978           char *buffer,
979           int bufsize,
980           mxml_save_cb_t cb
981       );
982
983       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
987       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
993   mxmlSetCDATA
994       Set the element name of a CDATA node.
995
996       int  mxmlSetCDATA (
997           mxml_node_t *node,
998           const char *data
999       );
1000
1001       The node is not changed if it (or its first child) is not a CDATA  ele‐
1002       ment node.
1003
1004
1005
1006   mxmlSetCustom
1007       Set the data and destructor of a custom data node.
1008
1009       int  mxmlSetCustom (
1010           mxml_node_t *node,
1011           void *data,
1012           mxml_custom_destroy_cb_t destroy
1013       );
1014
1015       The  node  is  not  changed  if it (or its first child) is not a custom
1016       node.
1017
1018
1019
1020   mxmlSetCustomHandlers
1021       Set the handling functions for custom data.
1022
1023       void mxmlSetCustomHandlers (
1024           mxml_custom_load_cb_t load,
1025           mxml_custom_save_cb_t save
1026       );
1027
1028       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
1031       The  save  function  accepts  a node pointer and must return a malloc'd
1032       string on success and NULL on error.
1033
1034   mxmlSetElement
1035       Set the name of an element node.
1036
1037       int  mxmlSetElement (
1038           mxml_node_t *node,
1039           const char *name
1040       );
1041
1042       The node is not changed if it is not an element node.
1043
1044   mxmlSetErrorCallback
1045       Set the error message callback.
1046
1047       void mxmlSetErrorCallback (
1048           mxml_error_cb_t cb
1049       );
1050
1051   mxmlSetInteger
1052       Set the value of an integer node.
1053
1054       int  mxmlSetInteger (
1055           mxml_node_t *node,
1056           int integer
1057       );
1058
1059       The node is not changed if it (or its first child) is  not  an  integer
1060       node.
1061
1062   mxmlSetOpaque
1063       Set the value of an opaque node.
1064
1065       int  mxmlSetOpaque (
1066           mxml_node_t *node,
1067           const char *opaque
1068       );
1069
1070       The  node  is  not  changed if it (or its first child) is not an opaque
1071       node.
1072
1073   mxmlSetOpaquef
1074       Set the value of an opaque string node to a formatted string.
1075
1076       int  mxmlSetOpaquef (
1077           mxml_node_t *node,
1078           const char *format,
1079           ...
1080       );
1081
1082       The node is not changed if it (or its first child)  is  not  an  opaque
1083       node.
1084
1085
1086
1087   mxmlSetReal
1088       Set the value of a real number node.
1089
1090       int  mxmlSetReal (
1091           mxml_node_t *node,
1092           double real
1093       );
1094
1095       The node is not changed if it (or its first child) is not a real number
1096       node.
1097
1098   mxmlSetText
1099       Set the value of a text node.
1100
1101       int  mxmlSetText (
1102           mxml_node_t *node,
1103           int whitespace,
1104           const char *string
1105       );
1106
1107       The node is not changed if it (or its first child) is not a text node.
1108
1109   mxmlSetTextf
1110       Set the value of a text node to a formatted string.
1111
1112       int  mxmlSetTextf (
1113           mxml_node_t *node,
1114           int whitespace,
1115           const char *format,
1116           ...
1117       );
1118
1119       The node is not changed if it (or its first child) is not a text node.
1120
1121   mxmlSetUserData
1122       Set the user data pointer for a node.
1123
1124       int  mxmlSetUserData (
1125           mxml_node_t *node,
1126           void *data
1127       );
1128
1129   mxmlSetWrapMargin
1130       Set the wrap margin when saving XML data.
1131
1132       void mxmlSetWrapMargin (
1133           int column
1134       );
1135
1136       Wrapping is disabled when "column" is 0.
1137
1138
1139
1140   mxmlWalkNext
1141       Walk to the next logical node in the tree.
1142
1143       mxml_node_t * mxmlWalkNext (
1144           mxml_node_t *node,
1145           mxml_node_t *top,
1146           int descend
1147       );
1148
1149       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
1153   mxmlWalkPrev
1154       Walk to the previous logical node in the tree.
1155
1156       mxml_node_t * mxmlWalkPrev (
1157           mxml_node_t *node,
1158           mxml_node_t *top,
1159           int descend
1160       );
1161
1162       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

TYPES

1167   mxml_custom_destroy_cb_t
1168       Custom data destructor
1169
1170       typedef void(*)(void *) mxml_custom_destroy_cb_t;
1171
1172   mxml_custom_load_cb_t
1173       Custom data load callback function
1174
1175       typedef int(*)(mxml_node_t *, const char *) mxml_custom_load_cb_t;
1176
1177   mxml_custom_save_cb_t
1178       Custom data save callback function
1179
1180       typedef char *(*)(mxml_node_t *) mxml_custom_save_cb_t;
1181
1182   mxml_entity_cb_t
1183       Entity callback function
1184
1185       typedef int(*)(const char *) mxml_entity_cb_t;
1186
1187   mxml_error_cb_t
1188       Error callback function
1189
1190       typedef void(*)(const char *) mxml_error_cb_t;
1191
1192   mxml_index_t
1193       An XML node index.
1194
1195       typedef struct _mxml_index_s mxml_index_t;
1196
1197   mxml_load_cb_t
1198       Load callback function
1199
1200       typedef mxml_type_t(*)(mxml_node_t *) mxml_load_cb_t;
1201
1202   mxml_node_t
1203       An XML node.
1204
1205       typedef struct _mxml_node_s mxml_node_t;
1206
1207   mxml_save_cb_t
1208       Save callback function
1209
1210       typedef const char *(*)(mxml_node_t *, int) mxml_save_cb_t;
1211
1212   mxml_sax_cb_t
1213       SAX callback function
1214
1215       typedef void(*)(mxml_node_t *, mxml_sax_event_t, void *) mxml_sax_cb_t;
1216
1217   mxml_sax_event_t
1218       SAX event type.
1219
1220       typedef enum mxml_sax_event_e mxml_sax_event_t;
1221
1222   mxml_type_t
1223       The XML node type.
1224
1225       typedef enum mxml_type_e mxml_type_t;
1226

SEE ALSO

1228       Mini-XML Programmers Manual, https://www.msweet.org/mxml
1229
1231       Copyright © 2003-2021 by Michael R Sweet.
1232
1233
1234
12352022-07-25                       Mini-XML API                          mxml(3)
Impressum