contrib/libxo/libxo/xo_open_list.3

   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
  56 Lists are sequences of instances of homogeneous data objects.
  57 Two
  58 distinct levels of calls are needed to represent them in our output
  59 styles.
  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
  62 that instance.
  63 .Pp
  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.
  67 .Pp
  68 A list is a set of one or more instances that appear under the same
  69 parent.
  70 The instances contain details about a specific object.
  71 One can think of instances as objects or records.
  72 A call is needed to
  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
  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
  86 Getting the list and instance calls correct is critical to the proper
  87 generation 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
 134 In contrast to a list of instances, a "leaf list" is list of simple
 135 values.
 136 To emit a leaf list, call the
 137 .Fn xo_emit
 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);
 142     }
 143 .Ed
 144 .Pp
 145 The name of the field must match the name of the leaf list.
 146 .Pp
 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
 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
 160 The
 161 .Nm libxo
 162 library first appeared in
 163 .Fx 11.0 .
 164 .Sh AUTHORS
 165 .Nm libxo
 166 was written by
 167 .An Phil Shafer Aq Mt phil@freebsd.org .
 168