406a584d7e
from 1.0.0:
Add "continuation" flag, to allow multiple "xo" invocations in a single line of output (#58)
Add --top-wrap to make top-level JSON wrappers
Add --{open,close}-{list,instace} options
Add xo_xml_leader(), to detect use of some bogus XML tags. It's still bad form, but it's a little safer now
Avoid call to xo_write before xo_flush, since the latter calls the former
Check return code from xo_flush_h properly (<0) (FreeBSD Bug 236935)
For JSON output, avoid newline before a container's close brace (#62)
Merge branch 'text_only' of https://github.com/zvr/libxo into zvr-text_only
Use XO_USE_INT_RETURN_CODES, not USE_INT_RETURN_CODES
add docs for --continuation
add docs for --not-first
call xo_state_set_flags before values and close containers; add XOIF_MADE_OUTPUT flag to track state; make proper empty JSON objects in xo_finish
color_map code has to be #ifdef'd out, since the struct definition
correct xo_flush_func_t (doesn't use xo_ssize_t)
make depth change for --top-wrap only for JSON
fix to handle --top-wrap in "xo" by being more consistent with handling trailing newlines
fix to handle text-only version #64 (from zvr)
fix xo_buf_has_room for round up to the next XO_BUFSIZ, not just add XO_BUFSIZ to the size (FreeBSD Bug 236937)
update docs for new "xo" options
update functions to use xo_ssize_t
update test cases
from 1.0.1:
Add EINTEGRITY to .pot files under test/gettext/ (fix from FreeBSD)
from 1.0.2:
handle failure from xo_vnsprintf; don't add -1 to "rc"
PR: 236937, 236935
Submitted by: phil
Reported by: Alfonso S. Siciliano <alfix86@gmail.com>
MFC after: 2 weeks
212 lines
4.5 KiB
Groff
212 lines
4.5 KiB
Groff
.\" #
|
|
.\" # Copyright (c) 2014, Juniper Networks, Inc.
|
|
.\" # All rights reserved.
|
|
.\" # This SOFTWARE is licensed under the LICENSE provided in the
|
|
.\" # ../Copyright file. By downloading, installing, copying, or
|
|
.\" # using the SOFTWARE, you agree to be bound by the terms of that
|
|
.\" # LICENSE.
|
|
.\" # Phil Shafer, July 2014
|
|
.\"
|
|
.Dd December 4, 2014
|
|
.Dt XO 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm xo
|
|
.Nd emit formatted output based on format string and arguments
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl options
|
|
.Op Ar argument...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility allows command line access to the functionality of
|
|
the
|
|
.Nm libxo
|
|
library.
|
|
Using
|
|
.Nm ,
|
|
shell scripts can emit
|
|
.Em XML ,
|
|
.Em JSON ,
|
|
or
|
|
.Em HTML
|
|
using the same commands that emit text output.
|
|
.Pp
|
|
.Bl -tag -width indent
|
|
.It Ic --close Ar path
|
|
Close tags for the given path
|
|
.It Ic -C | Ic --continuation
|
|
Indicates this output is a continuation of the previous output data
|
|
and should appear on the same line.
|
|
This is allows HTML output to be constructed correctly.
|
|
.It Ic --depth Ar num
|
|
Set the depth for pretty printing
|
|
.It Ic --help
|
|
Display help text
|
|
.It Ic -H | Ic --html
|
|
Generate HTML output
|
|
.It Ic -J | Ic --json
|
|
Generate JSON output
|
|
.It Ic --leading-xpath Ar path
|
|
Add a prefix to generated XPaths (HTML)
|
|
.It Ic --not-first
|
|
Indicate that this content is not the first in a series of sibling
|
|
objects, which is vital information for "JSON" output, which requires
|
|
a comma between such objects.
|
|
.It Ic --open Ar path
|
|
Open tags for the given path
|
|
.It Ic -p | Ic --pretty
|
|
Make 'pretty' output (add indent, newlines)
|
|
.It Ic --style Ar style
|
|
Generate given style (xml, json, text, html)
|
|
.It Ic -T | Ic --text
|
|
Generate text output (the default style)
|
|
.It Ic --top-warp
|
|
Indicates the entire object should be placed inside a top-level
|
|
object wrapper, specifically when generating JSON output.
|
|
.It Ic --version
|
|
Display version information
|
|
.It Ic -W | Ic --warn
|
|
Display warnings in text on stderr
|
|
.It Ic --warn-xml
|
|
Display warnings in xml on stdout
|
|
.It Ic --wrap Ar path
|
|
Wrap output in a set of containers
|
|
.It Ic -X | Ic --xml
|
|
Generate XML output
|
|
.It Ic --xpath
|
|
Add XPath data to HTML output
|
|
.El
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility accepts a format string suitable for
|
|
.Xr xo_emit 3
|
|
and a set of zero or more arguments used to supply data for that string.
|
|
.Pp
|
|
In addition,
|
|
.Nm
|
|
accepts any of the
|
|
.Nm libxo
|
|
options listed in
|
|
.Xr xo_options 7 .
|
|
.Sh EXAMPLES
|
|
In this example,
|
|
.Nm
|
|
is used to emit the same data encoded in text and then in XML by
|
|
adding the "-p" (pretty) and "-X" (XML output) flags:
|
|
.Bd -literal -offset indent
|
|
% xo 'The {:product} is {:status}\\n' stereo "in route"
|
|
The stereo is in route
|
|
% xo -p -X 'The {:product} is {:status}\\n' stereo "in route"
|
|
<product>stereo</product>
|
|
<status>in route</status>
|
|
.Ed
|
|
.Pp
|
|
In this example, the output from a
|
|
.Nm
|
|
command is shown in several styles:
|
|
.Bd -literal -offset indent
|
|
xo "The {k:name} weighs {:weight/%d} pounds.\\n" fish 6
|
|
.Pp
|
|
TEXT:
|
|
The fish weighs 6 pounds.
|
|
XML:
|
|
<name>fish</name>
|
|
<weight>6</weight>
|
|
JSON:
|
|
"name": "fish",
|
|
"weight": 6
|
|
HTML:
|
|
<div class="line">
|
|
<div class="text">The </div>
|
|
<div class="data" data-tag="name">fish</div>
|
|
<div class="text"> weighs </div>
|
|
<div class="data" data-tag="weight">6</div>
|
|
<div class="text"> pounds.</div>
|
|
</div>
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fl "-wrap <path>"
|
|
option can be used to wrap emitted content in a
|
|
specific hierarchy.
|
|
The path is a set of hierarchical names separated
|
|
by the '/' character.
|
|
.Bd -literal -offset indent
|
|
xo --wrap top/a/b/c '{:tag}' value
|
|
.Pp
|
|
XML:
|
|
<top>
|
|
<a>
|
|
<b>
|
|
<c>
|
|
<tag>value</tag>
|
|
</c>
|
|
</b>
|
|
</a>
|
|
</top>
|
|
JSON:
|
|
"top": {
|
|
"a": {
|
|
"b": {
|
|
"c": {
|
|
"tag": "value"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fl "\-open <path>"
|
|
and
|
|
.Fl "\-close <path>"
|
|
can be used to emit
|
|
hierarchical information without the matching close and open
|
|
tag.
|
|
This allows a shell script to emit open tags, data, and
|
|
then close tags.
|
|
The
|
|
.Fl \-depth
|
|
option may be used to set the
|
|
depth for indentation.
|
|
The
|
|
.Fl "\-leading-xpath"
|
|
may be used to
|
|
prepend data to the XPath values used for HTML output style.
|
|
.Bd -literal -offset indent
|
|
#!/bin/sh
|
|
xo --open top/data
|
|
xo --depth 2 '{tag}' value
|
|
xo --close top/data
|
|
.Pp
|
|
XML:
|
|
<top>
|
|
<data>
|
|
<tag>value</tag>
|
|
</data>
|
|
</top>
|
|
JSON:
|
|
"top": {
|
|
"data": {
|
|
"tag": "value"
|
|
}
|
|
}
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr libxo 3 ,
|
|
.Xr xo_emit 3 ,
|
|
.Xr xo_options 7
|
|
.Sh HISTORY
|
|
The
|
|
.Nm libxo
|
|
library first appeared in
|
|
.Fx 11.0 .
|
|
.Sh AUTHORS
|
|
.Nm libxo
|
|
was written by
|
|
.An Phil Shafer Aq Mt phil@freebsd.org .
|
|
|