1LIBXO(3) BSD Library Functions Manual LIBXO(3)
2
4 libxo — library for emitting text, XML, JSON, or HTML output
5
7 library “libxo”
8
10 #include <libxo/xo.h>
11
13 The functions defined in libxo are used to generate a choice of TEXT,
14 XML, JSON, or HTML output. A common set of functions are used, with com‐
15 mand line switches passed to the library to control the details of the
16 output.
17
18 Most commands emit text output aimed at humans. It is designed to be
19 parsed and understood by a user. Humans are gifted at extracting details
20 and pattern matching. Often programmers need to extract information from
21 this human-oriented output. Programmers use tools like grep(1), awk(1),
22 and regular expressions to ferret out the pieces of information they
23 need. Such solutions are fragile and require updates when output con‐
24 tents change or evolve, requiring testing and validation.
25
26 Modern tool developers favor encoding schemes like XML and JSON, which
27 allow trivial parsing and extraction of data. Such formats are simple,
28 well understood, hierarchical, easily parsed, and often integrate easier
29 with common tools and environments.
30
31 In addition, modern reality means that more output ends up in web
32 browsers than in terminals, making HTML output valuable.
33
34 libxo allows a single set of function calls in source code to generate
35 traditional text output, as well as XML and JSON formatted data. HTML
36 can also be generated; "<div>" elements surround the traditional text
37 output, with attributes that detail how to render the data.
38
39 There are four encoding styles supported by libxo:
40
41 • TEXT output can be display on a terminal session, allowing compati‐
42 bility with traditional command line usage.
43
44 • XML output is suitable for tools like XPath and protocols like NET‐
45 CONF.
46
47 • JSON output can be used for RESTful APIs and integration with lan‐
48 guages like Javascript and Python.
49
50 • HTML can be matched with a small CSS file to permit rendering in any
51 HTML5 browser.
52
53 In general, XML and JSON are suitable for encoding data, while TEXT is
54 suited for terminal output and HTML is suited for display in a web
55 browser (see xohtml(1) ).
56
57 libxo uses command line options to trigger rendering behavior. The fol‐
58 lowing options are recognised:
59
60 --libxo <options>
61 --libxo=<options>
62 --libxo:<brief-options>
63
64 Options is a comma-separated list of tokens that correspond to output
65 styles, flags, or features:
66
67 Token Action
68
69 dtrt Enable "Do The Right Thing" mode
70
71 html Emit HTML output
72
73 indent=xx
74 Set the indentation level
75
76 info Add info attributes (HTML)
77
78 json Emit JSON output
79
80 keys Emit the key attribute for keys (XML)
81
82 log-gettext
83 Log (via stderr) each gettext(3) string lookup
84
85 log-syslog
86 Log (via stderr) each syslog message (via xo_syslog(3))
87
88 no-humanize
89 Ignore the {h:} modifier (TEXT, HTML)
90
91 no-locale
92 Do not initialize the locale setting
93
94 no-retain
95 Prevent retaining formatting information
96
97 no-top Do not emit a top set of braces (JSON)
98
99 not-first
100 Pretend the 1st output item was not 1st (JSON)
101
102 pretty Emit pretty-printed output
103
104 retain Force retaining formatting information
105
106 text Emit TEXT output
107
108 underscores
109 Replace XML-friendly "-"s with JSON friendly "_"s e
110
111 units Add the 'units' (XML) or 'data-units (HTML) attribute
112
113 warn Emit warnings when libxo detects bad calls
114
115 warn-xml Emit warnings in XML
116
117 xml Emit XML output
118
119 xpath Add XPath expressions (HTML)
120
121 The “brief-options” are single letter commands, designed for those with
122 too little patience to use real tokens. No comma separator is used.
123
124 Token Action
125 H Enable HTML output (XO_STYLE_HTML)
126 I Enable info output (XOF_INFO)
127 i<num> Indent by <number>
128 J Enable JSON output (XO_STYLE_JSON)
129 P Enable pretty-printed output (XOF_PRETTY)
130 T Enable text output (XO_STYLE_TEXT)
131 W Enable warnings (XOF_WARN)
132 X Enable XML output (XO_STYLE_XML)
133 x Enable XPath data (XOF_XPATH)
134
135 Refer to xo_options(7) for additional option information.
136
137 The libxo library allows an application to generate text, XML, JSON, and
138 HTML output using a common set of function calls. The application de‐
139 cides at run time which output style should be produced. The application
140 calls a function xo_emit(3) to product output that is described in a for‐
141 mat string. A “field descriptor” tells libxo what the field is and what
142 it means. Each field descriptor is placed in braces with a printf-like
143 format string:
144
145 xo_emit(" {:lines/%7ju} {:words/%7ju} "
146 "{:characters/%7ju}{d:filename/%s}\n",
147 linect, wordct, charct, file);
148
149 Each field can have a role, with the 'value' role being the default, and
150 the role tells libxo how and when to render that field, as well as a
151 printf(3)-like format string.
152
153 Output can then be generated in various style, using the "--libxo" op‐
154 tion.
155
157 Handles give an abstraction for libxo that encapsulates the state of a
158 stream of output. Handles have the data type "xo_handle_t" and are
159 opaque to the caller.
160
161 The library has a default handle that is automatically initialized. By
162 default, this handle will send text style output to standard output. The
163 xo_set_style(3) and xo_set_flags(3) functions can be used to change this
164 behavior.
165
166 Many libxo functions take a handle as their first parameter; most that do
167 not use the default handle. Any function taking a handle can be passed
168 NULL to access the default handle.
169
170 For the typical command that is generating output on standard output,
171 there is no need to create an explicit handle, but they are available
172 when needed, e.g., for daemons that generate multiple streams of output.
173
175 The libxo library includes the following functions:
176
177 Function Description
178
179 xo_attr()
180
181 xo_attr_h()
182
183 xo_attr_hv() Allows the caller to emit XML attributes with the
184 next open element.
185
186 xo_create()
187
188 xo_create_to_file() Allow the caller to create a new handle. Note
189 that libxo has a default handle that allows the
190 caller to avoid use of an explicitly created han‐
191 dle. Only callers writing to files other than
192 stdout would need to call xo_create().
193
194 xo_destroy() Frees any resources associated with the handle,
195 including the handle itself.
196
197 xo_emit()
198
199 xo_emit_h()
200
201 xo_emit_hv() Emit formatted output. The fmt string controls
202 the conversion of the remaining arguments into
203 formatted output. See xo_format(5) for details.
204
205 xo_emit_warn()
206
207 xo_emit_warnx()
208
209 xo_emit_warn_c()
210
211 xo_emit_warn_hc()
212
213 xo_emit_err()
214
215 xo_emit_errc()
216
217 xo_emit_errx() These functions are mildly compatible with their
218 standard libc namesakes, but use the format string
219 defined in xo_format(5). While there is an in‐
220 creased cost for converting the strings, the out‐
221 put provided can be richer and more useful. See
222 also xo_err(3)
223
224 xo_warn()
225
226 xo_warnx()
227
228 xo_warn_c()
229
230 xo_warn_hc()
231
232 xo_err()
233
234 xo_errc()
235
236 xo_errx()
237
238 xo_message()
239
240 xo_message_c()
241
242 xo_message_hc()
243
244 xo_message_hcv() These functions are meant to be compatible with
245 their standard libc namesakes.
246
247 xo_finish()
248
249 xo_finish_h() Flush output, close open construct, and complete
250 any pending operations.
251
252 xo_flush()
253
254 xo_flush_h() Allow the caller to flush any pending output for a
255 handle.
256
257 xo_no_setlocale() Direct libxo to avoid initializing the locale.
258 This function should be called before any other
259 libxo function is called.
260
261 xo_open_container()
262
263 xo_open_container_h()
264
265 xo_open_container_hd()
266
267 xo_open_container_d()
268
269 xo_close_container()
270
271 xo_close_container_h()
272
273 xo_close_container_hd()
274
275 xo_close_container_d()
276 Containers a singleton levels of hierarchy, typi‐
277 cally used to organize related content.
278
279 xo_open_list_h()
280
281 xo_open_list()
282
283 xo_open_list_hd()
284
285 xo_open_list_d()
286
287 xo_open_instance_h()
288
289 xo_open_instance()
290
291 xo_open_instance_hd()
292
293 xo_open_instance_d()
294
295 xo_close_instance_h()
296
297 xo_close_instance()
298
299 xo_close_instance_hd()
300
301 xo_close_instance_d()
302
303 xo_close_list_h()
304
305 xo_close_list()
306
307 xo_close_list_hd()
308
309 xo_close_list_d() Lists are levels of hierarchy that can appear mul‐
310 tiple times within the same parent. Two calls are
311 needed to encapsulate them, one for the list and
312 one for each instance of that list. Typically
313 xo_open_list() and xo_close_list() are called out‐
314 side a for-loop, where xo_open_instance() it
315 called at the top of the loop, and
316 xo_close_instance() is called at the bottom of the
317 loop.
318
319 xo_parse_args() Inspects command line arguments for directions to
320 libxo. This function should be called before argv
321 is inspected by the application.
322
323 xo_set_allocator() Instructs libxo to use an alternative memory allo‐
324 cator and deallocator.
325
326 xo_set_flags()
327
328 xo_clear_flags() Change the flags set for a handle.
329
330 xo_set_info() Provides additional information about elements for
331 use with HTML rendering.
332
333 xo_set_options() Changes formatting options used by handle.
334
335 xo_set_style()
336
337 xo_set_style_name() Changes the output style used by a handle.
338
339 xo_set_writer() Instructs libxo to use an alternative set of low-
340 level output functions.
341
343 libxo-csv(7,) xo(1), xolint(1), xo_attr(3), xo_create(3), xo_emit(3),
344 xo_emit_err(3), xo_err(3), xo_finish(3), xo_flush(3), xo_no_setlocale(3),
345 xo_open_container(3), xo_open_list(3), xo_options(7,) xo_parse_args(3),
346 xo_set_allocator(3), xo_set_flags(3), xo_set_info(3), xo_set_options(3),
347 xo_set_style(3), xo_set_writer(3), xo_format(5)
348
350 The libxo library first appeared in FreeBSD 11.0.
351
353 libxo was written by Phil Shafer <phil@freebsd.org>.
354
355
357 FreeBSD uses libxo version 1.6.0. Complete documentation can be found on
358 github:
359
360 https://juniper.github.io/libxo/1.6.0/html/index.html
361
362 libxo lives on github as:
363
364 https://github.com/Juniper/libxo
365
366 The latest release of libxo is available at:
367
368 https://github.com/Juniper/libxo/releases
369
371 The libxo library was added in FreeBSD 11.0.
372
374 Phil Shafer
375
376BSD December 8, 2014 BSD