LIBXO(3)

💅 LIBXO(3) — containers, bestie

okay so this is the page for libxo, from the Library Functions Manual (yes the header says LIBXO(3) at both ends, we love a symmetrical queen 👑). It's all about the xo_open_container* and xo_close_container* girlies — opening and closing container constructs. Let's get into it 🎀

---

✨ NAME ✨

xo_open_container, xo_open_container_h, xo_open_container_hd, xo_open_container_d, xo_close_container, xo_close_container_h, xo_close_container_hd, xo_close_container_d — open (and close) container constructs 🫶

📚 LIBRARY 📚

library “libxo”

🧚 SYNOPSIS 🧚

#include <libxo/xo.h>

xo_ssize_t
xo_open_container(const char *name);

xo_ssize_t
xo_open_container_h(xo_handle_t *handle, const char *name);

xo_ssize_t
xo_open_container_hd(xo_handle_t *handle, const char *name);

xo_ssize_t
xo_open_container_d(const char *name);

xo_ssize_t
xo_close_container(const char *name);

xo_ssize_t
xo_close_container_h(xo_handle_t *handle, const char *name);

xo_ssize_t
xo_close_container_hd(xo_handle_t *handle);

xo_ssize_t
xo_close_container_d(void);

🌸 DESCRIPTION 🌸

So libxo has two types of hierarchy, and they're giving very different vibes: “containers” and “lists”. A container shows up once under a given parent, whereas a list holds instances that can appear multiple times (main character energy, honestly). A container is literally there to hold related fields and to give your data organization and scope. Bestie, the container has no value — it just serves to contain other nodes. It's the friend who holds everyone's bags 💅

To open a container, call xo_open_container() or xo_open_container_h(). The first one uses the default handle, and the second one lets you pass in a specific handle. iykyk ✨

To close a level, use the xo_close_container() or xo_close_container_h() functions.

⚠️ Every open call should have a matching close call, fr fr. If the XOF_WARN flag is set and the name you give doesn't match the name of the currently open container, a warning will be generated. Not a slay.

Example:

xo_open_container("top");
xo_open_container("system");
xo_emit("{:host-name/%s%s%s", hostname,
        domainname ? "." : "", domainname ?: "");
xo_close_container("system");
xo_close_container("top");

Sample Output:

Text:

my-host.example.org

XML:

<top>
  <system>
      <host-name>my-host.example.org</host-name>
  </system>
</top>

JSON:

"top" : {
  "system" : {
      "host-name": "my-host.example.org"
  }
}

HTML:

<div class="data"
     data-tag="host-name">my-host.example.org</div>

---

🦋 EMITTING HIERARCHY 🦋

To create a container, use the xo_open_container() and xo_close_container() set of functions, bestie.

The handle parameter contains a handle such as returned by xo_create(3), or NULL to use the default handle. The name parameter gives the name of the container, encoded in UTF-8. And since ASCII is a proper subset of UTF-8, traditional C strings can be used directly — no conversion drama, we love to see it 💖

The close functions with the “_d” suffix are used in “Do The Right Thing” mode, where the names of the open containers, lists, and instances are maintained internally by libxo so you, the caller, don't have to keep track of the open container name. That's the self-care we deserve 🙈

Use the XOF_WARN flag to generate a warning if the name given on the close does not match the current open container.

For TEXT and HTML output, containers are not rendered into output text — lowkey invisible. Though for HTML they are used when the XOF_XPATH flag is set. Sneaky but iconic ⭐

EXAMPLE:

xo_open_container("system");
xo_emit("The host name is {:host-name}\n", hn);
xo_close_container("system");

XML:

<system><host-name>foo</host-name></system>

---

👑 DTRT MODE 👑

Some users may find tracking the names of open containers, lists, and instances inconvenient — and honestly? Valid. So libxo offers a “Do The Right Thing” mode, where libxo will track the names of open containers, lists, and instances so the close function can be called without a name. The vibes are immaculate.

To enable DTRT mode, turn on the XOF_DTRT flag prior to making any other libxo output. Do it first, bestie, not later ‼️

xo_set_flags(NULL, XOF_DTRT);

Each open and close function has a version with the suffix “_d”, which will close the open container, list, or instance:

xo_open_container("top");
...
xo_close_container_d();

💀 One note, no cap: the XOF_WARN flag will also cause libxo to track open containers, lists, and instances. A warning is generated when the name given to the close function and the name recorded do not match.

---

🔥 SEE ALSO 🔥

• xo_emit(3)
• libxo(3)

🌈 HISTORY 🌈

The libxo library first appeared in FreeBSD 11.0. A whole era ✨

🫶 AUTHORS 🫶

libxo was written by Phil Shafer <phil@freebsd.org> — thank you king 👑

---

and that's the whole page, bestie 🎀 this edition comes to you from Debian, dated December 4, 2014, and yeah — it's LIBXO(3) all the way down. go open some containers, and for the love of everything, close them too 💜