2 .\" # Copyright (c) 2014, Juniper Networks, Inc.
3 .\" # All rights reserved.
4 .\" # This SOFTWARE is licensed under the LICENSE provided in the
5 .\" # ../Copyright file. By downloading, installing, copying, or
6 .\" # using the SOFTWARE, you agree to be bound by the terms of that
8 .\" # Phil Shafer, July 2014
15 .Nd library for emitting text, XML, JSON, or HTML output
21 The functions defined in
23 are used to generate a choice of
30 A common set of functions are used, with
31 command line switches passed to the library to control the details of
34 Most commands emit text output aimed at humans.
36 to be parsed and understood by a user.
37 Humans are gifted at extracting
38 details and pattern matching.
39 Often programmers need to extract
40 information from this human-oriented output.
45 and regular expressions to ferret out the pieces of
46 information they need.
47 Such solutions are fragile and require
48 updates when output contents change or evolve, requiring testing and
51 Modern tool developers favor encoding schemes like XML and JSON,
52 which allow trivial parsing and extraction of data.
54 simple, well understood, hierarchical, easily parsed, and often
55 integrate easier with common tools and environments.
57 In addition, modern reality means that more output ends up in web
58 browsers than in terminals, making HTML output valuable.
61 allows a single set of function calls in source code to generate
62 traditional text output, as well as XML and JSON formatted data.
64 can also be generated; "<div>" elements surround the traditional text
65 output, with attributes that detail how to render the data.
67 There are four encoding styles supported by
71 TEXT output can be display on a terminal session, allowing
72 compatibility with traditional command line usage.
74 XML output is suitable for tools like XPath and protocols like
77 JSON output can be used for RESTful APIs and integration with
78 languages like Javascript and Python.
80 HTML can be matched with a small CSS file to permit rendering in any
84 In general, XML and JSON are suitable for encoding data, while TEXT is
85 suited for terminal output and HTML is suited for display in a web
91 library allows an application to generate text, XML, JSON,
92 and HTML output using a common set of function calls.
94 decides at run time which output style should be produced.
96 application calls a function
98 to product output that is
99 described in a format string.
104 what the field is and what it means.
105 Each field descriptor is placed in
106 braces with a printf-like format string:
107 .Bd -literal -offset indent
108 xo_emit(" {:lines/%7ju} {:words/%7ju} "
109 "{:characters/%7ju}{d:filename/%s}\\n",
110 linect, wordct, charct, file);
113 Each field can have a role, with the 'value' role being the default,
116 how and when to render that field, as well as
118 .Xr printf 3 Ns -like
122 can then be generated in various style, using the "--libxo" option.
124 Handles give an abstraction for
126 that encapsulates the state of a
128 Handles have the data type "xo_handle_t" and are
129 opaque to the caller.
131 The library has a default handle that is automatically initialized.
132 By default, this handle will send text style output to standard output.
137 functions can be used to change this
142 functions take a handle as their first parameter; most that
143 do not use the default handle.
144 Any function taking a handle can
147 to access the default handle.
149 For the typical command that is generating output on standard output,
150 there is no need to create an explicit handle, but they are available
151 when needed, e.g., for daemons that generate multiple streams of
153 .Sh FUNCTION OVERVIEW
156 library includes the following functions:
157 .Bl -tag -width "xo_close_container_hd"
158 .It Sy "Function Description"
162 Allows the caller to emit XML attributes with the next open element.
164 .It Fn xo_create_to_file
165 Allow the caller to create a new handle.
168 has a default handle that allows the caller to avoid use of an
169 explicitly created handle.
170 Only callers writing to files other than
175 Frees any resources associated with the handle, including the handle
180 Emit formatted output.
183 string controls the conversion of the remaining arguments into
190 .It Fn xo_emit_warn_c
191 .It Fn xo_emit_warn_hc
195 These functions are mildly compatible with their standard libc
196 namesakes, but use the format string defined in
198 While there is an increased cost for converting the strings, the
199 output provided can be richer and more useful. See also
211 .It Fn xo_message_hcv
212 These functions are meant to be compatible with their standard libc namesakes.
215 Flush output, close open construct, and complete any pending
219 Allow the caller to flush any pending output for a handle.
220 .It Fn xo_no_setlocale
223 to avoid initializing the locale.
224 This function should be called before any other
227 .It Fn xo_open_container
228 .It Fn xo_open_container_h
229 .It Fn xo_open_container_hd
230 .It Fn xo_open_container_d
231 .It Fn xo_close_container
232 .It Fn xo_close_container_h
233 .It Fn xo_close_container_hd
234 .It Fn xo_close_container_d
235 Containers a singleton levels of hierarchy, typically used to organize
237 .It Fn xo_open_list_h
239 .It Fn xo_open_list_hd
240 .It Fn xo_open_list_d
241 .It Fn xo_open_instance_h
242 .It Fn xo_open_instance
243 .It Fn xo_open_instance_hd
244 .It Fn xo_open_instance_d
245 .It Fn xo_close_instance_h
246 .It Fn xo_close_instance
247 .It Fn xo_close_instance_hd
248 .It Fn xo_close_instance_d
249 .It Fn xo_close_list_h
251 .It Fn xo_close_list_hd
252 .It Fn xo_close_list_d
253 Lists are levels of hierarchy that can appear multiple times within
255 Two calls are needed to encapsulate them, one for
256 the list and one for each instance of that list.
264 it called at the top of the loop, and
265 .Fn xo_close_instance
266 is called at the bottom of the loop.
268 Inspects command line arguments for directions to
270 This function should be called before
272 is inspected by the application.
273 .It Fn xo_set_allocator
276 to use an alternative memory allocator and deallocator.
278 .It Fn xo_clear_flags
279 Change the flags set for a handle.
281 Provides additional information about elements for use with HTML
283 .It Fn xo_set_options
284 Changes formatting options used by handle.
286 .It Fn xo_set_style_name
287 Changes the output style used by a handle.
291 to use an alternative set of low-level output functions.
303 .Xr xo_no_setlocale 3 ,
304 .Xr xo_open_container 3 ,
306 .Xr xo_parse_args 3 ,
307 .Xr xo_set_allocator 3 ,
310 .Xr xo_set_options 3 ,
312 .Xr xo_set_writer 3 ,
317 library first appeared in
322 .An Phil Shafer Aq Mt phil@freebsd.org .