contrib/libxo/libxo/xo_options.7

   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
  19 allows the rendering of data into
  20 various output styles, including
  21 .Em text ,
  22 .Em XML ,
  23 .Em JSON ,
  24 and
  25 .Em HTML .
  26 .Nm libxo
  27 uses command line options to trigger rendering behavior.
  28 Options 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
  38 The first two forms accept a comma\-separated set of words, detailed
  39 below, while the third form accepts a set of letters, also below.
  40 The 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
  67 The brief options are a set of single\-letter aliases for the longer
  68 terms, 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
  89 Most of these option are simple and direct, but some require
  90 additional details:
  91 .Pp
  92 .Fa "flush\-line"
  93 performs line buffering, even when the output is not directed to
  94 a TTY device.
  95 .Pp
  96 .Fa info
  97 generates additional data for HTML, encoded in attributes using
  98 names that state with "data\-".
  99 .Pp
 100 .Fa keys
 101 adds a "key" attribute for XML output to indicate that a leaf is
 102 an identifier for the list member.
 103 .Pp
 104 .Fa no\-humanize
 105 avoids "humanizing" numeric output (see
 106 .Xr humanize_number 3
 107 for details).
 108 .Pp
 109 .Fa no\-locale
 110 instructs
 111 .Nm libxo
 112 to avoid translating output to the current locale.
 113 .Pp
 114 .Fa no\-retain
 115 disables the ability of
 116 .Nm libxo
 117 to internally retain "compiled" information about formatting strings.
 118 .Pp
 119 .Fa underscores
 120 can be used with
 121 .Em JSON
 122 output to change
 123 .Em XML \-friendly
 124 names with dashes into
 125 .Em JSON \-friendly
 126 name with underscores.
 127 .Pp
 128 .Fa warn
 129 allows
 130 .Nm libxo
 131 to emit warnings on stderr when application code make incorrect calls.
 132 .Fa warn\-xml causes those warnings to be placed in
 133 .Em XML
 134 inside the output.
 135 .Sh EXAMPLES
 136 The 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
 149 The
 150 .Nm libxo
 151 library first appeared in
 152 .Fx 11.0 .
 153 .Sh AUTHORS
 154 .Nm libxo
 155 was written by
 156 .An Phil Shafer Aq Mt phil@freebsd.org .