1.\" #
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
7.\" # LICENSE.
8.\" # Phil Shafer, July 2014
9.\"
10.Dd December 4, 2014
11.Dt LIBXO 3
12.Os
13.Sh NAME
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
17.Sh LIBRARY
18.Lb libxo
19.Sh SYNOPSIS
20.In libxo/xo.h
21.Ft int
22.Fn xo_open_container "const char *name"
23.Ft int
24.Fn xo_open_container_h "xo_handle_t *handle" "const char *name"
25.Ft int
26.Fn xo_open_container_hd "xo_handle_t *handle" "const char *name"
27.Ft int
28.Fn xo_open_container_d "const char *name"
29.Ft int
30.Fn xo_close_container "const char *name"
31.Ft int
32.Fn  xo_close_container_h "xo_handle_t *handle" "const char *name"
33.Ft int
34.Fn xo_close_container_hd "xo_handle_t *handle"
35.Ft int
36.Fn xo_close_container_d "void"
37.Sh DESCRIPTION
38.Nm libxo
39represents two types of hierarchy:
40.Dq containers
41and
42.Dq lists .
43A container appears once under a given parent where a list contains
44instances that can appear multiple times.
45A container is used to hold
46related fields and to give the data organization and scope.
47The container has no value, but serves to
48contain other nodes.
49.Pp
50To open a container, call
51.Fn xo_open_container
52or
53.Fn xo_open_container_h .
54The former uses the default handle and
55the latter accepts a specific handle.
56.Pp
57To close a level, use the
58.Fn xo_close_container
59or
60.Fn xo_close_container_h
61functions.
62.Pp
63Each open call should have a matching close call.
64If the
65.Dv XOF_WARN
66flag is set and the name given does not match the name of
67the currently open
68container, a warning will be generated.
69.Bd -literal -offset indent -compact
70    Example:
71
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");
78
79    Sample Output:
80      Text:
81        my-host.example.org
82      XML:
83        <top>
84          <system>
85              <host-name>my-host.example.org</host-name>
86          </system>
87        </top>
88      JSON:
89        "top" : {
90          "system" : {
91              "host-name": "my-host.example.org"
92          }
93        }
94      HTML:
95        <div class="data"
96             data-tag="host-name">my-host.example.org</div>
97.Ed
98.Sh EMITTING HIERARCHY
99To create a container, use the
100.Fn xo_open_container
101and
102.Fn xo_close_container
103set of functions.
104The
105.Fa handle
106parameter contains a handle such as returned by
107.Xr xo_create 3
108or
109.Dv NULL
110to use the default handle.
111The
112.Fa name
113parameter gives the name of the container, encoded in
114.Em UTF-8 .
115Since
116.Em ASCII
117is a proper subset of
118.Em UTF-8 ,
119traditional C strings can be used directly.
120.Pp
121The close functions with the
122.Dq _d
123suffix are used in
124.Dq "Do The Right Thing"
125mode, where the name of the open containers, lists, and
126instances are maintained internally by
127.Nm libxo
128to allow the caller to
129avoid keeping track of the open container name.
130.Pp
131Use the
132.Dv XOF_WARN
133flag to generate a warning if the name given on the
134close does not match the current open container.
135.Pp
136For TEXT and HTML output, containers are not rendered into output
137text, though for HTML they are used when the
138.Dv XOF_XPATH
139flag is set.
140.Pp
141.Bd -literal -offset indent -compact
142    EXAMPLE:
143       xo_open_container("system");
144       xo_emit("The host name is {:host-name}\n", hn);
145       xo_close_container("system");
146    XML:
147       <system><host-name>foo</host-name></system>
148.Ed
149.Sh DTRT MODE
150Some users may find tracking the names of open containers, lists, and
151instances inconvenient.
152.Nm libxo
153offers a
154.Dq "Do The Right Thing"
155mode, where
156.Nm libxo
157will track the names of open containers, lists, and instances so
158the close function can be called without a name.
159To enable
160.Em DTRT
161mode,
162turn on the
163.Dv XOF_DTRT
164flag prior to making any other
165.Nm libxo
166output.
167.Bd -literal -offset indent -compact
168    xo_set_flags(NULL, XOF_DTRT);
169.Ed
170Each open and close function has a version with the suffix
171.Dq _d ,
172which will close the open container, list, or instance:
173.Bd -literal -offset indent -compact
174    xo_open_container("top");
175    ...
176    xo_close_container_d();
177.Ed
178Note that the
179.Dv XOF_WARN
180flag will also cause
181.Nm libxo
182to track open
183containers, lists, and instances.
184A warning is generated when the name given to the close function
185and the name recorded do not match.
186.Sh SEE ALSO
187.Xr xo_emit 3 ,
188.Xr libxo 3
189