xref: /freebsd/contrib/libxo/doc/xo.rst (revision f6a3b357e9be4c6423c85eff9a847163a0d307c8)
1
2.. index:: --libxo, xo
3
4The "xo" Utility
5================
6
7The `xo` utility allows command line access to the functionality of
8the libxo library.  Using `xo`, shell scripts can emit XML, JSON, and
9HTML using the same commands that emit text output.
10
11The style of output can be selected using a specific option: "-X" for
12XML, "-J" for JSON, "-H" for HTML, or "-T" for TEXT, which is the
13default.  The "--style <style>" option can also be used.  The standard
14set of "--libxo" options are available (see :ref:`options`), as well
15as the `LIBXO_OPTIONS`_ environment variable.
16
17.. _`LIBXO_OPTIONS`: :ref:`libxo-options`
18
19The `xo` utility accepts a format string suitable for `xo_emit` and
20a 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
41The `--wrap $path` option can be used to wrap emitted content in a
42specific hierarchy.  The path is a set of hierarchical names separated
43by 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
68The `--open $path` and `--close $path` can be used to emit
69hierarchical information without the matching close and open
70tag.  This allows a shell script to emit open tags, data, and
71then close tags.  The `--depth` option may be used to set the
72depth for indentation.  The `--leading-xpath` may be used to
73prepend 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
93When making partial lines of output (where the format string does not
94include a newline), use the `--continuation` option to let secondary
95invocations know they are adding data to an existing line.
96
97When emitting a series of objects, use the `--not-first` option to
98ensure that any details from the previous object (e.g. commas in JSON)
99are handled correctly.
100
101Use the `--top-wrap` option to ensure any top-level object details are
102handled correctly, e.g. wrap the entire output in a top-level set of
103braces 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
138Lists and Instances
139-------------------
140
141A "*list*" is set of one or more instances that appear under the same
142parent.  The instances contain details about a specific object.  One
143can think of instances as objects or records.  A call is needed to
144open and close the list, while a distinct call is needed to open and
145close each instance of the list.
146
147Use the `--open-list` and `--open-instances` to open lists and
148instances.  Use the `--close-list` and `--close-instances` to close
149them.  Each of these options take a `name` parameter, providing the
150name of the list and instance.
151
152In the following example, a list named "machine" is created with three
153instances:
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
166The normal `libxo` functions use a state machine to help these
167transitions, but since each `xo` command is invoked independent of the
168previous calls, the state must be passed in explicitly via these
169command line options.
170
171Command 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
202Example
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>
212