xref: /freebsd/contrib/libxo/doc/options.rst (revision 773bec086828bf0f1ba663958853823f7a059fb5)

.. 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