1LIBXO(3) BSD Library Functions Manual LIBXO(3)
2
4 xo_open_marker, xo_open_marker_h, xo_close_marker, xo_close_marker_h —
5 prevent and allow closing of open constructs
6
8 library “libxo”
9
11 #include <libxo/xo.h>
12 xo_ssize_t
14 xo_open_marker(const char *name);
15 xo_ssize_t
17 xo_open_marker_h(xo_handle_t *handle, const char *name);
18 xo_ssize_t
20 xo_close_marker(const char *name);
21 xo_ssize_t
23 xo_close_marker_h(xo_handle_t *handle, const char *name);
24
26 libxo represents hierarchy using two constructs: “containers” and
27 “lists”. A marker can be used to affect how open constructs are closed,
28 either by preventing their (implicit or explicit) closure or by forcing
29 their closure. While a marker is open, no other open constructs can be
30 closed. When a marker is closed, all constructs open since the marker
31 was opened will be closed. A marker is used to "freeze" any open con‐
32 structs. Calls to xo_close_*() functions that would normally close them
33 will be ignored, effectively blocking their closure. However when
34 xo_close_marker() is called, any containers, lists, or leaf-lists open
35 since the matching xo_open_marker() call will be close and the marker
36 discarded. Markers use names which are not user-visible, allowing the
37 caller to choose appropriate internal names. The marker has no value and
38 is not emitted in any form.
39 To open a marker, call xo_open_marker() or xo_open_marker_h(). The for‐
41 mer uses the default handle and the latter accepts a specific handle.
42 To close a marker, use the xo_close_marker() or xo_close_marker_h() func‐
44 tions.
45 Each open call must have a matching close call.
47 In this example, the xo_close_container() call on line [1] will be ig‐
49 nored, since the open marker "outer" will prevent close of any open con‐
50 structs that precede it. The xo_close_marker() call on line [2] will
51 close the "system" container, since it was opened after the "outer"
52 marker.
53 Example:
54 xo_open_container("top");
56 xo_open_marker("outer");
57 xo_open_container("system");
58 xo_emit("{:host-name/%s%s%s", hostname,
59 domainname ? "." : "", domainname ?: "");
60 xo_close_container("top"); /* [1] */
61 xo_close_marker("outer"); /* [2] */
62 xo_close_container("top");
63 In this example, the code whiffles through a list of fish, calling a
65 function to emit details about each fish. The marker "fish-guts" is used
66 to ensure that any constructs opened by the function are closed properly.
67 for (i = 0; fish[i]; i++) {
69 xo_open_instance("fish");
70 xo_open_marker("fish-guts");
71 dump_fish_details(i);
72 xo_close_marker("fish-guts");
73 }
74
76 xo_emit(3), libxo(3)
77
79 The libxo library first appeared in FreeBSD 11.0.
80
82 libxo was written by Phil Shafer <phil@freebsd.org>.
83
86 FreeBSD uses libxo version 1.6.0. Complete documentation can be found on
87 github:
88 https://juniper.github.io/libxo/1.6.0/html/index.html
90 libxo lives on github as:
92 https://github.com/Juniper/libxo
94 The latest release of libxo is available at:
96 https://github.com/Juniper/libxo/releases
98
100 The libxo library was added in FreeBSD 11.0.
101
103 Phil Shafer
104BSD January 22, 2015 BSD