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 , 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 xo_ssize_t
  22 .Fn xo_open_container "const char *name"
  23 .Ft xo_ssize_t
  24 .Fn xo_open_container_h "xo_handle_t *handle" "const char *name"
  25 .Ft xo_ssize_t
  26 .Fn xo_open_container_hd "xo_handle_t *handle" "const char *name"
  27 .Ft xo_ssize_t
  28 .Fn xo_open_container_d "const char *name"
  29 .Ft xo_ssize_t
  30 .Fn xo_close_container "const char *name"
  31 .Ft xo_ssize_t
  32 .Fn  xo_close_container_h "xo_handle_t *handle" "const char *name"
  33 .Ft xo_ssize_t
  34 .Fn xo_close_container_hd "xo_handle_t *handle"
  35 .Ft xo_ssize_t
  36 .Fn xo_close_container_d "void"
  37 .Sh DESCRIPTION
  38 .Nm libxo
  39 represents two types of hierarchy:
  40 .Dq containers
  41 and
  42 .Dq lists .
  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
  48 contain other nodes.
  49 .Pp
  50 To open a container, call
  51 .Fn xo_open_container
  52 or
  53 .Fn xo_open_container_h .
  54 The former uses the default handle and
  55 the latter accepts a specific handle.
  56 .Pp
  57 To close a level, use the
  58 .Fn xo_close_container
  59 or
  60 .Fn xo_close_container_h
  61 functions.
  62 .Pp
  63 Each open call should have a matching close call.
  64 If the
  65 .Dv XOF_WARN
  66 flag is set and the name given does not match the name of
  67 the currently open
  68 container, 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
  99 To create a container, use the
 100 .Fn xo_open_container
 101 and
 102 .Fn xo_close_container
 103 set of functions.
 104 The
 105 .Fa handle
 106 parameter contains a handle such as returned by
 107 .Xr xo_create 3
 108 or
 109 .Dv NULL
 110 to use the default handle.
 111 The
 112 .Fa name
 113 parameter gives the name of the container, encoded in
 114 .Em UTF-8 .
 115 Since
 116 .Em ASCII
 117 is a proper subset of
 118 .Em UTF-8 ,
 119 traditional C strings can be used directly.
 120 .Pp
 121 The close functions with the
 122 .Dq _d
 123 suffix are used in
 124 .Dq "Do The Right Thing"
 125 mode, where the name of the open containers, lists, and
 126 instances are maintained internally by
 127 .Nm libxo
 128 to allow the caller to
 129 avoid keeping track of the open container name.
 130 .Pp
 131 Use the
 132 .Dv XOF_WARN
 133 flag to generate a warning if the name given on the
 134 close does not match the current open container.
 135 .Pp
 136 For TEXT and HTML output, containers are not rendered into output
 137 text, though for HTML they are used when the
 138 .Dv XOF_XPATH
 139 flag 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
 150 Some users may find tracking the names of open containers, lists, and
 151 instances inconvenient.
 152 .Nm libxo
 153 offers a
 154 .Dq "Do The Right Thing"
 155 mode, where
 156 .Nm libxo
 157 will track the names of open containers, lists, and instances so
 158 the close function can be called without a name.
 159 To enable
 160 .Em DTRT
 161 mode,
 162 turn on the
 163 .Dv XOF_DTRT
 164 flag prior to making any other
 165 .Nm libxo
 166 output.
 167 .Bd -literal -offset indent -compact
 168     xo_set_flags(NULL, XOF_DTRT);
 169 .Ed
 170 Each open and close function has a version with the suffix
 171 .Dq _d ,
 172 which 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
 178 Note that the
 179 .Dv XOF_WARN
 180 flag will also cause
 181 .Nm libxo
 182 to track open
 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.
 186 .Sh SEE ALSO
 187 .Xr xo_emit 3 ,
 188 .Xr libxo 3
 189 .Sh HISTORY
 190 The
 191 .Nm libxo
 192 library first appeared in
 193 .Fx 11.0 .
 194 .Sh AUTHORS
 195 .Nm libxo
 196 was written by
 197 .An Phil Shafer Aq Mt phil@freebsd.org .
 198