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 -C | Ic --continuation 40Indicates this output is a continuation of the previous output data 41and should appear on the same line. 42This is allows HTML output to be constructed correctly. 43.It Ic --depth Ar num 44Set the depth for pretty printing 45.It Ic --help 46Display help text 47.It Ic -H | Ic --html 48Generate HTML output 49.It Ic -J | Ic --json 50Generate JSON output 51.It Ic --leading-xpath Ar path 52Add a prefix to generated XPaths (HTML) 53.It Ic --not-first 54Indicate that this content is not the first in a series of sibling 55objects, which is vital information for "JSON" output, which requires 56a comma between such objects. 57.It Ic --open Ar path 58Open tags for the given path 59.It Ic -p | Ic --pretty 60Make 'pretty' output (add indent, newlines) 61.It Ic --style Ar style 62Generate given style (xml, json, text, html) 63.It Ic -T | Ic --text 64Generate text output (the default style) 65.It Ic --top-warp 66Indicates the entire object should be placed inside a top-level 67object wrapper, specifically when generating JSON output. 68.It Ic --version 69Display version information 70.It Ic -W | Ic --warn 71Display warnings in text on stderr 72.It Ic --warn-xml 73Display warnings in xml on stdout 74.It Ic --wrap Ar path 75Wrap output in a set of containers 76.It Ic -X | Ic --xml 77Generate XML output 78.It Ic --xpath 79Add XPath data to HTML output 80.El 81.Pp 82The 83.Nm 84utility accepts a format string suitable for 85.Xr xo_emit 3 86and a set of zero or more arguments used to supply data for that string. 87.Pp 88In addition, 89.Nm 90accepts any of the 91.Nm libxo 92options listed in 93.Xr xo_options 7 . 94.Sh EXAMPLES 95In this example, 96.Nm 97is used to emit the same data encoded in text and then in XML by 98adding 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 107In this example, the output from a 108.Nm 109command 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 131The 132.Fl "-wrap <path>" 133option can be used to wrap emitted content in a 134specific hierarchy. 135The path is a set of hierarchical names separated 136by 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 162The 163.Fl "\-open <path>" 164and 165.Fl "\-close <path>" 166can be used to emit 167hierarchical information without the matching close and open 168tag. 169This allows a shell script to emit open tags, data, and 170then close tags. 171The 172.Fl \-depth 173option may be used to set the 174depth for indentation. 175The 176.Fl "\-leading-xpath" 177may be used to 178prepend 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 203The 204.Nm libxo 205library first appeared in 206.Fx 11.0 . 207.Sh AUTHORS 208.Nm libxo 209was written by 210.An Phil Shafer Aq Mt phil@freebsd.org . 211 212