xo_open_list(3)

1LIBXO(3)                 BSD Library Functions Manual                 LIBXO(3)
2

NAME

4     xo_open_list, xo_open_list_h, xo_open_list_hd, xo_open_list_d
5     xo_open_instance, xo_open_instance_h, xo_open_instance_hd,
6     xo_open_instance_d xo_close_instance, xo_close_instance_h,
7     xo_close_instance_hd, xo_close_instance_d xo_close_list, xo_close_list_h,
8     xo_close_list_hd, xo_close_list_d — open and close lists and instances
9

LIBRARY

11     library “libxo”
12

SYNOPSIS

14     #include <libxo/xo.h>
15
16     xo_ssize_t
17     xo_open_list_h(xo_handle_t *xop, const char *name);
18
19     xo_ssize_t
20     xo_open_list(const char *name);
21
22     xo_ssize_t
23     xo_open_list_hd(xo_handle_t *xop, const char *name);
24
25     xo_ssize_t
26     xo_open_list_d(const char *name);
27
28     xo_ssize_t
29     xo_open_instance_h(xo_handle_t *xop, const char *name);
30
31     xo_ssize_t
32     xo_open_instance(const char *name);
33
34     xo_ssize_t
35     xo_open_instance_hd(xo_handle_t *xop, const char *name);
36
37     xo_ssize_t
38     xo_open_instance_d(const char *name);
39
40     xo_ssize_t
41     xo_close_instance_h(xo_handle_t *xop, const char *name);
42
43     xo_ssize_t
44     xo_close_instance(const char *name);
45
46     xo_ssize_t
47     xo_close_instance_hd(xo_handle_t *xop);
48
49     xo_ssize_t
50     xo_close_instance_d(void);
51
52     xo_ssize_t
53     xo_close_list_h(xo_handle_t *xop, const char *name);
54
55     xo_ssize_t
56     xo_close_list(const char *name);
57
58     xo_ssize_t
59     xo_close_list_hd(xo_handle_t *xop);
60
61     xo_ssize_t
62     xo_close_list_d(void);
63

DESCRIPTION

65     Lists are sequences of instances of homogeneous data objects.  Two dis‐
66     tinct levels of calls are needed to represent them in our output styles.
67     Calls must be made to open and close a list, and for each instance of
68     data in that list, calls must be make to open and close that instance.
69
70     The name given to all calls must be identical, and it is strongly sug‐
71     gested that the name be singular, not plural, as a matter of style and
72     usage expectations.
73
74     A list is a set of one or more instances that appear under the same par‐
75     ent.  The instances contain details about a specific object.  One can
76     think of instances as objects or records.  A call is needed to open and
77     close the list, while a distinct call is needed to open and close each
78     instance of the list:
79               xo_open_list("item");
80
81               for (ip = list; ip->i_title; ip++) {
82                   xo_open_instance("item");
83                   xo_emit("{L:Item} '{:name/%s}':\n", ip->i_title);
84                   xo_close_instance("item");
85               }
86
87               xo_close_list("item");
88     Getting the list and instance calls correct is critical to the proper
89     generation of XML and JSON data.
90
91               EXAMPLE:
92                   xo_open_list("user");
93                   for (i = 0; i < num_users; i++) {
94                       xo_open_instance("user");
95                       xo_emit("{k:name}:{:uid/%u}:{:gid/%u}:{:home}\n",
96                               pw[i].pw_name, pw[i].pw_uid,
97                               pw[i].pw_gid, pw[i].pw_dir);
98                       xo_close_instance("user");
99                   }
100                   xo_close_list("user");
101               TEXT:
102                   phil:1001:1001:/home/phil
103                   pallavi:1002:1002:/home/pallavi
104               XML:
105                   <user>
106                       <name>phil</name>
107                       <uid>1001</uid>
108                       <gid>1001</gid>
109                       <home>/home/phil</home>
110                   </user>
111                   <user>
112                       <name>pallavi</name>
113                       <uid>1002</uid>
114                       <gid>1002</gid>
115                       <home>/home/pallavi</home>
116                   </user>
117               JSON:
118                   user: [
119                       {
120                           "name": "phil",
121                           "uid": 1001,
122                           "gid": 1001,
123                           "home": "/home/phil",
124                       },
125                       {
126                           "name": "pallavi",
127                           "uid": 1002,
128                           "gid": 1002,
129                           "home": "/home/pallavi",
130                       }
131                   ]
132

LEAF LISTS

134     In contrast to a list of instances, a "leaf list" is list of simple val‐
135     ues.  To emit a leaf list, call the xo_emit() function using the ""l""
136     modifier:
137               for (ip = list; ip->i_title; ip++) {
138                   xo_emit("{Lwc:Item}{l:item}\n", ip->i_title);
139               }
140
141     The name of the field must match the name of the leaf list.
142
143     In JSON, leaf lists are rendered as arrays of values.  In XML, they are
144     rendered as multiple leaf elements.
145               JSON:
146                   "item": "hammer", "nail"
147               XML:
148                   <item>hammer</item>
149                   <item>nail</item>
150

HISTORY

155     The libxo library first appeared in FreeBSD 11.0.
156

AUTHORS

158     libxo was written by Phil Shafer <phil@freebsd.org>.
159
160

ADDITIONAL DOCUMENTATION

162     FreeBSD uses libxo version 1.6.0.  Complete documentation can be found on
163     github:
164
165           https://juniper.github.io/libxo/1.6.0/html/index.html
166
167     libxo lives on github as:
168
169           https://github.com/Juniper/libxo
170
171     The latest release of libxo is available at:
172
173           https://github.com/Juniper/libxo/releases
174

HISTORY

176     The libxo library was added in FreeBSD 11.0.
177

AUTHOR

179     Phil Shafer
180
181BSD                            December 4, 2014                            BSD