contrib/libxo/libxo/libxo.3

   1 .\" #
   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
   7 .\" # LICENSE.
   8 .\" # Phil Shafer, July 2014
   9 .\"
  10 .Dd December 8, 2014
  11 .Dt LIBXO 3
  12 .Os
  13 .Sh NAME
  14 .Nm libxo
  15 .Nd library for emitting text, XML, JSON, or HTML output
  16 .Sh LIBRARY
  17 .Lb libxo
  18 .Sh SYNOPSIS
  19 .In libxo/xo.h
  20 .Sh DESCRIPTION
  21 The functions defined in
  22 .Nm
  23 are used to generate a choice of
  24 .Em TEXT ,
  25 .Em XML ,
  26 .Em JSON ,
  27 or
  28 .Em HTML
  29 output.
  30 A common set of functions are used, with
  31 command line switches passed to the library to control the details of
  32 the output.
  33 .Pp
  34 Most commands emit text output aimed at humans.
  35 It is designed
  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.
  41 Programmers use tools
  42 like
  43 .Xr grep 1 ,
  44 .Xr awk 1 ,
  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
  49 validation.
  50 .Pp
  51 Modern tool developers favor encoding schemes like XML and JSON,
  52 which allow trivial parsing and extraction of data.
  53 Such formats are
  54 simple, well understood, hierarchical, easily parsed, and often
  55 integrate easier with common tools and environments.
  56 .Pp
  57 In addition, modern reality means that more output ends up in web
  58 browsers than in terminals, making HTML output valuable.
  59 .Pp
  60 .Nm
  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.
  63 HTML
  64 can also be generated; "<div>" elements surround the traditional text
  65 output, with attributes that detail how to render the data.
  66 .Pp
  67 There are four encoding styles supported by
  68 .Nm :
  69 .Bl -bullet
  70 .It
  71 TEXT output can be display on a terminal session, allowing
  72 compatibility with traditional command line usage.
  73 .It
  74 XML output is suitable for tools like XPath and protocols like
  75 NETCONF.
  76 .It
  77 JSON output can be used for RESTful APIs and integration with
  78 languages like Javascript and Python.
  79 .It
  80 HTML can be matched with a small CSS file to permit rendering in any
  81 HTML5 browser.
  82 .El
  83 .Pp
  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
  86 browser (see
  87 .Xr xohtml 1 ).
  88 .Pp
  89 The
  90 .Nm
  91 library allows an application to generate text, XML, JSON,
  92 and HTML output using a common set of function calls.
  93 The application
  94 decides at run time which output style should be produced.
  95 The
  96 application calls a function
  97 .Xr xo_emit 3
  98 to product output that is
  99 described in a format string.
 100 A
 101 .Dq field descriptor
 102 tells
 103 .Nm
 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);
 111 .Ed
 112 .Pp
 113 Each field can have a role, with the 'value' role being the default,
 114 and the role tells
 115 .Nm
 116 how and when to render that field, as well as
 117 a
 118 .Xr printf 3 Ns -like
 119 format string.
 120 .Pp
 121 Output
 122 can then be generated in various style, using the "--libxo" option.
 123 .Sh DEFAULT HANDLE
 124 Handles give an abstraction for
 125 .Nm
 126 that encapsulates the state of a
 127 stream of output.
 128 Handles have the data type "xo_handle_t" and are
 129 opaque to the caller.
 130 .Pp
 131 The library has a default handle that is automatically initialized.
 132 By default, this handle will send text style output to standard output.
 133 The
 134 .Xr xo_set_style 3
 135 and
 136 .Xr xo_set_flags 3
 137 functions can be used to change this
 138 behavior.
 139 .Pp
 140 Many
 141 .Nm
 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
 145 be passed
 146 .Dv NULL
 147 to access the default handle.
 148 .Pp
 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
 152 output.
 153 .Sh FUNCTION OVERVIEW
 154 The
 155 .Nm
 156 library includes the following functions:
 157 .Bl -tag -width "xo_close_container_hd"
 158 .It Sy "Function               Description"
 159 .It Fn xo_attr
 160 .It Fn xo_attr_h
 161 .It Fn xo_attr_hv
 162 Allows the caller to emit XML attributes with the next open element.
 163 .It Fn xo_create
 164 .It Fn xo_create_to_file
 165 Allow the caller to create a new handle.
 166 Note that
 167 .Nm
 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
 171 .Dv stdout
 172 would need to call
 173 .Fn xo_create .
 174 .It Fn xo_destroy
 175 Frees any resources associated with the handle, including the handle
 176 itself.
 177 .It Fn xo_emit
 178 .It Fn xo_emit_h
 179 .It Fn xo_emit_hv
 180 Emit formatted output.
 181 The
 182 .Fa fmt
 183 string controls the conversion of the remaining arguments into
 184 formatted output.
 185 See
 186 .Xr xo_format 5
 187 for details.
 188 .It Fn xo_emit_warn
 189 .It Fn xo_emit_warnx
 190 .It Fn xo_emit_warn_c
 191 .It Fn xo_emit_warn_hc
 192 .It Fn xo_emit_err
 193 .It Fn xo_emit_errc
 194 .It Fn xo_emit_errx
 195 These functions are mildly compatible with their standard libc
 196 namesakes, but use the format string defined in
 197 .Xr xo_format 5 .
 198 While there is an increased cost for converting the strings, the
 199 output provided can be richer and more useful.   See also
 200 .Xr xo_err 3
 201 .It Fn xo_warn
 202 .It Fn xo_warnx
 203 .It Fn xo_warn_c
 204 .It Fn xo_warn_hc
 205 .It Fn xo_err
 206 .It Fn xo_errc
 207 .It Fn xo_errx
 208 .It Fn xo_message
 209 .It Fn xo_message_c
 210 .It Fn xo_message_hc
 211 .It Fn xo_message_hcv
 212 These functions are meant to be compatible with their standard libc namesakes.
 213 .It Fn xo_finish
 214 .It Fn xo_finish_h
 215 Flush output, close open construct, and complete any pending
 216 operations.
 217 .It Fn xo_flush
 218 .It Fn xo_flush_h
 219 Allow the caller to flush any pending output for a handle.
 220 .It Fn xo_no_setlocale
 221 Direct
 222 .Nm
 223 to avoid initializing the locale.
 224 This function should be called before any other
 225 .Nm
 226 function is called.
 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
 236 related content.
 237 .It Fn xo_open_list_h
 238 .It Fn xo_open_list
 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
 250 .It Fn xo_close_list
 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
 254 the same parent.
 255 Two calls are needed to encapsulate them, one for
 256 the list and one for each instance of that list.
 257 Typically
 258 .Fn xo_open_list
 259 and
 260 .Fn xo_close_list
 261 are called outside a
 262 for-loop, where
 263 .Fn xo_open_instance
 264 it called at the top of the loop, and
 265 .Fn xo_close_instance
 266 is called at the bottom of the loop.
 267 .It Fn xo_parse_args
 268 Inspects command line arguments for directions to
 269 .Nm .
 270 This function should be called before
 271 .Va argv
 272 is inspected by the application.
 273 .It Fn xo_set_allocator
 274 Instructs
 275 .Nm
 276 to use an alternative memory allocator and deallocator.
 277 .It Fn xo_set_flags
 278 .It Fn xo_clear_flags
 279 Change the flags set for a handle.
 280 .It Fn xo_set_info
 281 Provides additional information about elements for use with HTML
 282 rendering.
 283 .It Fn xo_set_options
 284 Changes formatting options used by handle.
 285 .It Fn xo_set_style
 286 .It Fn xo_set_style_name
 287 Changes the output style used by a handle.
 288 .It Fn xo_set_writer
 289 Instructs
 290 .Nm
 291 to use an alternative set of low-level output functions.
 292 .El
 293 .Sh SEE ALSO
 294 .Xr xo 1 ,
 295 .Xr xolint 1 ,
 296 .Xr xo_attr 3 ,
 297 .Xr xo_create 3 ,
 298 .Xr xo_emit 3 ,
 299 .Xr xo_emit_err 3 ,
 300 .Xr xo_err 3 ,
 301 .Xr xo_finish 3 ,
 302 .Xr xo_flush 3 ,
 303 .Xr xo_no_setlocale 3 ,
 304 .Xr xo_open_container 3 ,
 305 .Xr xo_open_list 3 ,
 306 .Xr xo_parse_args 3 ,
 307 .Xr xo_set_allocator 3 ,
 308 .Xr xo_set_flags 3 ,
 309 .Xr xo_set_info 3 ,
 310 .Xr xo_set_options 3 ,
 311 .Xr xo_set_style 3 ,
 312 .Xr xo_set_writer 3 ,
 313 .Xr xo_format 5
 314 .Sh HISTORY
 315 The
 316 .Nm libxo
 317 library first appeared in
 318 .Fx 11.0 .
 319 .Sh AUTHORS
 320 .Nm libxo
 321 was written by
 322 .An Phil Shafer Aq Mt phil@freebsd.org .
 323