1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
.. 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 "+"s::
--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 "+"s::
--libxo colors=++++yellow/yellow
|
