xo_emit - Man Page

Text, XML, JSON, and HTML Output Emission Library (libxo, -lxo)

#include <libxo/xo.h>

xo_ssize_t
xo_emit(const char *fmt, ...);

xo_ssize_t
xo_emit_h(xo_handle_t *xop, const char *fmt, ...);

xo_ssize_t
xo_emit_hv(xo_handle_t *xop, const char *fmt, va_list vap);

xo_ssize_t
xo_emitr(const char *fmt, ...);

The xo_emit() function emits formatted output using the description in a format string along with a set of zero or more arguments, in a style similar to printf(3) but using a more complex format description string, as described in xo_format(5).

xo_emit() uses the default output handle, as described in libxo(3), where xo_emit_h() uses an explicit handle. xo_emit_hv() accepts a va_list for additional flexibility.

In this example, a set of four values is emitted using the following source code:

    xo_emit(" {:lines/%7ju} {:words/%7ju} "
            "{:characters/%7ju} {d:filename/%s}\n",
            linect, wordct, charct, file);

Output can then be generated in various style, using the "--libxo" option:

    % wc /etc/motd
          25     165    1140 /etc/motd
    % wc --libxo xml,pretty,warn /etc/motd
    <wc>
      <file>
        <lines>25</lines>
        <words>165</words>
        <characters>1140</characters>
        <filename>/etc/motd</filename>
      </file>
    </wc>
    % wc --libxo json,pretty,warn /etc/motd
    {
      "wc": {
        "file": [
          {
            "lines": 25,
            "words": 165,
            "characters": 1140,
            "filename": "/etc/motd"
          }
        ]
      }
    }
    % wc --libxo html,pretty,warn /etc/motd
    <div class="line">
      <div class="text"> </div>
      <div class="data" data-tag="lines">     25</div>
      <div class="text"> </div>
      <div class="data" data-tag="words">    165</div>
      <div class="text"> </div>
      <div class="data" data-tag="characters">   1140</div>
      <div class="text"> </div>
      <div class="data" data-tag="filename">/etc/motd</div>
    </div>

The libxo library can cache the compiled internal version of the format for circumstances when the format will be used repeatedly, such as a loop. This cannot be used when the format string is in a dynamic buffer, since the cache retains a reference to the static format string, typically a static compile-time constant value.

Typically static strings are placed in an executable's ".text" segment, so libxo knows that the formatting information in such static strings can be cached (retained), but shared libraries will have their own ".text" segment, so without the XOEF_RETAIN flag, libxo cannot presume to retain formatting information. If a caller in shared library code want their formats retained, they need to pass the XOEF_RETAIN flag.

The xo_emitr() function is a convenience function that passes the XOEF_RETAIN flag to xo_emit_hvf(), and can be used in shared libraries when the format string is static.

xo_emit returns a negative value on error. If the XOF_COLUMNS flag has been turned on for the specific handle using xo_set_flags(3), then the number of display columns consumed by the output will be returned.

xo_open_container(3), xo_open_list(3), xo_emit_f(3), xo_emit_field 3, xo_format(5), libxo(3)

The libxo library first appeared in FreeBSD 11.0.

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

FreeBSD uses libxo version 1.7.5. Complete documentation can be found on github:

https://juniper.github.io/libxo/1.7.5/html/index.html

libxo lives on github as:

https://github.com/Juniper/libxo

The latest release of libxo is available at:

https://github.com/Juniper/libxo/releases

The libxo library was added in FreeBSD 11.0.

Phil Shafer

libxo(3), libxo(7), xo(1), xo_attr(3), xo_create(3), xo_emit_err(3), xo_err(3), xo_error(3), xo_finish(3), xo_flush(3), xo_format(5), xohtml(1), xolint(1), xo_message(3), xo_no_setlocale(3), xo_open_container(3), xo_open_list(3), xo_open_marker(3), xo_parse_args(3), xo_set_allocator(3), xo_set_flags(3), xo_set_info(3), xo_set_options(3), xo_set_style(3), xo_set_version(3), xo_set_writer(3).