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>
--libxo=<options>
--libxo:<brief-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+\
               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

Encoders

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