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 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 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 In addition, modern reality means that more output ends up in web
32 browsers than in terminals, making HTML output valuable.
33 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 There are four encoding styles supported by libxo:
40 • TEXT output can be display on a terminal session, allowing compati‐
42 bility with traditional command line usage.
43 • XML output is suitable for tools like XPath and protocols like NET‐
45 CONF.
46 • JSON output can be used for RESTful APIs and integration with lan‐
48 guages like Javascript and Python.
49 • HTML can be matched with a small CSS file to permit rendering in any
51 HTML5 browser.
52 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 libxo uses command line options to trigger rendering behavior. The fol‐
58 lowing options are recognised:
59 --libxo <options>
61 --libxo=<options>
62 --libxo:<brief-options>
63 Options is a comma-separated list of tokens that correspond to output
65 styles, flags, or features:
66 Token Action
68 dtrt Enable "Do The Right Thing" mode
70 html Emit HTML output
72 indent=xx
74 Set the indentation level
75 info Add info attributes (HTML)
77 json Emit JSON output
79 keys Emit the key attribute for keys (XML)
81 log-gettext
83 Log (via stderr) each gettext(3) string lookup
84 log-syslog
86 Log (via stderr) each syslog message (via xo_syslog(3))
87 no-humanize
89 Ignore the {h:} modifier (TEXT, HTML)
90 no-locale
92 Do not initialize the locale setting
93 no-retain
95 Prevent retaining formatting information
96 no-top Do not emit a top set of braces (JSON)
98 not-first
100 Pretend the 1st output item was not 1st (JSON)
101 pretty Emit pretty-printed output
103 retain Force retaining formatting information
105 text Emit TEXT output
107 underscores
109 Replace XML-friendly "-"s with JSON friendly "_"s e
110 units Add the 'units' (XML) or 'data-units (HTML) attribute
112 warn Emit warnings when libxo detects bad calls
114 warn-xml Emit warnings in XML
116 xml Emit XML output
118 xpath Add XPath expressions (HTML)
120 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 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 Refer to xo_options(7) for additional option information.
136 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 xo_emit(" {:lines/%7ju} {:words/%7ju} "
146 "{:characters/%7ju}{d:filename/%s}\n",
147 linect, wordct, charct, file);
148 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 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 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 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 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 Function Description
178 xo_attr()
180 xo_attr_h()
182 xo_attr_hv() Allows the caller to emit XML attributes with the
184 next open element.
185 xo_create()
187 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 xo_destroy() Frees any resources associated with the handle,
195 including the handle itself.
196 xo_emit()
198 xo_emit_h()
200 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 xo_emit_warn()
206 xo_emit_warnx()
208 xo_emit_warn_c()
210 xo_emit_warn_hc()
212 xo_emit_err()
214 xo_emit_errc()
216 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 xo_warn()
225 xo_warnx()
227 xo_warn_c()
229 xo_warn_hc()
231 xo_err()
233 xo_errc()
235 xo_errx()
237 xo_message()
239 xo_message_c()
241 xo_message_hc()
243 xo_message_hcv() These functions are meant to be compatible with
245 their standard libc namesakes.
246 xo_finish()
248 xo_finish_h() Flush output, close open construct, and complete
250 any pending operations.
251 xo_flush()
253 xo_flush_h() Allow the caller to flush any pending output for a
255 handle.
256 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 xo_open_container()
262 xo_open_container_h()
264 xo_open_container_hd()
266 xo_open_container_d()
268 xo_close_container()
270 xo_close_container_h()
272 xo_close_container_hd()
274 xo_close_container_d()
276 Containers a singleton levels of hierarchy, typi‐
277 cally used to organize related content.
278 xo_open_list_h()
280 xo_open_list()
282 xo_open_list_hd()
284 xo_open_list_d()
286 xo_open_instance_h()
288 xo_open_instance()
290 xo_open_instance_hd()
292 xo_open_instance_d()
294 xo_close_instance_h()
296 xo_close_instance()
298 xo_close_instance_hd()
300 xo_close_instance_d()
302 xo_close_list_h()
304 xo_close_list()
306 xo_close_list_hd()
308 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 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 xo_set_allocator() Instructs libxo to use an alternative memory allo‐
324 cator and deallocator.
325 xo_set_flags()
327 xo_clear_flags() Change the flags set for a handle.
329 xo_set_info() Provides additional information about elements for
331 use with HTML rendering.
332 xo_set_options() Changes formatting options used by handle.
334 xo_set_style()
336 xo_set_style_name() Changes the output style used by a handle.
338 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
357 FreeBSD uses libxo version 1.6.0. Complete documentation can be found on
358 github:
359 https://juniper.github.io/libxo/1.6.0/html/index.html
361 libxo lives on github as:
363 https://github.com/Juniper/libxo
365 The latest release of libxo is available at:
367 https://github.com/Juniper/libxo/releases
369
371 The libxo library was added in FreeBSD 11.0.
372
374 Phil Shafer
375BSD December 8, 2014 BSD