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
8 .\" # Phil Shafer, July 2014
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
24 .Fn xo_open_list_h "xo_handle_t *xop" "const char *name"
26 .Fn xo_open_list "const char *name"
28 .Fn xo_open_list_hd "xo_handle_t *xop" "const char *name"
30 .Fn xo_open_list_d "const char *name"
32 .Fn xo_open_instance_h "xo_handle_t *xop" "const char *name"
34 .Fn xo_open_instance "const char *name"
36 .Fn xo_open_instance_hd "xo_handle_t *xop" "const char *name"
38 .Fn xo_open_instance_d "const char *name"
40 .Fn xo_close_instance_h "xo_handle_t *xop" "const char *name"
42 .Fn xo_close_instance "const char *name"
44 .Fn xo_close_instance_hd "xo_handle_t *xop"
46 .Fn xo_close_instance_d "void"
48 .Fn xo_close_list_h "xo_handle_t *xop" "const char *name"
50 .Fn xo_close_list "const char *name"
52 .Fn xo_close_list_hd "xo_handle_t *xop"
54 .Fn xo_close_list_d "void"
56 Lists are sequences of instances of homogeneous data objects.
58 distinct levels of calls are needed to represent them in our output
60 Calls must be made to open and close a list, and for each
61 instance of data in that list, calls must be make to open and close
64 The name given to all calls must be identical, and it is strongly
65 suggested that the name be singular, not plural, as a matter of
66 style and usage expectations.
68 A list is a set of one or more instances that appear under the same
70 The instances contain details about a specific object.
71 One can think of instances as objects or records.
73 open and close the list, while a distinct call is needed to open and
74 close each instance of the list:
75 .Bd -literal -offset indent -compact
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");
84 xo_close_list("item");
86 Getting the list and instance calls correct is critical to the proper
87 generation of XML and JSON data.
89 .Bd -literal -offset indent -compact
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");
99 xo_close_list("user");
101 phil:1001:1001:/home/phil
102 pallavi:1002:1002:/home/pallavi
108 <home>/home/phil</home>
114 <home>/home/pallavi</home>
122 "home": "/home/phil",
128 "home": "/home/pallavi",
134 In contrast to a list of instances, a "leaf list" is list of simple
136 To emit a leaf list, call the
138 function 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);
145 The name of the field must match the name of the leaf list.
147 In JSON, leaf lists are rendered as arrays of values. In XML, they
148 are rendered as multiple leaf elements.
149 .Bd -literal -offset indent -compact
151 "item": "hammer", "nail"
162 library first appeared in
167 .An Phil Shafer Aq Mt phil@freebsd.org .