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