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_emit 15.Nd emit formatted output based on format string and arguments 16.Sh LIBRARY 17.Lb libxo 18.Sh SYNOPSIS 19.In libxo/xo.h 20.Sh NAME 21.Nm xo_open_list 22.Nm xo_open_list_h 23.Nm xo_open_list_hd 24.Nm xo_open_list_d 25.Nm xo_open_instance 26.Nm xo_open_instance_h 27.Nm xo_open_instance_hd 28.Nm xo_open_instance_d 29.Nm xo_close_instance 30.Nm xo_close_instance_h 31.Nm xo_close_instance_hd 32.Nm xo_close_instance_d 33.Nm xo_close_list 34.Nm xo_close_list_h 35.Nm xo_close_list_hd 36.Nm xo_close_list_d 37.Nd open and close lists and instances 38.Sh LIBRARY 39.Lb libxo 40.Sh SYNOPSIS 41.Ft int 42.Fn xo_open_list_h "xo_handle_t *xop" "const char *name" 43.Ft int 44.Fn xo_open_list "const char *name" 45.Ft int 46.Fn xo_open_list_hd "xo_handle_t *xop" "const char *name" 47.Ft int 48.Fn xo_open_list_d "const char *name" 49.Ft int 50.Fn xo_open_instance_h "xo_handle_t *xop" "const char *name" 51.Ft int 52.Fn xo_open_instance "const char *name" 53.Ft int 54.Fn xo_open_instance_hd "xo_handle_t *xop" "const char *name" 55.Ft int 56.Fn xo_open_instance_d "const char *name" 57.Ft int 58.Fn xo_close_instance_h "xo_handle_t *xop" "const char *name" 59.Ft int 60.Fn xo_close_instance "const char *name" 61.Ft int 62.Fn xo_close_instance_hd "xo_handle_t *xop" 63.Ft int 64.Fn xo_close_instance_d "void" 65.Ft int 66.Fn xo_close_list_h "xo_handle_t *xop" "const char *name" 67.Ft int 68.Fn xo_close_list "const char *name" 69.Ft int 70.Fn xo_close_list_hd "xo_handle_t *xop" 71.Ft int 72.Fn xo_close_list_d "void" 73.Sh DESCRIPTION 74Lists are sequences of instances of homogeneous data objects. 75Two 76distinct levels of calls are needed to represent them in our output 77styles. 78Calls must be made to open and close a list, and for each 79instance of data in that list, calls must be make to open and close 80that instance. 81.Pp 82The name given to all calls must be identical, and it is strongly 83suggested that the name be singular, not plural, as a matter of 84style and usage expectations. 85.Pp 86A list is a set of one or more instances that appear under the same 87parent. 88The instances contain details about a specific object. 89One can think of instances as objects or records. 90A call is needed to 91open and close the list, while a distinct call is needed to open and 92close each instance of the list: 93.Bd -literal -offset indent -compact 94 xo_open_list("item"); 95 96 for (ip = list; ip->i_title; ip++) { 97 xo_open_instance("item"); 98 xo_emit("{L:Item} '{:name/%s}':\n", ip->i_title); 99 xo_close_instance("item"); 100 } 101 102 xo_close_list("item"); 103.Ed 104Getting the list and instance calls correct is critical to the proper 105generation of XML and JSON data. 106.Pp 107.Bd -literal -offset indent -compact 108 EXAMPLE: 109 xo_open_list("user"); 110 for (i = 0; i < num_users; i++) { 111 xo_open_instance("user"); 112 xo_emit("{k:name}:{:uid/%u}:{:gid/%u}:{:home}\n", 113 pw[i].pw_name, pw[i].pw_uid, 114 pw[i].pw_gid, pw[i].pw_dir); 115 xo_close_instance("user"); 116 } 117 xo_close_list("user"); 118 TEXT: 119 phil:1001:1001:/home/phil 120 pallavi:1002:1002:/home/pallavi 121 XML: 122 <user> 123 <name>phil</name> 124 <uid>1001</uid> 125 <gid>1001</gid> 126 <home>/home/phil</home> 127 </user> 128 <user> 129 <name>pallavi</name> 130 <uid>1002</uid> 131 <gid>1002</gid> 132 <home>/home/pallavi</home> 133 </user> 134 JSON: 135 user: [ 136 { 137 "name": "phil", 138 "uid": 1001, 139 "gid": 1001, 140 "home": "/home/phil", 141 }, 142 { 143 "name": "pallavi", 144 "uid": 1002, 145 "gid": 1002, 146 "home": "/home/pallavi", 147 } 148 ] 149.Ed 150.Pp 151.Sh LEAF LISTS 152In contrast to a list of instances, a "leaf list" is list of simple 153values. 154To emit a leaf list, call the 155.Fn xo_emit 156function using the ""l"" modifier: 157.Bd -literal -offset indent -compact 158 for (ip = list; ip->i_title; ip++) { 159 xo_emit("{Lwc:Item}{l:item}\n", ip->i_title); 160 } 161.Ed 162.Pp 163The name of the field must match the name of the leaf list. 164.Pp 165In JSON, leaf lists are rendered as arrays of values. In XML, they 166are rendered as multiple leaf elements. 167.Bd -literal -offset indent -compact 168 JSON: 169 "item": "hammer", "nail" 170 XML: 171 <item>hammer</item> 172 <item>nail</item> 173.Ed 174.Sh ADDITIONAL DOCUMENTATION 175Complete documentation can be found on github: 176.Bd -literal -offset indent 177http://juniper.github.io/libxo/libxo-manual.html 178.Ed 179.Pp 180.Nm libxo 181lives on github as: 182.Bd -literal -offset indent 183https://github.com/Juniper/libxo 184.Ed 185.Pp 186The latest release of 187.Nm libxo 188is available at: 189.Bd -literal -offset indent 190https://github.com/Juniper/libxo/releases 191.Ed 192.Sh SEE ALSO 193.Xr xo_emit 3 194.Sh HISTORY 195The 196.Nm libxo 197library was added in 198.Fx 11.0 . 199.Sh AUTHOR 200Phil Shafer 201