Command-line Arguments

libxo uses command line options to trigger rendering behavior. There are multiple conventions for passing options, all using the “--libxo” option:

--libxo <options>

The brief-options is a series of single letter abbrevations, where the options is a comma-separated list of words. Both provide access to identical functionality. The following invocations are all identical in outcome:

my-app --libxo warn,pretty arg1
my-app --libxo=warn,pretty arg1
my-app --libxo:WP arg1

Programs using libxo are expecting to call the xo_parse_args function to parse these arguments. See Parsing Command-line Arguments (xo_parse_args) for details.

Option Keywords

Options is a comma-separated list of tokens that correspond to output styles, flags, or features:

Token Action
color Enable colors/effects for display styles (TEXT, HTML)
colors=xxxx Adjust color output values
dtrt Enable “Do The Right Thing” mode
flush Flush after every libxo function call
flush-line Flush after every line (line-buffered)
html Emit HTML output
indent=xx Set the indentation level
info Add info attributes (HTML)
json Emit JSON output
keys Emit the key attribute for keys (XML)
log-gettext Log (via stderr) each gettext(3) string lookup
log-syslog Log (via stderr) each syslog message (via xo_syslog)
no-humanize Ignore the {h:} modifier (TEXT, HTML)
no-locale Do not initialize the locale setting
no-retain Prevent retaining formatting information
no-top Do not emit a top set of braces (JSON)
not-first Pretend the 1st output item was not 1st (JSON)
pretty Emit pretty-printed output
retain Force retaining formatting information
text Emit TEXT output
underscores Replace XML-friendly “-“s with JSON friendly “_”s
units Add the ‘units’ (XML) or ‘data-units (HTML) attribute
warn Emit warnings when libxo detects bad calls
warn-xml Emit warnings in XML
xml Emit XML output
xpath Add XPath expressions (HTML)

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

  • “colors” is described in Color Mapping.
  • “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.
  • “no-humanize” avoids “humanizing” numeric output (see The Humanize Modifier ({h:}) 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 (see Retaining Parsed Format Information for details).
  • “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.

Brief Options

The brief options are simple single-letter aliases to the normal keywords, as detailed below:

Option Action
c Enable color/effects for TEXT/HTML
F Force line-buffered flushing
H Enable HTML output (XO_STYLE_HTML)
I Enable info output (XOF_INFO)
i<num> Indent by <number>
J Enable JSON output (XO_STYLE_JSON)
k Add keys to XPATH expressions in HTML
n Disable humanization (TEXT, HTML)
P Enable pretty-printed output (XOF_PRETTY)
T Enable text output (XO_STYLE_TEXT)
U Add units to HTML output
u Change “-“s to “_”s in element names (JSON)
W Enable warnings (XOF_WARN)
X Enable XML output (XO_STYLE_XML)
x Enable XPath data (XOF_XPATH)

Color Mapping

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:}\n");

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+\

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


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