2.2.1 

Setting up the build

[If you downloaded a distfile, you can skip this step.]

Run the "setup.sh" script to set up the build. This script runs the "autoreconf" command to generate the "configure" script and other generated files.

    sh bin/setup.sh
            

Note: We're are currently using autoreconf version 2.69.

2.2.2 

Running the "configure" Script

Configure (and autoconf in general) provides a means of building software in diverse environments. Our configure script supports a set of options that can be used to adjust to your operating environment. Use "configure --help" to view these options.

We use the "build" directory to keep object files and generated files away from the source tree.

To run the configure script, change into the "build" directory, and run the "configure" script. Add any required options to the "../configure" command line.

    cd build
    ../configure
            

Expect to see the "configure" script generate the following error:

    /usr/bin/rm: cannot remove `libtoolT': No such file or directory
            

This error is harmless and can be safely ignored.

By default, libxo installs architecture-independent files, including extension library files, in the /usr/local directories. To specify an installation prefix other than /usr/local for all installation files, include the --prefix=prefix option and specify an alternate location. To install just the extension library files in a different, user-defined location, include the --with-extensions-dir=dir option and specify the location where the extension libraries will live.

    cd build
    ../configure [OPTION]... [VAR=VALUE]...
            

Section Contents:

• Section 2.2.2.1
• Section 2.2.2.2

    make
            

    make test
            

2.2.3 

Installing libxo

Once the software is built, you'll need to install libxo using the "make install" command. If you are the root user, or the owner of the installation directory, simply issue the command:

    make install
            

If you are not the "root" user and are using the "sudo" package, use:

    sudo make install
            

Verify the installation by viewing the output of "xo --version":

    % xo --version
    libxo version 0.3.5-git-develop
    xo version 0.3.5-git-develop
            

3.1.1 

Text Output

Most traditional programs generate text output on standard output, with contents like:

    36      ./src
    40      ./bin
    90      .
            

In this example (taken from du source code), the code to generate this data might look like:

    printf("%d\t%s\n", num_blocks, path);
            

Simple, direct, obvious. But it's only making text output. Imagine using a single code path to make TEXT, XML, JSON or HTML, deciding at run time which to generate.

libxo expands on the idea of printf format strings to make a single format containing instructions for creating multiple output styles:

    xo_emit("{:blocks/%d}\t{:path/%s}\n", num_blocks, path);
            

This line will generate the same text output as the earlier printf call, but also has enough information to generate XML, JSON, and HTML.

The following sections introduce the other formats.

3.1.2 

XML Output

XML output consists of a hierarchical set of elements, each encoded with a start tag and an end tag. The element should be named for data value that it is encoding:

    <item>
      <blocks>36</blocks>
      <path>./src</path>
    </item>
    <item>
      <blocks>40</blocks>
      <path>./bin</path>
    </item>
    <item>
      <blocks>90</blocks>
      <path>.</path>
    </item>
            

XML is a W3C standard for encoding data. See w3c.org/TR/xml for additional information.

3.1.3 

JSON Output

JSON output consists of a hierarchical set of objects and lists, each encoded with a quoted name, a colon, and a value. If the value is a string, it must be quoted, but numbers are not quoted. Objects are encoded using braces; lists are encoded using square brackets. Data inside objects and lists is separated using commas:

    items: [
        { "blocks": 36, "path" : "./src" },
        { "blocks": 40, "path" : "./bin" },
        { "blocks": 90, "path" : "./" }
    ]
            

3.1.4 

HTML Output

HTML output is designed to allow the output to be rendered in a web browser with minimal effort. Each piece of output data is rendered inside a <div> element, with a class name related to the role of the data. By using a small set of class attribute values, a CSS stylesheet can render the HTML into rich text that mirrors the traditional text content.

Additional attributes can be enabled to provide more details about the data, including data type, description, and an XPath location.

    <div class="line">
      <div class="data" data-tag="blocks">36</div>
      <div class="padding">      </div>
      <div class="data" data-tag="path">./src</div>
    </div>
    <div class="line">
      <div class="data" data-tag="blocks">40</div>
      <div class="padding">      </div>
      <div class="data" data-tag="path">./bin</div>
    </div>
    <div class="line">
      <div class="data" data-tag="blocks">90</div>
      <div class="padding">      </div>
      <div class="data" data-tag="path">./</div>
    </div>
            

3.2.1 

Field Roles

Field roles are optional, and indicate the role and formatting of the content. The roles are listed below; only one role is permitted:

    EXAMPLE:
        xo_emit("{L:Free}{D::}{P:   }{:free/%u} {U:Blocks}\n",
                free_blocks);
            

When a role is not provided, the "value" role is used as the default.

Roles and modifiers can also use more verbose names, when preceded by a comma:

    EXAMPLE:
        xo_emit("{,label:Free}{,decoration::}{,padding:   }"
                "{,value:free/%u} {,units:Blocks}\n",
                free_blocks);
            

Section Contents:

• Section 3.2.1.1
• Section 3.2.1.2
• Section 3.2.1.3
• Section 3.2.1.4
• Section 3.2.1.5
• Section 3.2.1.6
• Section 3.2.1.7
• Section 3.2.1.8
• Section 3.2.1.9
• Section 3.2.1.10

    xo_emit("{C:bold}{:value}{C:no-bold}\n", value);
            

    xo_emit("{C:bold}{C:inverse}both{C:no-bold}only inverse\n");
            

    xo_emit("{C:both,underline}{:value}{C:}\n", value);
            

    xo_emit("{C:bold,inverse}Ugly{C:no-bold,no-inverse}\n");
            

   xo_emit("{C:/%s%s}{:value}{C:}", need_bold ? "bold" : "",
           need_underline ? "underline" : "", value);
            

    xo_emit("{C:/fg-%s,bg-%s}{Lwc:Cost}{:cost/%u}{C:reset}\n",
            fg_color, bg_color, cost);
            

    xo_emit("{D:((}{:name}{D:))}\n", name);
            

   xo_emit("{G:}Invalid token\n");
            

   xo_emit("{G:libc}Service unavailable in restricted mode\n");
            

    xo_emit("{Lwc:Cost}{:cost/%u}\n", cost);
            

    xo_emit("{:cost/%u} {N:per year}\n", cost);
            

    xo_emit("{P:        }{Lwc:Cost}{:cost/%u}\n", cost);
    xo_emit("{P:/%30s}{Lwc:Cost}{:cost/%u}\n", "", cost);
            

    xo_emit("{T:Interface Statistics}\n");
    xo_emit("{T:/%20.20s}{T:/%6.6s}\n", "Item Name", "Cost");
            

    xo_emit("{T:Name/%20s}{T:Count/%6s}\n");
            

    xo_emit("{Lwc:Distance}{:distance/%u}{Uw:miles}\n", miles);
            

    <distance units="miles">50</distance>
            

    <div class="data" data-tag="distance" data-units="miles"
         data-xpath="/top/data/distance">50</div>
            

    xo_emit("{:length/%02u}x{:width/%02u}x{:height/%02u}\n",
            length, width, height);
    xo_emit("{:author} wrote \"{:poem}\" in {:year/%4d}\n,
            author, poem, year);
            

    xo_emit("({[:10}{:min/%d}/{:max/%d}{]:})\n", min, max);
            

    xo_emit("({[:/%d}{:min/%d}/{:max/%d}{]:})\n", width, min, max);
            

3.2.2 

Field Modifiers

Field modifiers are flags which modify the way content emitted for particular output styles:

Roles and modifiers can also use more verbose names, when preceded by a comma. For example, the modifier string "Lwc" (or "L,white,colon") means the field has a label role (text that describes the next field) and should be followed by a colon ('c') and a space ('w'). The modifier string "Vkq" (or ":key,quote") means the field has a value role (the default role), that it is a key for the current instance, and that the value should be quoted when encoded for JSON.

Section Contents:

• Section 3.2.2.1
• Section 3.2.2.2
• Section 3.2.2.3
• Section 3.2.2.4
• Section 3.2.2.5
• Section 3.2.2.6
• Section 3.2.2.7
• Section 3.2.2.8
• Section 3.2.2.9
• Section 3.2.2.10
• Section 3.2.2.11
• Section 3.2.2.12
• Section 3.2.2.13

    EXAMPLE:
      xo_emit("{La:} {a:}\n", "Label text", "label", "value");
    TEXT:
      Label text value
    JSON:
      "label": "value"
    XML:
      <label>value</label>
            

    EXAMPLE:
      xo_emit("{Lc:Name}{:name}\n", "phil");
    TEXT:
      Name:phil
            

    EXAMPLE:
      xo_emit("{Lcw:Name}{d:name} {:id/%d}\n", "phil", 1);
    TEXT:
      Name: phil 1
    XML:
      <id>1</id>
            

    EXAMPLE:
      xo_emit("{Lcw:Name}{:name} {e:id/%d}\n", "phil", 1);
    TEXT:
      Name: phil
    XML:
      <name>phil</name><id>1</id>
            

    xo_emit("{Lgwc:State}{g:state}\n", "full");
            

    EXAMPLE:
        xo_emit("{h:input/%u}, {h,hn-space:output/%u}, "
            "{h,hn-decimal:errors/%u}, {h,hn-1000:capacity/%u}, "
            "{h,hn-decimal:remaining/%u}\n",
            input, output, errors, capacity, remaining);
    TEXT:
        21, 57 K, 96M, 44M, 1.2G
            

    <div class="data" data-tag="errors"
         data-number="100663296">96M</div>
            

    EXAMPLE:
        xo_open_list("user");
        for (i = 0; i < num_users; i++) {
            xo_open_instance("user");
            xo_emit("User {k:name} has {:count} tickets\n",
               user[i].u_name, user[i].u_tickets);
            xo_close_instance("user");
        }
        xo_close_list("user");
            

    EXAMPLE:
        for (i = 0; i < num_users; i++) {
            xo_emit("Member {l:user}\n", user[i].u_name);
        }
    XML:
        <user>phil</user>
        <user>pallavi</user>
    JSON:
        "user": [ "phil", "pallavi" ]
            

    EXAMPLE:
      const char *bool = is_true ? "true" : "false";
      xo_emit("{n:fancy/%s}", bool);
    JSON:
      "fancy": true
            

    xo_emit("{:bytes} {Ngp:byte,bytes}\n", bytes);
            

    EXAMPLE:
      xo_emit("{q:time/%d}", 2014);
    JSON:
      "year": "2014"
            

    d i o u x X D O U e E f F g G a A c C p
            

    EXAMPLE:
      xo_emit("{t:description}", "   some  input   ");
    JSON:
      "description": "some input"
            

    EXAMPLE:
      xo_emit("{Lw:Name}{:name}\n", "phil");
    TEXT:
      Name phil
            

3.2.3 

Field Formatting

The field format is similar to the format string for printf(3). Its use varies based on the role of the field, but generally is used to format the field's contents.

If the format string is not provided for a value field, it defaults to "%s".

Note a field definition can contain zero or more printf-style 'directives', which are sequences that start with a '%' and end with one of following characters: "diouxXDOUeEfFgGaAcCsSp". Each directive is matched by one of more arguments to the xo_emit function.

The format string has the form:

  '%' format-modifier * format-character
            

The format- modifier can be:

• a '#' character, indicating the output value should be prefixed with '0x', typically to indicate a base 16 (hex) value.
• a minus sign ('‑'), indicating the output value should be padded on the right instead of the left.
• a leading zero ('0') indicating the output value should be padded on the left with zeroes instead of spaces (' ').
• one or more digits ('0' - '9') indicating the minimum width of the argument. If the width in columns of the output value is less than the minimum width, the value will be padded to reach the minimum.
• a period followed by one or more digits indicating the maximum number of bytes which will be examined for a string argument, or the maximum width for a non-string argument. When handling ASCII strings this functions as the field width but for multi-byte characters, a single character may be composed of multiple bytes. xo_emit will never dereference memory beyond the given number of bytes.
• a second period followed by one or more digits indicating the maximum width for a string argument. This modifier cannot be given for non-string arguments.
• one or more 'h' characters, indicating shorter input data.
• one or more 'l' characters, indicating longer input data.
• a 'z' character, indicating a 'size_t' argument.
• a 't' character, indicating a 'ptrdiff_t' argument.
• a ' ' character, indicating a space should be emitted before positive numbers.
• a '+' character, indicating sign should emitted before any number.

Note that 'q', 'D', 'O', and 'U' are considered deprecated and will be removed eventually.

The format character is described in the following table:

The 'h' and 'l' modifiers affect the size and treatment of the argument:

3.2.4 

UTF-8 and Locale Strings

For strings, the 'h' and 'l' modifiers affect the interpretation of the bytes pointed to argument. The default '%s' string is a 'char *' pointer to a string encoded as UTF-8. Since UTF-8 is compatible with ASCII data, a normal 7-bit ASCII string can be used. '%ls' expects a 'wchar_t *' pointer to a wide-character string, encoded as a 32-bit Unicode values. '%hs' expects a 'char *' pointer to a multi-byte string encoded with the current locale, as given by the LC_CTYPE, LANG, or LC_ALL environment varibles. The first of this list of variables is used and if none of the variables are set, the locale defaults to "UTF‑8".

libxo will convert these arguments as needed to either UTF-8 (for XML, JSON, and HTML styles) or locale-based strings for display in text style.

   xo_emit("All strings are utf-8 content {:tag/%ls}",
           L"except for wide strings");
            

"%S" is equivalent to "%ls".

For example, a function is passed a locale-base name, a hat size, and a time value. The hat size is formatted in a UTF-8 (ASCII) string, and the time value is formatted into a wchar_t string.

    void print_order (const char *name, int size,
                      struct tm *timep) {
        char buf[32];
        const char *size_val = "unknown";

        if (size > 0)
            snprintf(buf, sizeof(buf), "%d", size);
            size_val = buf;
        }

        wchar_t when[32];
        wcsftime(when, sizeof(when), L"%d%b%y", timep);

        xo_emit("The hat for {:name/%hs} is {:size/%s}.\n",
                name, size_val);
        xo_emit("It was ordered on {:order-time/%ls}.\n",
                when);
    }
            

It is important to note that xo_emit will perform the conversion required to make appropriate output. Text style output uses the current locale (as described above), while XML, JSON, and HTML use UTF-8.

UTF-8 and locale-encoded strings can use multiple bytes to encode one column of data. The traditional "precision'" (aka "max‑width") value for "%s" printf formatting becomes overloaded since it specifies both the number of bytes that can be safely referenced and the maximum number of columns to emit. xo_emit uses the precision as the former, and adds a third value for specifying the maximum number of columns.

In this example, the name field is printed with a minimum of 3 columns and a maximum of 6. Up to ten bytes of data at the location given by 'name' are in used in filling those columns.

    xo_emit("{:name/%3.10.6s}", name);
            

3.2.5 

Characters Outside of Field Definitions

Characters in the format string that are not part of a field definition are copied to the output for the TEXT style, and are ignored for the JSON and XML styles. For HTML, these characters are placed in a <div> with class "text".

  EXAMPLE:
      xo_emit("The hat is {:size/%s}.\n", size_val);
  TEXT:
      The hat is extra small.
  XML:
      <size>extra small</size>
  JSON:
      "size": "extra small"
  HTML:
      <div class="text">The hat is </div>
      <div class="data" data-tag="size">extra small</div>
      <div class="text">.</div>
            

3.2.6 

"%m" Is Supported

libxo supports the '%m' directive, which formats the error message associated with the current value of "errno". It is the equivalent of "%s" with the argument strerror(errno).

    xo_emit("{:filename} cannot be opened: {:error/%m}", filename);
    xo_emit("{:filename} cannot be opened: {:error/%s}",
            filename, strerror(errno));
            

3.2.7 

"%n" Is Not Supported

libxo does not support the '%n' directive. It's a bad idea and we just don't do it.

3.2.8 

The Encoding Format (eformat)

The "eformat" string is the format string used when encoding the field for JSON and XML. If not provided, it defaults to the primary format with any minimum width removed. If the primary is not given, both default to "%s".

3.2.9 

Content Strings

For padding and labels, the content string is considered the content, unless a format is given.

3.2.10 

Argument Validation

Many compilers and tool chains support validation of printf-like arguments. When the format string fails to match the argument list, a warning is generated. This is a valuable feature and while the formatting strings for libxo differ considerably from printf, many of these checks can still provide build-time protection against bugs.

libxo provide variants of functions that provide this ability, if the "‑‑enable‑printflike" option is passed to the "configure" script. These functions use the "_p" suffix, like "xo_emit_p()", xo_emit_hp()", etc.

The following are features of libxo formatting strings that are incompatible with printf-like testing:

• implicit formats, where "{:tag}" has an implicit "%s";
• the "max" parameter for strings, where "{:tag/%4.10.6s}" means up to ten bytes of data can be inspected to fill a minimum of 4 columns and a maximum of 6;
• percent signs in strings, where "{:filled}%" makes a single, trailing percent sign;
• the "l" and "h" modifiers for strings, where "{:tag/%hs}" means locale-based string and "{:tag/%ls}" means a wide character string;
• distinct encoding formats, where "{:tag/#%s/%s}" means the display styles (text and HTML) will use "#%s" where other styles use "%s";

If none of these features are in use by your code, then using the "_p" variants might be wise.

3.2.11 

Retaining Parsed Format Information

libxo can retain the parsed internal information related to the given format string, allowing subsequent xo_emit calls, the retained information is used, avoiding repetitive parsing of the format string.

    SYNTAX:
      int xo_emit_f(xo_emit_flags_t flags, const char fmt, ...);
    EXAMPLE:
      xo_emit_f(XOEF_RETAIN, "{:some/%02d}{:thing/%-6s}{:fancy}\n",
                     some, thing, fancy);
            

To retain parsed format information, use the XOEF_RETAIN flag to the xo_emit_f() function. A complete set of xo_emit_f functions exist to match all the xo_emit function signatures (with handles, varadic argument, and printf-like flags):

The format string must be immutable across multiple calls to xo_emit_f(), since the library retains the string. Typically this is done by using static constant strings, such as string literals. If the string is not immutable, the XOEF_RETAIN flag must not be used.

The functions xo_retain_clear() and xo_retain_clear_all() release internal information on either a single format string or all format strings, respectively. Neither is required, but the library will retain this information until it is cleared or the process exits.

    const char *fmt = "{:name}  {:count/%d}\n";
    for (i = 0; i < 1000; i++) {
        xo_open_instance("item");
        xo_emit_f(XOEF_RETAIN, fmt, name[i], count[i]);
    }
    xo_retain_clear(fmt);
            

The retained information is kept as thread-specific data.

3.2.12 

Example

In this example, the value for the number of items in stock is emitted:

        xo_emit("{P:   }{Lwc:In stock}{:in-stock/%u}\n",
                instock);
            

This call will generate the following output:

  TEXT: 
       In stock: 144
  XML:
      <in-stock>144</in-stock>
  JSON:
      "in-stock": 144,
  HTML:
      <div class="line">
        <div class="padding">   </div>
        <div class="label">In stock</div>
        <div class="decoration">:</div>
        <div class="padding"> </div>
        <div class="data" data-tag="in-stock">144</div>
      </div>
            

Clearly HTML wins the verbosity award, and this output does not include XOF_XPATH or XOF_INFO data, which would expand the penultimate line to:

       <div class="data" data-tag="in-stock"
          data-xpath="/top/data/item/in-stock"
          data-type="number"
          data-help="Number of items in stock">144</div>
            

3.3.1 

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 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.

    int xo_open_container_h (xo_handle_t *xop, const char *name);
    int xo_open_container (const char *name);
            

To close a level, use the xo_close_container() or xo_close_container_h() functions:

    int xo_close_container_h (xo_handle_t *xop, const char *name);
    int xo_close_container (const char *name);
            

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.

    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>
            

3.3.2 

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:

    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.

3.3.3 

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

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

This also works for lists and instances:

    xo_open_list("item");
    for (...) {
        xo_open_instance("item");
        xo_emit(...);
        xo_close_instance_d();
    }
    xo_close_list_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.

3.3.4 

Markers

Markers are used to protect and restore the state of open constructs. 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.

    for (i = 0; fish[i]; i++) {
        xo_open_instance("fish");
        xo_open_marker("fish-guts");
        dump_fish_details(i);
        xo_close_marker("fish-guts");
    }
            

5.1.1 

xo_create

A handle can be allocated using the xo_create() function:

    xo_handle_t *xo_create (unsigned style, unsigned flags);

  Example:
    xo_handle_t *xop = xo_create(XO_STYLE_JSON, XOF_WARN);
    ....
    xo_emit_h(xop, "testing\n");
            

See also Section 5.1.5.1 and Section 5.1.6.1.

5.1.2 

xo_create_to_file

By default, libxo writes output to standard output. A convenience function is provided for situations when output should be written to a different file:

    xo_handle_t *xo_create_to_file (FILE *fp, unsigned style,
                                    unsigned flags);
            

Use the XOF_CLOSE_FP flag to trigger a call to fclose() for the FILE pointer when the handle is destroyed.

5.1.3 

xo_set_writer

The xo_set_writer function allows custom 'write' functions which can tailor how libxo writes data. An opaque argument is recorded and passed back to the write function, allowing the function to acquire context information. The 'close' function can release this opaque data and any other resources as needed. The flush function can flush buffered data associated with the opaque object.

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

5.1.4 

xo_set_style

To set the style, use the xo_set_style() function:

    void xo_set_style(xo_handle_t *xop, unsigned style);
            

To use the default handle, pass a NULL handle:

    xo_set_style(NULL, XO_STYLE_XML);
            

5.1.5 

xo_get_style

To find the current style, use the xo_get_style() function:

    xo_style_t xo_get_style(xo_handle_t *xop);
            

To use the default handle, pass a NULL handle:

    style = xo_get_style(NULL);
            

Section Contents:

• Section 5.1.5.1
• Section 5.1.5.2

    int xo_set_style_name (xo_handle_t *xop, const char *style);
            

    EXAMPLE:
        xo_set_style_name(NULL, "html");
            

5.1.6 

xo_set_flags

To set the flags, use the xo_set_flags() function:

    void xo_set_flags(xo_handle_t *xop, unsigned flags);
            

To use the default handle, pass a NULL handle:

    xo_set_style(NULL, XO_STYLE_XML);
            

Section Contents:

• Section 5.1.6.1
• Section 5.1.6.2
• Section 5.1.6.3

    xo_emit("{k:name}", item);

  XML:
      <name key="key">truck</name>
            

    void xo_clear_flags (xo_handle_t *xop, xo_xof_flags_t flags);
            

    int xo_set_options (xo_handle_t *xop, const char *input);
            

5.1.7 

xo_destroy

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.

    void xo_destroy(xo_handle_t *xop);
            

5.2.1 

Single Field Emitting Functions (xo_emit_field)

The following functions can also make output, but only make a single field at a time:

    int xo_emit_field_hv (xo_handle_t *xop, const char *rolmod,
                  const char *contents, const char *fmt, 
                  const char *efmt, va_list vap);

    int xo_emit_field_h (xo_handle_t *xop, const char *rolmod, 
                 const char *contents, const char *fmt,
                 const char *efmt, ...);

    int xo_emit_field (const char *rolmod, const char *contents,
                 const char *fmt, const char *efmt, ...);
            

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.

    xo_emit("T", "Host name is ", NULL, NULL);
    xo_emit("V", "host-name", NULL, NULL, host-name);
            

5.2.2 

Attributes (xo_attr)

The xo_attr() function emits attributes for the XML output style.

    int xo_attr (const char *name, const char *fmt, ...);
    int xo_attr_h (xo_handle_t *xop, const char *name, 
                   const char *fmt, ...);
    int xo_attr_hv (xo_handle_t *xop, const char *name, 
                   const char *fmt, va_list vap);
            

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().

    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>
            

xo_attr is 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.

5.2.3 

Flushing Output (xo_flush)

libxo buffers data, both for performance and consistency, but also to allow some advanced features to work properly. At various times, the caller may wish to flush any data buffered within the library. The xo_flush() call is used for this:

    void xo_flush (void);
    void xo_flush_h (xo_handle_t *xop);
            

Calling xo_flush also triggers the flush function associated with the handle. For the default handle, this is equivalent to "fflush(stdio);".

5.2.4 

Finishing Output (xo_finish)

When the program is ready to exit or close a handle, a call to xo_finish() is required. This flushes any buffered data, closes open libxo constructs, and completes any pending operations.

    int xo_finish (void);
    int xo_finish_h (xo_handle_t *xop);
    void xo_finish_atexit (void);
            

Calling this function is vital to the proper operation of libxo, especially for the non-TEXT output styles.

xo_finish_atexit is suitable for use with atexit(3).

5.3.1 

Lists and Instances

Lists are sequences of instances of homogeneous data objects. Two distinct levels of calls are needed to represent them in our output styles. Calls must be made to open and close a list, and for each instance of data in that list, calls must be make to open and close that instance.

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("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",
            }
        ]
            

5.4.1 

Parsing Command-line Arguments (xo_parse_args)

The xo_parse_args() function is used to process a program's arguments. libxo-specific options are processed and removed from the argument list so the calling application does not need to process them. If successful, a new value for argc is returned. On failure, a message it emitted and -1 is returned.

    argc = xo_parse_args(argc, argv);
    if (argc < 0)
        exit(EXIT_FAILURE);
            

Following the call to xo_parse_args, the application can process the remaining arguments in a normal manner. See Section 4 for a description of valid arguments.

5.4.2 

xo_set_program

The xo_set_program function sets name of the program as reported by functions like xo_failure, xo_warn, xo_err, etc. The program name is initialized by xo_parse_args, but subsequent calls to xo_set_program can override this value.

    xo_set_program(argv[0]);
            

Note that the value is not copied, so the memory passed to xo_set_program (and xo_parse_args) must be maintained by the caller.

5.4.3 

xo_set_version

The xo_set_version function records a version number to be emitted as part of the data for encoding styles (XML and JSON). This version number is suitable for tracking changes in the content, allowing a user of the data to discern which version of the data model is in use.

     void xo_set_version (const char *version);
     void xo_set_version_h (xo_handle_t *xop, const char *version);
            

5.4.4 

Field Information (xo_info_t)

HTML data can include additional information in attributes that begin with "data‑". To enable this, three things must occur:

First the application must build an array of xo_info_t structures, one per tag. The array must be sorted by name, since libxo uses a binary search to find the entry that matches names from format instructions.

Second, the application must inform libxo about this information using the xo_set_info() call:

    typedef struct xo_info_s {
        const char *xi_name;    /* Name of the element */
        const char *xi_type;    /* Type of field */
        const char *xi_help;    /* Description of field */
    } xo_info_t;

    void xo_set_info (xo_handle_t *xop, xo_info_t *infop, int count);
            

Like other libxo calls, passing NULL for the handle tells libxo to use the default handle.

If the count is -1, libxo will count the elements of infop, but there must be an empty element at the end. More typically, the number is known to the application:

    xo_info_t info[] = {
        { "in-stock", "number", "Number of items in stock" },
        { "name", "string", "Name of the item" },
        { "on-order", "number", "Number of items on order" },
        { "sku", "string", "Stock Keeping Unit" },
        { "sold", "number", "Number of items sold" },
    };
    int info_count = (sizeof(info) / sizeof(info[0]));
    ...
    xo_set_info(NULL, info, info_count);
            

Third, the emission of info must be triggered with the XOF_INFO flag using either the xo_set_flags() function or the "‑‑libxo=info" command line argument.

The type and help values, if present, are emitted as the "data‑type" and "data‑help" attributes:

  <div class="data" data-tag="sku" data-type="string" 
       data-help="Stock Keeping Unit">GRO-000-533</div>
            

5.4.5 

Memory Allocation

The xo_set_allocator function allows libxo to be used in environments where the standard realloc() and free() functions are not available.

    void xo_set_allocator (xo_realloc_func_t realloc_func,
                           xo_free_func_t free_func);
            

realloc_func should expect the same arguments as realloc(3) and return a pointer to memory following the same convention. free_func will receive the same argument as free(3) and should release it, as appropriate for the environment.

By default, the standard realloc() and free() functions are used.

5.4.6 

LIBXO_OPTIONS

The environment variable "LIBXO_OPTIONS" can be set to a subset of libxo options, including:

• color
• flush
• flush-line
• no-color
• no-humanize
• no-locale
• no-retain
• pretty
• retain
• underscores
• warn

For example, warnings can be enabled by:

    % env LIBXO_OPTIONS=warn my-app
            

Since environment variables are inherited, child processes will have the same options, which may be undesirable, making the use of the "‑‑libxo" option is preferable in most situations.

5.4.7 

Errors, Warnings, and Messages

Many programs make use of the standard library functions err() and warn() to generate errors and warnings for the user. libxo wants to pass that information via the current output style, and provides compatible functions to allow this:

    void xo_warn (const char *fmt, ...);
    void xo_warnx (const char *fmt, ...);
    void xo_warn_c (int code, const char *fmt, ...);
    void xo_warn_hc (xo_handle_t *xop, int code,
                     const char *fmt, ...);
    void xo_err (int eval, const char *fmt, ...);
    void xo_errc (int eval, int code, const char *fmt, ...);
    void xo_errx (int eval, const char *fmt, ...);
    void xo_message (const char *fmt, ...);
    void xo_message_c (int code, const char *fmt, ...);
    void xo_message_hc (xo_handle_t *xop, int code,
                        const char *fmt, ...);
    void xo_message_hcv (xo_handle_t *xop, int code, 
                         const char *fmt, va_list vap);
            

These functions display the program name, a colon, a formatted message based on the arguments, and then optionally a colon and an error message associated with either "errno" or the "code" parameter.

    EXAMPLE:
        if (open(filename, O_RDONLY) < 0)
            xo_err(1, "cannot open file '%s'", filename);
            

5.4.8 

xo_error

The xo_error function can be used for generic errors that should be reported over the handle, rather than to stderr. The xo_error function behaves like xo_err for TEXT and HTML output styles, but puts the error into XML or JSON elements:

    EXAMPLE::
        xo_error("Does not %s", "compute");
    XML::
        <error><message>Does not compute</message></error>
    JSON::
        "error": { "message": "Does not compute" }
            

5.4.9 

xo_no_setlocale

libxo automatically initializes the locale based on setting of the environment variables LC_CTYPE, LANG, and LC_ALL. The first of this list of variables is used and if none of the variables, the locale defaults to "UTF‑8". The caller may wish to avoid this behavior, and can do so by calling the xo_no_setlocale() function.

    void xo_no_setlocale (void);
            

5.5.1 

Priority, Facility, and Flags

The xo_syslog, xo_vsyslog, and xo_open_log functions accept a set of flags which provide the priority of the message, the source facility, and some additional features. These values are OR'd together to create a single integer argument:

    xo_syslog(LOG_ERR | LOG_AUTH, "login-failed",
             "Login failed; user '{:user}' from host '{:address}'",
             user, addr);
            

These values are defined in <syslog.h>.

The priority value indicates the importance and potential impact of each message.

The facility value indicates the source of message, in fairly generic terms.

In addition to the values listed above, xo_open_log accepts a set of addition flags requesting specific behaviors.

5.5.2 

xo_syslog

Use the xo_syslog function to generate syslog messages by calling it with a log priority and facility, a message name, a format string, and a set of arguments. The priority/facility argument are discussed above, as is the message name.

The format string follows the same conventions as xo_emit's format string, with each field being rendered as an SD-PARAM pair.

    xo_syslog(LOG_ERR, "poofd-missing-file",
              "'{:filename}' not found: {:error/%m}", filename);

    ... [poofd-missing-file@32473 filename="/etc/poofd.conf"
          error="Permission denied"] '/etc/poofd.conf' not
          found: Permission denied
            

5.5.3 

Support functions

Section Contents:

• Section 5.5.3.1
• Section 5.5.3.2
• Section 5.5.3.3
• Section 5.5.3.4
• Section 5.5.3.5

    void my_log (const char *name, const char *fmt, ...)
    {
        va_list vap;
        va_start(vap, fmt);
        xo_vsyslog(LOG_ERR, name, fmt, vap);
        va_end(vap);
    }
            

    void
    xo_open_log (const char *ident, int logopt, int facility);
            

    void
    xo_close_log (void);
            

    int
    xo_set_logmask (int maskpri);

  Example:
    setlogmask(LOG_UPTO(LOG_WARN));
            

    void
    xo_set_syslog_enterprise_id (unsigned short eid);
            

5.6.1 

Loading Encoders

Encoders can be registered statically or discovered dynamically. Applications can choose to call the xo_encoder_register() function to explicitly register encoders, but more typically they are built as shared libraries, placed in the libxo/extensions directory, and loaded based on name. libxo looks for a file with the name of the encoder and an extension of ".enc". This can be a file or a symlink to the shared library file that supports the encoder.

    % ls -1 lib/libxo/extensions/*.enc
    lib/libxo/extensions/cbor.enc
    lib/libxo/extensions/test.enc
            

5.6.2 

Encoder Initialization

Each encoder must export a symbol used to access the library, which must have the following signature:

    int xo_encoder_library_init (XO_ENCODER_INIT_ARGS);
            

XO_ENCODER_INIT_ARGS is a macro defined in xo_encoder.h that defines an argument called "arg", a pointer of the type xo_encoder_init_args_t. This structure contains two fields:

• xei_version is the version number of the API as implemented within libxo. This version is currently as 1 using XO_ENCODER_VERSION. This number can be checked to ensure compatibility. The working assumption is that all versions should be backward compatible, but each side may need to accurately know the version supported by the other side. xo_encoder_library_init can optionally check this value, and must then set it to the version number used by the encoder, allowing libxo to detect version differences and react accordingly. For example, if version 2 adds new operations, then libxo will know that an encoding library that set xei_version to 1 cannot be expected to handle those new operations.
• xei_handler must be set to a pointer to a function of type xo_encoder_func_t, as defined in xo_encoder.h. This function takes a set of parameters: -- xop is a pointer to the opaque xo_handle_t structure -- op is an integer representing the current operation -- name is a string whose meaning differs by operation -- value is a string whose meaning differs by operation -- private is an opaque structure provided by the encoder

Additional arguments may be added in the future, so handler functions should use the XO_ENCODER_HANDLER_ARGS macro. An appropriate "extern" declaration is provided to help catch errors.

Once the encoder initialization function has completed processing, it should return zero to indicate that no error has occurred. A non-zero return code will cause the handle initialization to fail.

5.6.3 

Operations

The encoder API defines a set of operations representing the processing model of libxo. Content is formatted within libxo, and callbacks are made to the encoder's handler function when data is ready to be processed.

For all the open and close operations, the name parameter holds the name of the construct. For string, content, and attribute operations, the name parameter is the name of the field and the value parameter is the value. "string" are differentiated from "content" to allow differing treatment of true, false, null, and numbers from real strings, though content values are formatted as strings before the handler is called. For version operations, the value parameter contains the version.

All strings are encoded in UTF-8.

10.1.1 

Can you share the history of libxo?

In 2001, we added an XML API to the JUNOS operating system, which is built on top of FreeBSD. Eventually this API became standardized as the NETCONF API (RFC 6241). As part of this effort, we modified many FreeBSD utilities to emit XML, typically via a "‑X" switch. The results were mixed. The cost of maintaining this code, updating it, and carrying it were non-trivial, and contributed to our expense (and the associated delay) with upgrading the version of FreeBSD on which each release of JUNOS is based.

A recent (2014) effort within JUNOS aims at removing our modifications to the underlying FreeBSD code as a means of reducing the expense and delay in tracking HEAD. JUNOS is structured to have system components generate XML that is rendered by the CLI (think: login shell) into human-readable text. This allows the API to use the same plumbing as the CLI, and ensures that all components emit XML, and that it is emitted with knowledge of the consumer of that XML, yielding an API that have no incremental cost or feature delay.

libxo is an effort to mix the best aspects of the JUNOS strategy into FreeBSD in a seemless way, allowing commands to make printf-like output calls with a single code path.

10.1.2 

Did the complex semantics of format strings evolve over time?

The history is both long and short: libxo's functionality is based on what JUNOS does in a data modeling language called ODL (output definition language). In JUNOS, all subcomponents generate XML, which is feed to the CLI, where data from the ODL files tell is how to render that XML into text. ODL might had a set of tags like:

     tag docsis-state {
         help "State of the DOCSIS interface";
         type string;
     }

     tag docsis-mode {
         help "DOCSIS mode (2.0/3.0) of the DOCSIS interface";
         type string;
     }

     tag docsis-upstream-speed {
         help "Operational upstream speed of the interface";
         type string;
     }

     tag downstream-scanning {
         help "Result of scanning in downstream direction";
         type string;
     }

     tag ranging {
         help "Result of ranging action";
         type string;
     }

     tag signal-to-noise-ratio {
         help "Signal to noise ratio for all channels";
         type string;
     }

     tag power {
         help "Operational power of the signal on all channels";
         type string;
     }

     format docsis-status-format {
         picture "
   State   : @, Mode: @, Upstream speed: @
   Downstream scanning: @, Ranging: @
   Signal to noise ratio: @
   Power: @
";
         line {
             field docsis-state;
             field docsis-mode;
             field docsis-upstream-speed;
             field downstream-scanning;
             field ranging;
             field signal-to-noise-ratio;
             field power;
         }
     }
            

These tag definitions are compiled into field definitions that are triggered when matching XML elements are seen. ODL also supports other means of defining output.

The roles and modifiers describe these details.

In moving these ideas to bsd, two things had to happen: the formatting had to happen at the source since BSD won't have a JUNOS-like CLI to do the rendering, and we can't depend on external data models like ODL, which was seen as too hard a sell to the BSD community.

The results were that the xo_emit strings are used to encode the roles, modifiers, names, and formats. They are dense and a bit cryptic, but not so unlike printf format strings that developers will be lost.

libxo is a new implementation of these ideas and is distinct from the previous implementation in JUNOS.

10.1.3 

What makes a good field name?

To make useful, consistent field names, follow these guidelines:

Use lower case, even for TLAs

Lower case is more civilized. Even TLAs should be lower case to avoid scenarios where the differences between "XPath" and "Xpath" drive your users crazy. Using "xpath" is simpler and better.

Use hyphens, not underscores

Use of hyphens is traditional in XML, and the XOF_UNDERSCORES flag can be used to generate underscores in JSON, if desired. But the raw field name should use hyphens.

Use full words

Don't abbreviate especially when the abbreviation is not obvious or not widely used. Use "data‑size", not "dsz" or "dsize". Use "interface" instead of "ifname", "if‑name", "iface", "if", or "intf".

Use <verb>-<units>

Using the form <verb>-<units> or <verb>-<classifier>-<units> helps in making consistent, useful names, avoiding the situation where one app uses "sent‑packet" and another "packets‑sent" and another "packets‑we‑have‑sent". The <units> can be dropped when it is obvious, as can obvious words in the classification. Use "receive‑after‑window‑packets" instead of "received‑packets‑of‑data‑after‑window".

Reuse existing field names

Nothing's worse than writing expressions like:

    if ($src1/process[pid == $pid]/name == 
        $src2/proc-table/proc-list
                   /proc-entry[process-id == $pid]/proc-name) {
        ...
    }
            

Find someone else who is expressing similar data and follow their fields and hierarchy. Remember the quote is not "Consistency is the hobgoblin of little minds", but "A foolish consistency is the hobgoblin of little minds".

Use containment as scoping

In the previous example, all the names are prefixed with "proc‑", which is redundant given that they are nested under the process table.

Think about your users

Have empathy for your users, choosing clear and useful fields that contain clear and useful data. You may need to augment the display content with xo_attr() calls (Section 5.2.2) or "{e:}" fields (Section 3.2.2.4) to make the data useful.

Don't use an arbitrary number postfix

What does "errors2" mean? No one will know. "errors‑after‑restart" would be a better choice. Think of your users, and think of the future. If you make "errors2", the next guy will happily make "errors3" and before you know it, someone will be asking what's the difference between errors37 and errors63.

Be consistent, uniform, unsurprising, and predictable

Think of your field vocabulary as an API. You want it useful, expressive, meaningful, direct, and obvious. You want the client application's programmer to move between without the need to understand a variety of opinions on how fields are named. They should see the system as a single cohesive whole, not a sack of cats.

Field names constitute the means by which client programmers interact with our system. By choosing wise names now, you are making their lives better.

After using "xolint" to find errors in your field descriptors, use "xolint -V" to spell check your field names and to detect different names for the same data. "dropped‑short" and "dropped‑too‑short" are both reasonable names, but using them both will lead users to ask the difference between the two fields. If there is no difference, use only one of the field names. If there is a difference, change the names to make that difference more obvious.

10.2.1 

'A percent sign appearing in text is a literal'

The message "A percent sign appearing in text is a literal" can be caused by code like:

    xo_emit("cost: %d", cost);
            

This code should be replaced with code like:

    xo_emit("{L:cost}: {:cost/%d}", cost);
            

This can be a bit surprising and could be a field that was not properly converted to a libxo-style format string.

10.2.2 

'Unknown long name for role/modifier'

The message "Unknown long name for role/modifier" can be caused by code like:

    xo_emit("{,humanization:value}", value);
            

This code should be replaced with code like:

    xo_emit("{,humanize:value}", value);
            

The hn-* modifiers (hn-decimal, hn-space, hn-1000) are only valid for fields with the {h:} modifier.

10.2.3 

'Last character before field definition is a field type'

The message "Last character before field definition is a field type" can be caused by code like:

A common typo:

    xo_emit("{T:Min} T{:Max}");
            

This code should be replaced with code like:

    xo_emit("{T:Min} {T:Max}");
            

Twiddling the "{" and the field role is a common typo.

10.2.4 

'Encoding format uses different number of arguments'

The message "Encoding format uses different number of arguments" can be caused by code like:

    xo_emit("{:name/%6.6s %%04d/%s}", name, number);
            

This code should be replaced with code like:

    xo_emit("{:name/%6.6s %04d/%s-%d}", name, number);
            

Both format should consume the same number of arguments off the stack

10.2.5 

'Only one field role can be used'

The message "Only one field role can be used" can be caused by code like:

    xo_emit("{LT:Max}");
            

This code should be replaced with code like:

    xo_emit("{T:Max}");
            

10.2.6 

'Potential missing slash after C, D, N, L, or T with format'

The message "Potential missing slash after C, D, N, L, or T with format" can be caused by code like:

    xo_emit("{T:%6.6s}\n", "Max");
            

This code should be replaced with code like:

    xo_emit("{T:/%6.6s}\n", "Max");
            

The "%6.6s" will be a literal, not a field format. While it's possibly valid, it's likely a missing "/".

10.2.7 

'An encoding format cannot be given (roles: DNLT)'

The message "An encoding format cannot be given (roles: DNLT)" can be caused by code like:

    xo_emit("{T:Max//%s}", "Max");
            

Fields with the C, D, N, L, and T roles are not emitted in the 'encoding' style (JSON, XML), so an encoding format would make no sense.

10.2.8 

'Format cannot be given when content is present (roles: CDLN)'

The message "Format cannot be given when content is present (roles: CDLN)" can be caused by code like:

    xo_emit("{N:Max/%6.6s}", "Max");
            

Fields with the C, D, L, or N roles can't have both static literal content ("{L:Label}") and a format ("{L:/%s}"). This error will also occur when the content has a backslash in it, like "{N:Type of I/O}"; backslashes should be escaped, like "{N:Type of I\\/O}". Note the double backslash, one for handling 'C' strings, and one for libxo.

10.2.9 

'Field has color without fg- or bg- (role: C)'

The message "Field has color without fg- or bg- (role: C)" can be caused by code like:

    xo_emit("{C:green}{:foo}{C:}", x);
            

This code should be replaced with code like:

    xo_emit("{C:fg-green}{:foo}{C:}", x);
            

Colors must be prefixed by either "fg‑" or "bg‑".

10.2.10 

'Field has invalid color or effect (role: C)'

The message "Field has invalid color or effect (role: C)" can be caused by code like:

    xo_emit("{C:fg-purple,bold}{:foo}{C:gween}", x);
            

This code should be replaced with code like:

    xo_emit("{C:fg-red,bold}{:foo}{C:fg-green}", x);
            

The list of colors and effects are limited. The set of colors includes default, black, red, green, yellow, blue, magenta, cyan, and white, which must be prefixed by either "fg‑" or "bg‑". Effects are limited to bold, no-bold, underline, no-underline, inverse, no-inverse, normal, and reset. Values must be separated by commas.

10.2.11 

'Field has humanize modifier but no format string'

The message "Field has humanize modifier but no format string" can be caused by code like:

    xo_emit("{h:value}", value);
            

This code should be replaced with code like:

    xo_emit("{h:value/%d}", value);
            

Humanization is only value for numbers, which are not likely to use the default format ("%s").

10.2.12 

'Field has hn-* modifier but not 'h' modifier'

The message "Field has hn-* modifier but not 'h' modifier" can be caused by code like:

    xo_emit("{,hn-1000:value}", value);
            

This code should be replaced with code like:

    xo_emit("{h,hn-1000:value}", value);
            

The hn-* modifiers (hn-decimal, hn-space, hn-1000) are only valid for fields with the {h:} modifier.

10.2.13 

'Value field must have a name (as content)")'

The message "Value field must have a name (as content)")" can be caused by code like:

    xo_emit("{:/%s}", "value");
            

This code should be replaced with code like:

    xo_emit("{:tag-name/%s}", "value");
            

The field name is used for XML and JSON encodings. These tags names are static and must appear directly in the field descriptor.

10.2.14 

'Use hyphens, not underscores, for value field name'

The message "Use hyphens, not underscores, for value field name" can be caused by code like:

    xo_emit("{:no_under_scores}", "bad");
            

This code should be replaced with code like:

    xo_emit("{:no-under-scores}", "bad");
            

Use of hyphens is traditional in XML, and the XOF_UNDERSCORES flag can be used to generate underscores in JSON, if desired. But the raw field name should use hyphens.

10.2.15 

'Value field name cannot start with digit'

The message "Value field name cannot start with digit" can be caused by code like:

    xo_emit("{:10-gig/}");
            

This code should be replaced with code like:

    xo_emit("{:ten-gig/}");
            

XML element names cannot start with a digit.

10.2.16 

'Value field name should be lower case'

The message "Value field name should be lower case" can be caused by code like:

    xo_emit("{:WHY-ARE-YOU-SHOUTING}", "NO REASON");
            

This code should be replaced with code like:

    xo_emit("{:why-are-you-shouting}", "no reason");
            

Lower case is more civilized. Even TLAs should be lower case to avoid scenarios where the differences between "XPath" and "Xpath" drive your users crazy. Lower case rules the seas.

10.2.17 

'Value field name should be longer than two characters'

The message "Value field name should be longer than two characters" can be caused by code like:

    xo_emit("{:x}", "mumble");
            

This code should be replaced with code like:

    xo_emit("{:something-meaningful}", "mumble");
            

Field names should be descriptive, and it's hard to be descriptive in less than two characters. Consider your users and try to make something more useful. Note that this error often occurs when the field type is placed after the colon ("{:T/%20s}"), instead of before it ("{T:/20s}").

10.2.18 

'Value field name contains invalid character'

The message "Value field name contains invalid character" can be caused by code like:

    xo_emit("{:cost-in-$$/%u}", 15);
            

This code should be replaced with code like:

    xo_emit("{:cost-in-dollars/%u}", 15);
            

An invalid character is often a sign of a typo, like "{:]}" instead of "{]:}". Field names are restricted to lower-case characters, digits, and hyphens.

10.2.19 

'decoration field contains invalid character'

The message "decoration field contains invalid character" can be caused by code like:

    xo_emit("{D:not good}");
            

This code should be replaced with code like:

    xo_emit("{D:((}{:good}{D:))}", "yes");
            

This is minor, but fields should use proper roles. Decoration fields are meant to hold punctuation and other characters used to decorate the content, typically to make it more readable to human readers.

10.2.20 

'Anchor content should be decimal width'

The message "Anchor content should be decimal width" can be caused by code like:

    xo_emit("{[:mumble}");
            

This code should be replaced with code like:

    xo_emit("{[:32}");
            

Anchors need an integer value to specify the width of the set of anchored fields. The value can be positive (for left padding/right justification) or negative (for right padding/left justification) and can appear in either the start or stop anchor field descriptor.

10.2.21 

'Anchor format should be "%d"'

The message "Anchor format should be "%d"" can be caused by code like:

    xo_emit("{[:/%s}");
            

This code should be replaced with code like:

    xo_emit("{[:/%d}");
            

Anchors only grok integer values, and if the value is not static, if must be in an 'int' argument, represented by the "%d" format. Anything else is an error.

10.2.22 

'Anchor cannot have both format and encoding format")'

The message "Anchor cannot have both format and encoding format")" can be caused by code like:

    xo_emit("{[:32/%d}");
            

This code should be replaced with code like:

    xo_emit("{[:32}");
            

Anchors can have a static value or argument for the width, but cannot have both.

10.2.23 

'Max width only valid for strings'

The message "Max width only valid for strings" can be caused by code like:

    xo_emit("{:tag/%2.4.6d}", 55);
            

This code should be replaced with code like:

    xo_emit("{:tag/%2.6d}", 55);
            

libxo allows a true 'max width' in addition to the traditional printf-style 'max number of bytes to use for input'. But this is supported only for string values, since it makes no sense for non-strings. This error may occur from a typo, like "{:tag/%6..6d}" where only one period should be used.

11.3.1 

Setting up the context

To use libxo, you'll need to include the "xo.h" header file in your source code files:

    #include <libxo/xo.h>
            

In your main() function, you'll need to call xo_parse_args to handling argument parsing (Section 5.4.1). This function removes libxo-specific arguments the program's argv and returns either the number of remaining arguments or -1 to indicate an error.

    int main (int argc, char **argv)
    {
        argc = xo_parse_args(argc, argv);
        if (argc < 0)
            return argc;
        ....
    }
            

At the bottom of your main(), you'll need to call xo_finish() to complete output processing for the default handle (Section 5.1). libxo provides the xo_finish_atexit function that is suitable for use with the atexit(3) function.

    atexit(xo_finish_atexit);
            

11.3.2 

Converting printf Calls

The second task is inspecting code for printf(3) calls and replacing them with xo_emit() calls. The format strings are similar in task, but libxo format strings wrap output fields in braces. The following two calls produce identical text output:

    printf("There are %d %s events\n", count, etype);
    xo_emit("There are {:count/%d} {:event} events\n", count, etype);
            

"count" and "event" are used as names for JSON and XML output. The "count" field uses the format "%d" and "event" uses the default "%s" format. Both are "value" roles, which is the default role.

Since text outside of output fields is passed verbatim, other roles are less important, but their proper use can help make output more useful. The "note" and "label" roles allow HTML output to recognize the relationship between text and the associated values, allowing appropriate "hover" and "onclick" behavior. Using the "units" role allows the presentation layer to perform conversions when needed. The "warning" and "error" roles allows use of color and font to draw attention to warnings. The "padding" role makes the use of vital whitespace more clear (Section 3.2.1.6).

The "title" role indicates the headings of table and sections. This allows HTML output to use CSS to make this relationship more obvious.

    printf("Statistics:\n");
    xo_emit("{T:Statistics}:\n");
            

The "color" roles controls foreground and background colors, as well as effects like bold and underline (see Section 3.2.1.1).

    xo_emit("{C:bold}required{C:}\n");
            

Finally, the start- and stop-anchor roles allow justification and padding over multiple fields (see Section 3.2.1.10).

    snprintf(buf, sizeof(buf), "(%u/%u/%u)", min, ave, max);
    printf("%30s", buf);

    xo_emit("{[:30}({:minimum/%u}/{:average/%u}/{:maximum/%u}{]:}",
            min, ave, max);
            

11.3.3 

Creating Hierarchy

Text output doesn't have any sort of hierarchy, but XML and JSON require this. Typically applications use indentation to represent these relationship:

    printf("table %d\n", tnum);
    for (i = 0; i < tmax; i++) {
        printf("    %s %d\n", table[i].name, table[i].size);
    }

    xo_emit("{T:/table %d}\n", tnum);
    xo_open_list("table");
    for (i = 0; i < tmax; i++) {
        xo_open_instance("table");
        xo_emit("{P:    }{k:name} {:size/%d}\n",
                table[i].name, table[i].size);
        xo_close_instance("table");
    }
    xo_close_list("table");
            

The open and close list functions are used before and after the list, and the open and close instance functions are used before and after each instance with in the list.

Typically these developer looks for a "for" loop as an indication of where to put these calls.

In addition, the open and close container functions allow for organization levels of hierarchy.

    printf("Paging information:\n");
    printf("    Free:      %lu\n", free);
    printf("    Active:    %lu\n", active);
    printf("    Inactive:  %lu\n", inactive);

    xo_open_container("paging-information");
    xo_emit("{P:    }{L:Free:      }{:free/%lu}\n", free);
    xo_emit("{P:    }{L:Active:    }{:active/%lu}\n", active);
    xo_emit("{P:    }{L:Inactive:  }{:inactive/%lu}\n", inactive);
    xo_close_container("paging-information");
            

11.3.4 

Converting Error Functions

libxo provides variants of the standard error and warning functions, err(3) and warn(3). There are two variants, one for putting the errors on standard error, and the other writes the errors and warnings to the handle using the appropriate encoding style:

    err(1, "cannot open output file: %s", file);

    xo_err(1, "cannot open output file: %s", file);
    xo_emit_err(1, "cannot open output file: {:filename}", file);
            

11.5.1 

i18n and xo_emit

There are three features used in libxo used to support i18n:

• The "{G:}" role looks for a translation of the format string.
• The "{g:}" modifier looks for a translation of the field.
• The "{p:}" modifier looks for a pluralized version of the field.

Together these three flags allows a single function call to give native language support, as well as libxo's normal XML, JSON, and HTML support.

    printf(gettext("Received %zu %s from {g:server} server\n"),
           counter, ngettext("byte", "bytes", counter),
           gettext("web"));

    xo_emit("{G:}Received {:received/%zu} {Ngp:byte,bytes} "
            "from {g:server} server\n", counter, "web");
            

libxo will see the "{G:}" role and will first simplify the format string, removing field formats and modifiers.

    "Received {:received} {N:byte,bytes} from {:server} server\n"
            

libxo calls gettext(3) with that string to get a localized version. If your language were Pig Latin, the result might look like:

    "Eceivedray {:received} {N:byte,bytes} omfray "
               "{:server} erversay\n"
            

Note the field names do not change and they should not be translated. The contents of the note ("byte,bytes") should also not be translated, since the "g" modifier will need the untranslated value as the key for the message catalog.

The field "{g:server}" requests the rendered value of the field be translated using gettext(3). In this example, "web" would be used.

The field "{Ngp:byte,bytes}" shows an example of plural form using the "p" modifier with the "g" modifier. The base singular and plural forms appear inside the field, separated by a comma. At run time, libxo uses the previous field's numeric value to decide which form to use by calling ngettext(3).

If a domain name is needed, it can be supplied as the content of the {G:} role. Domain names remain in use throughout the format string until cleared with another domain name.

    printf(dgettext("dns", "Host %s not found: %d(%s)\n"),
        name, errno, dgettext("strerror", strerror(errno)));

    xo_emit("{G:dns}Host {:hostname} not found: "
            "%d({G:strerror}{g:%m})\n", name, errno);