contrib/libxo/xo/xo.1

   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 4, 2014
  11 .Dt XO 1
  12 .Os
  13 .Sh NAME
  14 .Nm xo
  15 .Nd emit formatted output based on format string and arguments
  16 .Sh SYNOPSIS
  17 .Nm
  18 .Op Fl options
  19 .Op Ar argument...
  20 .Sh DESCRIPTION
  21 The
  22 .Nm
  23 utility allows command line access to the functionality of
  24 the
  25 .Nm libxo
  26 library.
  27 Using
  28 .Nm ,
  29 shell scripts can emit
  30 .Em XML ,
  31 .Em JSON ,
  32 or
  33 .Em HTML
  34 using the same commands that emit text output.
  35 .Pp
  36 .Bl -tag -width indent
  37 .It Ic --close Ar path
  38 Close tags for the given path
  39 .It Ic -C | Ic --continuation
  40 Indicates this output is a continuation of the previous output data
  41 and should appear on the same line.
  42 This is allows HTML output to be constructed correctly.
  43 .It Ic --depth Ar num
  44 Set the depth for pretty printing
  45 .It Ic --help
  46 Display help text
  47 .It Ic -H | Ic --html
  48 Generate HTML output
  49 .It Ic -J | Ic --json
  50 Generate JSON output
  51 .It Ic --leading-xpath Ar path
  52 Add a prefix to generated XPaths (HTML)
  53 .It Ic --not-first
  54 Indicate that this content is not the first in a series of sibling
  55 objects, which is vital information for "JSON" output, which requires
  56 a comma between such objects.
  57 .It Ic --open Ar path
  58 Open tags for the given path
  59 .It Ic -p | Ic --pretty
  60 Make 'pretty' output (add indent, newlines)
  61 .It Ic --style Ar style
  62 Generate given style (xml, json, text, html)
  63 .It Ic -T | Ic --text
  64 Generate text output (the default style)
  65 .It Ic --top-warp
  66 Indicates the entire object should be placed inside a top-level
  67 object wrapper, specifically when generating JSON output.
  68 .It Ic --version
  69 Display version information
  70 .It Ic -W | Ic --warn
  71 Display warnings in text on stderr
  72 .It Ic --warn-xml
  73 Display warnings in xml on stdout
  74 .It Ic --wrap Ar path
  75 Wrap output in a set of containers
  76 .It Ic -X | Ic --xml
  77 Generate XML output
  78 .It Ic --xpath
  79 Add XPath data to HTML output
  80 .El
  81 .Pp
  82 The
  83 .Nm
  84 utility accepts a format string suitable for
  85 .Xr xo_emit 3
  86 and a set of zero or more arguments used to supply data for that string.
  87 .Pp
  88 In addition,
  89 .Nm
  90 accepts any of the
  91 .Nm libxo
  92 options listed in
  93 .Xr xo_options 7 .
  94 .Sh EXAMPLES
  95 In this example,
  96 .Nm
  97 is used to emit the same data encoded in text and then in XML by
  98 adding the "-p" (pretty) and "-X" (XML output) flags:
  99 .Bd -literal -offset indent
 100   % xo 'The {:product} is {:status}\\n' stereo "in route"
 101   The stereo is in route
 102   % xo -p -X 'The {:product} is {:status}\\n' stereo "in route"
 103   <product>stereo</product>
 104   <status>in route</status>
 105 .Ed
 106 .Pp
 107 In this example, the output from a
 108 .Nm
 109 command is shown in several styles:
 110 .Bd -literal -offset indent
 111   xo "The {k:name} weighs {:weight/%d} pounds.\\n" fish 6
 112 .Pp
 113   TEXT:
 114     The fish weighs 6 pounds.
 115   XML:
 116     <name>fish</name>
 117     <weight>6</weight>
 118   JSON:
 119     "name": "fish",
 120     "weight": 6
 121   HTML:
 122     <div class="line">
 123       <div class="text">The </div>
 124       <div class="data" data-tag="name">fish</div>
 125       <div class="text"> weighs </div>
 126       <div class="data" data-tag="weight">6</div>
 127       <div class="text"> pounds.</div>
 128     </div>
 129 .Ed
 130 .Pp
 131 The
 132 .Fl "-wrap <path>"
 133 option can be used to wrap emitted content in a
 134 specific hierarchy.
 135 The path is a set of hierarchical names separated
 136 by the '/' character.
 137 .Bd -literal -offset indent
 138   xo --wrap top/a/b/c '{:tag}' value
 139 .Pp
 140   XML:
 141     <top>
 142       <a>
 143         <b>
 144           <c>
 145             <tag>value</tag>
 146           </c>
 147         </b>
 148       </a>
 149     </top>
 150   JSON:
 151     "top": {
 152       "a": {
 153         "b": {
 154           "c": {
 155             "tag": "value"
 156           }
 157         }
 158       }
 159     }
 160 .Ed
 161 .Pp
 162 The
 163 .Fl "\-open <path>"
 164 and
 165 .Fl "\-close <path>"
 166 can be used to emit
 167 hierarchical information without the matching close and open
 168 tag.
 169 This allows a shell script to emit open tags, data, and
 170 then close tags.
 171 The
 172 .Fl \-depth
 173 option may be used to set the
 174 depth for indentation.
 175 The
 176 .Fl "\-leading-xpath"
 177 may be used to
 178 prepend data to the XPath values used for HTML output style.
 179 .Bd -literal -offset indent
 180   #!/bin/sh
 181   xo --open top/data
 182   xo --depth 2 '{tag}' value
 183   xo --close top/data
 184 .Pp
 185   XML:
 186     <top>
 187       <data>
 188         <tag>value</tag>
 189       </data>
 190     </top>
 191   JSON:
 192     "top": {
 193       "data": {
 194         "tag": "value"
 195       }
 196     }
 197 .Ed
 198 .Sh SEE ALSO
 199 .Xr libxo 3 ,
 200 .Xr xo_emit 3 ,
 201 .Xr xo_options 7
 202 .Sh HISTORY
 203 The
 204 .Nm libxo
 205 library first appeared in
 206 .Fx 11.0 .
 207 .Sh AUTHORS
 208 .Nm libxo
 209 was written by
 210 .An Phil Shafer Aq Mt phil@freebsd.org .
 211