LIBXO(3)

💖 LIBXO — like, the whole vibe 💖

okay bestie, sit DOWN, because we're talking about libxo from the Library Functions Manual and honestly? it's giving main character energy. the NAME of this whole situation is literally just libxo — description of libxo usage. that's it, that's the pitch, and it ate. 💅

---

✨ NAME ✨

libxo — description of libxo usage 🦋

---

🌸 DESCRIPTION 🌸

okay so here's the tea: libxo is a software component that lets other software generate a whole variety of output styles — we're talking text, XML, JSON, and HTML. iconic lineup honestly. 🌈

the way that works is: you write one single section of code, and that one section provides the formatting and structural information, and then at run-time you get to choose which format gets emitted. so it's one code path, many lewks. and the reason that's so slay is that it gives you functional equivalence between the format options — like, XML and JSON formatted output can reliably carry the same content, no cap. it also reduces software maintenance costs, since there's a single code path to change or correct, rather than one per output style. no more maintaining five parallel copies of everything, we are NOT doing that in this house. 🙈

and "Structured" output styles like JSON and XML? those allow programmatic parsing of the output content in reliable and robust ways, and it future-proofs by allowing the addition of new fields without impacting parsing. that's the future-proofing, periodt. 💅

libxo also supports "plug-in" encoders, which allow new output styles to be developed independently — like 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. trade-offs, we love a trade-off. ✨

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. chaos permitted, honestly encouraged. 💀

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

five whole ways to say the same thing and every single one of them is valid. obsessed. 😭

---

🎀 EXAMPLES 🎀

the following example shows the same content generated using multiple style options: text, XML, JSON, and HTML. same content, four outfits, all of them cute. 👑

% 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. so you get the real number and the cute little abbreviation. best of both. 🫶

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). 💖

---

🌈 SEE ALSO 🌈

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

go read them, bestie, they're all part of the same cinematic universe. ⭐

---

🦋 HISTORY 🦋

the libxo library first appeared in FreeBSD 11.0. vintage, but like, the good kind. 💜

---

👑 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 (yes, again, bestie) 🔥

the libxo library was added in FreeBSD 11.0.

okay so real talk — the original page has HISTORY twice and AUTHOR/AUTHORS twice too. I'm not merging them, I'm not "fixing" them, I'm just delivering them exactly as they came. that's called respecting the source material. 💅

---

🌸 AUTHOR 🌸

Phil Shafer

---

and that's the whole thing!! 💖 this page came to us from Debian, dated February 23, 2023, and it's LIBXO(3) — the one and only. go forth and emit structured output, bestie, you're gonna do amazing. slay ✨ 🎀