contrib/libxo/doc/options.rst

   1
   2 .. index:: --libxo
   3 .. index:: Options
   4
   5 .. _options:
   6
   7 Command-line Arguments
   8 ======================
   9
  10 libxo uses command line options to trigger rendering behavior.  There
  11 are multiple conventions for passing options, all using the
  12 "`--libxo`" option::
  13
  14   --libxo <options>
  15   --libxo=<options>
  16   --libxo:<brief-options>
  17
  18 The *brief-options* is a series of single letter abbrevations, where
  19 the *options* is a comma-separated list of words.  Both provide access
  20 to identical functionality.  The following invocations are all
  21 identical in outcome::
  22
  23   my-app --libxo warn,pretty arg1
  24   my-app --libxo=warn,pretty arg1
  25   my-app --libxo:WP arg1
  26
  27 Programs using libxo are expecting to call the xo_parse_args function
  28 to parse these arguments.  See :ref:`xo_parse_args` for details.
  29
  30 Option Keywords
  31 ---------------
  32
  33 Options is a comma-separated list of tokens that correspond to output
  34 styles, flags, or features:
  35
  36   =============== =======================================================
  37   Token           Action
  38   =============== =======================================================
  39   color           Enable colors/effects for display styles (TEXT, HTML)
  40   colors=xxxx     Adjust color output values
  41   dtrt            Enable "Do The Right Thing" mode
  42   flush           Flush after every libxo function call
  43   flush-line      Flush after every line (line-buffered)
  44   html            Emit HTML output
  45   indent=xx       Set the indentation level
  46   info            Add info attributes (HTML)
  47   json            Emit JSON output
  48   keys            Emit the key attribute for keys (XML)
  49   log-gettext     Log (via stderr) each gettext(3) string lookup
  50   log-syslog      Log (via stderr) each syslog message (via xo_syslog)
  51   no-humanize     Ignore the {h:} modifier (TEXT, HTML)
  52   no-locale       Do not initialize the locale setting
  53   no-retain       Prevent retaining formatting information
  54   no-top          Do not emit a top set of braces (JSON)
  55   not-first       Pretend the 1st output item was not 1st (JSON)
  56   pretty          Emit pretty-printed output
  57   retain          Force retaining formatting information
  58   text            Emit TEXT output
  59   underscores     Replace XML-friendly "-"s with JSON friendly "_"s
  60   units           Add the 'units' (XML) or 'data-units (HTML) attribute
  61   warn            Emit warnings when libxo detects bad calls
  62   warn-xml        Emit warnings in XML
  63   xml             Emit XML output
  64   xpath           Add XPath expressions (HTML)
  65   =============== =======================================================
  66
  67 Most of these option are simple and direct, but some require
  68 additional details:
  69
  70 - "colors" is described in :ref:`color-mapping`.
  71 - "flush-line" performs line buffering, even when the output is not
  72   directed to a TTY device.
  73 - "info" generates additional data for HTML, encoded in attributes
  74   using names that state with "data-".
  75 - "keys" adds a "key" attribute for XML output to indicate that a leaf
  76   is an identifier for the list member.
  77 - "no-humanize" avoids "humanizing" numeric output (see
  78   :ref:`humanize-modifier` for details).
  79 - "no-locale" instructs libxo to avoid translating output to the
  80   current locale.
  81 - "no-retain" disables the ability of libxo to internally retain
  82   "compiled" information about formatting strings (see :ref:`retain`
  83   for details).
  84 - "underscores" can be used with JSON output to change XML-friendly
  85   names with dashes into JSON-friendly name with underscores.
  86 - "warn" allows libxo to emit warnings on stderr when application code
  87   make incorrect calls.
  88 - "warn-xml" causes those warnings to be placed in XML inside the
  89   output.
  90
  91 Brief Options
  92 -------------
  93
  94 The brief options are simple single-letter aliases to the normal
  95 keywords, as detailed below:
  96
  97   ======== =============================================
  98    Option   Action
  99   ======== =============================================
 100    c        Enable color/effects for TEXT/HTML
 101    F        Force line-buffered flushing
 102    H        Enable HTML output (XO_STYLE_HTML)
 103    I        Enable info output (XOF_INFO)
 104    i<num>   Indent by <number>
 105    J        Enable JSON output (XO_STYLE_JSON)
 106    k        Add keys to XPATH expressions in HTML
 107    n        Disable humanization (TEXT, HTML)
 108    P        Enable pretty-printed output (XOF_PRETTY)
 109    T        Enable text output (XO_STYLE_TEXT)
 110    U        Add units to HTML output
 111    u        Change "-"s to "_"s in element names (JSON)
 112    W        Enable warnings (XOF_WARN)
 113    X        Enable XML output (XO_STYLE_XML)
 114    x        Enable XPath data (XOF_XPATH)
 115   ======== =============================================
 116
 117 .. index:: Colors
 118
 119 .. _color-mapping:
 120
 121 Color Mapping
 122 -------------
 123
 124 The "colors" option takes a value that is a set of mappings from the
 125 pre-defined set of colors to new foreground and background colors.
 126 The value is a series of "fg/bg" values, separated by a "+".  Each
 127 pair of "fg/bg" values gives the colors to which a basic color is
 128 mapped when used as a foreground or background color.  The order is
 129 the mappings is:
 130
 131 - black
 132 - red
 133 - green
 134 - yellow
 135 - blue
 136 - magenta
 137 - cyan
 138 - white
 139
 140 Pairs may be skipped, leaving them mapped as normal, as are missing
 141 pairs or single colors.
 142
 143 For example consider the following xo_emit call::
 144
 145     xo_emit("{C:fg-red,bg-green}Merry XMas!!{C:}\n");
 146
 147 To turn all colored output to red-on-blue, use eight pairs of
 148 "red/blue" mappings separated by plus signs ("+")::
 149
 150     --libxo colors=red/blue+red/blue+red/blue+red/blue+\
 151                    red/blue+red/blue+red/blue+red/blue
 152
 153 To turn the red-on-green text to magenta-on-cyan, give a "magenta"
 154 foreground value for red (the second mapping) and a "cyan" background
 155 to green (the third mapping)::
 156
 157     --libxo colors=+magenta+/cyan
 158
 159 Consider the common situation where blue output looks unreadable on a
 160 terminal session with a black background.  To turn both "blue"
 161 foreground and background output to "yellow", give only the fifth
 162 mapping, skipping the first four mappings with bare plus signs ("+")::
 163
 164     --libxo colors=++++yellow/yellow
 165
 166 Encoders
 167 --------
 168
 169 In addition to the four "built-in" formats, libxo supports an
 170 extensible mechanism for adding encoders.  These are activated
 171 using the "encoder" keyword::
 172
 173    --libxo encoder=cbor
 174
 175 The encoder can include encoder-specific options, separated by either
 176 colons (":") or plus signs ("+"):
 177
 178     --libxo encoder=csv+path=filesystem+leaf=name+no-header
 179     --libxo encoder=csv:path=filesystem:leaf=name:no-header
 180
 181 For brevity, the string "@" can be used in place of the string
 182 "encoder=".
 183
 184     df --libxo @csv:no-header