1.\" # 2.\" # Copyright (c) 2014-2017, 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 May 11, 2017 11.Dt LIBXO 3 12.Os 13.Sh NAME 14.Nm xo_options 15.Nd common options for libxo\-based commands 16.Sh DESCRIPTION 17.Pp 18.Nm libxo 19allows the rendering of data into 20various output styles, including 21.Em text , 22.Em XML , 23.Em JSON , 24and 25.Em HTML . 26.Nm libxo 27uses command line options to trigger rendering behavior. 28Options are recognised in three forms: 29.Bl -bullet 30.It 31\-\-libxo <options> 32.It 33\-\-libxo=<options> 34.It 35\-\-libxo:<brief\-options> 36.El 37.Pp 38The first two forms accept a comma\-separated set of words, detailed 39below, while the third form accepts a set of letters, also below. 40The triggered functionality is identical. 41.Bl -column "Token2341234" 42.It Sy "Option " "Action" 43.It "color " "Enable colors/effects for display styles (TEXT, HTML)" 44.It "flush " "Flush after each emit call" 45.It "flush\-line " "Flush each line of output" 46.It "html " "Emit HTML output" 47.It "indent=xx " "Set the indentation level" 48.It "info " "Add info attributes (HTML)" 49.It "json " "Emit JSON output" 50.It "keys " "Emit the key attribute for keys (XML)" 51.It "log\-gettext" "Log (via stderr) each gettext(3) string lookup" 52.It "log\-syslog " "Log (via stderr) each syslog message (via xo_syslog)" 53.It "no\-humanize" "Ignore the {h:} modifier (TEXT, HTML)" 54.It "no\-locale " "Do not initialize the locale setting" 55.It "no\-retain " "Prevent retaining formatting information" 56.It "pretty " "Emit pretty\-printed output" 57.It "retain " "Force retaining formatting information" 58.It "text " "Emit TEXT output" 59.It "underscores" "Replace XML\-friendly \"\-\"s with JSON friendly \"_\"s" 60.It "units " "Add the 'units' (XML) or 'data\-units (HTML) attribute" 61.It "warn " "Emit warnings when libxo detects bad calls" 62.It "warn\-xml " "Emit warnings in XML" 63.It "xml " "Emit XML output" 64.It "xpath " "Add XPath expressions (HTML)" 65.El 66.Pp 67The brief options are a set of single\-letter aliases for the longer 68terms, used as a single string: 69.Bl -column "Value" "Equivalent Token" 70.It Sy "Value" "Equivalent Token" 71.It "c 72.It "f " "flush" 73.It "F " "flush\-line" 74.It "H " "html" 75.It "I " "info" 76.It "i<num>" "indent=<num>" 77.It "J " "json" 78.It "k " "keys" 79.It "n " "no\-humanize" 80.It "P " "pretty" 81.It "T " "text" 82.It "U " "units" 83.It "u " "underscore 84.It "W " "warn" 85.It "X " "xml" 86.It "x " "xpath" 87.El 88.Pp 89Most of these option are simple and direct, but some require 90additional details: 91.Pp 92.Fa "flush\-line" 93performs line buffering, even when the output is not directed to 94a TTY device. 95.Pp 96.Fa info 97generates additional data for HTML, encoded in attributes using 98names that state with "data\-". 99.Pp 100.Fa keys 101adds a "key" attribute for XML output to indicate that a leaf is 102an identifier for the list member. 103.Pp 104.Fa no\-humanize 105avoids "humanizing" numeric output (see 106.Xr humanize_number 3 107for details). 108.Pp 109.Fa no\-locale 110instructs 111.Nm libxo 112to avoid translating output to the current locale. 113.Pp 114.Fa no\-retain 115disables the ability of 116.Nm libxo 117to internally retain "compiled" information about formatting strings. 118.Pp 119.Fa underscores 120can be used with 121.Em JSON 122output to change 123.Em XML \-friendly 124names with dashes into 125.Em JSON \-friendly 126name with underscores. 127.Pp 128.Fa warn 129allows 130.Nm libxo 131to emit warnings on stderr when application code make incorrect calls. 132.Fa warn\-xml causes those warnings to be placed in 133.Em XML 134inside the output. 135.Sh EXAMPLES 136The following are three example invocations of 137.Xr ps 1 : 138.Bd -literal 139 ps \-\-libxo json,pretty,warn \-ux 140 141 ps \-\-libxo=xml \-lg 142 143 ps \-\-libxo:Hxc 1 144.Ed 145.Sh SEE ALSO 146.Xr libxo 3 , 147.Xr xo_format 5 148.Sh HISTORY 149The 150.Nm libxo 151library first appeared in 152.Fx 11.0 . 153.Sh AUTHORS 154.Nm libxo 155was written by 156.An Phil Shafer Aq Mt phil@freebsd.org . 157