2 .\" # Copyright (c) 2014, Juniper Networks, Inc.
3 .\" # All rights reserved.
4 .\" # This SOFTWARE is licensed under the LICENSE provided in the
5 .\" # ../Copyright file. By downloading, installing, copying, or
6 .\" # using the SOFTWARE, you agree to be bound by the terms of that
8 .\" # Phil Shafer, July 2014
15 .Nd open (and close) container constructs
22 .Nm xo_open_container_h
23 .Nm xo_open_container_hd
24 .Nm xo_open_container_d
25 .Nm xo_close_container
26 .Nm xo_close_container_h
27 .Nm xo_close_container_hd
28 .Nm xo_close_container_d
29 .Nd open and close containers
34 .Fn xo_open_container "const char *name"
36 .Fn xo_open_container_h "xo_handle_t *handle" "const char *name"
38 .Fn xo_open_container_hd "xo_handle_t *handle" "const char *name"
40 .Fn xo_open_container_d "const char *name"
42 .Fn xo_close_container "const char *name"
44 .Fn xo_close_container_h "xo_handle_t *handle" "const char *name"
46 .Fn xo_close_container_hd "xo_handle_t *handle"
48 .Fn xo_close_container_d "void"
51 represents two types of hierarchy:
55 A container appears once under a given parent where a list contains
56 instances that can appear multiple times.
57 A container is used to hold
58 related fields and to give the data organization and scope.
59 The container has no value, but serves to
62 To open a container, call
65 .Fn xo_open_container_h .
66 The former uses the default handle and
67 the latter accepts a specific handle.
69 To close a level, use the
70 .Fn xo_close_container
72 .Fn xo_close_container_h
75 Each open call should have a matching close call.
78 flag is set and the name given does not match the name of
80 container, a warning will be generated.
81 .Bd -literal -offset indent -compact
84 xo_open_container("top");
85 xo_open_container("system");
86 xo_emit("{:host-name/%s%s%s", hostname,
87 domainname ? "." : "", domainname ?: "");
88 xo_close_container("system");
89 xo_close_container("top");
97 <host-name>my-host.example.org</host-name>
103 "host-name": "my-host.example.org"
108 data-tag="host-name">my-host.example.org</div>
110 .Sh EMITTING HIERARCHY
111 To create a container, use the
112 .Fn xo_open_container
114 .Fn xo_close_container
118 parameter contains a handle such as returned by
122 to use the default handle.
125 parameter gives the name of the container, encoded in
129 is a proper subset of
131 traditional C strings can be used directly.
133 The close functions with the
136 .Dq \&Do The Right Thing
137 mode, where the name of the open containers, lists, and
138 instances are maintained internally by
140 to allow the caller to
141 avoid keeping track of the open container name.
145 flag to generate a warning if the name given on the
146 close does not match the current open container.
148 For TEXT and HTML output, containers are not rendered into output
149 text, though for HTML they are used when the
153 .Bd -literal -offset indent -compact
155 xo_open_container("system");
156 xo_emit("The host name is {:host-name}\n", hn);
157 xo_close_container("system");
159 <system><host-name>foo</host-name></system>
162 Some users may find tracking the names of open containers, lists, and
163 instances inconvenient.
166 .Dq \&Do The Right Thing
169 will track the names of open containers, lists, and instances so
170 the close function can be called without a name.
176 flag prior to making any other
179 .Bd -literal -offset indent -compact
180 xo_set_flags(NULL, XOF_DTRT);
182 Each open and close function has a version with the suffix
184 which will close the open container, list, or instance:
185 .Bd -literal -offset indent -compact
186 xo_open_container("top");
188 xo_close_container_d();
195 containers, lists, and instances.
196 A warning is generated when the name given to the close function
197 and the name recorded do not match.
198 .Sh ADDITIONAL DOCUMENTATION
199 Complete documentation can be found on github:
200 .Bd -literal -offset indent
201 http://juniper.github.io/libxo/libxo-manual.html
206 .Bd -literal -offset indent
207 https://github.com/Juniper/libxo
210 The latest release of
213 .Bd -literal -offset indent
214 https://github.com/Juniper/libxo/releases