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 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.Sh HISTORY 190The 191.Nm libxo 192library first appeared in 193.Fx 11.0 . 194.Sh AUTHORS 195.Nm libxo 196was written by 197.An Phil Shafer Aq Mt phil@freebsd.org . 198 199