xo_options - Man Page

libxo allows the rendering of data into various output styles, including text, XML, JSON, and HTML. libxo uses command line options to trigger rendering behavior. Options are recognised in three forms:

• --libxo <options>

• --libxo=<options>

• --libxo:<brief-options>

The first two forms accept a comma-separated set of words, detailed below, while the third form accepts a set of letters, also below. The triggered functionality is identical.

The brief options are a set of single-letter aliases for the longer terms, used as a single string:

Most of these option are simple and direct, but some require additional details:

flush-line performs line buffering, even when the output is not directed to a TTY device.

info generates additional data for HTML, encoded in attributes using names that state with "data-".

keys adds a "key" attribute for XML output to indicate that a leaf is an identifier for the list member.

map and map-file are described below.

no-humanize avoids "humanizing" numeric output (see humanize_number(3) for details).

no-locale instructs libxo to avoid translating output to the current locale.

no-retain disables the ability of libxo to internally retain "compiled" information about formatting strings.

underscores can be used with JSON output to change XML -friendly names with dashes into JSON -friendly name with underscores.

warn allows libxo to emit warnings on stderr when application code make incorrect calls. warn-xml causes those warnings to be placed in XML inside the output.

The colors option takes a value that is a set of mappings from the pre-defined set of colors to new foreground and background colors. The value is a series of "fg/bg" values, separated by a "+". Each pair of "fg/bg" values gives the colors to which a basic color is mapped when used as a foreground or background color. The order is the mappings is:

- black
- red
- green
- yellow
- blue
- magenta
- cyan
- white

Pairs may be skipped, leaving them mapped as normal, as are missing pairs or single colors.

For example consider the following xo_emit call:

    xo_emit("{C:fg-red,bg-green}Merry XMas!!{C:}0);

To turn all colored output to red-on-blue, use eight pairs of "red/blue" mappings separated by plus signs ("+"):

    --libxo colors=red/blue+red/blue+red/blue+red/blue+                   red/blue+red/blue+red/blue+red/blue

To turn the red-on-green text to magenta-on-cyan, give a "magenta" foreground value for red (the second mapping) and a "cyan" background to green (the third mapping):

    --libxo colors=+magenta+/cyan

Consider the common situation where blue output looks unreadable on a terminal session with a black background. To turn both "blue" foreground and background output to "yellow", give only the fifth mapping, skipping the first four mappings with bare plus signs ("+"):

    --libxo colors=++++yellow/yellow

libxo supports mapping between tag names, for scenarios where the tags need to make specific values. For example, the "user" tag might be needed as the "owner" tag. libxo can perform this one-to-one tag replacement.

Note that libxo does not perform more complex transformations; languages such as XSLT or SLAX should be used when something more than simple one-to-one replacement is required.

Mapping can be specified using the map and map-file options. The map option accepts one or more mapping, in the format "old=new", separated by colons:

    --libxo map:one=red,map:two=blue

This example would turn:

    <one>fish</one>
    <two>fish</two>

into:

    <red>fish</red>
    <blue>fish</blue>

In another example, the command-line options:

    --libxo map:user=owner:name=file:size=bytes:modify-time=time

would turn:

    <entry>
      <name>xx-00000009</name>
      <user>phil</user>
      <size>12345</size>
      <modify-time value="1644355825">1644355825</modify-time>
    </entry>

into:

    <entry>
      <file>xx-00000009</file>
      <owner>phil</owner>
      <bytes>12345</bytes>
      <time value="1644355825">1644355825</time>
    </entry>

The map-file option allows the mappings to be placed into a file, one per line:

    --libxo map-file=foo.map

where "foo.map" might contain:

    # comments are supported, white space is ignored
    user = owner
    name=file
    # blank lines are allowed

        size = bytes
    modify-time= time

This untidy example demonstrates the flexibility in the libxo mapping files.

If the filename given with the map-file option contains no slashes ("/") and such a file does not exist in the current working directory, libxo will look for the file in the "map" subdirectory of the system "share" directory, typically /usr/share/libxo/map/.

In addition to the four "built-in" formats, libxo supports an extensible mechanism for adding encoders. These are activated using the encoder keyword::

   --libxo encoder=cbor

The encoder can include encoder-specific options, separated by either colons (":") or plus signs ("+"):

    --libxo encoder=csv+path=filesystem+leaf=name+no-header
    --libxo encoder=csv:path=filesystem:leaf=name:no-header

For brevity, the string "@" can be used in place of the string "encoder=".

    df --libxo @csv:no-header

The following are three example invocations of ps(1):

      ps --libxo json,pretty,warn -ux

      ps --libxo=xml -lg

      ps --libxo:Hxc 1

libxo(3), xo_format(5)

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), libxo-csv(7), xo(1), xo_csv(7), xohtml(1), xo_parse_args(3).