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
|
.\" #
.\" # Copyright (c) 2014, 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 December 4, 2014
.Dt LIBXO 3
.Os
.Sh NAME
.Nm xo_parse_args , xo_set_program
.Nd detect, parse, and remove arguments for libxo
.Sh LIBRARY
.Lb libxo
.Sh SYNOPSIS
.In libxo/xo.h
.Ft int
.Fn xo_parse_args "int argc" "char **argv"
.Ft int
.Fn xo_set_program "const char *name"
.Sh DESCRIPTION
The
.Fn xo_parse_args
function is used to process command-line arguments.
.Nm libxo
specific
options are processed and removed
from the argument list so the calling application does not
need to process them.
If successful, a new value for argc is returned.
On failure, a message it emitted and -1 is returned.
.Bd -literal -offset indent
argc = xo_parse_args(argc, argv);
if (argc < 0)
exit(EXIT_FAILURE);
.Ed
.Pp
Following the call to
.Fn xo_parse_args ,
the application can process the remaining arguments in a normal manner.
.Pp
.Nm libxo
uses command line options to trigger rendering behavior.
The following options are recognised:
.Pp
.Bl -tag -width "--libxo"
.It
\-\^\-libxo <options>
.It
\-\^\-libxo=<options>
.It
\-\^\-libxo:<brief-options>
.El
.Pp
Options is a comma-separated list of tokens that correspond to output
styles, flags, or features:
.Pp
.Bl -tag -width "12345678"
.It Sy "Token Action"
.It Dv dtrt
Enable "Do The Right Thing" mode
.It Dv html
Emit HTML output
.It Dv indent=xx
Set the indentation level
.It Dv info
Add info attributes (HTML)
.It Dv json
Emit JSON output
.It Dv keys
Emit the key attribute for keys (XML)
.It Dv log-gettext
Log (via stderr) each
.Xr gettext 3
string lookup
.It Dv log-syslog
Log (via stderr) each syslog message (via
.Xr xo_syslog 3 )
.If Dv no-humanize
Ignore the {h:} modifier (TEXT, HTML)
.It Dv no-locale
Do not initialize the locale setting
.It Dv no-retain
Prevent retaining formatting information
.It Dv no-top
Do not emit a top set of braces (JSON)
.It Dv not-first
Pretend the 1st output item was not 1st (JSON)
.It Dv pretty
Emit pretty-printed output
.It Dv retain
Force retaining formatting information
.It Dv text
Emit TEXT output
.If Dv underscores
Replace XML-friendly "-"s with JSON friendly "_"s e
.It Dv units
Add the 'units' (XML) or 'data-units (HTML) attribute
.It Dv warn
Emit warnings when libxo detects bad calls
.It Dv warn-xml
Emit warnings in XML
.It Dv xml
Emit XML output
.It Dv xpath
Add XPath expressions (HTML)
.El
.Pp
The
.Dq brief-options
are single letter commands, designed for those with
too little patience to use real tokens.
No comma separator is used.
.Bl -column "i<num>"
.It Sy "Token Action"
.It "H " "Enable HTML output (XO_STYLE_HTML)"
.It "I " "Enable info output (XOF_INFO)"
.It "i<num> " "Indent by <number>"
.It "J " "Enable JSON output (XO_STYLE_JSON)"
.It "P " "Enable pretty-printed output (XOF_PRETTY)"
.It "T " "Enable text output (XO_STYLE_TEXT)"
.It "W " "Enable warnings (XOF_WARN)"
.It "X " "Enable XML output (XO_STYLE_XML)"
.It "x " "Enable XPath data (XOF_XPATH)"
.El
.Pp
The
.Fn xo_set_program
function sets name of the program as reported by
functions like
.Fn xo_failure ,
.Fn xo_warn ,
.Fn xo_err ,
etc.
The program name is initialized by
.Fn xo_parse_args ,
but subsequent calls to
.Fn xo_set_program
can override this value.
.Pp
Note that the value is not copied, so the memory passed to
.Fn xo_set_program
(and
.Fn xo_parse_args )
must be maintained by the caller.
.Pp
.Sh SEE ALSO
.Xr xo_emit 3 ,
.Xr libxo 3
|
