1LIBXO-CSV(7) BSD Miscellaneous Information Manual LIBXO-CSV(7)
2
4 --libxo encoder=csv[+options] — a CVS encoder for libxo-based commands
5
7 The libxo library supports a "pluggable" encoder mechanism, and ships
8 with an encoder for CSV (comma separated values) files. The encoder al‐
9 lows paths and fields to be selected out of the output contents:
10 % df --libxo @csv
12 name,total-blocks,used-blocks,available-blocks,used-percent,mounted-on
13 zroot/ROOT/default,3825984331,29376725,3796607605,1,/
14 devfs,1,1,0,100,/dev
15 zroot/usr/home,3808301289,11693684,3796607605,0,/usr/home
16 zroot/var/audit,3796607806,201,3796607605,0,/var/audit
17 ...
18 % df --libxo @csv+leafs=name.used-percent
19 name,used-percent
20 zroot/ROOT/default,1
21 devfs,100
22 zroot/usr/home,0
23 zroot/var/audit,0
24 ...
25 % df --libxo @csv+leafs=available-blocks+no-header /
26 3796607605
27 contains software to generate four "built-in" formats: text, XML, JSON,
28 and HTML. These formats are common and useful, but there are other com‐
29 mon and useful formats that users will want, and including them all in
30 the libxo software would be difficult and cumbersome.
31 To allow support for additional encodings, libxo includes a "pluggable"
33 extension mechanism for dynamically loading new encoders. libxo -based
34 applications can automatically use any installed encoder.
35 Use the "encoder=XXX" option to access encoders. The following example
37 uses the "cbor" encoder, saving the output into a file:
38 df --libxo encoder=cbor > df-output.cbor
40 Encoders can support specific options that can be accessed by following
42 the encoder name with a colon (':') or a plus sign ('+') and one of more
43 options, separated by the same character:
44 df --libxo encoder=csv+path=filesystem+leaf=name+no-header
46 df --libxo encoder=csv:path=filesystem:leaf=name:no-header
47 These examples instructs libxo to load the "csv" encoder and pass the
49 following options:
50 path=filesystem
52 leaf=name
53 no-header
54 Each of these option is interpreted by the encoder, and all such options
56 names and semantics are specific to the particular encoder. Refer to the
57 intended encoder for documentation on its options.
58 The string "@" can be used in place of the string "encoder=".
60 df --libxo @csv:no-header
62
64 libxo ships with a custom encoder for "CSV" files, a common format for
65 comma separated values. The output of the CSV encoder can be loaded di‐
66 rectly into spreadsheets or similar applications.
67 A standard for CSV files is provided in RFC 4180, but since the format
69 predates that standard by decades, there are many minor differences in
70 CSV file consumers and their expectations. The CSV encoder has a number
71 of options to tailor output to those expectations.
72 Consider the following XML:
74 % list-items --libxo xml,pretty
76 <top>
77 <data test="value">
78 <item test2="value2">
79 <sku test3="value3" key="key">GRO-000-415</sku>
80 <name key="key">gum</name>
81 <sold>1412</sold>
82 <in-stock>54</in-stock>
83 <on-order>10</on-order>
84 </item>
85 <item>
86 <sku test3="value3" key="key">HRD-000-212</sku>
87 <name key="key">rope</name>
88 <sold>85</sold>
89 <in-stock>4</in-stock>
90 <on-order>2</on-order>
91 </item>
92 <item>
93 <sku test3="value3" key="key">HRD-000-517</sku>
94 <name key="key">ladder</name>
95 <sold>0</sold>
96 <in-stock>2</in-stock>
97 <on-order>1</on-order>
98 </item>
99 </data>
100 </top>
101 This output is a list of `instances` (named "item"), each containing a
103 set of `leafs` ("sku", "name", etc).
104 The CSV encoder will emit the leaf values in this output as `fields` in‐
106 side a CSV `record`, which is a line containing a set of comma-separated
107 values:
108 % list-items --libxo encoder=csv
110 sku,name,sold,in-stock,on-order
111 GRO-000-415,gum,1412,54,10
112 HRD-000-212,rope,85,4,2
113 HRD-000-517,ladder,0,2,1
114 Be aware that since the CSV encoder looks for data instances, when used
116 with xo, the `--instance` option will be needed:
117 % xo --libxo encoder=csv --instance foo 'The {:product} is {:status}0 stereo "in route"
119 product,status
120 stereo,in route
121
123 By default, the CSV encoder will attempt to emit any list instance gener‐
124 ated by the application. In some cases, this may be unacceptable, and a
125 specific list may be desired.
126 Use the "path" option to limit the processing of output to a specific hi‐
128 erarchy. The path should be one or more names of containers or lists.
129 For example, if the "list-items" application generates other lists, the
131 user can give "path=top/data/item" as a path:
132 % list-items --libxo encoder=csv:path=top/data/item
134 sku,name,sold,in-stock,on-order
135 GRO-000-415,gum,1412,54,10
136 HRD-000-212,rope,85,4,2
137 HRD-000-517,ladder,0,2,1
138 Paths are "relative", meaning they need not be a complete set of names to
140 the list. This means that "path=item" may be sufficient for the above
141 example.
142
144 The CSV encoding requires that all lines of output have the same number
145 of fields with the same order. In contrast, XML and JSON allow any order
146 (though libxo forces key leafs to appear before other leafs).
147 To maintain a consistent set of fields inside the CSV file, the same set
149 of leafs must be selected from each list item. By default, the CSV en‐
150 coder records the set of leafs that appear in the first list instance it
151 processes, and extract only those leafs from future instances. If the
152 first instance is missing a leaf that is desired by the consumer, the
153 "leaf" option can be used to ensure that an empty value is recorded for
154 instances that lack a particular leaf.
155 The "leafs" option can also be used to exclude leafs, limiting the output
157 to only those leafs provided.
158 In addition, the order of the output fields follows the order in which
160 the leafs are listed. "leafs=one.two" and "leafs=two.one" give distinct
161 output.
162 So the "leafs" option can be used to expand, limit, and order the set of
164 leafs.
165 The value of the leafs option should be one or more leaf names, separated
167 by a period ("."):
168 % list-items --libxo encoder=csv:leafs=sku.on-order
170 sku,on-order
171 GRO-000-415,10
172 HRD-000-212,2
173 HRD-000-517,1
174 % list-items -libxo encoder=csv:leafs=on-order.sku
175 on-order,sku
176 10,GRO-000-415
177 2,HRD-000-212
178 1,HRD-000-517
179 Note that since libxo uses terminology from YANG (:RFC:`7950`), the data
181 modeling language for NETCONF (:RFC:`6241`), which uses "leafs" as the
182 plural form of "leaf". libxo follows that convention.
183
185 CSV files typical begin with a line that defines the fields included in
186 that file, in an attempt to make the contents self-defining:
187 sku,name,sold,in-stock,on-order
189 GRO-000-415,gum,1412,54,10
190 HRD-000-212,rope,85,4,2
191 HRD-000-517,ladder,0,2,1
192 There is no reliable mechanism for determining whether this header line
194 is included, so the consumer must make an assumption.
195 The csv encoder defaults to producing the header line, but the "no-
197 header" option can be included to avoid the header line.
198
200 RFC 4180 specifies that fields containing spaces should be quoted, but
201 many CSV consumers do not handle quotes. The "no-quotes" option instruct
202 the CSV encoder to avoid the use of quotes.
203
205 RFC 4180 defines the end-of-line marker as a carriage return followed by
206 a newline. This "CRLF" convention dates from the distant past, but its
207 use was anchored in the 1980s by the `DOS` operating system.
208 The CSV encoder defaults to using the standard Unix end-of-line marker, a
210 simple newline. Use the "dos" option to use the `CRLF` convention.
211
213 The handling of command-line options is complex, since there are three
214 hierarchies in use, but the rules are:
215 • commas separate libxo options
217 --libxo json,pretty,warn
219 • pluses separate encoder options
221 --libxo @csv+dos+no-header,warn
223 • periods separate tag names
225 --libxo @csv+leafs=name.used.free+dos,warn
227
229 libxo(3), xo_options(7)
230
232 The libxo library first appeared in FreeBSD 11.0. The CSV encoder first
233 appeared in FreeBSD 13.0.
234
236 libxo was written by Phil Shafer <phil@freebsd.org>.
237
240 FreeBSD uses libxo version 1.6.0. Complete documentation can be found on
241 github:
242 https://juniper.github.io/libxo/1.6.0/html/index.html
244 libxo lives on github as:
246 https://github.com/Juniper/libxo
248 The latest release of libxo is available at:
250 https://github.com/Juniper/libxo/releases
252
254 The libxo library was added in FreeBSD 11.0.
255
257 Phil Shafer
258BSD May 13, 2021 BSD