.. index:: --libxo
.. index:: Options
.. _options:
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 :ref:`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 :ref:`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
:ref:`humanize-modifier` 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 :ref:`retain`
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)
======== =============================================
.. index:: Colors
.. _color-mapping:
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