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