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 =============== ======================================================= 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 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 plus signs ("+"):: 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 plus signs ("+"):: 163 164 --libxo colors=++++yellow/yellow 165 166Encoders 167-------- 168 169In addition to the four "built-in" formats, libxo supports an 170extensible mechanism for adding encoders. These are activated 171using the "encoder" keyword:: 172 173 --libxo encoder=cbor 174 175The encoder can include encoder-specific options, separated by either 176colons (":") 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 181For brevity, the string "@" can be used in place of the string 182"encoder=". 183 184 df --libxo @csv:no-header 185