LIBXO(3)

💖 LIBXO(3) 💖

okay bestie, welcome to LIBXO(3) — the Library Functions Manual page, but make it cute. this is the one about opening (and closing) container constructs. pull up a chair, grab a strawberry 🍓, we're doing hierarchy today.

---

✨ 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 does two kinds of hierarchy, and honestly it's giving organized queen energy 👑: “containers” and “lists”. a container shows up once under a given parent, whereas a list holds instances that can show up multiple times. a container is what you use to hold related fields together and to give your data some structure and scope. and here's the thing — the container itself has no value, it literally just serves to contain other nodes. it's the friend holding everyone's bags 💅.

to open a container, call xo_open_container() or xo_open_container_h(). the first one uses the default handle, the second one takes a specific handle that you hand it. same vibe, different handle situation.

to close a level, use xo_close_container() or xo_close_container_h().

every open call should have a matching close call, no cap. and if the XOF_WARN flag is set and the name you gave doesn't match the name of the currently open container? yeah, you're getting a warning generated at you. 🙈

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, you use the xo_open_container() and xo_close_container() set of functions, periodt. the handle parameter contains a handle — like one returned by xo_create(3) — or NULL if you just want the default handle. the name parameter gives the name of the container, and it's encoded in UTF-8. and because ASCII is a proper subset of UTF-8 (iykyk), you can just use traditional C strings directly, no drama. ✨

the close functions with the “_d” suffix are the ones you use in “Do The Right Thing” mode, where the names of the open containers, lists, and instances are all maintained internally by libxo so the caller gets to avoid keeping track of the open container name. that's the whole point — no more name-bookkeeping homework. 🎀

use the XOF_WARN flag to generate a warning if the name you gave on the close doesn't match the current open container.

for TEXT and HTML output, containers are not rendered into the output text — though for HTML they are used when the XOF_XPATH flag is set. so they're lowkey invisible but highkey still doing work. 💅

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. fair! libxo offers a “Do The Right Thing” mode, where libxo will track the names of open containers, lists, and instances so that the close function can be called without a name. to enable DTRT mode, turn on the XOF_DTRT flag prior to making any other libxo output — order matters, bestie.

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();

note that the XOF_WARN flag will also cause libxo to track open containers, lists, and instances. a warning gets generated when the name given to the close function and the name recorded don't match. 👀

---

🔍 SEE ALSO 🔍

• xo_emit(3)
• libxo(3)

---

📜 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

---

and that's the whole page, bestie — you officially know how to open and close containers without losing your mind. 💖✨🦋

this came to you from Debian, dated December 4, 2014, filed under LIBXO(3). stay slay, go forth, and always match your closes to your opens. 🎀💅🫶