6 This section gives details about the functions in libxo, how to call
7 them, and the actions they perform.
15 libxo uses "handles" to control its rendering functionality. The
16 handle contains state and buffered data, as well as callback functions
19 Handles give an abstraction for libxo that encapsulates the state of a
20 stream of output. Handles have the data type "`xo_handle_t`" and are
23 The library has a default handle that is automatically initialized.
24 By default, this handle will send text style output (`XO_STYLE_TEXT`) to
25 standard output. The xo_set_style and xo_set_flags functions can be
26 used to change this behavior.
28 For the typical command that is generating output on standard output,
29 there is no need to create an explicit handle, but they are available
30 when needed, e.g., for daemons that generate multiple streams of
33 Many libxo functions take a handle as their first parameter; most that
34 do not use the default handle. Any function taking a handle can be
35 passed NULL to access the default handle. For the convenience of
36 callers, the libxo library includes handle-less functions that
37 implicitly use the default handle.
39 For example, the following are equivalent::
42 xo_emit_h(NULL, "test");
44 Handles are created using `xo_create` and destroy using
52 .. c:function:: xo_handle_t *xo_create (xo_style_t style, xo_xof_flags_t flags)
54 The `xo_create` function allocates a new handle which can be passed
55 to further libxo function calls. The `xo_handle_t` structure is
58 :param xo_style_t style: Output style (XO_STYLE\_*)
59 :param xo_xof_flags_t flags: Flags for this handle (XOF\_*)
60 :return: New libxo handle
61 :rtype: xo_handle_t \*
66 xo_handle_t *xop = xo_create(XO_STYLE_JSON, XOF_WARN | XOF_PRETTY);
68 xo_emit_h(xop, "testing\n");
70 See also :ref:`output-styles` and :ref:`flags`.
72 .. index:: xo_create_to_file
73 .. index:: XOF_CLOSE_FP
79 xo_handle_t *xo_create_to_file (FILE *fp, unsigned style, unsigned flags)
81 The `xo_create_to_file` function is aconvenience function is
82 provided for situations when output should be written to a different
83 file, rather than the default of standard output.
85 The `XOF_CLOSE_FP` flag can be set on the returned handle to trigger a
86 call to fclose() for the FILE pointer when the handle is destroyed,
87 avoiding the need for the caller to perform this task.
89 :param fp: FILE to use as base for this handle
91 :param xo_style_t style: Output style (XO_STYLE\_*)
92 :param xo_xof_flags_t flags: Flags for this handle (XOF\_*)
93 :return: New libxo handle
94 :rtype: xo_handle_t \*
96 .. index:: xo_set_writer
97 .. index:: xo_write_func_t
98 .. index:: xo_close_func_t
99 .. index:: xo_flush_func_t
105 void xo_set_writer (xo_handle_t *xop, void *opaque, \
106 xo_write_func_t write_func, xo_close_func_t close_func, \
107 xo_flush_func_t flush_func)
109 The `xo_set_writer` function allows custom functions which can
110 tailor how libxo writes data. The `opaque` argument is recorded and
111 passed back to the functions, allowing the function to acquire
112 context information. The *write_func* function writes data to the
113 output stream. The *close_func* function can release this opaque
114 data and any other resources as needed. The *flush_func* function
115 is called to flush buffered data associated with the opaque object.
117 :param xop: Handle to modify (or NULL for default handle)
118 :type xop: xo_handle_t *
119 :param opaque: Pointer to opaque data passed to the given functions
121 :param xo_write_func_t write_func: New write function
122 :param xo_close_func_t close_func: New close function
123 :param xo_flush_func_t flush_func: New flush function
126 .. index:: xo_get_style
131 .. c:function:: xo_style_t xo_get_style(xo_handle_t *xop)
133 Use the `xo_get_style` function to find the current output style for
134 a given handle. To use the default handle, pass a `NULL` handle.
136 :param xop: Handle to interrogate (or NULL for default handle)
137 :type xop: xo_handle_t *
138 :returns: Output style (XO_STYLE\_*)
144 style = xo_get_style(NULL);
146 .. index:: XO_STYLE_TEXT
147 .. index:: XO_STYLE_XML
148 .. index:: XO_STYLE_JSON
149 .. index:: XO_STYLE_HTML
153 Output Styles (XO_STYLE\_\*)
154 ++++++++++++++++++++++++++++
156 The libxo functions accept a set of output styles:
158 =============== =========================
160 =============== =========================
161 XO_STYLE_TEXT Traditional text output
162 XO_STYLE_XML XML encoded data
163 XO_STYLE_JSON JSON encoded data
164 XO_STYLE_HTML HTML encoded data
165 =============== =========================
167 The "XML", "JSON", and "HTML" output styles all use the UTF-8
168 character encoding. "TEXT" using locale-based encoding.
170 .. index:: xo_set_style
175 .. c:function:: void xo_set_style(xo_handle_t *xop, xo_style_t style)
177 The `xo_set_style` function is used to change the output style
178 setting for a handle. To use the default handle, pass a `NULL`
181 :param xop: Handle to modify
182 :type xop: xo_handle_t *
183 :param xo_style_t style: Output style (XO_STYLE\_*)
189 xo_set_style(NULL, XO_STYLE_XML);
191 .. index:: xo_set_style_name
196 .. c:function:: int xo_set_style_name (xo_handle_t *xop, const char *style)
198 The `xo_set_style_name` function can be used to set the style based
199 on a name encoded as a string: The name can be any of the supported
200 styles: "text", "xml", "json", or "html".
202 :param xop: Handle for modify (or NULL for default handle)
203 :type xop: xo_handle_t \*
204 :param style: Text name of the style
205 :type style: const char \*
206 :returns: zero for success, non-zero for error
212 xo_set_style_name(NULL, "html");
214 .. index:: xo_set_flags
219 .. c:function:: void xo_set_flags(xo_handle_t *xop, xo_xof_flags_t flags)
221 :param xop: Handle for modify (or NULL for default handle)
222 :type xop: xo_handle_t \*
223 :param xo_xof_flags_t flags: Flags to add for the handle
226 Use the `xo_set_flags` function to turn on flags for a given libxo
227 handle. To use the default handle, pass a `NULL` handle.
232 xo_set_flags(NULL, XOF_PRETTY | XOF_WARN);
234 .. index:: Flags; XOF_*
235 .. index:: XOF_CLOSE_FP
237 .. index:: XOF_COLOR_ALLOWED
241 .. index:: XOF_NO_ENV
242 .. index:: XOF_NO_HUMANIZE
243 .. index:: XOF_PRETTY
244 .. index:: XOF_UNDERSCORES
247 .. index:: XOF_WARN_XML
249 .. index:: XOF_COLUMNS
257 The set of valid flags include:
259 =================== =========================================
261 =================== =========================================
262 XOF_CLOSE_FP Close file pointer on `xo_destroy`
263 XOF_COLOR Enable color and effects in output
264 XOF_COLOR_ALLOWED Allow color/effect for terminal output
265 XOF_DTRT Enable "do the right thing" mode
266 XOF_INFO Display info data attributes (HTML)
267 XOF_KEYS Emit the key attribute (XML)
268 XOF_NO_ENV Do not use the :ref:`libxo-options` env var
269 XOF_NO_HUMANIZE Display humanization (TEXT, HTML)
270 XOF_PRETTY Make "pretty printed" output
271 XOF_UNDERSCORES Replaces hyphens with underscores
272 XOF_UNITS Display units (XML, HMTL)
273 XOF_WARN Generate warnings for broken calls
274 XOF_WARN_XML Generate warnings in XML on stdout
275 XOF_XPATH Emit XPath expressions (HTML)
276 XOF_COLUMNS Force xo_emit to return columns used
277 XOF_FLUSH Flush output after each `xo_emit` call
278 =================== =========================================
280 The `XOF_CLOSE_FP` flag will trigger the call of the *close_func*
281 (provided via `xo_set_writer`) when the handle is destroyed.
283 The `XOF_COLOR` flag enables color and effects in output regardless
284 of output device, while the `XOF_COLOR_ALLOWED` flag allows color
285 and effects only if the output device is a terminal.
287 The `XOF_PRETTY` flag requests "pretty printing", which will trigger
288 the addition of indentation and newlines to enhance the readability of
289 XML, JSON, and HTML output. Text output is not affected.
291 The `XOF_WARN` flag requests that warnings will trigger diagnostic
292 output (on standard error) when the library notices errors during
293 operations, or with arguments to functions. Without warnings enabled,
294 such conditions are ignored.
296 Warnings allow developers to debug their interaction with libxo.
297 The function `xo_failure` can used as a breakpoint for a debugger,
298 regardless of whether warnings are enabled.
300 If the style is `XO_STYLE_HTML`, the following additional flags can be
303 =============== =========================================
305 =============== =========================================
306 XOF_XPATH Emit "data-xpath" attributes
307 XOF_INFO Emit additional info fields
308 =============== =========================================
310 The `XOF_XPATH` flag enables the emission of XPath expressions detailing
311 the hierarchy of XML elements used to encode the data field, if the
312 XPATH style of output were requested.
314 The `XOF_INFO` flag encodes additional informational fields for HTML
315 output. See :ref:`field-information` for details.
317 If the style is `XO_STYLE_XML`, the following additional flags can be
320 =============== =========================================
322 =============== =========================================
323 XOF_KEYS Flag "key" fields for XML
324 =============== =========================================
326 The `XOF_KEYS` flag adds "key" attribute to the XML encoding for
327 field definitions that use the "k" modifier. The key attribute has
330 xo_emit("{k:name}", item);
333 <name key="key">truck</name>
335 .. index:: xo_clear_flags
340 .. c:function:: void xo_clear_flags (xo_handle_t *xop, xo_xof_flags_t flags)
342 :param xop: Handle for modify (or NULL for default handle)
343 :type xop: xo_handle_t \*
344 :param xo_xof_flags_t flags: Flags to clear for the handle
347 Use the `xo_clear_flags` function to turn off the given flags in a
348 specific handle. To use the default handle, pass a `NULL` handle.
350 .. index:: xo_set_options
355 .. c:function:: int xo_set_options (xo_handle_t *xop, const char *input)
357 :param xop: Handle for modify (or NULL for default handle)
358 :type xop: xo_handle_t \*
359 :param input: string containing options to set
360 :type input: const char *
361 :returns: zero for success, non-zero for error
364 The `xo_set_options` function accepts a comma-separated list of
365 output styles and modifier flags and enables them for a specific
366 handle. The options are identical to those listed in
367 :ref:`options`. To use the default handle, pass a `NULL` handle.
369 .. index:: xo_destroy
374 .. c:function:: void xo_destroy(xo_handle_t *xop)
376 :param xop: Handle for modify (or NULL for default handle)
377 :type xop: xo_handle_t \*
380 The `xo_destroy` function releases a handle and any resources it is
381 using. Calling `xo_destroy` with a `NULL` handle will release any
382 resources associated with the default handle.
386 Emitting Content (xo_emit)
387 --------------------------
389 The functions in this section are used to emit output. They use a
390 `format` string containing field descriptors as specified in
391 :ref:`format-strings`. The use of a handle is optional and `NULL` can
392 be passed to access the internal "default" handle. See
395 The remaining arguments to `xo_emit` and `xo_emit_h` are a set of
396 arguments corresponding to the fields in the format string. Care must
397 be taken to ensure the argument types match the fields in the format
398 string, since an inappropriate or missing argument can ruin your day.
399 The `vap` argument to `xo_emit_hv` points to a variable argument list
400 that can be used to retrieve arguments via `va_arg`.
402 .. c:function:: xo_ssize_t xo_emit (const char *fmt, ...)
404 :param fmt: The format string, followed by zero or more arguments
405 :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted
408 .. c:function:: xo_ssize_t xo_emit_h (xo_handle_t *xop, const char *fmt, ...)
410 :param xop: Handle for modify (or NULL for default handle)
411 :type xop: xo_handle_t \*
412 :param fmt: The format string, followed by zero or more arguments
413 :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted
416 .. c:function:: xo_ssize_t xo_emit_hv (xo_handle_t *xop, const char *fmt, va_list vap)
418 :param xop: Handle for modify (or NULL for default handle)
419 :type xop: xo_handle_t \*
420 :param fmt: The format string
421 :param va_list vap: A set of variadic arguments
422 :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted
425 .. index:: xo_emit_field
427 Single Field Emitting Functions (xo_emit_field)
428 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
430 The functions in this section emit formatted output similar to
431 `xo_emit` but where `xo_emit` uses a single string argument containing
432 the description for multiple fields, `xo_emit_field` emits a single
433 field using multiple ar- guments to contain the field description.
434 `xo_emit_field_h` adds an ex- plicit handle to use instead of the
435 default handle, while `xo_emit_field_hv` accepts a va_list for
436 additional flexibility.
438 The arguments `rolmod`, `content`, `fmt`, and `efmt` are detailed in
439 :ref:`field-formatting`. Using distinct arguments allows callers to
440 pass the field description in pieces, rather than having to use
441 something like `snprintf` to build the format string required by
442 `xo_emit`. The arguments are each NUL-terminated strings. The `rolmod`
443 argument contains the `role` and `modifier` portions of the field
444 description, the `content` argument contains the `content` portion, and
445 the `fmt` and `efmt` contain the `field-format` and `encoding-format` por-
448 As with `xo_emit`, the `fmt` and `efmt` values are both optional,
449 since the `field-format` string defaults to "%s", and the
450 `encoding-format`'s default value is derived from the `field-format`
451 per :ref:`field-formatting`. However, care must be taken to avoid
452 using a value directly as the format, since characters like '{', '%',
453 and '}' will be interpreted as formatting directives, and may cause
454 xo_emit_field to dereference arbitrary values off the stack, leading
455 to bugs, core files, and gnashing of teeth.
457 .. c:function:: xo_ssize_t xo_emit_field (const char *rolmod, const char *content, const char *fmt, const char *efmt, ...)
459 :param rolmod: A comma-separated list of field roles and field modifiers
460 :type rolmod: const char *
461 :param content: The "content" portion of the field description string
462 :type content: const char *
463 :param fmt: Contents format string
464 :type fmt: const char *
465 :param efmt: Encoding format string, followed by additional arguments
466 :type efmt: const char *
467 :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted
473 xo_emit_field("T", title, NULL, NULL, NULL);
474 xo_emit_field("T", "Host name is ", NULL, NULL);
475 xo_emit_field("V", "host-name", NULL, NULL, host-name);
476 xo_emit_field(",leaf-list,quotes", "sku", "%s-%u", "%s-000-%u",
479 .. c:function:: xo_ssize_t xo_emit_field_h (xo_handle_t *xop, const char *rolmod, const char *contents, const char *fmt, const char *efmt, ...)
481 :param xop: Handle for modify (or NULL for default handle)
482 :type xop: xo_handle_t \*
483 :param rolmod: A comma-separated list of field roles and field modifiers
484 :type rolmod: const char *
485 :param contents: The "contents" portion of the field description string
486 :type contents: const char *
487 :param fmt: Content format string
488 :type fmt: const char *
489 :param efmt: Encoding format string, followed by additional arguments
490 :type efmt: const char *
491 :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted
494 .. c:function:: xo_ssize_t xo_emit_field_hv (xo_handle_t *xop, const char *rolmod, const char *contents, const char *fmt, const char *efmt, va_list vap)
496 :param xop: Handle for modify (or NULL for default handle)
497 :type xop: xo_handle_t \*
498 :param rolmod: A comma-separated list of field roles and field modifiers
499 :type rolmod: const char *
500 :param contents: The "contents" portion of the field description string
501 :type contents: const char *
502 :param fmt: Content format string
503 :type fmt: const char *
504 :param efmt: Encoding format string
505 :type efmt: const char *
506 :param va_list vap: A set of variadic arguments
507 :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted
516 The functions in this section emit an XML attribute with the given name
517 and value. This only affects the XML output style.
519 The `name` parameter give the name of the attribute to be encoded. The
520 `fmt` parameter gives a printf-style format string used to format the
521 value of the attribute using any remaining arguments, or the vap
522 parameter passed to `xo_attr_hv`.
524 All attributes recorded via `xo_attr` are placed on the next
525 container, instance, leaf, or leaf list that is emitted.
527 Since attributes are only emitted in XML, their use should be limited
528 to meta-data and additional or redundant representations of data
529 already emitted in other form.
531 .. c:function:: xo_ssize_t xo_attr (const char *name, const char *fmt, ...)
533 :param name: Attribute name
534 :type name: const char *
535 :param fmt: Attribute value, as variadic arguments
536 :type fmt: const char *
537 :returns: -1 for error, or the number of bytes in the formatted attribute value
543 xo_attr("seconds", "%ld", (unsigned long) login_time);
544 struct tm *tmp = localtime(login_time);
545 strftime(buf, sizeof(buf), "%R", tmp);
546 xo_emit("Logged in at {:login-time}\n", buf);
548 <login-time seconds="1408336270">00:14</login-time>
551 .. c:function:: xo_ssize_t xo_attr_h (xo_handle_t *xop, const char *name, const char *fmt, ...)
553 :param xop: Handle for modify (or NULL for default handle)
554 :type xop: xo_handle_t \*
556 The `xo_attr_h` function follows the conventions of `xo_attr` but
557 adds an explicit libxo handle.
559 .. c:function:: xo_ssize_t xo_attr_hv (xo_handle_t *xop, const char *name, const char *fmt, va_list vap)
561 The `xo_attr_h` function follows the conventions of `xo_attr_h`
562 but replaced the variadic list with a variadic pointer.
566 Flushing Output (xo_flush)
567 ~~~~~~~~~~~~~~~~~~~~~~~~~~
569 .. c:function:: xo_ssize_t xo_flush (void)
571 :returns: -1 for error, or the number of bytes generated
574 libxo buffers data, both for performance and consistency, but also
575 to allow for the proper function of various advanced features. At
576 various times, the caller may wish to flush any data buffered within
577 the library. The `xo_flush` call is used for this.
579 Calling `xo_flush` also triggers the flush function associated with
580 the handle. For the default handle, this is equivalent to
583 .. c:function:: xo_ssize_t xo_flush_h (xo_handle_t *xop)
585 :param xop: Handle for flush (or NULL for default handle)
586 :type xop: xo_handle_t \*
587 :returns: -1 for error, or the number of bytes generated
590 The `xo_flush_h` function follows the conventions of `xo_flush`,
591 but adds an explicit libxo handle.
594 .. index:: xo_finish_atexit
597 Finishing Output (xo_finish)
598 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
600 When the program is ready to exit or close a handle, a call to
601 `xo_finish` or `xo_finish_h` is required. This flushes any buffered
602 data, closes open libxo constructs, and completes any pending
605 Calling this function is vital to the proper operation of libxo,
606 especially for the non-TEXT output styles.
608 .. c:function:: xo_ssize_t xo_finish (void)
610 :returns: -1 on error, or the number of bytes flushed
613 .. c:function:: xo_ssize_t xo_finish_h (xo_handle_t *xop)
615 :param xop: Handle for finish (or NULL for default handle)
616 :type xop: xo_handle_t \*
617 :returns: -1 on error, or the number of bytes flushed
620 .. c:function:: void xo_finish_atexit (void)
622 The `xo_finish_atexit` function is suitable for use with
623 :manpage:`atexit(3)` to ensure that `xo_finish` is called
624 on the default handle when the application exits.
627 .. index:: xo_open_container
628 .. index:: xo_close_container
633 libxo represents two types of hierarchy: containers and lists. A
634 container appears once under a given parent where a list consists of
635 instances that can appear multiple times. A container is used to hold
636 related fields and to give the data organization and scope.
640 .. admonition:: YANG Terminology
642 libxo uses terminology from YANG (:RFC:`7950`), the data modeling
643 language for NETCONF: container, list, leaf, and leaf-list.
645 For XML and JSON, individual fields appear inside hierarchies which
646 provide context and meaning to the fields. Unfortunately, these
647 encoding have a basic disconnect between how lists is similar objects
650 XML encodes lists as set of sequential elements::
656 JSON encodes lists using a single name and square brackets::
658 "user": [ "phil", "pallavi", "sjg" ]
660 This means libxo needs three distinct indications of hierarchy: one
661 for containers of hierarchy appear only once for any specific parent,
662 one for lists, and one for each item in a list.
664 .. index:: Containers
669 A "*container*" is an element of a hierarchy that appears only once
670 under any specific parent. The container has no value, but serves to
671 contain and organize other nodes.
673 To open a container, call xo_open_container() or
674 xo_open_container_h(). The former uses the default handle and the
675 latter accepts a specific handle. To close a level, use the
676 xo_close_container() or xo_close_container_h() functions.
678 Each open call must have a matching close call. If the XOF_WARN flag
679 is set and the name given does not match the name of the currently open
680 container, a warning will be generated.
682 .. c:function:: xo_ssize_t xo_open_container (const char *name)
684 :param name: Name of the container
685 :type name: const char *
686 :returns: -1 on error, or the number of bytes generated
689 The `name` parameter gives the name of the container, encoded in
690 UTF-8. Since ASCII is a proper subset of UTF-8, traditional C
691 strings can be used directly.
693 .. c:function:: xo_ssize_t xo_open_container_h (xo_handle_t *xop, const char *name)
695 :param xop: Handle to use (or NULL for default handle)
696 :type xop: xo_handle_t *
698 The `xo_open_container_h` function adds a `handle` parameter.
700 .. c:function:: xo_ssize_t xo_close_container (const char *name)
702 :param name: Name of the container
703 :type name: const char *
704 :returns: -1 on error, or the number of bytes generated
707 .. c:function:: xo_ssize_t xo_close_container_h (xo_handle_t *xop, const char *name)
709 :param xop: Handle to use (or NULL for default handle)
710 :type xop: xo_handle_t *
712 The `xo_close_container_h` function adds a `handle` parameter.
714 Use the :index:`XOF_WARN` flag to generate a warning if the name given
715 on the close does not match the current open container.
717 For TEXT and HTML output, containers are not rendered into output
718 text, though for HTML they are used to record an XPath value when the
719 :index:`XOF_XPATH` flag is set.
724 xo_open_container("top");
725 xo_open_container("system");
726 xo_emit("{:host-name/%s%s%s}", hostname,
727 domainname ? "." : "", domainname ?: "");
728 xo_close_container("system");
729 xo_close_container("top");
735 <host-name>my-host.example.org</host-name>
741 "host-name": "my-host.example.org"
746 data-tag="host-name">my-host.example.org</div>
748 .. index:: xo_open_instance
749 .. index:: xo_close_instance
750 .. index:: xo_open_list
751 .. index:: xo_close_list
756 A "*list*" is set of one or more instances that appear under the same
757 parent. The instances contain details about a specific object. One
758 can think of instances as objects or records. A call is needed to
759 open and close the list, while a distinct call is needed to open and
760 close each instance of the list.
762 The name given to all calls must be identical, and it is strongly
763 suggested that the name be singular, not plural, as a matter of
764 style and usage expectations::
767 xo_open_list("item");
769 for (ip = list; ip->i_title; ip++) {
770 xo_open_instance("item");
771 xo_emit("{L:Item} '{:name/%s}':\n", ip->i_title);
772 xo_close_instance("item");
775 xo_close_list("item");
777 Getting the list and instance calls correct is critical to the proper
778 generation of XML and JSON data.
783 .. c:function:: xo_ssize_t xo_open_list (const char *name)
785 :param name: Name of the list
786 :type name: const char *
787 :returns: -1 on error, or the number of bytes generated
790 The `xo_open_list` function open a list of instances.
792 .. c:function:: xo_ssize_t xo_open_list_h (xo_handle_t *xop, const char *name)
794 :param xop: Handle to use (or NULL for default handle)
795 :type xop: xo_handle_t *
800 .. c:function:: xo_ssize_t xo_close_list (const char *name)
802 :param name: Name of the list
803 :type name: const char *
804 :returns: -1 on error, or the number of bytes generated
807 The `xo_close_list` function closes a list of instances.
809 .. c:function:: xo_ssize_t xo_close_list_h (xo_handle_t *xop, const char *name)
811 :param xop: Handle to use (or NULL for default handle)
812 :type xop: xo_handle_t *
814 The `xo_close_container_h` function adds a `handle` parameter.
819 .. c:function:: xo_ssize_t xo_open_instance (const char *name)
821 :param name: Name of the instance (same as the list name)
822 :type name: const char *
823 :returns: -1 on error, or the number of bytes generated
826 The `xo_open_instance` function open a single instance.
828 .. c:function:: xo_ssize_t xo_open_instance_h (xo_handle_t *xop, const char *name)
830 :param xop: Handle to use (or NULL for default handle)
831 :type xop: xo_handle_t *
833 The `xo_open_instance_h` function adds a `handle` parameter.
838 .. c:function:: xo_ssize_t xo_close_instance (const char *name)
840 :param name: Name of the instance
841 :type name: const char *
842 :returns: -1 on error, or the number of bytes generated
845 The `xo_close_instance` function closes an open instance.
847 .. c:function:: xo_ssize_t xo_close_instance_h (xo_handle_t *xop, const char *name)
849 :param xop: Handle to use (or NULL for default handle)
850 :type xop: xo_handle_t *
852 The `xo_close_instance_h` function adds a `handle` parameter.
857 xo_open_list("user");
858 for (i = 0; i < num_users; i++) {
859 xo_open_instance("user");
860 xo_emit("{k:name}:{:uid/%u}:{:gid/%u}:{:home}\n",
861 pw[i].pw_name, pw[i].pw_uid,
862 pw[i].pw_gid, pw[i].pw_dir);
863 xo_close_instance("user");
865 xo_close_list("user");
867 phil:1001:1001:/home/phil
868 pallavi:1002:1002:/home/pallavi
874 <home>/home/phil</home>
880 <home>/home/pallavi</home>
888 "home": "/home/phil",
894 "home": "/home/pallavi",
901 Markers are used to protect and restore the state of open hierarchy
902 constructs (containers, lists, or instances). While a marker is open,
903 no other open constructs can be closed. When a marker is closed, all
904 constructs open since the marker was opened will be closed.
906 Markers use names which are not user-visible, allowing the caller to
907 choose appropriate internal names.
909 In this example, the code whiffles through a list of fish, calling a
910 function to emit details about each fish. The marker "fish-guts" is
911 used to ensure that any constructs opened by the function are closed
915 for (i = 0; fish[i]; i++) {
916 xo_open_instance("fish");
917 xo_open_marker("fish-guts");
918 dump_fish_details(i);
919 xo_close_marker("fish-guts");
922 .. c:function:: xo_ssize_t xo_open_marker(const char *name)
924 :param name: Name of the instance
925 :type name: const char *
926 :returns: -1 on error, or the number of bytes generated
929 The `xo_open_marker` function records the current state of open tags
930 in order for `xo_close_marker` to close them at some later point.
932 .. c:function:: xo_ssize_t xo_open_marker_h(const char *name)
934 :param xop: Handle to use (or NULL for default handle)
935 :type xop: xo_handle_t *
937 The `xo_open_marker_h` function adds a `handle` parameter.
939 .. c:function:: xo_ssize_t xo_close_marker(const char *name)
941 :param name: Name of the instance
942 :type name: const char *
943 :returns: -1 on error, or the number of bytes generated
946 The `xo_close_marker` function closes any open containers, lists, or
947 instances as needed to return to the state recorded when
948 `xo_open_marker` was called with the matching name.
950 .. c:function:: xo_ssize_t xo_close_marker(const char *name)
952 :param xop: Handle to use (or NULL for default handle)
953 :type xop: xo_handle_t *
955 The `xo_close_marker_h` function adds a `handle` parameter.
960 Some users may find tracking the names of open containers, lists, and
961 instances inconvenient. libxo offers a "Do The Right Thing" mode, where
962 libxo will track the names of open containers, lists, and instances so
963 the close function can be called without a name. To enable DTRT mode,
964 turn on the XOF_DTRT flag prior to making any other libxo output::
966 xo_set_flags(NULL, XOF_DTRT);
970 Each open and close function has a version with the suffix "_d", which
971 will close the open container, list, or instance::
973 xo_open_container_d("top");
975 xo_close_container_d();
977 This also works for lists and instances::
979 xo_open_list_d("item");
981 xo_open_instance_d("item");
983 xo_close_instance_d();
989 Note that the XOF_WARN flag will also cause libxo to track open
990 containers, lists, and instances. A warning is generated when the
991 name given to the close function and the name recorded do not match.
996 .. index:: xo_parse_args
999 Parsing Command-line Arguments (xo_parse_args)
1000 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1002 .. c:function:: int xo_parse_args (int argc, char **argv)
1004 :param int argc: Number of arguments
1005 :param argv: Array of argument strings
1006 :return: -1 on error, or the number of remaining arguments
1009 The `xo_parse_args` function is used to process a program's
1010 arguments. libxo-specific options are processed and removed from
1011 the argument list so the calling application does not need to
1012 process them. If successful, a new value for argc is returned. On
1013 failure, a message is emitted and -1 is returned::
1015 argc = xo_parse_args(argc, argv);
1019 Following the call to xo_parse_args, the application can process the
1020 remaining arguments in a normal manner. See :ref:`options` for a
1021 description of valid arguments.
1023 .. index:: xo_set_program
1028 .. c:function:: void xo_set_program (const char *name)
1030 :param name: Name to use as the program name
1031 :type name: const char *
1034 The `xo_set_program` function sets the name of the program as
1035 reported by functions like `xo_failure`, `xo_warn`, `xo_err`, etc.
1036 The program name is initialized by `xo_parse_args`, but subsequent
1037 calls to `xo_set_program` can override this value::
1040 xo_set_program(argv[0]);
1042 Note that the value is not copied, so the memory passed to
1043 `xo_set_program` (and `xo_parse_args`) must be maintained by the
1046 .. index:: xo_set_version
1051 .. c:function:: void xo_set_version (const char *version)
1053 :param name: Value to use as the version string
1054 :type name: const char *
1057 The `xo_set_version` function records a version number to be emitted
1058 as part of the data for encoding styles (XML and JSON). This
1059 version number is suitable for tracking changes in the content,
1060 allowing a user of the data to discern which version of the data
1063 .. c:function:: void xo_set_version_h (xo_handle_t *xop, const char *version)
1065 :param xop: Handle to use (or NULL for default handle)
1066 :type xop: xo_handle_t *
1068 The `xo_set_version` function adds a `handle` parameter.
1072 .. index:: xo_info_t
1074 .. _field-information:
1076 Field Information (xo_info_t)
1077 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1079 HTML data can include additional information in attributes that
1080 begin with "data-". To enable this, three things must occur:
1082 First the application must build an array of xo_info_t structures,
1083 one per tag. The array must be sorted by name, since libxo uses a
1084 binary search to find the entry that matches names from format
1087 Second, the application must inform libxo about this information using
1088 the `xo_set_info` call::
1090 typedef struct xo_info_s {
1091 const char *xi_name; /* Name of the element */
1092 const char *xi_type; /* Type of field */
1093 const char *xi_help; /* Description of field */
1096 void xo_set_info (xo_handle_t *xop, xo_info_t *infop, int count);
1098 Like other libxo calls, passing `NULL` for the handle tells libxo to
1099 use the default handle.
1101 If the count is -1, libxo will count the elements of infop, but there
1102 must be an empty element at the end. More typically, the number is
1103 known to the application::
1105 xo_info_t info[] = {
1106 { "in-stock", "number", "Number of items in stock" },
1107 { "name", "string", "Name of the item" },
1108 { "on-order", "number", "Number of items on order" },
1109 { "sku", "string", "Stock Keeping Unit" },
1110 { "sold", "number", "Number of items sold" },
1112 int info_count = (sizeof(info) / sizeof(info[0]));
1114 xo_set_info(NULL, info, info_count);
1116 Third, the emission of info must be triggered with the `XOF_INFO` flag
1117 using either the `xo_set_flags` function or the "`--libxo=info`"
1118 command line argument.
1120 The type and help values, if present, are emitted as the "data-type"
1121 and "data-help" attributes::
1123 <div class="data" data-tag="sku" data-type="string"
1124 data-help="Stock Keeping Unit">GRO-000-533</div>
1126 .. c:function:: void xo_set_info (xo_handle_t *xop, xo_info_t *infop, int count)
1128 :param xop: Handle to use (or NULL for default handle)
1129 :type xop: xo_handle_t *
1130 :param infop: Array of information structures
1131 :type infop: xo_info_t *
1134 .. index:: xo_set_allocator
1135 .. index:: xo_realloc_func_t
1136 .. index:: xo_free_func_t
1141 The `xo_set_allocator` function allows libxo to be used in
1142 environments where the standard :manpage:`realloc(3)` and
1143 :manpage:`free(3)` functions are not appropriate.
1145 .. c:function:: void xo_set_allocator (xo_realloc_func_t realloc_func, xo_free_func_t free_func)
1147 :param xo_realloc_func_t realloc_func: Allocation function
1148 :param xo_free_func_t free_func: Free function
1150 *realloc_func* should expect the same arguments as
1151 :manpage:`realloc(3)` and return a pointer to memory following the
1152 same convention. *free_func* will receive the same argument as
1153 :manpage:`free(3)` and should release it, as appropriate for the
1156 By default, the standard :manpage:`realloc(3)` and :manpage:`free(3)`
1166 The environment variable "LIBXO_OPTIONS" can be set to a subset of
1167 libxo options, including:
1181 For example, warnings can be enabled by::
1183 % env LIBXO_OPTIONS=warn my-app
1185 Since environment variables are inherited, child processes will have
1186 the same options, which may be undesirable, making the use of the
1187 "`--libxo`" command-line option preferable in most situations.
1192 .. index:: xo_message
1194 Errors, Warnings, and Messages
1195 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1197 Many programs make use of the standard library functions
1198 :manpage:`err(3)` and :manpage:`warn(3)` to generate errors and
1199 warnings for the user. libxo wants to pass that information via the
1200 current output style, and provides compatible functions to allow
1203 void xo_warn (const char *fmt, ...);
1204 void xo_warnx (const char *fmt, ...);
1205 void xo_warn_c (int code, const char *fmt, ...);
1206 void xo_warn_hc (xo_handle_t *xop, int code,
1207 const char *fmt, ...);
1208 void xo_err (int eval, const char *fmt, ...);
1209 void xo_errc (int eval, int code, const char *fmt, ...);
1210 void xo_errx (int eval, const char *fmt, ...);
1214 void xo_message (const char *fmt, ...);
1215 void xo_message_c (int code, const char *fmt, ...);
1216 void xo_message_hc (xo_handle_t *xop, int code,
1217 const char *fmt, ...);
1218 void xo_message_hcv (xo_handle_t *xop, int code,
1219 const char *fmt, va_list vap);
1221 These functions display the program name, a colon, a formatted message
1222 based on the arguments, and then optionally a colon and an error
1223 message associated with either *errno* or the *code* parameter::
1226 if (open(filename, O_RDONLY) < 0)
1227 xo_err(1, "cannot open file '%s'", filename);
1230 .. index:: xo_error_h
1231 .. index:: xo_error_hv
1232 .. index:: xo_errorn
1233 .. index:: xo_errorn_h
1234 .. index:: xo_errorn_hv
1239 .. c:function:: void xo_error (const char *fmt, ...)
1241 :param fmt: Format string
1242 :type fmt: const char *
1245 .. c:function:: void xo_error_h (xo_handle_t *xop, const char *fmt, ...)
1247 :param xop: libxo handle pointer
1248 :type xop: xo_handle_t *
1249 :param fmt: Format string
1250 :type fmt: const char *
1253 .. c:function:: void xo_error_hv (xo_handle_t *xop, const char *fmt, va_list vap)
1255 :param xop: libxo handle pointer
1256 :type xop: xo_handle_t *
1257 :param fmt: Format string
1258 :type fmt: const char *
1259 :param vap: variadic arguments
1263 .. c:function:: void xo_errorn (const char *fmt, ...)
1265 :param fmt: Format string
1266 :type fmt: const char *
1269 .. c:function:: void xo_errorn_h (xo_handle_t *xop, const char *fmt, ...)
1271 :param xop: libxo handle pointer
1272 :type xop: xo_handle_t *
1273 :param fmt: Format string
1274 :type fmt: const char *
1277 .. c:function:: void xo_errorn_hv (xo_handle_t *xop, int need_newline, const char *fmt, va_list vap)
1279 :param xop: libxo handle pointer
1280 :type xop: xo_handle_t *
1281 :param need_newline: boolean indicating need for trailing newline
1282 :type need_newline: int
1283 :param fmt: Format string
1284 :type fmt: const char *
1285 :param vap: variadic arguments
1289 The `xo_error` function can be used for generic errors that should
1290 be reported over the handle, rather than to stderr. The `xo_error`
1291 function behaves like `xo_err` for TEXT and HTML output styles, but
1292 puts the error into XML or JSON elements::
1295 xo_error("Does not %s", "compute");
1297 <error><message>Does not compute</message></error>
1299 "error": { "message": "Does not compute" }
1301 The `xo_error_h` and `xo_error_hv` add a handle object and a
1302 variadic-ized parameter to the signature, respectively.
1304 The `xo_errorn` function supplies a newline at the end the error
1305 message if the format string does not include one. The
1306 `xo_errorn_h` and `xo_errorn_hv` functions add a handle object and
1307 a variadic-ized parameter to the signature, respectively. The
1308 `xo_errorn_hv` function also adds a boolean to indicate the need for
1311 .. index:: xo_no_setlocale
1317 .. c:function:: void xo_no_setlocale (void)
1319 libxo automatically initializes the locale based on setting of the
1320 environment variables LC_CTYPE, LANG, and LC_ALL. The first of this
1321 list of variables is used and if none of the variables, the locale
1322 defaults to "UTF-8". The caller may wish to avoid this behavior,
1323 and can do so by calling the `xo_no_setlocale` function.
1325 Emitting syslog Messages
1326 ------------------------
1328 syslog is the system logging facility used throughout the unix world.
1329 Messages are sent from commands, applications, and daemons to a
1330 hierarchy of servers, where they are filtered, saved, and forwarded
1331 based on configuration behaviors.
1333 syslog is an older protocol, originally documented only in source
1334 code. By the time :RFC:`3164` published, variation and mutation left the
1335 leading "<pri>" string as only common content. :RFC:`5424` defines a new
1336 version (version 1) of syslog and introduces structured data into the
1337 messages. Structured data is a set of name/value pairs transmitted
1338 distinctly alongside the traditional text message, allowing filtering
1339 on precise values instead of regular expressions.
1341 These name/value pairs are scoped by a two-part identifier; an
1342 enterprise identifier names the party responsible for the message
1343 catalog and a name identifying that message. `Enterprise IDs`_ are
1344 defined by IANA, the Internet Assigned Numbers Authority.
1347 https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers
1349 Use the `xo_set_syslog_enterprise_id` function to set the Enterprise
1352 The message name should follow the conventions in
1353 :ref:`good-field-names`\ , as should the fields within the message::
1355 /* Both of these calls are optional */
1356 xo_set_syslog_enterprise_id(32473);
1357 xo_open_log("my-program", 0, LOG_DAEMON);
1359 /* Generate a syslog message */
1360 xo_syslog(LOG_ERR, "upload-failed",
1361 "error <%d> uploading file '{:filename}' "
1362 "as '{:target/%s:%s}'",
1363 code, filename, protocol, remote);
1365 xo_syslog(LOG_INFO, "poofd-invalid-state",
1366 "state {:current/%u} is invalid {:connection/%u}",
1369 The developer should be aware that the message name may be used in the
1370 future to allow access to further information, including
1371 documentation. Care should be taken to choose quality, descriptive
1376 Priority, Facility, and Flags
1377 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1379 The `xo_syslog`, `xo_vsyslog`, and `xo_open_log` functions
1380 accept a set of flags which provide the priority of the message, the
1381 source facility, and some additional features. These values are OR'd
1382 together to create a single integer argument::
1384 xo_syslog(LOG_ERR | LOG_AUTH, "login-failed",
1385 "Login failed; user '{:user}' from host '{:address}'",
1388 These values are defined in <syslog.h>.
1390 The priority value indicates the importance and potential impact of
1393 ============= =======================================================
1394 Priority Description
1395 ============= =======================================================
1396 LOG_EMERG A panic condition, normally broadcast to all users
1397 LOG_ALERT A condition that should be corrected immediately
1398 LOG_CRIT Critical conditions
1399 LOG_ERR Generic errors
1400 LOG_WARNING Warning messages
1401 LOG_NOTICE Non-error conditions that might need special handling
1402 LOG_INFO Informational messages
1403 LOG_DEBUG Developer-oriented messages
1404 ============= =======================================================
1406 The facility value indicates the source of message, in fairly generic
1409 =============== =======================================================
1410 Facility Description
1411 =============== =======================================================
1412 LOG_AUTH The authorization system (e.g. :manpage:`login(1)`)
1413 LOG_AUTHPRIV As LOG_AUTH, but logged to a privileged file
1414 LOG_CRON The cron daemon: :manpage:`cron(8)`
1415 LOG_DAEMON System daemons, not otherwise explicitly listed
1416 LOG_FTP The file transfer protocol daemons
1417 LOG_KERN Messages generated by the kernel
1418 LOG_LPR The line printer spooling system
1419 LOG_MAIL The mail system
1420 LOG_NEWS The network news system
1421 LOG_SECURITY Security subsystems, such as :manpage:`ipfw(4)`
1422 LOG_SYSLOG Messages generated internally by :manpage:`syslogd(8)`
1423 LOG_USER Messages generated by user processes (default)
1424 LOG_UUCP The uucp system
1425 LOG_LOCAL0..7 Reserved for local use
1426 =============== =======================================================
1428 In addition to the values listed above, xo_open_log accepts a set of
1429 addition flags requesting specific logging behaviors:
1431 ============ ====================================================
1433 ============ ====================================================
1434 LOG_CONS If syslogd fails, attempt to write to /dev/console
1435 LOG_NDELAY Open the connection to :manpage:`syslogd(8)` immediately
1436 LOG_PERROR Write the message also to standard error output
1437 LOG_PID Log the process id with each message
1438 ============ ====================================================
1440 .. index:: xo_syslog
1445 .. c:function:: void xo_syslog (int pri, const char *name, const char *fmt, ...)
1447 :param int pri: syslog priority
1448 :param name: Name of the syslog event
1449 :type name: const char *
1450 :param fmt: Format string, followed by arguments
1451 :type fmt: const char *
1454 Use the `xo_syslog` function to generate syslog messages by calling
1455 it with a log priority and facility, a message name, a format
1456 string, and a set of arguments. The priority/facility argument are
1457 discussed above, as is the message name.
1459 The format string follows the same conventions as `xo_emit`'s format
1460 string, with each field being rendered as an SD-PARAM pair::
1462 xo_syslog(LOG_ERR, "poofd-missing-file",
1463 "'{:filename}' not found: {:error/%m}", filename);
1465 ... [poofd-missing-file@32473 filename="/etc/poofd.conf"
1466 error="Permission denied"] '/etc/poofd.conf' not
1467 found: Permission denied
1472 .. index:: xo_vsyslog
1477 .. c:function:: void xo_vsyslog (int pri, const char *name, const char *fmt, va_list vap)
1479 :param int pri: syslog priority
1480 :param name: Name of the syslog event
1481 :type name: const char *
1482 :param fmt: Format string
1483 :type fmt: const char *
1484 :param va_list vap: Variadic argument list
1487 xo_vsyslog is identical in function to xo_syslog, but takes the set of
1488 arguments using a va_list::
1492 my_log (const char *name, const char *fmt, ...)
1496 xo_vsyslog(LOG_ERR, name, fmt, vap);
1500 .. index:: xo_open_log
1505 .. c:function:: void xo_open_log (const char *ident, int logopt, int facility)
1508 :type indent: const char *
1509 :param int logopt: Bit field containing logging options
1510 :param int facility:
1513 xo_open_log functions similar to :manpage:`openlog(3)`, allowing
1514 customization of the program name, the log facility number, and the
1515 additional option flags described in :ref:`syslog-details`.
1517 .. index:: xo_close_log
1522 .. c:function:: void xo_close_log (void)
1524 The `xo_close_log` function is similar to :manpage:`closelog(3)`,
1525 closing the log file and releasing any associated resources.
1527 .. index:: xo_set_logmask
1532 .. c:function:: int xo_set_logmask (int maskpri)
1534 :param int maskpri: the log priority mask
1535 :returns: The previous log priority mask
1537 The `xo_set_logmask` function is similar to :manpage:`setlogmask(3)`,
1538 restricting the set of generated log event to those whose associated
1539 bit is set in maskpri. Use `LOG_MASK(pri)` to find the appropriate bit,
1540 or `LOG_UPTO(toppri)` to create a mask for all priorities up to and
1544 setlogmask(LOG_UPTO(LOG_WARN));
1546 .. index:: xo_set_syslog_enterprise_id
1548 xo_set_syslog_enterprise_id
1549 +++++++++++++++++++++++++++
1551 .. c:function:: void xo_set_syslog_enterprise_id (unsigned short eid)
1553 Use the `xo_set_syslog_enterprise_id` to supply a platform- or
1554 application-specific enterprise id. This value is used in any future
1557 Ideally, the operating system should supply a default value via the
1558 "kern.syslog.enterprise_id" sysctl value. Lacking that, the
1559 application should provide a suitable value.
1561 Enterprise IDs are administered by IANA, the Internet Assigned Number
1562 Authority. The complete list is EIDs on their web site::
1564 https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers
1566 New EIDs can be requested from IANA using the following page::
1568 http://pen.iana.org/pen/PenApplication.page
1570 Each software development organization that defines a set of syslog
1571 messages should register their own EID and use that value in their
1572 software to ensure that messages can be uniquely identified by the
1573 combination of EID + message name.
1575 Creating Custom Encoders
1576 ------------------------
1578 The number of encoding schemes in current use is staggering, with new
1579 and distinct schemes appearing daily. While libxo provide XML, JSON,
1580 HMTL, and text natively, there are requirements for other encodings.
1582 Rather than bake support for all possible encoders into libxo, the API
1583 allows them to be defined externally. libxo can then interfaces with
1584 these encoding modules using a simplistic API. libxo processes all
1585 functions calls, handles state transitions, performs all formatting,
1586 and then passes the results as operations to a customized encoding
1587 function, which implements specific encoding logic as required. This
1588 means your encoder doesn't need to detect errors with unbalanced
1589 open/close operations but can rely on libxo to pass correct data.
1591 By making a simple API, libxo internals are not exposed, insulating the
1592 encoder and the library from future or internal changes.
1594 The three elements of the API are:
1600 The following sections provide details about these topics.
1604 libxo source contains an encoder for Concise Binary Object
1605 Representation, aka CBOR (:RFC:`7049`), which can be used as an
1606 example for the API for other encoders.
1611 Encoders can be registered statically or discovered dynamically.
1612 Applications can choose to call the `xo_encoder_register` function
1613 to explicitly register encoders, but more typically they are built as
1614 shared libraries, placed in the libxo/extensions directory, and loaded
1615 based on name. libxo looks for a file with the name of the encoder
1616 and an extension of ".enc". This can be a file or a symlink to the
1617 shared library file that supports the encoder::
1619 % ls -1 lib/libxo/extensions/*.enc
1620 lib/libxo/extensions/cbor.enc
1621 lib/libxo/extensions/test.enc
1623 Encoder Initialization
1624 ~~~~~~~~~~~~~~~~~~~~~~
1626 Each encoder must export a symbol used to access the library, which
1627 must have the following signature::
1629 int xo_encoder_library_init (XO_ENCODER_INIT_ARGS);
1631 `XO_ENCODER_INIT_ARGS` is a macro defined in "xo_encoder.h" that defines
1632 an argument called "arg", a pointer of the type
1633 `xo_encoder_init_args_t`. This structure contains two fields:
1635 - `xei_version` is the version number of the API as implemented
1636 within libxo. This version is currently as 1 using
1637 `XO_ENCODER_VERSION`. This number can be checked to ensure
1638 compatibility. The working assumption is that all versions should
1639 be backward compatible, but each side may need to accurately know
1640 the version supported by the other side. `xo_encoder_library_init`
1641 can optionally check this value, and must then set it to the version
1642 number used by the encoder, allowing libxo to detect version
1643 differences and react accordingly. For example, if version 2 adds
1644 new operations, then libxo will know that an encoding library that
1645 set `xei_version` to 1 cannot be expected to handle those new
1648 - xei_handler must be set to a pointer to a function of type
1649 `xo_encoder_func_t`, as defined in "xo_encoder.h". This function
1650 takes a set of parameters:
1651 - xop is a pointer to the opaque `xo_handle_t` structure
1652 - op is an integer representing the current operation
1653 - name is a string whose meaning differs by operation
1654 - value is a string whose meaning differs by operation
1655 - private is an opaque structure provided by the encoder
1657 Additional arguments may be added in the future, so handler functions
1658 should use the `XO_ENCODER_HANDLER_ARGS` macro. An appropriate
1659 "extern" declaration is provided to help catch errors.
1661 Once the encoder initialization function has completed processing, it
1662 should return zero to indicate that no error has occurred. A non-zero
1663 return code will cause the handle initialization to fail.
1668 The encoder API defines a set of operations representing the
1669 processing model of libxo. Content is formatted within libxo, and
1670 callbacks are made to the encoder's handler function when data is
1671 ready to be processed:
1673 ======================= =======================================
1674 Operation Meaning (Base function)
1675 ======================= =======================================
1676 XO_OP_CREATE Called when the handle is created
1677 XO_OP_OPEN_CONTAINER Container opened (xo_open_container)
1678 XO_OP_CLOSE_CONTAINER Container closed (xo_close_container)
1679 XO_OP_OPEN_LIST List opened (xo_open_list)
1680 XO_OP_CLOSE_LIST List closed (xo_close_list)
1681 XO_OP_OPEN_LEAF_LIST Leaf list opened (xo_open_leaf_list)
1682 XO_OP_CLOSE_LEAF_LIST Leaf list closed (xo_close_leaf_list)
1683 XO_OP_OPEN_INSTANCE Instance opened (xo_open_instance)
1684 XO_OP_CLOSE_INSTANCE Instance closed (xo_close_instance)
1685 XO_OP_STRING Field with Quoted UTF-8 string
1686 XO_OP_CONTENT Field with content
1687 XO_OP_FINISH Finish any pending output
1688 XO_OP_FLUSH Flush any buffered output
1689 XO_OP_DESTROY Clean up resources
1690 XO_OP_ATTRIBUTE An attribute name/value pair
1691 XO_OP_VERSION A version string
1692 ======================= =======================================
1694 For all the open and close operations, the name parameter holds the
1695 name of the construct. For string, content, and attribute operations,
1696 the name parameter is the name of the field and the value parameter is
1697 the value. "string" are differentiated from "content" to allow differing
1698 treatment of true, false, null, and numbers from real strings, though
1699 content values are formatted as strings before the handler is called.
1700 For version operations, the value parameter contains the version.
1702 All strings are encoded in UTF-8.