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
14 .Nm xo_open_container , xo_open_container_h , xo_open_container_hd , xo_open_container_d
15 .Nm xo_close_container , xo_close_container_h , xo_close_container_hd , xo_close_container_d
16 .Nd open (and close) container constructs
22 .Fn xo_open_container "const char *name"
24 .Fn xo_open_container_h "xo_handle_t *handle" "const char *name"
26 .Fn xo_open_container_hd "xo_handle_t *handle" "const char *name"
28 .Fn xo_open_container_d "const char *name"
30 .Fn xo_close_container "const char *name"
32 .Fn xo_close_container_h "xo_handle_t *handle" "const char *name"
34 .Fn xo_close_container_hd "xo_handle_t *handle"
36 .Fn xo_close_container_d "void"
39 represents two types of hierarchy:
43 A container appears once under a given parent where a list contains
44 instances that can appear multiple times.
45 A container is used to hold
46 related fields and to give the data organization and scope.
47 The container has no value, but serves to
50 To open a container, call
53 .Fn xo_open_container_h .
54 The former uses the default handle and
55 the latter accepts a specific handle.
57 To close a level, use the
58 .Fn xo_close_container
60 .Fn xo_close_container_h
63 Each open call should have a matching close call.
66 flag is set and the name given does not match the name of
68 container, a warning will be generated.
69 .Bd -literal -offset indent -compact
72 xo_open_container("top");
73 xo_open_container("system");
74 xo_emit("{:host-name/%s%s%s", hostname,
75 domainname ? "." : "", domainname ?: "");
76 xo_close_container("system");
77 xo_close_container("top");
85 <host-name>my-host.example.org</host-name>
91 "host-name": "my-host.example.org"
96 data-tag="host-name">my-host.example.org</div>
98 .Sh EMITTING HIERARCHY
99 To create a container, use the
100 .Fn xo_open_container
102 .Fn xo_close_container
106 parameter contains a handle such as returned by
110 to use the default handle.
113 parameter gives the name of the container, encoded in
117 is a proper subset of
119 traditional C strings can be used directly.
121 The close functions with the
124 .Dq "Do The Right Thing"
125 mode, where the name of the open containers, lists, and
126 instances are maintained internally by
128 to allow the caller to
129 avoid keeping track of the open container name.
133 flag to generate a warning if the name given on the
134 close does not match the current open container.
136 For TEXT and HTML output, containers are not rendered into output
137 text, though for HTML they are used when the
141 .Bd -literal -offset indent -compact
143 xo_open_container("system");
144 xo_emit("The host name is {:host-name}\n", hn);
145 xo_close_container("system");
147 <system><host-name>foo</host-name></system>
150 Some users may find tracking the names of open containers, lists, and
151 instances inconvenient.
154 .Dq "Do The Right Thing"
157 will track the names of open containers, lists, and instances so
158 the close function can be called without a name.
164 flag prior to making any other
167 .Bd -literal -offset indent -compact
168 xo_set_flags(NULL, XOF_DTRT);
170 Each open and close function has a version with the suffix
172 which will close the open container, list, or instance:
173 .Bd -literal -offset indent -compact
174 xo_open_container("top");
176 xo_close_container_d();
183 containers, lists, and instances.
184 A warning is generated when the name given to the close function
185 and the name recorded do not match.