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 21The functions defined in 22.Nm 23are used to generate a choice of 24.Em TEXT , 25.Em XML , 26.Em JSON , 27or 28.Em HTML 29output. 30A common set of functions are used, with 31command line switches passed to the library to control the details of 32the output. 33.Pp 34Most commands emit text output aimed at humans. 35It is designed 36to be parsed and understood by a user. 37Humans are gifted at extracting 38details and pattern matching. 39Often programmers need to extract 40information from this human-oriented output. 41Programmers use tools 42like 43.Xr grep 1 , 44.Xr awk 1 , 45and regular expressions to ferret out the pieces of 46information they need. 47Such solutions are fragile and require 48updates when output contents change or evolve, requiring testing and 49validation. 50.Pp 51Modern tool developers favor encoding schemes like XML and JSON, 52which allow trivial parsing and extraction of data. 53Such formats are 54simple, well understood, hierarchical, easily parsed, and often 55integrate easier with common tools and environments. 56.Pp 57In addition, modern reality means that more output ends up in web 58browsers than in terminals, making HTML output valuable. 59.Pp 60.Nm 61allows a single set of function calls in source code to generate 62traditional text output, as well as XML and JSON formatted data. 63HTML 64can also be generated; "<div>" elements surround the traditional text 65output, with attributes that detail how to render the data. 66.Pp 67There are four encoding styles supported by 68.Nm : 69.Bl -bullet 70.It 71TEXT output can be display on a terminal session, allowing 72compatibility with traditional command line usage. 73.It 74XML output is suitable for tools like XPath and protocols like 75NETCONF. 76.It 77JSON output can be used for RESTful APIs and integration with 78languages like Javascript and Python. 79.It 80HTML can be matched with a small CSS file to permit rendering in any 81HTML5 browser. 82.El 83.Pp 84In general, XML and JSON are suitable for encoding data, while TEXT is 85suited for terminal output and HTML is suited for display in a web 86browser (see 87.Xr xohtml 1 ). 88.Pp 89The 90.Nm 91library allows an application to generate text, XML, JSON, 92and HTML output using a common set of function calls. 93The application 94decides at run time which output style should be produced. 95The 96application calls a function 97.Xr xo_emit 3 98to product output that is 99described in a format string. 100A 101.Dq field descriptor 102tells 103.Nm 104what the field is and what it means. 105Each field descriptor is placed in 106braces 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 113Each field can have a role, with the 'value' role being the default, 114and the role tells 115.Nm 116how and when to render that field, as well as 117a 118.Xr printf 3 Ns -like 119format string. 120.Pp 121Output 122can then be generated in various style, using the "--libxo" option. 123.Sh DEFAULT HANDLE 124Handles give an abstraction for 125.Nm 126that encapsulates the state of a 127stream of output. 128Handles have the data type "xo_handle_t" and are 129opaque to the caller. 130.Pp 131The library has a default handle that is automatically initialized. 132By default, this handle will send text style output to standard output. 133The 134.Xr xo_set_style 3 135and 136.Xr xo_set_flags 3 137functions can be used to change this 138behavior. 139.Pp 140Many 141.Nm 142functions take a handle as their first parameter; most that 143do not use the default handle. 144Any function taking a handle can 145be passed 146.Dv NULL 147to access the default handle. 148.Pp 149For the typical command that is generating output on standard output, 150there is no need to create an explicit handle, but they are available 151when needed, e.g., for daemons that generate multiple streams of 152output. 153.Sh FUNCTION OVERVIEW 154The 155.Nm 156library 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 162Allows the caller to emit XML attributes with the next open element. 163.It Fn xo_create 164.It Fn xo_create_to_file 165Allow the caller to create a new handle. 166Note that 167.Nm 168has a default handle that allows the caller to avoid use of an 169explicitly created handle. 170Only callers writing to files other than 171.Dv stdout 172would need to call 173.Fn xo_create . 174.It Fn xo_destroy 175Frees any resources associated with the handle, including the handle 176itself. 177.It Fn xo_emit 178.It Fn xo_emit_h 179.It Fn xo_emit_hv 180Emit formatted output. 181The 182.Fa fmt 183string controls the conversion of the remaining arguments into 184formatted output. 185See 186.Xr xo_format 5 187for 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 195These functions are mildly compatible with their standard libc 196namesakes, but use the format string defined in 197.Xr xo_format 5 . 198While there is an increased cost for converting the strings, the 199output 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 212These functions are meant to be compatible with their standard libc namesakes. 213.It Fn xo_finish 214.It Fn xo_finish_h 215Flush output, close open construct, and complete any pending 216operations. 217.It Fn xo_flush 218.It Fn xo_flush_h 219Allow the caller to flush any pending output for a handle. 220.It Fn xo_no_setlocale 221Direct 222.Nm 223to avoid initializing the locale. 224This function should be called before any other 225.Nm 226function 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 235Containers a singleton levels of hierarchy, typically used to organize 236related 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 253Lists are levels of hierarchy that can appear multiple times within 254the same parent. 255Two calls are needed to encapsulate them, one for 256the list and one for each instance of that list. 257Typically 258.Fn xo_open_list 259and 260.Fn xo_close_list 261are called outside a 262for-loop, where 263.Fn xo_open_instance 264it called at the top of the loop, and 265.Fn xo_close_instance 266is called at the bottom of the loop. 267.It Fn xo_parse_args 268Inspects command line arguments for directions to 269.Nm . 270This function should be called before 271.Va argv 272is inspected by the application. 273.It Fn xo_set_allocator 274Instructs 275.Nm 276to use an alternative memory allocator and deallocator. 277.It Fn xo_set_flags 278.It Fn xo_clear_flags 279Change the flags set for a handle. 280.It Fn xo_set_info 281Provides additional information about elements for use with HTML 282rendering. 283.It Fn xo_set_options 284Changes formatting options used by handle. 285.It Fn xo_set_style 286.It Fn xo_set_style_name 287Changes the output style used by a handle. 288.It Fn xo_set_writer 289Instructs 290.Nm 291to 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 315The 316.Nm libxo 317library first appeared in 318.Fx 11.0 . 319.Sh AUTHORS 320.Nm libxo 321was written by 322.An Phil Shafer Aq Mt phil@freebsd.org . 323 324