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 89.Nm libxo 90uses command line options to trigger rendering behavior. 91The following options are recognised: 92.Pp 93.Bl -tag -width "--libxo" 94.It 95\-\^\-libxo <options> 96.It 97\-\^\-libxo=<options> 98.It 99\-\^\-libxo:<brief-options> 100.El 101.Pp 102Options is a comma-separated list of tokens that correspond to output 103styles, flags, or features: 104.Pp 105.Bl -tag -width "12345678" 106.It Sy "Token Action" 107.It Dv dtrt 108Enable "Do The Right Thing" mode 109.It Dv html 110Emit HTML output 111.It Dv indent=xx 112Set the indentation level 113.It Dv info 114Add info attributes (HTML) 115.It Dv json 116Emit JSON output 117.It Dv keys 118Emit the key attribute for keys (XML) 119.It Dv log-gettext 120Log (via stderr) each 121.Xr gettext 3 122string lookup 123.It Dv log-syslog 124Log (via stderr) each syslog message (via 125.Xr xo_syslog 3 ) 126.It Dv no-humanize 127Ignore the {h:} modifier (TEXT, HTML) 128.It Dv no-locale 129Do not initialize the locale setting 130.It Dv no-retain 131Prevent retaining formatting information 132.It Dv no-top 133Do not emit a top set of braces (JSON) 134.It Dv not-first 135Pretend the 1st output item was not 1st (JSON) 136.It Dv pretty 137Emit pretty-printed output 138.It Dv retain 139Force retaining formatting information 140.It Dv text 141Emit TEXT output 142.It Dv underscores 143Replace XML-friendly "-"s with JSON friendly "_"s e 144.It Dv units 145Add the 'units' (XML) or 'data-units (HTML) attribute 146.It Dv warn 147Emit warnings when libxo detects bad calls 148.It Dv warn-xml 149Emit warnings in XML 150.It Dv xml 151Emit XML output 152.It Dv xpath 153Add XPath expressions (HTML) 154.El 155.Pp 156The 157.Dq brief-options 158are single letter commands, designed for those with 159too little patience to use real tokens. 160No comma separator is used. 161.Bl -column "i<num>" 162.It Sy "Token Action" 163.It "H " "Enable HTML output (XO_STYLE_HTML)" 164.It "I " "Enable info output (XOF_INFO)" 165.It "i<num> " "Indent by <number>" 166.It "J " "Enable JSON output (XO_STYLE_JSON)" 167.It "P " "Enable pretty-printed output (XOF_PRETTY)" 168.It "T " "Enable text output (XO_STYLE_TEXT)" 169.It "W " "Enable warnings (XOF_WARN)" 170.It "X " "Enable XML output (XO_STYLE_XML)" 171.It "x " "Enable XPath data (XOF_XPATH)" 172.El 173.Pp 174Refer to 175.Xr xo_options 7 176for additional option information. 177.Pp 178The 179.Nm 180library allows an application to generate text, XML, JSON, 181and HTML output using a common set of function calls. 182The application 183decides at run time which output style should be produced. 184The 185application calls a function 186.Xr xo_emit 3 187to product output that is 188described in a format string. 189A 190.Dq field descriptor 191tells 192.Nm 193what the field is and what it means. 194Each field descriptor is placed in 195braces with a printf-like format string: 196.Bd -literal -offset indent 197 xo_emit(" {:lines/%7ju} {:words/%7ju} " 198 "{:characters/%7ju}{d:filename/%s}\\n", 199 linect, wordct, charct, file); 200.Ed 201.Pp 202Each field can have a role, with the 'value' role being the default, 203and the role tells 204.Nm 205how and when to render that field, as well as 206a 207.Xr printf 3 Ns -like 208format string. 209.Pp 210Output 211can then be generated in various style, using the "--libxo" option. 212.Sh DEFAULT HANDLE 213Handles give an abstraction for 214.Nm 215that encapsulates the state of a 216stream of output. 217Handles have the data type "xo_handle_t" and are 218opaque to the caller. 219.Pp 220The library has a default handle that is automatically initialized. 221By default, this handle will send text style output to standard output. 222The 223.Xr xo_set_style 3 224and 225.Xr xo_set_flags 3 226functions can be used to change this 227behavior. 228.Pp 229Many 230.Nm 231functions take a handle as their first parameter; most that 232do not use the default handle. 233Any function taking a handle can 234be passed 235.Dv NULL 236to access the default handle. 237.Pp 238For the typical command that is generating output on standard output, 239there is no need to create an explicit handle, but they are available 240when needed, e.g., for daemons that generate multiple streams of 241output. 242.Sh FUNCTION OVERVIEW 243The 244.Nm 245library includes the following functions: 246.Bl -tag -width "xo_close_container_hd" 247.It Sy "Function Description" 248.It Fn xo_attr 249.It Fn xo_attr_h 250.It Fn xo_attr_hv 251Allows the caller to emit XML attributes with the next open element. 252.It Fn xo_create 253.It Fn xo_create_to_file 254Allow the caller to create a new handle. 255Note that 256.Nm 257has a default handle that allows the caller to avoid use of an 258explicitly created handle. 259Only callers writing to files other than 260.Dv stdout 261would need to call 262.Fn xo_create . 263.It Fn xo_destroy 264Frees any resources associated with the handle, including the handle 265itself. 266.It Fn xo_emit 267.It Fn xo_emit_h 268.It Fn xo_emit_hv 269Emit formatted output. 270The 271.Fa fmt 272string controls the conversion of the remaining arguments into 273formatted output. 274See 275.Xr xo_format 5 276for details. 277.It Fn xo_emit_warn 278.It Fn xo_emit_warnx 279.It Fn xo_emit_warn_c 280.It Fn xo_emit_warn_hc 281.It Fn xo_emit_err 282.It Fn xo_emit_errc 283.It Fn xo_emit_errx 284These functions are mildly compatible with their standard libc 285namesakes, but use the format string defined in 286.Xr xo_format 5 . 287While there is an increased cost for converting the strings, the 288output provided can be richer and more useful. See also 289.Xr xo_err 3 290.It Fn xo_warn 291.It Fn xo_warnx 292.It Fn xo_warn_c 293.It Fn xo_warn_hc 294.It Fn xo_err 295.It Fn xo_errc 296.It Fn xo_errx 297.It Fn xo_message 298.It Fn xo_message_c 299.It Fn xo_message_hc 300.It Fn xo_message_hcv 301These functions are meant to be compatible with their standard libc namesakes. 302.It Fn xo_finish 303.It Fn xo_finish_h 304Flush output, close open construct, and complete any pending 305operations. 306.It Fn xo_flush 307.It Fn xo_flush_h 308Allow the caller to flush any pending output for a handle. 309.It Fn xo_no_setlocale 310Direct 311.Nm 312to avoid initializing the locale. 313This function should be called before any other 314.Nm 315function is called. 316.It Fn xo_open_container 317.It Fn xo_open_container_h 318.It Fn xo_open_container_hd 319.It Fn xo_open_container_d 320.It Fn xo_close_container 321.It Fn xo_close_container_h 322.It Fn xo_close_container_hd 323.It Fn xo_close_container_d 324Containers a singleton levels of hierarchy, typically used to organize 325related content. 326.It Fn xo_open_list_h 327.It Fn xo_open_list 328.It Fn xo_open_list_hd 329.It Fn xo_open_list_d 330.It Fn xo_open_instance_h 331.It Fn xo_open_instance 332.It Fn xo_open_instance_hd 333.It Fn xo_open_instance_d 334.It Fn xo_close_instance_h 335.It Fn xo_close_instance 336.It Fn xo_close_instance_hd 337.It Fn xo_close_instance_d 338.It Fn xo_close_list_h 339.It Fn xo_close_list 340.It Fn xo_close_list_hd 341.It Fn xo_close_list_d 342Lists are levels of hierarchy that can appear multiple times within 343the same parent. 344Two calls are needed to encapsulate them, one for 345the list and one for each instance of that list. 346Typically 347.Fn xo_open_list 348and 349.Fn xo_close_list 350are called outside a 351for-loop, where 352.Fn xo_open_instance 353it called at the top of the loop, and 354.Fn xo_close_instance 355is called at the bottom of the loop. 356.It Fn xo_parse_args 357Inspects command line arguments for directions to 358.Nm . 359This function should be called before 360.Va argv 361is inspected by the application. 362.It Fn xo_set_allocator 363Instructs 364.Nm 365to use an alternative memory allocator and deallocator. 366.It Fn xo_set_flags 367.It Fn xo_clear_flags 368Change the flags set for a handle. 369.It Fn xo_set_info 370Provides additional information about elements for use with HTML 371rendering. 372.It Fn xo_set_options 373Changes formatting options used by handle. 374.It Fn xo_set_style 375.It Fn xo_set_style_name 376Changes the output style used by a handle. 377.It Fn xo_set_writer 378Instructs 379.Nm 380to use an alternative set of low-level output functions. 381.El 382.Sh SEE ALSO 383.Xr libxo-csv 7, 384.Xr xo 1 , 385.Xr xolint 1 , 386.Xr xo_attr 3 , 387.Xr xo_create 3 , 388.Xr xo_emit 3 , 389.Xr xo_emit_err 3 , 390.Xr xo_err 3 , 391.Xr xo_finish 3 , 392.Xr xo_flush 3 , 393.Xr xo_no_setlocale 3 , 394.Xr xo_open_container 3 , 395.Xr xo_open_list 3 , 396.Xr xo_options 7, 397.Xr xo_parse_args 3 , 398.Xr xo_set_allocator 3 , 399.Xr xo_set_flags 3 , 400.Xr xo_set_info 3 , 401.Xr xo_set_options 3 , 402.Xr xo_set_style 3 , 403.Xr xo_set_writer 3 , 404.Xr xo_format 5 405.Sh HISTORY 406The 407.Nm libxo 408library first appeared in 409.Fx 11.0 . 410.Sh AUTHORS 411.Nm libxo 412was written by 413.An Phil Shafer Aq Mt phil@freebsd.org . 414 415