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
|
.\" #
.\" # Copyright (c) 2014-2017, Juniper Networks, Inc.
.\" # All rights reserved.
.\" # This SOFTWARE is licensed under the LICENSE provided in the
.\" # ../Copyright file. By downloading, installing, copying, or
.\" # using the SOFTWARE, you agree to be bound by the terms of that
.\" # LICENSE.
.\" # Phil Shafer, July 2014
.\"
.Dd May 11, 2017
.Dt LIBXO 3
.Os
.Sh NAME
.Nm xo_options
.Nd common options for libxo\-based commands
.Sh DESCRIPTION
.Pp
.Nm libxo
allows the rendering of data into
various output styles, including
.Em text ,
.Em XML ,
.Em JSON ,
and
.Em HTML .
.Nm libxo
uses command line options to trigger rendering behavior.
Options are recognised in three forms:
.Bl -bullet
.It
\-\-libxo <options>
.It
\-\-libxo=<options>
.It
\-\-libxo:<brief\-options>
.El
.Pp
The first two forms accept a comma\-separated set of words, detailed
below, while the third form accepts a set of letters, also below.
The triggered functionality is identical.
.Bl -column "Token2341234"
.It Sy "Option " "Action"
.It "color " "Enable colors/effects for display styles (TEXT, HTML)"
.It "flush " "Flush after each emit call"
.It "flush\-line " "Flush each line of output"
.It "html " "Emit HTML output"
.It "indent=xx " "Set the indentation level"
.It "info " "Add info attributes (HTML)"
.It "json " "Emit JSON output"
.It "keys " "Emit the key attribute for keys (XML)"
.It "log\-gettext" "Log (via stderr) each gettext(3) string lookup"
.It "log\-syslog " "Log (via stderr) each syslog message (via xo_syslog)"
.It "no\-humanize" "Ignore the {h:} modifier (TEXT, HTML)"
.It "no\-locale " "Do not initialize the locale setting"
.It "no\-retain " "Prevent retaining formatting information"
.It "pretty " "Emit pretty\-printed output"
.It "retain " "Force retaining formatting information"
.It "text " "Emit TEXT output"
.It "underscores" "Replace XML\-friendly \"\-\"s with JSON friendly \"_\"s"
.It "units " "Add the 'units' (XML) or 'data\-units (HTML) attribute"
.It "warn " "Emit warnings when libxo detects bad calls"
.It "warn\-xml " "Emit warnings in XML"
.It "xml " "Emit XML output"
.It "xpath " "Add XPath expressions (HTML)"
.El
.Pp
The brief options are a set of single\-letter aliases for the longer
terms, used as a single string:
.Bl -column "Value" "Equivalent Token"
.It Sy "Value" "Equivalent Token"
.It "c
.It "f " "flush"
.It "F " "flush\-line"
.It "H " "html"
.It "I " "info"
.It "i<num>" "indent=<num>"
.It "J " "json"
.It "k " "keys"
.It "n " "no\-humanize"
.It "P " "pretty"
.It "T " "text"
.It "U " "units"
.It "u " "underscore
.It "W " "warn"
.It "X " "xml"
.It "x " "xpath"
.El
.Pp
Most of these option are simple and direct, but some require
additional details:
.Pp
.Fa "flush\-line"
performs line buffering, even when the output is not directed to
a TTY device.
.Pp
.Fa info
generates additional data for HTML, encoded in attributes using
names that state with "data\-".
.Pp
.Fa keys
adds a "key" attribute for XML output to indicate that a leaf is
an identifier for the list member.
.Pp
.Fa no\-humanize
avoids "humanizing" numeric output (see
.Xr humanize_number 3
for details).
.Pp
.Fa no\-locale
instructs
.Nm libxo
to avoid translating output to the current locale.
.Pp
.Fa no\-retain
disables the ability of
.Nm libxo
to internally retain "compiled" information about formatting strings.
.Pp
.Fa underscores
can be used with
.Em JSON
output to change
.Em XML \-friendly
names with dashes into
.Em JSON \-friendly
name with underscores.
.Pp
.Fa warn
allows
.Nm libxo
to emit warnings on stderr when application code make incorrect calls.
.Fa warn\-xml causes those warnings to be placed in
.Em XML
inside the output.
.Sh EXAMPLES
The following are three example invocations of
.Xr ps 1 :
.Bd -literal
ps \-\-libxo json,pretty,warn \-ux
ps \-\-libxo=xml \-lg
ps \-\-libxo:Hxc 1
.Ed
.Sh SEE ALSO
.Xr libxo 3 ,
.Xr xo_format 5
|
