libxo - Man Page

libxo is a software component that allows other software to generate a variety of output styles, including text, XML, JSON, and HTML. Using libxo, a single section of code provides formatting and structural information, allowing a run-time choice of which format to emit. Using a single section of code allows functional equivalence between format options, e.g. XML and JSON formatted output can reliably carry the same content. It also reduces software maintenance costs, since there is a single code path to change or correct, rather than one per output style.

"Structured" output styles like JSON and XML allow programmatic parsing of the output content in reliable and robust ways, and future-proofs by allowing the addition of new fields without impacting parsing.

libxo supports "plug-in" encoders, which allow new output styles to be developed independently, such as the "CSV" encoder, which creates Comma-Separated Values, suitable for spreadsheets and other common uses. See xo_csv

Command-line options are used to control operation and output style and features. These options begin with --libxo but can take one of several forms which trade brevity for clarity.

See xo_options(7) for complete details about the specific options and their operation.

Options are recognised in three forms:

• --libxo <options>

• --libxo=<options>

• --libxo:<brief-options>

The first two forms accept a comma-separated set of words, while the third form accepts a set of letters. Both are detailed in xo_options(7).

The styles can be intermixed in any order.

For example, the brief "X" option and the word "xml" both trigger XML output, while the "P" and "pretty" options will "pretty-print" the output, using indentation and multiple lines. Any of the following will execute df with both the "xml" and "pretty" options:

• df --libxo xml,pretty

• df --libxo xml --libxo pretty

• df --libxo=xml,pretty

• df --libxo=xml --libxo pretty

• df --libxo:XP

The following example shows the same content generated using multiple style options: text, XML, JSON, and HTML:

% df --libxo:JP -h /
{
  "storage-system-information": {
    "filesystem": [
      {
        "name": "zroot/ROOT/default",
        "blocks": "1.5T",
        "used": "27G",
        "available": "1.5T",
        "used-percent": 2,
        "mounted-on": "/"
      }
    ]
  }
}
% df --libxo:XP -h /
<storage-system-information>
  <filesystem>
    <name>zroot/ROOT/default</name>
    <blocks value="1668731555840">1.5T</blocks>
    <used value="29448773632">27G</used>
    <available value="1639282782208">1.5T</available>
    <used-percent>2</used-percent>
    <mounted-on>/</mounted-on>
  </filesystem>
</storage-system-information>
% df --libxo:HP -h /
<div class="line">
  <div class="title">Filesystem        </div>
  <div class="text"> </div>
  <div class="title">   Size</div>
  <div class="text"> </div>
  <div class="title">   Used</div>
  <div class="text"> </div>
  <div class="title">  Avail</div>
  <div class="text"> </div>
  <div class="title">Capacity</div>
  <div class="text">  </div>
  <div class="title">Mounted on</div>
</div>
<div class="line">
  <div class="data" data-tag="name">zroot/ROOT/default</div>
  <div class="text">  </div>
  <div class="data" data-tag="blocks">  1.5T</div>
  <div class="text">  </div>
  <div class="data" data-tag="used">   27G</div>
  <div class="text">  </div>
  <div class="data" data-tag="available">  1.5T</div>
  <div class="text"> </div>
  <div class="data" data-tag="used-percent">    2</div>
  <div class="units">%</div>
  <div class="text">  </div>
  <div class="text">  </div>
  <div class="data" data-tag="mounted-on">/</div>
</div>
%

Note that the XML style includes both the raw and "human" formatted values, which 'df' generates with the "-h" option.

Also note that the HTML style is suitable for inclusion in web applications with a suitable CSS file, such as /usr/share/libxo/xohtml.css which is used by xohtml(1).

xo_options(7), libxo(3), xolint(1), xo_emit(3)

The libxo library first appeared in FreeBSD 11.0.

libxo was written by Phil Shafer <phil@freebsd.org>.

FreeBSD uses libxo version 1.7.5. Complete documentation can be found on github:

https://juniper.github.io/libxo/1.7.5/html/index.html

libxo lives on github as:

https://github.com/Juniper/libxo

The latest release of libxo is available at:

https://github.com/Juniper/libxo/releases

The libxo library was added in FreeBSD 11.0.

Phil Shafer