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 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
938       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
944   mxmlSaveFd
945       Save an XML tree to a file descriptor.
946
947       int  mxmlSaveFd (
948           mxml_node_t *node,
949           int fd,
950           mxml_save_cb_t cb
951       );
952
953       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
959   mxmlSaveFile
960       Save an XML tree to a file.
961
962       int  mxmlSaveFile (
963           mxml_node_t *node,
964           FILE *fp,
965           mxml_save_cb_t cb
966       );
967
968       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
974   mxmlSaveString
975       Save an XML node tree to a string.
976
977       int  mxmlSaveString (
978           mxml_node_t *node,
979           char *buffer,
980           int bufsize,
981           mxml_save_cb_t cb
982       );
983
984       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
988       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
994   mxmlSetCDATA
995       Set the element name of a CDATA node.
996
997       int  mxmlSetCDATA (
998           mxml_node_t *node,
999           const char *data
1000       );
1001
1002       The  node is not changed if it (or its first child) is not a CDATA ele‐
1003       ment node.
1004
1005
1006
1007   mxmlSetCustom
1008       Set the data and destructor of a custom data node.
1009
1010       int  mxmlSetCustom (
1011           mxml_node_t *node,
1012           void *data,
1013           mxml_custom_destroy_cb_t destroy
1014       );
1015
1016       The node is not changed if it (or its first  child)  is  not  a  custom
1017       node.
1018
1019
1020
1021   mxmlSetCustomHandlers
1022       Set the handling functions for custom data.
1023
1024       void mxmlSetCustomHandlers (
1025           mxml_custom_load_cb_t load,
1026           mxml_custom_save_cb_t save
1027       );
1028
1029       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
1032       The save function accepts a node pointer and  must  return  a  malloc'd
1033       string on success and NULL on error.
1034
1035   mxmlSetElement
1036       Set the name of an element node.
1037
1038       int  mxmlSetElement (
1039           mxml_node_t *node,
1040           const char *name
1041       );
1042
1043       The node is not changed if it is not an element node.
1044
1045   mxmlSetErrorCallback
1046       Set the error message callback.
1047
1048       void mxmlSetErrorCallback (
1049           mxml_error_cb_t cb
1050       );
1051
1052   mxmlSetInteger
1053       Set the value of an integer node.
1054
1055       int  mxmlSetInteger (
1056           mxml_node_t *node,
1057           int integer
1058       );
1059
1060       The  node  is  not changed if it (or its first child) is not an integer
1061       node.
1062
1063   mxmlSetOpaque
1064       Set the value of an opaque node.
1065
1066       int  mxmlSetOpaque (
1067           mxml_node_t *node,
1068           const char *opaque
1069       );
1070
1071       The node is not changed if it (or its first child)  is  not  an  opaque
1072       node.
1073
1074   mxmlSetOpaquef
1075       Set the value of an opaque string node to a formatted string.
1076
1077       int  mxmlSetOpaquef (
1078           mxml_node_t *node,
1079           const char *format,
1080           ...
1081       );
1082
1083       The  node  is  not  changed if it (or its first child) is not an opaque
1084       node.
1085
1086
1087
1088   mxmlSetReal
1089       Set the value of a real number node.
1090
1091       int  mxmlSetReal (
1092           mxml_node_t *node,
1093           double real
1094       );
1095
1096       The node is not changed if it (or its first child) is not a real number
1097       node.
1098
1099   mxmlSetText
1100       Set the value of a text node.
1101
1102       int  mxmlSetText (
1103           mxml_node_t *node,
1104           int whitespace,
1105           const char *string
1106       );
1107
1108       The node is not changed if it (or its first child) is not a text node.
1109
1110   mxmlSetTextf
1111       Set the value of a text node to a formatted string.
1112
1113       int  mxmlSetTextf (
1114           mxml_node_t *node,
1115           int whitespace,
1116           const char *format,
1117           ...
1118       );
1119
1120       The node is not changed if it (or its first child) is not a text node.
1121
1122   mxmlSetUserData
1123       Set the user data pointer for a node.
1124
1125       int  mxmlSetUserData (
1126           mxml_node_t *node,
1127           void *data
1128       );
1129
1130   mxmlSetWrapMargin
1131       Set the wrap margin when saving XML data.
1132
1133       void mxmlSetWrapMargin (
1134           int column
1135       );
1136
1137       Wrapping is disabled when "column" is 0.
1138
1139
1140
1141   mxmlWalkNext
1142       Walk to the next logical node in the tree.
1143
1144       mxml_node_t * mxmlWalkNext (
1145           mxml_node_t *node,
1146           mxml_node_t *top,
1147           int descend
1148       );
1149
1150       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
1154   mxmlWalkPrev
1155       Walk to the previous logical node in the tree.
1156
1157       mxml_node_t * mxmlWalkPrev (
1158           mxml_node_t *node,
1159           mxml_node_t *top,
1160           int descend
1161       );
1162
1163       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

TYPES

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

SEE ALSO

1229       Mini-XML Programmers Manual, https://www.msweet.org/mxml
1230
1232       Copyright © 2003-2019 by Michael R Sweet.
1233
1234
1235
12362020-10-09                       Mini-XML API                          mxml(3)
Impressum