LIBXO(3)

💅 LIBXO(3) — ok so hear me out

bestie, we're in section 3 of the manual (that's library functions for the uninitiated 💖) and today's topic is libxo's marker functions. yes, the whole page is about markers. no, i'm not gonna make it boring. let's go 🎀

---

✨ NAME ✨

xo_open_marker, xo_open_marker_h, xo_close_marker, xo_close_marker_h — the girlies that prevent and allow closing of open constructs. literally the bouncers of your output tree 🫶

---

📚 LIBRARY 📚

library “libxo” — she's the moment, she's the icon 👑

---

🌸 SYNOPSIS 🌸

#include <libxo/xo.h>

xo_ssize_t
xo_open_marker(const char *name);

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

xo_ssize_t
xo_close_marker(const char *name);

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

not me listing all four signatures exactly as they are 💅 copy them character for character, i don't make the rules (i do, actually, and that's the rule).

---

🦋 DESCRIPTION 🦋

okay so first, the lore 🧚: libxo represents hierarchy using two constructs — “containers” and “lists”. that's the whole family tree.

a marker is what you use to affect how open constructs get closed. two ways, pick your fighter:

• by preventing their closure (implicit or explicit, both count)
• by forcing their closure

💀 while a marker is open, no other open constructs can be closed. like, none. zero. the door is LOCKED.

and when a marker is closed? all constructs open since the marker was opened will be closed. everything. all of it. periodt.

so think of a marker as a way to "freeze" any open constructs ❄️. calls to xo_close_*() functions that would normally close them get ignored — effectively blocking their closure. no cap, they just get ghosted 🙈.

but the second you call xo_close_marker(), any containers, lists, or leaf-lists opened since the matching xo_open_marker() call get closed, and the marker itself gets discarded. bye bestie 👋

markers use names which are not user-visible — so you get to pick whatever internal names feel right to you. no one's watching, go feral 🍓. the marker has no value and is not emitted in any form. it's giving invisible main character energy.

---

🌈 opening & closing, the basics

to open a marker, call xo_open_marker() or xo_open_marker_h().

• the former uses the default handle
• the latter accepts a specific handle

to close a marker, use the xo_close_marker() or xo_close_marker_h() functions.

⭐ and fr fr: each open call must have a matching close call. that's the vibe check. don't leave her hanging 😭

---

🐟 example one — the "outer" marker

in this example, the xo_close_container() call on line [1] will be ignored, since the open marker "outer" will prevent close of any open constructs that precede it. lowkey rude of it but okay.

the xo_close_marker() call on line [2] will close the "system" container, since it was opened after the "outer" marker. slay, order matters 💅

Example:

xo_open_container("top");
xo_open_marker("outer");
xo_open_container("system");
xo_emit("{:host-name/%s%s%s", hostname,
        domainname ? "." : "", domainname ?: "");
xo_close_container("top");   /* [1] */
xo_close_marker("outer");    /* [2] */
xo_close_container("top");

---

🧜‍♀️ example two — the "fish-guts" agenda

in this example, the code whiffles through a list of fish (yes, whiffles, that's the technical term, i don't make the words i just deliver them 🐠), calling a function to emit details about each fish.

the marker "fish-guts" is used to ensure that any constructs opened by the function are closed properly. iconic safety net behavior honestly 🥹

for (i = 0; fish[i]; i++) {
    xo_open_instance("fish");
    xo_open_marker("fish-guts");
    dump_fish_details(i);
    xo_close_marker("fish-guts");
}

---

👀 SEE ALSO 👀

• xo_emit(3)
• libxo(3)

go read them, i'll wait 💜

---

🎀 HISTORY 🎀

the libxo library first appeared in FreeBSD 11.0. a legend was born ✨

---

🫶 AUTHORS 🫶

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

---

and that's the page bestie!! this edition came to you from Debian, dated January 22, 2015, and it's filed under LIBXO(3) in case you need to find her again 🌸 mwah 💋