LIBXO(3)

✨ LIBXO(3) ✨

okay bestie, so this page is literally the LIBXO(3) entry from the Library Functions Manual, and it's all about xo_options — the common options that every libxo-based command gets to use. pull up a chair, grab a boba, we're doing this 💖

---

🎀 NAME 🎀

• xo_options — common options for libxo-based commands

---

🌈 DESCRIPTION 🌈

so libxo is that girl: it lets you render your data into a bunch of different output styles — text, XML, JSON, HTML, the whole wardrobe. 💅 and it uses command line options to trigger which rendering behavior you want.

Options are recognised in three forms:

• --libxo <options>
• --libxo=<options>
• --libxo:<brief-options>

The first two forms accept a comma-separated set of words (detailed below 👇), while the third form accepts a set of letters (also below 👇). The triggered functionality is identical. fr fr, same vibes, different spelling.

Here's the full menu of long options and what they do:

• color — enable colors/effects for display styles (TEXT, HTML)
• flush — flush after each emit call
• flush-line — flush each line of output
• html — emit HTML output
• indent=xx — set the indentation level
• info — add info attributes (HTML)
• json — emit JSON output
• keys — emit the key attribute for keys (XML)
• log-gettext — log (via stderr) each gettext(3) string lookup
• log-syslog — log (via stderr) each syslog message (via xo_syslog)
• map — map between tag names
• map-file — use a file to specify mapping between tag names
• no-humanize — ignore the {h:} modifier (TEXT, HTML)
• no-locale — do not initialize the locale setting
• no-retain — prevent retaining formatting information
• pretty — emit pretty-printed output
• retain — force retaining formatting information
• text — emit TEXT output
• underscores — replace XML-friendly dashes with JSON-friendly underscores
• units — add the 'units' (XML) or 'data-units (HTML) attribute
• warn — emit warnings when libxo detects bad calls
• warn-xml — emit warnings in XML
• xml — emit XML output
• xpath — add XPath expressions (HTML)

---

🧚 the brief options, aka the short girls 🧚

The brief options are a set of single-letter aliases for the longer terms, used as a single string. no spaces, no commas, just vibes:

• c — (no equivalent token given, bestie, that's literally what the page says)
• f — flush
• F — flush-line
• H — html
• I — info
• i<num> — indent=<num>
• J — json
• k — keys
• n — no-humanize
• P — pretty
• T — text
• U — units
• u — underscore
• W — warn
• X — xml
• x — xpath

---

Most of these options are simple and direct, but some of them need extra details, and honestly same:

• flush-line performs line buffering, even when the output is not directed to a TTY device.
• info generates additional data for HTML, encoded in attributes using names that start with "data-".
• keys adds a "key" attribute for XML output to indicate that a leaf is an identifier for the list member.
• map and map-file are described below. (spoiler alert 🫶)
• no-humanize avoids "humanizing" numeric output (see humanize_number(3) for details).
• no-locale instructs libxo to avoid translating output to the current locale.
• no-retain disables the ability of libxo to internally retain "compiled" information about formatting strings.
• underscores can be used with JSON output to change XML-friendly names with dashes into JSON-friendly names with underscores.
• warn allows libxo to emit warnings on stderr when application code makes incorrect calls. warn-xml causes those warnings to be placed in XML inside the output.

---

🎨 Color Mapping 🎨

The colors option takes a value that is a set of mappings from the pre-defined set of colors to new foreground and background colors. The value is a series of "fg/bg" values, separated by a "+".

Each pair of "fg/bg" values gives the colors to which a basic color is mapped when used as a foreground or background color. The order of the mappings is:

• black
• red
• green
• yellow
• blue
• magenta
• cyan
• white

Pairs may be skipped, leaving them mapped as normal — same for missing pairs or single colors. 💅

For example, consider the following xo_emit call:

xo_emit("{C:fg-red,bg-green}Merry XMas!!{C:}0);

To turn all colored output to red-on-blue, use eight pairs of "red/blue" mappings separated by plus signs ("+"):

--libxo colors=red/blue+red/blue+red/blue+red/blue+                   red/blue+red/blue+red/blue+red/blue

To turn the red-on-green text to magenta-on-cyan, give a "magenta" foreground value for red (the second mapping) and a "cyan" background to green (the third mapping):

--libxo colors=+magenta+/cyan

Now consider the common situation where blue output looks unreadable on a terminal session with a black background 😭. To turn both "blue" foreground and background output to "yellow", give only the fifth mapping, skipping the first four mappings with bare plus signs ("+"):

--libxo colors=++++yellow/yellow

---

🏷️ Tag Mapping 🏷️

libxo supports mapping between tag names, for scenarios where the tags need to make specific values. For example, the "user" tag might be needed as the "owner" tag. libxo can perform this one-to-one tag replacement. slay.

⚠️ Note that libxo does not perform more complex transformations; languages such as XSLT or SLAX should be used when something more than simple one-to-one replacement is required.

Mapping can be specified using the map and map-file options. The map option accepts one or more mappings, in the format "old=new", separated by colons:

--libxo map:one=red,map:two=blue

This example would turn:

<one>fish</one>
<two>fish</two>

into:

<red>fish</red>
<blue>fish</blue>

In another example, the command-line options:

--libxo map:user=owner:name=file:size=bytes:modify-time=time

would turn:

<entry>
  <name>xx-00000009</name>
  <user>phil</user>
  <size>12345</size>
  <modify-time value="1644355825">1644355825</modify-time>
</entry>

into:

<entry>
  <file>xx-00000009</file>
  <owner>phil</owner>
  <bytes>12345</bytes>
  <time value="1644355825">1644355825</time>
</entry>

The map-file option allows the mappings to be placed into a file, one per line:

--libxo map-file=foo.map

where "foo.map" might contain:

# comments are supported, white space is ignored
user = owner
name=file
# blank lines are allowed

    size = bytes
modify-time= time

This untidy example demonstrates the flexibility in the libxo mapping files. (not me judging the formatting 🙈)

If the filename given with the map-file option contains no slashes ("/") and such a file does not exist in the current working directory, libxo will look for the file in the "map" subdirectory of the system "share" directory, typically /usr/share/libxo/map/.

---

🧩 Encoders 🧩

In addition to the four "built-in" formats, libxo supports an extensible mechanism for adding encoders. These are activated using the encoder keyword::

--libxo encoder=cbor

The encoder can include encoder-specific options, separated by either colons (":") or plus signs ("+"):

--libxo encoder=csv+path=filesystem+leaf=name+no-header
--libxo encoder=csv:path=filesystem:leaf=name:no-header

For brevity, the string "@" can be used in place of the string "encoder=":

df --libxo @csv:no-header

---

🔥 EXAMPLES 🔥

The following are three example invocations of ps(1):

ps --libxo json,pretty,warn -ux

ps --libxo=xml -lg

ps --libxo:Hxc 1

---

👀 SEE ALSO 👀

• libxo(3)
• xo_format(5)

---

📜 HISTORY 📜

The libxo library first appeared in FreeBSD 11.0.

---

👑 AUTHORS 👑

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

---

📚 ADDITIONAL DOCUMENTATION 📚

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

---

📜 HISTORY 📜

The libxo library was added in FreeBSD 11.0.

---

✍️ AUTHOR ✍️

Phil Shafer

---

aaaand that's the whole page, bestie 🫶 this one came from Debian, dated May 11, 2017, and it's the LIBXO(3) manual — go forth and --libxo responsibly, mwah 💖✨