svn commit: r334068 - in head: contrib/libxo contrib/libxo/doc contrib/libxo/doc/_static contrib/libxo/doc/_templates contrib/libxo/libxo contrib/libxo/tests/core contrib/libxo/tests/core/saved con...
Phil Shafer
phil at FreeBSD.org
Wed May 23 01:20:32 UTC 2018
Author: phil
Date: Wed May 23 01:20:31 2018
New Revision: 334068
URL: https://svnweb.freebsd.org/changeset/base/334068
Log:
Import libxo-0.9.0:
- Add xo_format_is_numeric() with improved logic to decide if format
strings are numeric, so json output quotes them
- Convert docs to sphinx/rst
- update tests
Includes fix for PR 221676:
https://github.com/Juniper/libxo/commit/27d3021cc3cc8cfbe9ddee5930cd7a9afea8f68f#diff-5a0d468963477f7daedb8308c219dd80
PR: 221676
MFC after: 5 days
Added:
head/contrib/libxo/doc/_static/
- copied from r334067, vendor/Juniper/libxo/dist/doc/_static/
head/contrib/libxo/doc/_templates/
- copied from r334067, vendor/Juniper/libxo/dist/doc/_templates/
head/contrib/libxo/doc/api.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/api.rst
head/contrib/libxo/doc/conf.py
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/conf.py
head/contrib/libxo/doc/example.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/example.rst
head/contrib/libxo/doc/faq.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/faq.rst
head/contrib/libxo/doc/field-formatting.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/field-formatting.rst
head/contrib/libxo/doc/field-modifiers.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/field-modifiers.rst
head/contrib/libxo/doc/field-roles.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/field-roles.rst
head/contrib/libxo/doc/format-strings.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/format-strings.rst
head/contrib/libxo/doc/formatting.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/formatting.rst
head/contrib/libxo/doc/getting.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/getting.rst
head/contrib/libxo/doc/howto.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/howto.rst
head/contrib/libxo/doc/index.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/index.rst
head/contrib/libxo/doc/intro.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/intro.rst
head/contrib/libxo/doc/options.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/options.rst
head/contrib/libxo/doc/xo.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/xo.rst
head/contrib/libxo/doc/xohtml.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/xohtml.rst
head/contrib/libxo/doc/xolint.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/xolint.rst
head/contrib/libxo/doc/xopo.rst
- copied unchanged from r334067, vendor/Juniper/libxo/dist/doc/xopo.rst
Modified:
head/contrib/libxo/configure.ac
head/contrib/libxo/doc/Makefile.am
head/contrib/libxo/doc/libxo-manual.html
head/contrib/libxo/libxo/libxo.c
head/contrib/libxo/tests/core/saved/test_01.E.out
head/contrib/libxo/tests/core/saved/test_01.H.out
head/contrib/libxo/tests/core/saved/test_01.HIPx.out
head/contrib/libxo/tests/core/saved/test_01.HP.out
head/contrib/libxo/tests/core/saved/test_01.J.out
head/contrib/libxo/tests/core/saved/test_01.JP.out
head/contrib/libxo/tests/core/saved/test_01.T.out
head/contrib/libxo/tests/core/saved/test_01.X.out
head/contrib/libxo/tests/core/saved/test_01.XP.out
head/contrib/libxo/tests/core/saved/test_12.J.out
head/contrib/libxo/tests/core/saved/test_12.JP.out
head/contrib/libxo/tests/core/test_01.c
head/contrib/libxo/tests/gettext/saved/gt_01.J.out
head/contrib/libxo/tests/gettext/saved/gt_01.JP.out
head/lib/libxo/add.man
head/lib/libxo/xo_config.h
head/usr.bin/xohtml/xohtml.sh
Directory Properties:
head/contrib/libxo/ (props changed)
Modified: head/contrib/libxo/configure.ac
==============================================================================
--- head/contrib/libxo/configure.ac Wed May 23 01:12:39 2018 (r334067)
+++ head/contrib/libxo/configure.ac Wed May 23 01:20:31 2018 (r334068)
@@ -12,7 +12,7 @@
#
AC_PREREQ(2.2)
-AC_INIT([libxo], [0.8.4], [phil at juniper.net])
+AC_INIT([libxo], [0.9.0], [phil at juniper.net])
AM_INIT_AUTOMAKE([-Wall -Werror foreign -Wno-portability])
# Support silent build rules. Requires at least automake-1.11.
Modified: head/contrib/libxo/doc/Makefile.am
==============================================================================
--- head/contrib/libxo/doc/Makefile.am Wed May 23 01:12:39 2018 (r334067)
+++ head/contrib/libxo/doc/Makefile.am Wed May 23 01:20:31 2018 (r334068)
@@ -68,3 +68,8 @@ else
doc docs:
@${ECHO} "The 'oxtradoc' tool is not installed; see libslax.org"
endif
+
+SPHINX = python3.4 -msphinx
+
+html sphinx sphinx-html:
+ ${SPHINX} -M html ${srcdir} .
Copied: head/contrib/libxo/doc/api.rst (from r334067, vendor/Juniper/libxo/dist/doc/api.rst)
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/contrib/libxo/doc/api.rst Wed May 23 01:20:31 2018 (r334068, copy of r334067, vendor/Juniper/libxo/dist/doc/api.rst)
@@ -0,0 +1,1620 @@
+.. index: API
+
+The libxo API
+=============
+
+This section gives details about the functions in libxo, how to call
+them, and the actions they perform.
+
+.. index:: Handles
+.. _handles:
+
+Handles
+-------
+
+libxo uses "handles" to control its rendering functionality. The
+handle contains state and buffered data, as well as callback functions
+to process data.
+
+Handles give an abstraction for libxo that encapsulates the state of a
+stream of output. Handles have the data type "`xo_handle_t`" and are
+opaque to the caller.
+
+The library has a default handle that is automatically initialized.
+By default, this handle will send text style output (`XO_STYLE_TEXT`) to
+standard output. The xo_set_style and xo_set_flags functions can be
+used to change this behavior.
+
+For the typical command that is generating output on standard output,
+there is no need to create an explicit handle, but they are available
+when needed, e.g., for daemons that generate multiple streams of
+output.
+
+Many libxo functions take a handle as their first parameter; most that
+do not use the default handle. Any function taking a handle can be
+passed NULL to access the default handle. For the convenience of
+callers, the libxo library includes handle-less functions that
+implicitly use the default handle.
+
+For example, the following are equivalent::
+
+ xo_emit("test");
+ xo_emit_h(NULL, "test");
+
+Handles are created using `xo_create` and destroy using
+`xo_destroy`.
+
+.. index:: xo_create
+
+xo_create
+~~~~~~~~~
+
+.. c:function:: xo_handle_t *xo_create (xo_style_t style, xo_xof_flags_t flags)
+
+ The `xo_create` function allocates a new handle which can be passed
+ to further libxo function calls. The `xo_handle_t` structure is
+ opaque.
+
+ :param xo_style_t style: Output style (XO_STYLE\_*)
+ :param xo_xof_flags_t flags: Flags for this handle (XOF\_*)
+ :return: New libxo handle
+ :rtype: xo_handle_t \*
+
+ ::
+
+ EXAMPLE:
+ xo_handle_t *xop = xo_create(XO_STYLE_JSON, XOF_WARN | XOF_PRETTY);
+ ....
+ xo_emit_h(xop, "testing\n");
+
+ See also :ref:`output-styles` and :ref:`flags`.
+
+.. index:: xo_create_to_file
+.. index:: XOF_CLOSE_FP
+
+xo_create_to_file
+~~~~~~~~~~~~~~~~~
+
+.. c:function::
+ xo_handle_t *xo_create_to_file (FILE *fp, unsigned style, unsigned flags)
+
+ The `xo_create_to_file` function is aconvenience function is
+ provided for situations when output should be written to a different
+ file, rather than the default of standard output.
+
+ The `XOF_CLOSE_FP` flag can be set on the returned handle to trigger a
+ call to fclose() for the FILE pointer when the handle is destroyed,
+ avoiding the need for the caller to perform this task.
+
+ :param fp: FILE to use as base for this handle
+ :type fp: FILE *
+ :param xo_style_t style: Output style (XO_STYLE\_*)
+ :param xo_xof_flags_t flags: Flags for this handle (XOF\_*)
+ :return: New libxo handle
+ :rtype: xo_handle_t \*
+
+.. index:: xo_set_writer
+.. index:: xo_write_func_t
+.. index:: xo_close_func_t
+.. index:: xo_flush_func_t
+
+xo_set_writer
+~~~~~~~~~~~~~
+
+.. c:function::
+ void xo_set_writer (xo_handle_t *xop, void *opaque, \
+ xo_write_func_t write_func, xo_close_func_t close_func, \
+ xo_flush_func_t flush_func)
+
+ The `xo_set_writer` function allows custom functions which can
+ tailor how libxo writes data. The `opaque` argument is recorded and
+ passed back to the functions, allowing the function to acquire
+ context information. The *write_func* function writes data to the
+ output stream. The *close_func* function can release this opaque
+ data and any other resources as needed. The *flush_func* function
+ is called to flush buffered data associated with the opaque object.
+
+ :param xop: Handle to modify (or NULL for default handle)
+ :type xop: xo_handle_t *
+ :param opaque: Pointer to opaque data passed to the given functions
+ :type opaque: void *
+ :param xo_write_func_t write_func: New write function
+ :param xo_close_func_t close_func: New close function
+ :param xo_flush_func_t flush_func: New flush function
+ :returns: void
+
+.. index:: xo_get_style
+
+xo_get_style
+~~~~~~~~~~~~
+
+.. c:function:: xo_style_t xo_get_style(xo_handle_t *xop)
+
+ Use the `xo_get_style` function to find the current output style for
+ a given handle. To use the default handle, pass a `NULL` handle.
+
+ :param xop: Handle to interrogate (or NULL for default handle)
+ :type xop: xo_handle_t *
+ :returns: Output style (XO_STYLE\_*)
+ :rtype: xo_style_t
+
+ ::
+
+ EXAMPLE::
+ style = xo_get_style(NULL);
+
+.. index:: XO_STYLE_TEXT
+.. index:: XO_STYLE_XML
+.. index:: XO_STYLE_JSON
+.. index:: XO_STYLE_HTML
+
+.. _output-styles:
+
+Output Styles (XO_STYLE\_\*)
+++++++++++++++++++++++++++++
+
+The libxo functions accept a set of output styles:
+
+=============== =========================
+ Flag Description
+=============== =========================
+ XO_STYLE_TEXT Traditional text output
+ XO_STYLE_XML XML encoded data
+ XO_STYLE_JSON JSON encoded data
+ XO_STYLE_HTML HTML encoded data
+=============== =========================
+
+The "XML", "JSON", and "HTML" output styles all use the UTF-8
+character encoding. "TEXT" using locale-based encoding.
+
+.. index:: xo_set_style
+
+xo_set_style
+~~~~~~~~~~~~
+
+.. c:function:: void xo_set_style(xo_handle_t *xop, xo_style_t style)
+
+ The `xo_set_style` function is used to change the output style
+ setting for a handle. To use the default handle, pass a `NULL`
+ handle.
+
+ :param xop: Handle to modify
+ :type xop: xo_handle_t *
+ :param xo_style_t style: Output style (XO_STYLE\_*)
+ :returns: void
+
+ ::
+
+ EXAMPLE:
+ xo_set_style(NULL, XO_STYLE_XML);
+
+.. index:: xo_set_style_name
+
+xo_set_style_name
+~~~~~~~~~~~~~~~~~
+
+.. c:function:: int xo_set_style_name (xo_handle_t *xop, const char *style)
+
+ The `xo_set_style_name` function can be used to set the style based
+ on a name encoded as a string: The name can be any of the supported
+ styles: "text", "xml", "json", or "html".
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :param style: Text name of the style
+ :type style: const char \*
+ :returns: zero for success, non-zero for error
+ :rtype: int
+
+ ::
+
+ EXAMPLE:
+ xo_set_style_name(NULL, "html");
+
+.. index:: xo_set_flags
+
+xo_set_flags
+~~~~~~~~~~~~
+
+.. c:function:: void xo_set_flags(xo_handle_t *xop, xo_xof_flags_t flags)
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :param xo_xof_flags_t flags: Flags to add for the handle
+ :returns: void
+
+ Use the `xo_set_flags` function to turn on flags for a given libxo
+ handle. To use the default handle, pass a `NULL` handle.
+
+ ::
+
+ EXAMPLE:
+ xo_set_flags(NULL, XOF_PRETTY | XOF_WARN);
+
+.. index:: Flags; XOF_*
+.. index:: XOF_CLOSE_FP
+.. index:: XOF_COLOR
+.. index:: XOF_COLOR_ALLOWED
+.. index:: XOF_DTRT
+.. index:: XOF_INFO
+.. index:: XOF_KEYS
+.. index:: XOF_NO_ENV
+.. index:: XOF_NO_HUMANIZE
+.. index:: XOF_PRETTY
+.. index:: XOF_UNDERSCORES
+.. index:: XOF_UNITS
+.. index:: XOF_WARN
+.. index:: XOF_WARN_XML
+.. index:: XOF_XPATH
+.. index:: XOF_COLUMNS
+.. index:: XOF_FLUSH
+
+.. _flags:
+
+Flags (XOF\_\*)
++++++++++++++++
+
+The set of valid flags include:
+
+=================== =========================================
+ Flag Description
+=================== =========================================
+ XOF_CLOSE_FP Close file pointer on `xo_destroy`
+ XOF_COLOR Enable color and effects in output
+ XOF_COLOR_ALLOWED Allow color/effect for terminal output
+ XOF_DTRT Enable "do the right thing" mode
+ XOF_INFO Display info data attributes (HTML)
+ XOF_KEYS Emit the key attribute (XML)
+ XOF_NO_ENV Do not use the :ref:`libxo-options` env var
+ XOF_NO_HUMANIZE Display humanization (TEXT, HTML)
+ XOF_PRETTY Make "pretty printed" output
+ XOF_UNDERSCORES Replaces hyphens with underscores
+ XOF_UNITS Display units (XML, HMTL)
+ XOF_WARN Generate warnings for broken calls
+ XOF_WARN_XML Generate warnings in XML on stdout
+ XOF_XPATH Emit XPath expressions (HTML)
+ XOF_COLUMNS Force xo_emit to return columns used
+ XOF_FLUSH Flush output after each `xo_emit` call
+=================== =========================================
+
+The `XOF_CLOSE_FP` flag will trigger the call of the *close_func*
+(provided via `xo_set_writer`) when the handle is destroyed.
+
+The `XOF_COLOR` flag enables color and effects in output regardless
+of output device, while the `XOF_COLOR_ALLOWED` flag allows color
+and effects only if the output device is a terminal.
+
+The `XOF_PRETTY` flag requests "pretty printing", which will trigger
+the addition of indentation and newlines to enhance the readability of
+XML, JSON, and HTML output. Text output is not affected.
+
+The `XOF_WARN` flag requests that warnings will trigger diagnostic
+output (on standard error) when the library notices errors during
+operations, or with arguments to functions. Without warnings enabled,
+such conditions are ignored.
+
+Warnings allow developers to debug their interaction with libxo.
+The function `xo_failure` can used as a breakpoint for a debugger,
+regardless of whether warnings are enabled.
+
+If the style is `XO_STYLE_HTML`, the following additional flags can be
+used:
+
+=============== =========================================
+ Flag Description
+=============== =========================================
+ XOF_XPATH Emit "data-xpath" attributes
+ XOF_INFO Emit additional info fields
+=============== =========================================
+
+The `XOF_XPATH` flag enables the emission of XPath expressions detailing
+the hierarchy of XML elements used to encode the data field, if the
+XPATH style of output were requested.
+
+The `XOF_INFO` flag encodes additional informational fields for HTML
+output. See :ref:`field-information` for details.
+
+If the style is `XO_STYLE_XML`, the following additional flags can be
+used:
+
+=============== =========================================
+ Flag Description
+=============== =========================================
+ XOF_KEYS Flag "key" fields for XML
+=============== =========================================
+
+The `XOF_KEYS` flag adds "key" attribute to the XML encoding for
+field definitions that use the "k" modifier. The key attribute has
+the value "key"::
+
+ xo_emit("{k:name}", item);
+
+ XML:
+ <name key="key">truck</name>
+
+.. index:: xo_clear_flags
+
+xo_clear_flags
+++++++++++++++
+
+.. c:function:: void xo_clear_flags (xo_handle_t *xop, xo_xof_flags_t flags)
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :param xo_xof_flags_t flags: Flags to clear for the handle
+ :returns: void
+
+ Use the `xo_clear_flags` function to turn off the given flags in a
+ specific handle. To use the default handle, pass a `NULL` handle.
+
+.. index:: xo_set_options
+
+xo_set_options
+++++++++++++++
+
+.. c:function:: int xo_set_options (xo_handle_t *xop, const char *input)
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :param input: string containing options to set
+ :type input: const char *
+ :returns: zero for success, non-zero for error
+ :rtype: int
+
+ The `xo_set_options` function accepts a comma-separated list of
+ output styles and modifier flags and enables them for a specific
+ handle. The options are identical to those listed in
+ :ref:`options`. To use the default handle, pass a `NULL` handle.
+
+.. index:: xo_destroy
+
+xo_destroy
+++++++++++
+
+.. c:function:: void xo_destroy(xo_handle_t *xop)
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :returns: void
+
+ The `xo_destroy` function releases a handle and any resources it is
+ using. Calling `xo_destroy` with a `NULL` handle will release any
+ resources associated with the default handle.
+
+.. index:: xo_emit
+
+Emitting Content (xo_emit)
+--------------------------
+
+The functions in this section are used to emit output.
+
+The "fmt" argument is a string containing field descriptors as
+specified in :ref:`format-strings`. The use of a handle is optional and
+`NULL` can be passed to access the internal "default" handle. See
+:ref:`handles`.
+
+The remaining arguments to `xo_emit` and `xo_emit_h` are a set of
+arguments corresponding to the fields in the format string. Care must
+be taken to ensure the argument types match the fields in the format
+string, since an inappropriate cast can ruin your day. The vap
+argument to `xo_emit_hv` points to a variable argument list that can
+be used to retrieve arguments via `va_arg`.
+
+.. c:function:: int xo_emit (const char *fmt, ...)
+
+ :param fmt: The format string, followed by zero or more arguments
+ :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted
+ :rtype: int
+
+.. c:function:: int xo_emit_h (xo_handle_t *xop, const char *fmt, ...)
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :param fmt: The format string, followed by zero or more arguments
+ :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted
+ :rtype: int
+
+.. c:function:: int xo_emit_hv (xo_handle_t *xop, const char *fmt, va_list vap)
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :param fmt: The format string
+ :param va_list vap: A set of variadic arguments
+ :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted
+ :rtype: int
+
+.. index:: xo_emit_field
+
+Single Field Emitting Functions (xo_emit_field)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The functions in this section can also make output, but only make a
+single field at a time. These functions are intended to avoid the
+scenario where one would otherwise need to compose a format
+descriptors using `snprintf`. The individual parts of the format
+descriptor are passed in distinctly.
+
+.. c:function:: int xo_emit_field (const char *rolmod, const char *contents, const char *fmt, const char *efmt, ...)
+
+ :param rolmod: A comma-separated list of field roles and field modifiers
+ :type rolmod: const char *
+ :param contents: The "contents" portion of the field description string
+ :type contents: const char *
+ :param fmt: Content format string
+ :type fmt: const char *
+ :param efmt: Encoding format string, followed by additional arguments
+ :type efmt: const char *
+ :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted
+ :rtype: int
+
+ ::
+
+ EXAMPLE::
+ xo_emit_field("T", "Host name is ", NULL, NULL);
+ xo_emit_field("V", "host-name", NULL, NULL, host-name);
+
+.. c:function:: int xo_emit_field_h (xo_handle_t *xop, const char *rolmod, const char *contents, const char *fmt, const char *efmt, ...)
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :param rolmod: A comma-separated list of field roles and field modifiers
+ :type rolmod: const char *
+ :param contents: The "contents" portion of the field description string
+ :type contents: const char *
+ :param fmt: Content format string
+ :type fmt: const char *
+ :param efmt: Encoding format string, followed by additional arguments
+ :type efmt: const char *
+ :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted
+ :rtype: int
+
+.. c:function:: int xo_emit_field_hv (xo_handle_t *xop, const char *rolmod, const char *contents, const char *fmt, const char *efmt, va_list vap)
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :param rolmod: A comma-separated list of field roles and field modifiers
+ :type rolmod: const char *
+ :param contents: The "contents" portion of the field description string
+ :type contents: const char *
+ :param fmt: Content format string
+ :type fmt: const char *
+ :param efmt: Encoding format string
+ :type efmt: const char *
+ :param va_list vap: A set of variadic arguments
+ :returns: If XOF_COLUMNS is set, the number of columns used; otherwise the number of bytes emitted
+ :rtype: int
+
+.. index:: xo_attr
+.. _xo_attr:
+
+Attributes (xo_attr)
+~~~~~~~~~~~~~~~~~~~~
+
+The functions in this section emit an XML attribute with the given name
+and value. This only affects the XML output style.
+
+The `name` parameter give the name of the attribute to be encoded. The
+`fmt` parameter gives a printf-style format string used to format the
+value of the attribute using any remaining arguments, or the vap
+parameter passed to `xo_attr_hv`.
+
+All attributes recorded via `xo_attr` are placed on the next
+container, instance, leaf, or leaf list that is emitted.
+
+Since attributes are only emitted in XML, their use should be limited
+to meta-data and additional or redundant representations of data
+already emitted in other form.
+
+.. c:function:: int xo_attr (const char *name, const char *fmt, ...)
+
+ :param name: Attribute name
+ :type name: const char *
+ :param fmt: Attribute value, as variadic arguments
+ :type fmt: const char *
+ :returns: -1 for error, or the number of bytes in the formatted attribute value
+ :rtype: int
+
+ ::
+
+ EXAMPLE:
+ xo_attr("seconds", "%ld", (unsigned long) login_time);
+ struct tm *tmp = localtime(login_time);
+ strftime(buf, sizeof(buf), "%R", tmp);
+ xo_emit("Logged in at {:login-time}\n", buf);
+ XML:
+ <login-time seconds="1408336270">00:14</login-time>
+
+
+.. c:function:: int xo_attr_h (xo_handle_t *xop, const char *name, const char *fmt, ...)
+
+ :param xop: Handle for modify (or NULL for default handle)
+ :type xop: xo_handle_t \*
+
+ The `xo_attr_h` function follows the conventions of `xo_attr` but
+ adds an explicit libxo handle.
+
+.. c:function:: int xo_attr_hv (xo_handle_t *xop, const char *name, const char *fmt, va_list vap)
+
+ The `xo_attr_h` function follows the conventions of `xo_attr_h`
+ but replaced the variadic list with a variadic pointer.
+
+.. index:: xo_flush
+
+Flushing Output (xo_flush)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. c:function:: xo_ssize_t xo_flush (void)
+
+ :returns: -1 for error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ libxo buffers data, both for performance and consistency, but also
+ to allow for the proper function of various advanced features. At
+ various times, the caller may wish to flush any data buffered within
+ the library. The `xo_flush` call is used for this.
+
+ Calling `xo_flush` also triggers the flush function associated with
+ the handle. For the default handle, this is equivalent to
+ "fflush(stdio);".
+
+.. c:function:: xo_ssize_t xo_flush_h (xo_handle_t *xop)
+
+ :param xop: Handle for flush (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :returns: -1 for error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `xo_flush_h` function follows the conventions of `xo_flush`,
+ but adds an explicit libxo handle.
+
+.. index:: xo_finish
+.. index:: xo_finish_atexit
+.. index:: atexit
+
+Finishing Output (xo_finish)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When the program is ready to exit or close a handle, a call to
+`xo_finish` or `xo_finish_h` is required. This flushes any buffered
+data, closes open libxo constructs, and completes any pending
+operations.
+
+Calling this function is vital to the proper operation of libxo,
+especially for the non-TEXT output styles.
+
+.. c:function:: xo_ssize_t xo_finish (void)
+
+ :returns: -1 on error, or the number of bytes flushed
+ :rtype: xo_ssize_t
+
+.. c:function:: xo_ssize_t xo_finish_h (xo_handle_t *xop)
+
+ :param xop: Handle for finish (or NULL for default handle)
+ :type xop: xo_handle_t \*
+ :returns: -1 on error, or the number of bytes flushed
+ :rtype: xo_ssize_t
+
+.. c:function:: void xo_finish_atexit (void)
+
+ The `xo_finish_atexit` function is suitable for use with
+ :manpage:`atexit(3)` to ensure that `xo_finish` is called
+ on the default handle when the application exits.
+
+.. index:: UTF-8
+.. index:: xo_open_container
+.. index:: xo_close_container
+
+Emitting Hierarchy
+------------------
+
+libxo represents two types of hierarchy: containers and lists. A
+container appears once under a given parent where a list consists of
+instances that can appear multiple times. A container is used to hold
+related fields and to give the data organization and scope.
+
+.. index:: YANG
+
+.. admonition:: YANG Terminology
+
+ libxo uses terminology from YANG (:RFC:`7950`), the data modeling
+ language for NETCONF: container, list, leaf, and leaf-list.
+
+For XML and JSON, individual fields appear inside hierarchies which
+provide context and meaning to the fields. Unfortunately, these
+encoding have a basic disconnect between how lists is similar objects
+are represented.
+
+XML encodes lists as set of sequential elements::
+
+ <user>phil</user>
+ <user>pallavi</user>
+ <user>sjg</user>
+
+JSON encodes lists using a single name and square brackets::
+
+ "user": [ "phil", "pallavi", "sjg" ]
+
+This means libxo needs three distinct indications of hierarchy: one
+for containers of hierarchy appear only once for any specific parent,
+one for lists, and one for each item in a list.
+
+.. index:: Containers
+
+Containers
+~~~~~~~~~~
+
+A "*container*" is an element of a hierarchy that appears only once
+under any specific parent. The container has no value, but serves to
+contain and organize other nodes.
+
+To open a container, call xo_open_container() or
+xo_open_container_h(). The former uses the default handle and the
+latter accepts a specific handle. To close a level, use the
+xo_close_container() or xo_close_container_h() functions.
+
+Each open call must have a matching close call. If the XOF_WARN flag
+is set and the name given does not match the name of the currently open
+container, a warning will be generated.
+
+.. c:function:: xo_ssize_t xo_open_container (const char *name)
+
+ :param name: Name of the container
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `name` parameter gives the name of the container, encoded in
+ UTF-8. Since ASCII is a proper subset of UTF-8, traditional C
+ strings can be used directly.
+
+.. c:function:: xo_ssize_t xo_open_container_h (xo_handle_t *xop, const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_open_container_h` function adds a `handle` parameter.
+
+.. c:function:: xo_ssize_t xo_close_container (const char *name)
+
+ :param name: Name of the container
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+.. c:function:: xo_ssize_t xo_close_container_h (xo_handle_t *xop, const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_close_container_h` function adds a `handle` parameter.
+
+Use the :index:`XOF_WARN` flag to generate a warning if the name given
+on the close does not match the current open container.
+
+For TEXT and HTML output, containers are not rendered into output
+text, though for HTML they are used to record an XPath value when the
+:index:`XOF_XPATH` flag is set.
+
+::
+
+ EXAMPLE:
+ xo_open_container("top");
+ xo_open_container("system");
+ xo_emit("{:host-name/%s%s%s}", hostname,
+ domainname ? "." : "", domainname ?: "");
+ xo_close_container("system");
+ xo_close_container("top");
+ TEXT:
+ my-host.example.org
+ XML:
+ <top>
+ <system>
+ <host-name>my-host.example.org</host-name>
+ </system>
+ </top>
+ JSON:
+ "top" : {
+ "system" : {
+ "host-name": "my-host.example.org"
+ }
+ }
+ HTML:
+ <div class="data"
+ data-tag="host-name">my-host.example.org</div>
+
+.. index:: xo_open_instance
+.. index:: xo_close_instance
+.. index:: xo_open_list
+.. index:: xo_close_list
+
+Lists and Instances
+~~~~~~~~~~~~~~~~~~~
+
+A "*list*" is set of one or more instances that appear under the same
+parent. The instances contain details about a specific object. One
+can think of instances as objects or records. A call is needed to
+open and close the list, while a distinct call is needed to open and
+close each instance of the list.
+
+The name given to all calls must be identical, and it is strongly
+suggested that the name be singular, not plural, as a matter of
+style and usage expectations::
+
+ EXAMPLE:
+ xo_open_list("item");
+
+ for (ip = list; ip->i_title; ip++) {
+ xo_open_instance("item");
+ xo_emit("{L:Item} '{:name/%s}':\n", ip->i_title);
+ xo_close_instance("item");
+ }
+
+ xo_close_list("item");
+
+Getting the list and instance calls correct is critical to the proper
+generation of XML and JSON data.
+
+Opening Lists
++++++++++++++
+
+.. c:function:: xo_ssize_t xo_open_list (const char *name)
+
+ :param name: Name of the list
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `xo_open_list` function open a list of instances.
+
+.. c:function:: xo_ssize_t xo_open_list_h (xo_handle_t *xop, const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+Closing Lists
++++++++++++++
+
+.. c:function:: xo_ssize_t xo_close_list (const char *name)
+
+ :param name: Name of the list
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `xo_close_list` function closes a list of instances.
+
+.. c:function:: xo_ssize_t xo_close_list_h (xo_handle_t *xop, const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_close_container_h` function adds a `handle` parameter.
+
+Opening Instances
++++++++++++++++++
+
+.. c:function:: xo_ssize_t xo_open_instance (const char *name)
+
+ :param name: Name of the instance (same as the list name)
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `xo_open_instance` function open a single instance.
+
+.. c:function:: xo_ssize_t xo_open_instance_h (xo_handle_t *xop, const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_open_instance_h` function adds a `handle` parameter.
+
+Closing Instances
++++++++++++++++++
+
+.. c:function:: xo_ssize_t xo_close_instance (const char *name)
+
+ :param name: Name of the instance
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `xo_close_instance` function closes an open instance.
+
+.. c:function:: xo_ssize_t xo_close_instance_h (xo_handle_t *xop, const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_close_instance_h` function adds a `handle` parameter.
+
+ ::
+
+ EXAMPLE:
+ xo_open_list("user");
+ for (i = 0; i < num_users; i++) {
+ xo_open_instance("user");
+ xo_emit("{k:name}:{:uid/%u}:{:gid/%u}:{:home}\n",
+ pw[i].pw_name, pw[i].pw_uid,
+ pw[i].pw_gid, pw[i].pw_dir);
+ xo_close_instance("user");
+ }
+ xo_close_list("user");
+ TEXT:
+ phil:1001:1001:/home/phil
+ pallavi:1002:1002:/home/pallavi
+ XML:
+ <user>
+ <name>phil</name>
+ <uid>1001</uid>
+ <gid>1001</gid>
+ <home>/home/phil</home>
+ </user>
+ <user>
+ <name>pallavi</name>
+ <uid>1002</uid>
+ <gid>1002</gid>
+ <home>/home/pallavi</home>
+ </user>
+ JSON:
+ user: [
+ {
+ "name": "phil",
+ "uid": 1001,
+ "gid": 1001,
+ "home": "/home/phil",
+ },
+ {
+ "name": "pallavi",
+ "uid": 1002,
+ "gid": 1002,
+ "home": "/home/pallavi",
+ }
+ ]
+
+Markers
+~~~~~~~
+
+Markers are used to protect and restore the state of open hierarchy
+constructs (containers, lists, or instances). While a marker is open,
+no other open constructs can be closed. When a marker is closed, all
+constructs open since the marker was opened will be closed.
+
+Markers use names which are not user-visible, allowing the caller to
+choose appropriate internal names.
+
+In this example, the code whiffles through a list of fish, calling a
+function to emit details about each fish. The marker "fish-guts" is
+used to ensure that any constructs opened by the function are closed
+properly::
+
+ EXAMPLE:
+ for (i = 0; fish[i]; i++) {
+ xo_open_instance("fish");
+ xo_open_marker("fish-guts");
+ dump_fish_details(i);
+ xo_close_marker("fish-guts");
+ }
+
+.. c:function:: xo_ssize_t xo_open_marker(const char *name)
+
+ :param name: Name of the instance
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `xo_open_marker` function records the current state of open tags
+ in order for `xo_close_marker` to close them at some later point.
+
+.. c:function:: xo_ssize_t xo_open_marker_h(const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_open_marker_h` function adds a `handle` parameter.
+
+.. c:function:: xo_ssize_t xo_close_marker(const char *name)
+
+ :param name: Name of the instance
+ :type name: const char *
+ :returns: -1 on error, or the number of bytes generated
+ :rtype: xo_ssize_t
+
+ The `xo_close_marker` function closes any open containers, lists, or
+ instances as needed to return to the state recorded when
+ `xo_open_marker` was called with the matching name.
+
+.. c:function:: xo_ssize_t xo_close_marker(const char *name)
+
+ :param xop: Handle to use (or NULL for default handle)
+ :type xop: xo_handle_t *
+
+ The `xo_close_marker_h` function adds a `handle` parameter.
+
+DTRT Mode
+~~~~~~~~~
+
+Some users may find tracking the names of open containers, lists, and
+instances inconvenient. libxo offers a "Do The Right Thing" mode, where
+libxo will track the names of open containers, lists, and instances so
+the close function can be called without a name. To enable DTRT mode,
+turn on the XOF_DTRT flag prior to making any other libxo output::
+
+ xo_set_flags(NULL, XOF_DTRT);
+
+.. index:: XOF_DTRT
+
+Each open and close function has a version with the suffix "_d", which
+will close the open container, list, or instance::
+
+ xo_open_container_d("top");
+ ...
+ xo_close_container_d();
+
+This also works for lists and instances::
+
+ xo_open_list_d("item");
+ for (...) {
+ xo_open_instance_d("item");
+ xo_emit(...);
+ xo_close_instance_d();
+ }
+ xo_close_list_d();
+
+.. index:: XOF_WARN
+
+Note that the XOF_WARN flag will also cause libxo to track open
+containers, lists, and instances. A warning is generated when the
+name given to the close function and the name recorded do not match.
+
+Support Functions
+-----------------
+
+.. index:: xo_parse_args
+.. _xo_parse_args:
+
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-src-all
mailing list