xo_open_container(3)

1LIBXO(3)                 BSD Library Functions Manual                 LIBXO(3)
2

NAME

4     xo_open_container, xo_open_container_h, xo_open_container_hd,
5     xo_open_container_d xo_close_container, xo_close_container_h,
6     xo_close_container_hd, xo_close_container_d — open (and close) container
7     constructs
8

LIBRARY

10     library “libxo”
11

SYNOPSIS

13     #include <libxo/xo.h>
14
15     xo_ssize_t
16     xo_open_container(const char *name);
17
18     xo_ssize_t
19     xo_open_container_h(xo_handle_t *handle, const char *name);
20
21     xo_ssize_t
22     xo_open_container_hd(xo_handle_t *handle, const char *name);
23
24     xo_ssize_t
25     xo_open_container_d(const char *name);
26
27     xo_ssize_t
28     xo_close_container(const char *name);
29
30     xo_ssize_t
31     xo_close_container_h(xo_handle_t *handle, const char *name);
32
33     xo_ssize_t
34     xo_close_container_hd(xo_handle_t *handle);
35
36     xo_ssize_t
37     xo_close_container_d(void);
38

DESCRIPTION

40     libxo represents two types of hierarchy: “containers” and “lists”.  A
41     container appears once under a given parent where a list contains in‐
42     stances that can appear multiple times.  A container is used to hold re‐
43     lated fields and to give the data organization and scope.  The container
44     has no value, but serves to contain other nodes.
45
46     To open a container, call xo_open_container() or xo_open_container_h().
47     The former uses the default handle and the latter accepts a specific han‐
48     dle.
49
50     To close a level, use the xo_close_container() or xo_close_container_h()
51     functions.
52
53     Each open call should have a matching close call.  If the XOF_WARN flag
54     is set and the name given does not match the name of the currently open
55     container, a warning will be generated.
56               Example:
57
58                   xo_open_container("top");
59                   xo_open_container("system");
60                   xo_emit("{:host-name/%s%s%s", hostname,
61                           domainname ? "." : "", domainname ?: "");
62                   xo_close_container("system");
63                   xo_close_container("top");
64
65               Sample Output:
66                 Text:
67                   my-host.example.org
68                 XML:
69                   <top>
70                     <system>
71                         <host-name>my-host.example.org</host-name>
72                     </system>
73                   </top>
74                 JSON:
75                   "top" : {
76                     "system" : {
77                         "host-name": "my-host.example.org"
78                     }
79                   }
80                 HTML:
81                   <div class="data"
82                        data-tag="host-name">my-host.example.org</div>
83

EMITTING HIERARCHY

85     To create a container, use the xo_open_container() and
86     xo_close_container() set of functions.  The handle parameter contains a
87     handle such as returned by xo_create(3) or NULL to use the default han‐
88     dle.  The name parameter gives the name of the container, encoded in
89     UTF-8.  Since ASCII is a proper subset of UTF-8, traditional C strings
90     can be used directly.
91
92     The close functions with the “_d” suffix are used in “Do The Right Thing”
93     mode, where the name of the open containers, lists, and instances are
94     maintained internally by libxo to allow the caller to avoid keeping track
95     of the open container name.
96
97     Use the XOF_WARN flag to generate a warning if the name given on the
98     close does not match the current open container.
99
100     For TEXT and HTML output, containers are not rendered into output text,
101     though for HTML they are used when the XOF_XPATH flag is set.
102
103               EXAMPLE:
104                  xo_open_container("system");
105                  xo_emit("The host name is {:host-name}\n", hn);
106                  xo_close_container("system");
107               XML:
108                  <system><host-name>foo</host-name></system>
109

DTRT MODE

111     Some users may find tracking the names of open containers, lists, and in‐
112     stances inconvenient.  libxo offers a “Do The Right Thing” mode, where
113     libxo will track the names of open containers, lists, and instances so
114     the close function can be called without a name.  To enable DTRT mode,
115     turn on the XOF_DTRT flag prior to making any other libxo output.
116               xo_set_flags(NULL, XOF_DTRT);
117     Each open and close function has a version with the suffix “_d”, which
118     will close the open container, list, or instance:
119               xo_open_container("top");
120               ...
121               xo_close_container_d();
122     Note that the XOF_WARN flag will also cause libxo to track open contain‐
123     ers, lists, and instances.  A warning is generated when the name given to
124     the close function and the name recorded do not match.
125

HISTORY

130     The libxo library first appeared in FreeBSD 11.0.
131

AUTHORS

133     libxo was written by Phil Shafer <phil@freebsd.org>.
134
135

ADDITIONAL DOCUMENTATION

137     FreeBSD uses libxo version 1.6.0.  Complete documentation can be found on
138     github:
139
140           https://juniper.github.io/libxo/1.6.0/html/index.html
141
142     libxo lives on github as:
143
144           https://github.com/Juniper/libxo
145
146     The latest release of libxo is available at:
147
148           https://github.com/Juniper/libxo/releases
149

HISTORY

151     The libxo library was added in FreeBSD 11.0.
152

AUTHOR

154     Phil Shafer
155
156BSD                            December 4, 2014                            BSD