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 July, 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 .Lb libxo
  23 are used to generate a choice of
  24 .Em TEXT ,
  25 .Em XML ,
  26 .Em JSON ,
  27 or
  28 .Em HTML
  29 output.  A common set of functions are used, with
  30 command line switches passed to the library to control the details of
  31 the output.
  32 .Pp
  33 Most commands emit text output aimed at humans.  It is designed
  34 to be parsed and understood by a user.  Humans are gifted at extracted
  35 details and pattern matching.  Often programmers need to extract
  36 information from this human-oriented output.  Programmers use tools
  37 like grep, awk, and regular expressions to ferret out the pieces of
  38 information they need.  Such solutions are fragile and require
  39 updates when output contents change or evolve, requiring testing and
  40 validation.
  41 .Pp
  42 Modern tool developers favors encoding schemes like XML and JSON,
  43 which allow trivial parsing and extraction of data.  Such formats are
  44 simple, well understood, hierarchical, easily parsed, and often
  45 integrate easier with common tools and environments.
  46 .Pp
  47 In addition, modern reality means that more output ends up in web
  48 browsers than in terminals, making HTML output valuable.
  49 .Pp
  50 .Em libxo
  51 allows a single set of function calls in source code to generate
  52 traditional text output, as well as XML and JSON formatted data.  HTML
  53 can also be generated; "<div>" elements surround the traditional text
  54 output, with attributes that detail how to render the data.
  55 .Pp
  56 There are four encoding styles supported by libxo: TEXT, HTML, JSON,
  57 and XML.  JSON and XML are suitable for encoding data, while TEXT and
  58 HTML are suited for display to the user.  TEXT output can be display
  59 on a terminal session, allowing compatibility with traditional usage.
  60 HTML can be matched with a small CSS file to permit rendering in any
  61 HTML5 browser.  XML output is suitable for tools like XPath and
  62 protocols like NETCONF.  JSON output can be used for RESTful APIs.
  63 .Pp
  64 The
  65 .Em libxo
  66 library allows an application to generate text, XML, JSON,
  67 and HTML output using a common set of function calls.  The application
  68 decides at run time which output style should be produced.  The
  69 application calls a function
  70 .Fn xo_emit
  71 to product output that is
  72 described in a format string.  A "field descriptor" tells libxo what
  73 the field is and what it means.  Each field descriptor is placed in
  74 braces with a printf-like format string:
  75 .Bd -literal -offset indent
  76     xo_emit(" {:lines/%7ju} {:words/%7ju} "
  77             "{:characters/%7ju}{d:filename/%s}\\n",
  78             linect, wordct, charct, file);
  79 .Ed
  80 .Pp
  81 Each field can have a role, with the 'value' role being the default,
  82 and the role tells libxo how and when to render that field, as well as
  83 a
  84 .Xr printf 3 -like
  85 format string.
  86 .Pp
  87 Output
  88 can then be generated in various style, using the "--libxo" option.
  89 .Sh DEFAULT HANDLE
  90 Handles give an abstraction for libxo that encapsulates the state of a
  91 stream of output.  Handles have the data type "xo_handle_t" and are
  92 opaque to the caller.
  93
  94 The library has a default handle that is automatically initialized.
  95 By default, this handle will send text style output to standard output.
  96 The xo_set_style and xo_set_flags functions can be used to change this
  97 behavior.
  98
  99 Many libxo functions take a handle as their first parameter; most that
 100 do not use the default handle.  Any function taking a handle can
 101 be passed NULL to access the default handle.
 102
 103 For the typical command that is generating output on standard output,
 104 there is no need to create an explicit handle, but they are available
 105 when needed, e.g. for daemons that generate multiple streams of
 106 output.
 107 .Sh ADDITIONAL DOCUMENTATION
 108 .Pp
 109 Complete documentation can be found on github:
 110 .Bd -literal -offset indent
 111 http://juniper.github.io/libxo/libxo-manual.html
 112 .Ed
 113 .Pp
 114 libxo lives on github as:
 115 .Bd -literal -offset indent
 116 https://github.com/Juniper/libxo
 117 .Ed
 118 .Pp
 119 The latest release of libxo is available at:
 120 .Bd -literal -offset indent
 121 https://github.com/Juniper/libxo/releases
 122 .Ed
 123 .Sh SEE ALSO
 124 .Xr xo_attr 3 ,
 125 .Xr xo_create 3 ,
 126 .Xr xo_emit 3 ,
 127 .Xr xo_err 3 ,
 128 .Xr xo_finish 3 ,
 129 .Xr xo_flush 3 ,
 130 .Xr xo_format 5 ,
 131 .Xr xo_no_setlocale 3 ,
 132 .Xr xo_open_container 3 ,
 133 .Xr xo_open_list 3 ,
 134 .Xr xo_parse_args 3 ,
 135 .Xr xo_set_allocator 3 ,
 136 .Xr xo_set_flags 3 ,
 137 .Xr xo_set_info 3 ,
 138 .Xr xo_set_options 3 ,
 139 .Xr xo_set_style 3 ,
 140 .Xr xo_set_writer 3 ,
 141 .Xr xo 1 ,
 142 and
 143 .Xr xolint 1 .
 144 .Sh HISTORY
 145 The
 146 .Fa libxo
 147 library was added in FreeBSD 11.0.
 148 .Sh AUTHOR
 149 Phil Shafer