1LIBXO-CSV(7)         BSD Miscellaneous Information Manual         LIBXO-CSV(7)
2

NAME

4     --libxo encoder=csv[+options] — a CVS encoder for libxo-based commands
5

DESCRIPTION

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
11             % 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
32     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
36     Use the "encoder=XXX" option to access encoders.  The following example
37     uses the "cbor" encoder, saving the output into a file:
38
39             df --libxo encoder=cbor > df-output.cbor
40
41     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
45             df --libxo encoder=csv+path=filesystem+leaf=name+no-header
46             df --libxo encoder=csv:path=filesystem:leaf=name:no-header
47
48     These examples instructs libxo to load the "csv" encoder and pass the
49     following options:
50
51            path=filesystem
52            leaf=name
53            no-header
54
55     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
59     The string "@" can be used in place of the string "encoder=".
60
61             df --libxo @csv:no-header
62

The CSV (Comma Separated Values) Encoder

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
68     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
73     Consider the following XML:
74
75             % 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
102     This output is a list of `instances` (named "item"), each containing a
103     set of `leafs` ("sku", "name", etc).
104
105     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
109             % 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
115     Be aware that since the CSV encoder looks for data instances, when used
116     with xo, the `--instance` option will be needed:
117
118             % xo --libxo encoder=csv --instance foo 'The {:product} is {:status}0 stereo "in route"
119             product,status
120             stereo,in route
121

The path Option

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
127     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
130     For example, if the "list-items" application generates other lists, the
131     user can give "path=top/data/item" as a path:
132
133             % 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
139     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

The leafs Option

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
148     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
156     The "leafs" option can also be used to exclude leafs, limiting the output
157     to only those leafs provided.
158
159     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
163     So the "leafs" option can be used to expand, limit, and order the set of
164     leafs.
165
166     The value of the leafs option should be one or more leaf names, separated
167     by a period ("."):
168
169             % 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
180     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

The no-header Option

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
188             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
193     There is no reliable mechanism for determining whether this header line
194     is included, so the consumer must make an assumption.
195
196     The csv encoder defaults to producing the header line, but the "no-
197     header" option can be included to avoid the header line.
198

The no-quotes Option

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

The dos Option

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
209     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

Option Handling

213     The handling of command-line options is complex, since there are three
214     hierarchies in use, but the rules are:
215
216     commas separate libxo options
217
218           --libxo json,pretty,warn
219
220     pluses separate encoder options
221
222         --libxo @csv+dos+no-header,warn
223
224     periods separate tag names
225
226         --libxo @csv+leafs=name.used.free+dos,warn
227

SEE ALSO

229     libxo(3), xo_options(7)
230

HISTORY

232     The libxo library first appeared in FreeBSD 11.0.  The CSV encoder first
233     appeared in FreeBSD 13.0.
234

AUTHORS

236     libxo was written by Phil Shafer <phil@freebsd.org>.
237
238

ADDITIONAL DOCUMENTATION

240     FreeBSD uses libxo version 1.6.0.  Complete documentation can be found on
241     github:
242
243           https://juniper.github.io/libxo/1.6.0/html/index.html
244
245     libxo lives on github as:
246
247           https://github.com/Juniper/libxo
248
249     The latest release of libxo is available at:
250
251           https://github.com/Juniper/libxo/releases
252

HISTORY

254     The libxo library was added in FreeBSD 11.0.
255

AUTHOR

257     Phil Shafer
258
259BSD                              May 13, 2021                              BSD
Impressum