Manual Pages  — LIBXO

xo_open_container xo_close_container – open (and close) container constructs

LIBRARY SYNOPSIS DESCRIPTION EMITTING HIERARCHY DTRT MODE SEE ALSO HISTORY AUTHORS

libxo

#include <libxo/xo.h>

xo_ssize_t
xo_open_container(const char *name);

xo_ssize_t
xo_open_container_h(xo_handle_t *handle, const char *name);

xo_ssize_t
xo_open_container_hd(xo_handle_t *handle, const char *name);

xo_ssize_t
xo_open_container_d(const char *name);

xo_ssize_t
xo_close_container(const char *name);

xo_ssize_t
xo_close_container_h(xo_handle_t *handle, const char *name);

xo_ssize_t
xo_close_container_hd(xo_handle_t *handle);

xo_ssize_t
xo_close_container_d(void);

libxo represents two types of hierarchy: "containers" and "lists". A container appears once under a given parent where a list contains instances that can appear multiple times. A container is used to hold related fields and to give the data organization and scope. The container has no value, but serves to contain 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 should 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.

    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");

    Sample Output:
      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>

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);

Each open and close function has a version with the suffix "_d", which will close the open container, list, or instance:

    xo_open_container("top");
    ...
    xo_close_container_d();

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.

The libxo library first appeared in FreeBSD 11.0 .

libxo was written by Phil Shafer <Mt phil@freebsd.org>.