.\" #
.\" # 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 Fl -close Ar path
Close tags for the given path
.It Fl -close-instance Ar name
Close an open instance name
.It Fl -close-list Ar name
Close an open list name
.It Fl C | Fl -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 Fl -depth Ar num
Set the depth for pretty printing
.It Fl -help
Display help text
.It Fl H | Fl -html
Generate HTML output
.It Fl I Ar name | Fl -instance Ar name
Wrap in an instance of the given name.
See
.Sx Lists and Instances
below.
.It Fl J | Fl -json
Generate JSON output
.It Fl -leading-xpath Ar path
Add a prefix to generated XPaths (HTML)
.It Fl -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 Fl -open Ar path
Open tags for the given path
.It Fl -open-instance Ar name
Open an instance given by name.
See
.Sx Lists and Instances
below.
.It Fl -open-list Ar name
Open a list given by name.
See
.Sx Lists and Instances
below.
.It Fl O Ar opts | Fl -option Ar opts
Give formatting options
.It Fl p | Fl -pretty
Make 'pretty' output (add indent, newlines)
.It Fl -style Ar style
Generate given style (xml, json, text, html)
.It Fl T | Fl -text
Generate text output (the default style)
.It Fl -top-warp
Indicates the entire object should be placed inside a top-level
object wrapper, specifically when generating JSON output.
.It Fl -version
Display version information
.It Fl W | Fl -warn
Display warnings in text on stderr
.It Fl -warn-xml
Display warnings in xml on stdout
.It Fl -wrap Ar path
Wrap output in a set of containers
.It Fl X | Fl -xml
Generate XML output
.It Fl -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 .
.Ss Lists and Instances
A
.Em list
is a set of one or more instances that appear under the same parent.
The instances contain details about a specific object.
One can think of instances as objects or records.
A call is needed to open and close the list, while a distinct call
is needed to open and close each instance of the list.
.Pp
Use
.Fl -open-list
and
.Fl -open-instance
to open lists and instances.
Use
.Fl -close-list
and
.Fl -close-instance
to close them.
Each of these options take a
.Ar name
parameter, providing the name of the list and instance.
.Pp
In the following example, a list named "machine" is created with
three instances:
.Bd -literal -offset indent
  opts="--json"
  xo $opts --open-list machine
  NF=
  for name in red green blue; do
      xo $opts --depth 1 $NF --open-instance machine
      xo $opts --depth 2 "Machine {k:name} has {:memory}\\n" $name 55
      xo $opts --depth 1 --close-instance machine
      NF=--not-first
  done
  xo $opts $NF --close-list machine
.Ed
.Pp
The normal
.Nm libxo
functions use a state machine to help these transitions, but since
each
.Nm
command is invoked independent of the previous calls, the state
must be passed in explicitly via these command line options.
.Pp
The
.Fl I
.Pq Fl -instance
option can be used to treat a single
.Nm
invocation as an instance with the given set of fields:
.Bd -literal -offset indent
  % xo --libxo:XP --instance foo 'The {:product} is {:status}\\n' \\
        stereo "in route"
  <foo>
    <product>stereo</product>
    <status>in route</status>
  </foo>
.Ed
.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
The
.Nm libxo
library was written by
.An Phil Shafer Aq Mt phil@freebsd.org .
.Sh ADDITIONAL DOCUMENTATION
.Fx
uses
.Nm libxo
version 2.1.0.
Complete documentation can be found on github:
.Bd -literal -offset indent
https://juniper.github.io/libxo/2.1.0/html/index.html
.Ed
.Pp
.Nm libxo
lives on github as:
.Bd -literal -offset indent
https://github.com/Juniper/libxo
.Ed
.Pp
The latest release of
.Nm libxo
is available at:
.Bd -literal -offset indent
https://github.com/Juniper/libxo/releases
.Ed
.Sh HISTORY
The
.Nm libxo
library was added in
.Fx 11.0 .
.Sh AUTHOR
Phil Shafer