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 "12345678901234567"
  37 .It Fl "-close <path>"
  38 Close tags for the given path
  39 .It Fl "-depth <num>"
  40 Set the depth for pretty printing
  41 .It Fl "-help"
  42 Display this help text
  43 .It Fl "-html OR -H"
  44 Generate HTML output
  45 .It Fl "-json OR -J"
  46 Generate JSON output
  47 .It Fl "-leading-xpath <path>"
  48 Add a prefix to generated XPaths (HTML)
  49 .It Fl "-open <path>"
  50 Open tags for the given path
  51 .It Fl "-pretty OR -p"
  52 Make 'pretty' output (add indent, newlines)
  53 .It Fl "-style <style>"
  54 Generate given style (xml, json, text, html)
  55 .It Fl "-text OR -T"
  56 Generate text output (the default style)
  57 .It Fl "-version"
  58 Display version information
  59 .It Fl "-warn OR -W"
  60 Display warnings in text on stderr
  61 .It Fl "-warn-xml"
  62 Display warnings in xml on stdout
  63 .It Fl "-wrap <path>"
  64 Wrap output in a set of containers
  65 .It Fl "-xml OR -X"
  66 Generate XML output
  67 .It Fl "-xpath"
  68 Add XPath data to HTML output
  69 .El
  70 .Pp
  71 The
  72 .Nm
  73 utility accepts a format string suitable for
  74 .Xr xo_emit 3
  75 and a set of zero or more arguments used to supply data for that string.
  76 .Bd -literal -offset indent
  77     xo "The {k:name} weighs {:weight/%d} pounds.\\n" fish 6
  78
  79   TEXT:
  80     The fish weighs 6 pounds.
  81   XML:
  82     <name>fish</name>
  83     <weight>6</weight>
  84   JSON:
  85     "name": "fish",
  86     "weight": 6
  87   HTML:
  88     <div class="line">
  89       <div class="text">The </div>
  90       <div class="data" data-tag="name">fish</div>
  91       <div class="text"> weighs </div>
  92       <div class="data" data-tag="weight">6</div>
  93       <div class="text"> pounds.</div>
  94     </div>
  95 .Ed
  96 .Pp
  97 The
  98 .Fl "-wrap <path>"
  99 option can be used to wrap emitted content in a
 100 specific hierarchy.
 101 The path is a set of hierarchical names separated
 102 by the '/' character.
 103 .Bd -literal -offset indent
 104     xo --wrap top/a/b/c '{:tag}' value
 105
 106   XML:
 107     <top>
 108       <a>
 109         <b>
 110           <c>
 111             <tag>value</tag>
 112           </c>
 113         </b>
 114       </a>
 115     </top>
 116   JSON:
 117     "top": {
 118       "a": {
 119         "b": {
 120           "c": {
 121             "tag": "value"
 122           }
 123         }
 124       }
 125     }
 126 .Ed
 127 .Pp
 128 The
 129 .Fl "\-open <path>"
 130 and
 131 .Fl "\-close <path>"
 132 can be used to emit
 133 hierarchical information without the matching close and open
 134 tag.
 135 This allows a shell script to emit open tags, data, and
 136 then close tags.
 137 The
 138 .Fl \-depth
 139 option may be used to set the
 140 depth for indentation.
 141 The
 142 .Fl "\-leading-xpath"
 143 may be used to
 144 prepend data to the XPath values used for HTML output style.
 145 .Bd -literal -offset indent
 146     #!/bin/sh
 147     xo --open top/data
 148     xo --depth 2 '{tag}' value
 149     xo --close top/data
 150   XML:
 151     <top>
 152       <data>
 153         <tag>value</tag>
 154       </data>
 155     </top>
 156   JSON:
 157     "top": {
 158       "data": {
 159         "tag": "value"
 160       }
 161     }
 162 .Ed
 163 .Sh EXAMPLE
 164 .Bd -literal
 165   % xo 'The {:product} is {:status}\n' stereo "in route"
 166   The stereo is in route
 167   % xo -p -X 'The {:product} is {:status}\n' stereo "in route"
 168   <product>stereo</product>
 169   <status>in route</status>
 170 .Ed
 171 .Sh SEE ALSO
 172 .Xr libxo 3 ,
 173 .Xr xo_emit 3