contrib/libxo/doc/xo.rst

   1
   2 .. index:: --libxo, xo
   3
   4 The "xo" Utility
   5 ================
   6
   7 The `xo` utility allows command line access to the functionality of
   8 the libxo library.  Using `xo`, shell scripts can emit XML, JSON, and
   9 HTML using the same commands that emit text output.
  10
  11 The style of output can be selected using a specific option: "-X" for
  12 XML, "-J" for JSON, "-H" for HTML, or "-T" for TEXT, which is the
  13 default.  The "--style <style>" option can also be used.  The standard
  14 set of "--libxo" options are available (see :ref:`options`), as well
  15 as the `LIBXO_OPTIONS`_ environment variable.
  16
  17 .. _`LIBXO_OPTIONS`: :ref:`libxo-options`
  18
  19 The `xo` utility accepts a format string suitable for `xo_emit` and
  20 a set of zero or more arguments used to supply data for that string::
  21
  22     xo "The {k:name} weighs {:weight/%d} pounds.\n" fish 6
  23
  24   TEXT:
  25     The fish weighs 6 pounds.
  26   XML:
  27     <name>fish</name>
  28     <weight>6</weight>
  29   JSON:
  30     "name": "fish",
  31     "weight": 6
  32   HTML:
  33     <div class="line">
  34       <div class="text">The </div>
  35       <div class="data" data-tag="name">fish</div>
  36       <div class="text"> weighs </div>
  37       <div class="data" data-tag="weight">6</div>
  38       <div class="text"> pounds.</div>
  39     </div>
  40
  41 The `--wrap $path` option can be used to wrap emitted content in a
  42 specific hierarchy.  The path is a set of hierarchical names separated
  43 by the '/' character::
  44
  45     xo --wrap top/a/b/c '{:tag}' value
  46
  47   XML:
  48     <top>
  49       <a>
  50         <b>
  51           <c>
  52             <tag>value</tag>
  53           </c>
  54         </b>
  55       </a>
  56     </top>
  57   JSON:
  58     "top": {
  59       "a": {
  60         "b": {
  61           "c": {
  62             "tag": "value"
  63           }
  64         }
  65       }
  66     }
  67
  68 The `--open $path` and `--close $path` can be used to emit
  69 hierarchical information without the matching close and open
  70 tag.  This allows a shell script to emit open tags, data, and
  71 then close tags.  The `--depth` option may be used to set the
  72 depth for indentation.  The `--leading-xpath` may be used to
  73 prepend data to the XPath values used for HTML output style::
  74
  75   EXAMPLE;
  76     #!/bin/sh
  77     xo --open top/data
  78     xo --depth 2 '{:tag}' value
  79     xo --close top/data
  80   XML:
  81     <top>
  82       <data>
  83         <tag>value</tag>
  84       </data>
  85     </top>
  86   JSON:
  87     "top": {
  88       "data": {
  89         "tag": "value"
  90       }
  91     }
  92
  93 When making partial lines of output (where the format string does not
  94 include a newline), use the `--continuation` option to let secondary
  95 invocations know they are adding data to an existing line.
  96
  97 When emitting a series of objects, use the `--not-first` option to
  98 ensure that any details from the previous object (e.g. commas in JSON)
  99 are handled correctly.
 100
 101 Use the `--top-wrap` option to ensure any top-level object details are
 102 handled correctly, e.g. wrap the entire output in a top-level set of
 103 braces for JSON output.
 104
 105   EXAMPLE;
 106     #!/bin/sh
 107     xo --top-wrap --open top/data
 108     xo --depth 2 'First {:tag} ' value1
 109     xo --depth 2 --continuation 'and then {:tag}\n' value2
 110     xo --top-wrap --close top/data
 111   TEXT:
 112     First value1 and then value2
 113   HTML:
 114     <div class="line">
 115       <div class="text">First </div>
 116       <div class="data" data-tag="tag">value1</div>
 117       <div class="text"> </div>
 118       <div class="text">and then </div>
 119       <div class="data" data-tag="tag">value2</div>
 120     </div>
 121   XML:
 122     <top>
 123       <data>
 124         <tag>value1</tag>
 125         <tag>value2</tag>
 126       </data>
 127     </top>
 128   JSON:
 129     {
 130       "top": {
 131         "data": {
 132         "tag": "value1",
 133         "tag": "value2"
 134         }
 135       }
 136     }
 137
 138 Lists and Instances
 139 -------------------
 140
 141 A "*list*" is set of one or more instances that appear under the same
 142 parent.  The instances contain details about a specific object.  One
 143 can think of instances as objects or records.  A call is needed to
 144 open and close the list, while a distinct call is needed to open and
 145 close each instance of the list.
 146
 147 Use the `--open-list` and `--open-instances` to open lists and
 148 instances.  Use the `--close-list` and `--close-instances` to close
 149 them.  Each of these options take a `name` parameter, providing the
 150 name of the list and instance.
 151
 152 In the following example, a list named "machine" is created with three
 153 instances:
 154
 155     opts="--json"
 156     xo $opts --open-list machine
 157     NF=
 158     for name in red green blue; do
 159         xo $opts --depth 1 $NF --open-instance machine
 160         xo $opts --depth 2 "Machine {k:name} has {:memory}\n" $name 55
 161         xo $opts --depth 1 --close-instance machine
 162         NF=--not-first
 163     done
 164     xo $opts $NF --close-list machine
 165
 166 The normal `libxo` functions use a state machine to help these
 167 transitions, but since each `xo` command is invoked independent of the
 168 previous calls, the state must be passed in explicitly via these
 169 command line options.
 170
 171 Command Line Options
 172 --------------------
 173
 174 ::
 175
 176   Usage: xo [options] format [fields]
 177     --close <path>        Close tags for the given path
 178     --close-instance <name> Close an open instance name
 179     --close-list <name>   Close an open list name
 180     --continuation OR -C  Output belongs on same line as previous output
 181     --depth <num>         Set the depth for pretty printing
 182     --help                Display this help text
 183     --html OR -H          Generate HTML output
 184     --json OR -J          Generate JSON output
 185     --leading-xpath <path> Add a prefix to generated XPaths (HTML)
 186     --not-first           Indicate this object is not the first (JSON)
 187     --open <path>         Open tags for the given path
 188     --open-instance <name> Open an instance given by name
 189     --open-list <name>   Open a list given by name
 190     --option <opts> -or -O <opts>  Give formatting options
 191     --pretty OR -p        Make 'pretty' output (add indent, newlines)
 192     --style <style>       Generate given style (xml, json, text, html)
 193     --text OR -T          Generate text output (the default style)
 194     --top-wrap            Generate a top-level object wrapper (JSON)
 195     --version             Display version information
 196     --warn OR -W          Display warnings in text on stderr
 197     --warn-xml            Display warnings in xml on stdout
 198     --wrap <path>         Wrap output in a set of containers
 199     --xml OR -X           Generate XML output
 200     --xpath               Add XPath data to HTML output);
 201
 202 Example
 203 -------
 204
 205 ::
 206
 207   % xo 'The {:product} is {:status}\n' stereo "in route"
 208   The stereo is in route
 209   % ./xo/xo -p -X 'The {:product} is {:status}\n' stereo "in route"
 210   <product>stereo</product>
 211   <status>in route</status>