diff options
Diffstat (limited to 'static/freebsd/man3/libxo.3')
| -rw-r--r-- | static/freebsd/man3/libxo.3 | 414 |
1 files changed, 414 insertions, 0 deletions
diff --git a/static/freebsd/man3/libxo.3 b/static/freebsd/man3/libxo.3 new file mode 100644 index 00000000..95c00598 --- /dev/null +++ b/static/freebsd/man3/libxo.3 @@ -0,0 +1,414 @@ +.\" # +.\" # Copyright (c) 2014, Juniper Networks, Inc. +.\" # All rights reserved. +.\" # This SOFTWARE is licensed under the LICENSE provided in the +.\" # ../Copyright file. By downloading, installing, copying, or +.\" # using the SOFTWARE, you agree to be bound by the terms of that +.\" # LICENSE. +.\" # Phil Shafer, July 2014 +.\" +.Dd December 8, 2014 +.Dt LIBXO 3 +.Os +.Sh NAME +.Nm libxo +.Nd library for emitting text, XML, JSON, or HTML output +.Sh LIBRARY +.Lb libxo +.Sh SYNOPSIS +.In libxo/xo.h +.Sh DESCRIPTION +The functions defined in +.Nm +are used to generate a choice of +.Em TEXT , +.Em XML , +.Em JSON , +or +.Em HTML +output. +A common set of functions are used, with +command line switches passed to the library to control the details of +the output. +.Pp +Most commands emit text output aimed at humans. +It is designed +to be parsed and understood by a user. +Humans are gifted at extracting +details and pattern matching. +Often programmers need to extract +information from this human-oriented output. +Programmers use tools +like +.Xr grep 1 , +.Xr awk 1 , +and regular expressions to ferret out the pieces of +information they need. +Such solutions are fragile and require +updates when output contents change or evolve, requiring testing and +validation. +.Pp +Modern tool developers favor encoding schemes like XML and JSON, +which allow trivial parsing and extraction of data. +Such formats are +simple, well understood, hierarchical, easily parsed, and often +integrate easier with common tools and environments. +.Pp +In addition, modern reality means that more output ends up in web +browsers than in terminals, making HTML output valuable. +.Pp +.Nm +allows a single set of function calls in source code to generate +traditional text output, as well as XML and JSON formatted data. +HTML +can also be generated; "<div>" elements surround the traditional text +output, with attributes that detail how to render the data. +.Pp +There are four encoding styles supported by +.Nm : +.Bl -bullet +.It +TEXT output can be display on a terminal session, allowing +compatibility with traditional command line usage. +.It +XML output is suitable for tools like XPath and protocols like +NETCONF. +.It +JSON output can be used for RESTful APIs and integration with +languages like Javascript and Python. +.It +HTML can be matched with a small CSS file to permit rendering in any +HTML5 browser. +.El +.Pp +In general, XML and JSON are suitable for encoding data, while TEXT is +suited for terminal output and HTML is suited for display in a web +browser (see +.Xr xohtml 1 ). +.Pp +.Nm libxo +uses command line options to trigger rendering behavior. +The following options are recognised: +.Pp +.Bl -tag -width "--libxo" +.It +\-\^\-libxo <options> +.It +\-\^\-libxo=<options> +.It +\-\^\-libxo:<brief-options> +.El +.Pp +Options is a comma-separated list of tokens that correspond to output +styles, flags, or features: +.Pp +.Bl -tag -width "12345678" +.It Sy "Token Action" +.It Dv dtrt +Enable "Do The Right Thing" mode +.It Dv html +Emit HTML output +.It Dv indent=xx +Set the indentation level +.It Dv info +Add info attributes (HTML) +.It Dv json +Emit JSON output +.It Dv keys +Emit the key attribute for keys (XML) +.It Dv log-gettext +Log (via stderr) each +.Xr gettext 3 +string lookup +.It Dv log-syslog +Log (via stderr) each syslog message (via +.Xr xo_syslog 3 ) +.It Dv no-humanize +Ignore the {h:} modifier (TEXT, HTML) +.It Dv no-locale +Do not initialize the locale setting +.It Dv no-retain +Prevent retaining formatting information +.It Dv no-top +Do not emit a top set of braces (JSON) +.It Dv not-first +Pretend the 1st output item was not 1st (JSON) +.It Dv pretty +Emit pretty-printed output +.It Dv retain +Force retaining formatting information +.It Dv text +Emit TEXT output +.It Dv underscores +Replace XML-friendly "-"s with JSON friendly "_"s e +.It Dv units +Add the 'units' (XML) or 'data-units (HTML) attribute +.It Dv warn +Emit warnings when libxo detects bad calls +.It Dv warn-xml +Emit warnings in XML +.It Dv xml +Emit XML output +.It Dv xpath +Add XPath expressions (HTML) +.El +.Pp +The +.Dq brief-options +are single letter commands, designed for those with +too little patience to use real tokens. +No comma separator is used. +.Bl -column "i<num>" +.It Sy "Token Action" +.It "H " "Enable HTML output (XO_STYLE_HTML)" +.It "I " "Enable info output (XOF_INFO)" +.It "i<num> " "Indent by <number>" +.It "J " "Enable JSON output (XO_STYLE_JSON)" +.It "P " "Enable pretty-printed output (XOF_PRETTY)" +.It "T " "Enable text output (XO_STYLE_TEXT)" +.It "W " "Enable warnings (XOF_WARN)" +.It "X " "Enable XML output (XO_STYLE_XML)" +.It "x " "Enable XPath data (XOF_XPATH)" +.El +.Pp +Refer to +.Xr xo_options 7 +for additional option information. +.Pp +The +.Nm +library allows an application to generate text, XML, JSON, +and HTML output using a common set of function calls. +The application +decides at run time which output style should be produced. +The +application calls a function +.Xr xo_emit 3 +to product output that is +described in a format string. +A +.Dq field descriptor +tells +.Nm +what the field is and what it means. +Each field descriptor is placed in +braces with a printf-like format string: +.Bd -literal -offset indent + xo_emit(" {:lines/%7ju} {:words/%7ju} " + "{:characters/%7ju}{d:filename/%s}\\n", + linect, wordct, charct, file); +.Ed +.Pp +Each field can have a role, with the 'value' role being the default, +and the role tells +.Nm +how and when to render that field, as well as +a +.Xr printf 3 Ns -like +format string. +.Pp +Output +can then be generated in various style, using the "--libxo" option. +.Sh DEFAULT HANDLE +Handles give an abstraction for +.Nm +that encapsulates the state of a +stream of output. +Handles have the data type "xo_handle_t" and are +opaque to the caller. +.Pp +The library has a default handle that is automatically initialized. +By default, this handle will send text style output to standard output. +The +.Xr xo_set_style 3 +and +.Xr xo_set_flags 3 +functions can be used to change this +behavior. +.Pp +Many +.Nm +functions take a handle as their first parameter; most that +do not use the default handle. +Any function taking a handle can +be passed +.Dv NULL +to access the default handle. +.Pp +For the typical command that is generating output on standard output, +there is no need to create an explicit handle, but they are available +when needed, e.g., for daemons that generate multiple streams of +output. +.Sh FUNCTION OVERVIEW +The +.Nm +library includes the following functions: +.Bl -tag -width "xo_close_container_hd" +.It Sy "Function Description" +.It Fn xo_attr +.It Fn xo_attr_h +.It Fn xo_attr_hv +Allows the caller to emit XML attributes with the next open element. +.It Fn xo_create +.It Fn xo_create_to_file +Allow the caller to create a new handle. +Note that +.Nm +has a default handle that allows the caller to avoid use of an +explicitly created handle. +Only callers writing to files other than +.Dv stdout +would need to call +.Fn xo_create . +.It Fn xo_destroy +Frees any resources associated with the handle, including the handle +itself. +.It Fn xo_emit +.It Fn xo_emit_h +.It Fn xo_emit_hv +Emit formatted output. +The +.Fa fmt +string controls the conversion of the remaining arguments into +formatted output. +See +.Xr xo_format 5 +for details. +.It Fn xo_emit_warn +.It Fn xo_emit_warnx +.It Fn xo_emit_warn_c +.It Fn xo_emit_warn_hc +.It Fn xo_emit_err +.It Fn xo_emit_errc +.It Fn xo_emit_errx +These functions are mildly compatible with their standard libc +namesakes, but use the format string defined in +.Xr xo_format 5 . +While there is an increased cost for converting the strings, the +output provided can be richer and more useful. See also +.Xr xo_err 3 +.It Fn xo_warn +.It Fn xo_warnx +.It Fn xo_warn_c +.It Fn xo_warn_hc +.It Fn xo_err +.It Fn xo_errc +.It Fn xo_errx +.It Fn xo_message +.It Fn xo_message_c +.It Fn xo_message_hc +.It Fn xo_message_hcv +These functions are meant to be compatible with their standard libc namesakes. +.It Fn xo_finish +.It Fn xo_finish_h +Flush output, close open construct, and complete any pending +operations. +.It Fn xo_flush +.It Fn xo_flush_h +Allow the caller to flush any pending output for a handle. +.It Fn xo_no_setlocale +Direct +.Nm +to avoid initializing the locale. +This function should be called before any other +.Nm +function is called. +.It Fn xo_open_container +.It Fn xo_open_container_h +.It Fn xo_open_container_hd +.It Fn xo_open_container_d +.It Fn xo_close_container +.It Fn xo_close_container_h +.It Fn xo_close_container_hd +.It Fn xo_close_container_d +Containers a singleton levels of hierarchy, typically used to organize +related content. +.It Fn xo_open_list_h +.It Fn xo_open_list +.It Fn xo_open_list_hd +.It Fn xo_open_list_d +.It Fn xo_open_instance_h +.It Fn xo_open_instance +.It Fn xo_open_instance_hd +.It Fn xo_open_instance_d +.It Fn xo_close_instance_h +.It Fn xo_close_instance +.It Fn xo_close_instance_hd +.It Fn xo_close_instance_d +.It Fn xo_close_list_h +.It Fn xo_close_list +.It Fn xo_close_list_hd +.It Fn xo_close_list_d +Lists are levels of hierarchy that can appear multiple times within +the same parent. +Two calls are needed to encapsulate them, one for +the list and one for each instance of that list. +Typically +.Fn xo_open_list +and +.Fn xo_close_list +are called outside a +for-loop, where +.Fn xo_open_instance +it called at the top of the loop, and +.Fn xo_close_instance +is called at the bottom of the loop. +.It Fn xo_parse_args +Inspects command line arguments for directions to +.Nm . +This function should be called before +.Va argv +is inspected by the application. +.It Fn xo_set_allocator +Instructs +.Nm +to use an alternative memory allocator and deallocator. +.It Fn xo_set_flags +.It Fn xo_clear_flags +Change the flags set for a handle. +.It Fn xo_set_info +Provides additional information about elements for use with HTML +rendering. +.It Fn xo_set_options +Changes formatting options used by handle. +.It Fn xo_set_style +.It Fn xo_set_style_name +Changes the output style used by a handle. +.It Fn xo_set_writer +Instructs +.Nm +to use an alternative set of low-level output functions. +.El +.Sh SEE ALSO +.Xr libxo-csv 7, +.Xr xo 1 , +.Xr xolint 1 , +.Xr xo_attr 3 , +.Xr xo_create 3 , +.Xr xo_emit 3 , +.Xr xo_emit_err 3 , +.Xr xo_err 3 , +.Xr xo_finish 3 , +.Xr xo_flush 3 , +.Xr xo_no_setlocale 3 , +.Xr xo_open_container 3 , +.Xr xo_open_list 3 , +.Xr xo_options 7, +.Xr xo_parse_args 3 , +.Xr xo_set_allocator 3 , +.Xr xo_set_flags 3 , +.Xr xo_set_info 3 , +.Xr xo_set_options 3 , +.Xr xo_set_style 3 , +.Xr xo_set_writer 3 , +.Xr xo_format 5 +.Sh HISTORY +The +.Nm libxo +library first appeared in +.Fx 11.0 . +.Sh AUTHORS +.Nm libxo +was written by +.An Phil Shafer Aq Mt phil@freebsd.org . + |