1 2.. index:: --libxo 3.. index:: Options 4 5.. _options: 6 7Command-line Arguments 8====================== 9 10libxo uses command line options to trigger rendering behavior. There 11are multiple conventions for passing options, all using the 12"`--libxo`" option:: 13 14 --libxo <options> 15 --libxo=<options> 16 --libxo:<brief-options> 17 18The *brief-options* is a series of single letter abbrevations, where 19the *options* is a comma-separated list of words. Both provide access 20to identical functionality. The following invocations are all 21identical in outcome:: 22 23 my-app --libxo warn,pretty arg1 24 my-app --libxo=warn,pretty arg1 25 my-app --libxo:WP arg1 26 27Programs using libxo are expecting to call the xo_parse_args function 28to parse these arguments. See :ref:`xo_parse_args` for details. 29 30Option Keywords 31--------------- 32 33Options is a comma-separated list of tokens that correspond to output 34styles, flags, or features: 35 36=============== ======================================================= 37Token Action 38=============== ======================================================= 39color Enable colors/effects for display styles (TEXT, HTML) 40colors=xxxx Adjust color output values 41dtrt Enable "Do The Right Thing" mode 42flush Flush after every libxo function call 43flush-line Flush after every line (line-buffered) 44html Emit HTML output 45indent=xx Set the indentation level 46info Add info attributes (HTML) 47json Emit JSON output 48keys Emit the key attribute for keys (XML) 49log-gettext Log (via stderr) each gettext(3) string lookup 50log-syslog Log (via stderr) each syslog message (via xo_syslog) 51no-humanize Ignore the {h:} modifier (TEXT, HTML) 52no-locale Do not initialize the locale setting 53no-retain Prevent retaining formatting information 54no-top Do not emit a top set of braces (JSON) 55not-first Pretend the 1st output item was not 1st (JSON) 56pretty Emit pretty-printed output 57retain Force retaining formatting information 58text Emit TEXT output 59underscores Replace XML-friendly "-"s with JSON friendly "_"s 60units Add the 'units' (XML) or 'data-units (HTML) attribute 61warn Emit warnings when libxo detects bad calls 62warn-xml Emit warnings in XML 63xml Emit XML output 64xpath Add XPath expressions (HTML) 65=============== ======================================================= 66 67Most of these option are simple and direct, but some require 68additional 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 91Brief Options 92------------- 93 94The brief options are simple single-letter aliases to the normal 95keywords, 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 121Color Mapping 122------------- 123 124The "colors" option takes a value that is a set of mappings from the 125pre-defined set of colors to new foreground and background colors. 126The value is a series of "fg/bg" values, separated by a "+". Each 127pair of "fg/bg" values gives the colors to which a basic color is 128mapped when used as a foreground or background color. The order is 129the mappings is: 130 131- black 132- red 133- green 134- yellow 135- blue 136- magenta 137- cyan 138- white 139 140Pairs may be skipped, leaving them mapped as normal, as are missing 141pairs or single colors. 142 143For example consider the following xo_emit call:: 144 145 xo_emit("{C:fg-red,bg-green}Merry XMas!!{C:}\n"); 146 147To turn all colored output to red-on-blue, use eight pairs of 148"red/blue" mappings separated by "+"s:: 149 150 --libxo colors=red/blue+red/blue+red/blue+red/blue+\ 151 red/blue+red/blue+red/blue+red/blue 152 153To turn the red-on-green text to magenta-on-cyan, give a "magenta" 154foreground value for red (the second mapping) and a "cyan" background 155to green (the third mapping):: 156 157 --libxo colors=+magenta+/cyan 158 159Consider the common situation where blue output looks unreadable on a 160terminal session with a black background. To turn both "blue" 161foreground and background output to "yellow", give only the fifth 162mapping, skipping the first four mappings with bare "+"s:: 163 164 --libxo colors=++++yellow/yellow 165