xref: /freebsd/contrib/libxo/libxo/xo_open_list.3 (revision d93a896e) 
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 int
24.Fn xo_open_list_h "xo_handle_t *xop" "const char *name"
25.Ft int
26.Fn xo_open_list "const char *name"
27.Ft int
28.Fn xo_open_list_hd "xo_handle_t *xop" "const char *name"
29.Ft int
30.Fn xo_open_list_d "const char *name"
31.Ft int
32.Fn xo_open_instance_h "xo_handle_t *xop" "const char *name"
33.Ft int
34.Fn xo_open_instance "const char *name"
35.Ft int
36.Fn xo_open_instance_hd "xo_handle_t *xop" "const char *name"
37.Ft int
38.Fn xo_open_instance_d "const char *name"
39.Ft int
40.Fn xo_close_instance_h "xo_handle_t *xop" "const char *name"
41.Ft int
42.Fn xo_close_instance "const char *name"
43.Ft int
44.Fn xo_close_instance_hd "xo_handle_t *xop"
45.Ft int
46.Fn xo_close_instance_d "void"
47.Ft int
48.Fn xo_close_list_h "xo_handle_t *xop" "const char *name"
49.Ft int
50.Fn xo_close_list "const char *name"
51.Ft int
52.Fn xo_close_list_hd "xo_handle_t *xop"
53.Ft int
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