contrib/libxo/libxo/xo_open_container.3

   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
  15 .Nd open (and close) container constructs
  16 .Sh LIBRARY
  17 .Lb libxo
  18 .Sh SYNOPSIS
  19 .In libxo/xo.h
  20 .Sh NAME
  21 .Nm xo_open_container
  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
  30 .Sh LIBRARY
  31 .Lb libxo
  32 .Sh SYNOPSIS
  33 .Ft int
  34 .Fn xo_open_container "const char *name"
  35 .Ft int
  36 .Fn xo_open_container_h "xo_handle_t *handle" "const char *name"
  37 .Ft int
  38 .Fn xo_open_container_hd "xo_handle_t *handle" "const char *name"
  39 .Ft int
  40 .Fn xo_open_container_d "const char *name"
  41 .Ft int
  42 .Fn xo_close_container "const char *name"
  43 .Ft int
  44 .Fn  xo_close_container_h "xo_handle_t *handle" "const char *name"
  45 .Ft int
  46 .Fn xo_close_container_hd "xo_handle_t *handle"
  47 .Ft int
  48 .Fn xo_close_container_d "void"
  49 .Sh DESCRIPTION
  50 .Nm libxo
  51 represents two types of hierarchy:
  52 .Dq containers
  53 and
  54 .Dq lists .
  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
  60 contain other nodes.
  61 .Pp
  62 To open a container, call
  63 .Fn xo_open_container
  64 or
  65 .Fn xo_open_container_h .
  66 The former uses the default handle and
  67 the latter accepts a specific handle.
  68 .Pp
  69 To close a level, use the
  70 .Fn xo_close_container
  71 or
  72 .Fn xo_close_container_h
  73 functions.
  74 .Pp
  75 Each open call should have a matching close call.
  76 If the
  77 .Dv XOF_WARN
  78 flag is set and the name given does not match the name of
  79 the currently open
  80 container, a warning will be generated.
  81 .Bd -literal -offset indent -compact
  82     Example:
  83
  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");
  90
  91     Sample Output:
  92       Text:
  93         my-host.example.org
  94       XML:
  95         <top>
  96           <system>
  97               <host-name>my-host.example.org</host-name>
  98           </system>
  99         </top>
 100       JSON:
 101         "top" : {
 102           "system" : {
 103               "host-name": "my-host.example.org"
 104           }
 105         }
 106       HTML:
 107         <div class="data"
 108              data-tag="host-name">my-host.example.org</div>
 109 .Ed
 110 .Sh EMITTING HIERARCHY
 111 To create a container, use the
 112 .Fn xo_open_container
 113 and
 114 .Fn xo_close_container
 115 set of functions.
 116 The
 117 .Fa handle
 118 parameter contains a handle such as returned by
 119 .Xr xo_create 3
 120 or
 121 .Dv NULL
 122 to use the default handle.
 123 The
 124 .Fa name
 125 parameter gives the name of the container, encoded in
 126 .Em UTF-8 .
 127 Since
 128 .Em ASCII
 129 is a proper subset of
 130 .Em UTF-8 ,
 131 traditional C strings can be used directly.
 132 .Pp
 133 The close functions with the
 134 .Dq _d
 135 suffix are used in
 136 .Dq \&Do The Right Thing
 137 mode, where the name of the open containers, lists, and
 138 instances are maintained internally by
 139 .Nm libxo
 140 to allow the caller to
 141 avoid keeping track of the open container name.
 142 .Pp
 143 Use the
 144 .Dv XOF_WARN
 145 flag to generate a warning if the name given on the
 146 close does not match the current open container.
 147 .Pp
 148 For TEXT and HTML output, containers are not rendered into output
 149 text, though for HTML they are used when the
 150 .Dv XOF_XPATH
 151 flag is set.
 152 .Pp
 153 .Bd -literal -offset indent -compact
 154     EXAMPLE:
 155        xo_open_container("system");
 156        xo_emit("The host name is {:host-name}\n", hn);
 157        xo_close_container("system");
 158     XML:
 159        <system><host-name>foo</host-name></system>
 160 .Ed
 161 .Sh DTRT MODE
 162 Some users may find tracking the names of open containers, lists, and
 163 instances inconvenient.
 164 .Nm libxo
 165 offers a
 166 .Dq \&Do The Right Thing
 167 mode, where
 168 .Nm libxo
 169 will track the names of open containers, lists, and instances so
 170 the close function can be called without a name.
 171 To enable
 172 .Em DTRT
 173 mode,
 174 turn on the
 175 .Dv XOF_DTRT
 176 flag prior to making any other
 177 .Nm libxo
 178 output.
 179 .Bd -literal -offset indent -compact
 180     xo_set_flags(NULL, XOF_DTRT);
 181 .Ed
 182 Each open and close function has a version with the suffix
 183 .Dq _d ,
 184 which will close the open container, list, or instance:
 185 .Bd -literal -offset indent -compact
 186     xo_open_container("top");
 187     ...
 188     xo_close_container_d();
 189 .Ed
 190 Note that the
 191 .Dv XOF_WARN
 192 flag will also cause
 193 .Nm libxo
 194 to track open
 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
 202 .Ed
 203 .Pp
 204 .Nm libxo
 205 lives on github as:
 206 .Bd -literal -offset indent
 207 https://github.com/Juniper/libxo
 208 .Ed
 209 .Pp
 210 The latest release of
 211 .Nm libxo
 212 is available at:
 213 .Bd -literal -offset indent
 214 https://github.com/Juniper/libxo/releases
 215 .Ed
 216 .Sh SEE ALSO
 217 .Xr xo_emit 3
 218 .Sh HISTORY
 219 The
 220 .Nm libxo
 221 library was added in
 222 .Fx 11.0 .
 223 .Sh AUTHOR
 224 Phil Shafer