5c5819b2b6
- Two changes to encoder options:
encoder options may use plus or colon, but only one
encoder names can be specified as "@name"
This results in the syntax:
df --libxo @csv:no-header:leafs=name.available-blocks /
- If xo_set_program is called before xo_parse_args, honor the requested value
- add xo_errorn* function; repair newline-adding-on-xo_error bug
- test programs now use fixed name, since linux libtool prefixs "lt-"
- Fix "horse butt" comment in source code
- update test cases
PR: 242686
185 lines
6.4 KiB
ReStructuredText
185 lines
6.4 KiB
ReStructuredText
|
|
.. 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
|