1csv(n)                          CSV processing                          csv(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       csv - Procedures to handle CSV data.
9

SYNOPSIS

11       package require Tcl  8.3
12
13       package require csv  ?0.7?
14
15       ::csv::iscomplete data
16
17       ::csv::join values {sepChar ,} {delChar "}
18
19       ::csv::joinlist values {sepChar ,} {delChar "}
20
21       ::csv::joinmatrix matrix {sepChar ,} {delChar "}
22
23       ::csv::read2matrix ?-alternate? chan m {sepChar ,} {expand none}
24
25       ::csv::read2queue ?-alternate? chan q {sepChar ,}
26
27       ::csv::report cmd matrix ?chan?
28
29       ::csv::split ?-alternate? line {sepChar ,} {delChar "}
30
31       ::csv::split2matrix ?-alternate? m line {sepChar ,} {expand none}
32
33       ::csv::split2queue ?-alternate? q line {sepChar ,}
34
35       ::csv::writematrix m chan {sepChar ,} {delChar "}
36
37       ::csv::writequeue q chan {sepChar ,} {delChar "}
38
39_________________________________________________________________
40

DESCRIPTION

42       The csv package provides commands to manipulate information in CSV FOR‐
43       MAT (CSV = Comma Separated Values).
44

COMMANDS

46       The following commands are available:
47
48       ::csv::iscomplete data
49              A predicate checking if the argument  data  is  a  complete  csv
50              record. The result is a boolean flag indicating the completeness
51              of the data. The result is true if the data is complete.
52
53       ::csv::join values {sepChar ,} {delChar "}
54              Takes a list of values and returns a string in CSV  format  con‐
55              taining  these values. The separator character can be defined by
56              the caller, but this is optional. The default is ",". The  quot‐
57              ing  character  can  be  defined  by  the  caller,  but  this is
58              optional. The default is '"'.
59
60       ::csv::joinlist values {sepChar ,} {delChar "}
61              Takes a list of lists of values and returns a string in CSV for‐
62              mat  containing  these  values.  The  separator character can be
63              defined by the caller, but this is optional. The default is ",".
64              The  quoting character can be defined by the caller, but this is
65              optional. The default is '"'.  Each element of the outer list is
66              considered  a  record,  these  are  separated by newlines in the
67              result. The elements of each record are formatted as usual  (via
68              ::csv::join).
69
70       ::csv::joinmatrix matrix {sepChar ,} {delChar "}
71              Takes  a  matrix  object  following  the  API  specified for the
72              struct::matrix package and returns a string in CSV  format  con‐
73              taining  these values. The separator character can be defined by
74              the caller, but this is optional. The default is ",". The  quot‐
75              ing  character  can  be  defined  by  the  caller,  but  this is
76              optional. The default is ´"'. Each row of the matrix is  consid‐
77              ered  a  record,  these are separated by newlines in the result.
78              The  elements  of  each  record  are  formatted  as  usual  (via
79              ::csv::join).
80
81       ::csv::read2matrix ?-alternate? chan m {sepChar ,} {expand none}
82              A  wrapper  around  ::csv::split2matrix (see below) reading CSV-
83              formatted lines from  the  specified  channel  (until  EOF)  and
84              adding  them  to  the  given  matrix.  For an explanation of the
85              expand argument see ::csv::split2matrix.
86
87       ::csv::read2queue ?-alternate? chan q {sepChar ,}
88              A wrapper around ::csv::split2queue (see below) reading CSV-for‐
89              matted  lines  from the specified channel (until EOF) and adding
90              them to the given queue.
91
92       ::csv::report cmd matrix ?chan?
93              A report command which can be used by the matrix methods  format
94              2string  and format 2chan. For the latter this command delegates
95              the work to ::csv::writematrix. cmd is  expected  to  be  either
96              printmatrix  or printmatrix2channel. The channel argument, chan,
97              has to be present for the latter and must not be present for the
98              first.
99
100       ::csv::split ?-alternate? line {sepChar ,} {delChar "}
101              converts  a  line  in  CSV format into a list of the values con‐
102              tained in the line. The character used to  separate  the  values
103              from  each  other can be defined by the caller, via sepChar, but
104              this is optional. The default is ",". The quoting character  can
105              be  defined  by the caller, but this is optional. The default is
106              '"'.
107
108              If the option -alternate is spcified a slightly different syntax
109              is  used  to parse the input. This syntax is explained below, in
110              the section FORMAT.
111
112       ::csv::split2matrix ?-alternate? m line {sepChar ,} {expand none}
113              The same as ::csv::split, but appends the resulting  list  as  a
114              new row to the matrix m, using the method add row. The expansion
115              mode specified via expand determines how the command  handles  a
116              matrix  with  less  columns  than contained in line. The allowed
117              modes are:
118
119              none   This is the default mode. In this mode it is the  respon‐
120                     sibility  of  the  caller  to  ensure that the matrix has
121                     enough columns to contain the full line. If there are not
122                     enough  columns  the list of values is silently truncated
123                     at the end to fit.
124
125              empty  In this mode the command expands an empty matrix to  hold
126                     all  columns  of the specified line, but goes no further.
127                     The overall effect is that the first of a series of lines
128                     determines  the  number  of columns in the matrix and all
129                     following lines are truncated to that size,  as  if  mode
130                     none was set.
131
132              auto   In  this mode the command expands the matrix as needed to
133                     hold all columns contained in line. The overall effect is
134                     that  after adding a series of lines the matrix will have
135                     enough columns to hold all columns of  the  longest  line
136                     encountered so far.
137
138       ::csv::split2queue ?-alternate? q line {sepChar ,}
139              The  same as ::csv::split, but appending the resulting list as a
140              single item to the queue q, using the method put.
141
142       ::csv::writematrix m chan {sepChar ,} {delChar "}
143              A wrapper around ::csv::join taking all rows in the matrix m and
144              writing them CSV formatted into the channel chan.
145
146       ::csv::writequeue q chan {sepChar ,} {delChar "}
147              A  wrapper  around  ::csv::join  taking all items in the queue q
148              (assumes that they are lists) and  writing  them  CSV  formatted
149              into the channel chan.
150

FORMAT

152       The format of regular CSV files is specified as
153
154       [1]    Each  record  of a csv file (comma-separated values, as exported
155              e.g. by Excel) is a set of ASCII values separated  by  ",".  For
156              other  languages  it  may  be  ";" however, although this is not
157              important for this case as the functions provided here allow any
158              separator character.
159
160       [2]    If  and  only if a value contains itself the separator ",", then
161              it (the value) has to be put between "". If the value  does  not
162              contain the separator character then quoting is optional.
163
164       [3]    If  a  value  contains the character ", that character is repre‐
165              sented by "".
166
167       [4]    The output string "" represents the value ". In other words,  it
168              is  assumed  that  it  was created through rule 3, and only this
169              rule, i.e. that the value was not quoted.
170
171       An alternate format definition mainly used  by  MS  products  specifies
172       that  the  output string "" is an representatation of the empty string.
173       In other words, it is assumed that the output was generated out of  the
174       empty  string by quoting it (i.e. rule 2), and not through rule 3. This
175       is the only difference between the regular and the alternate format.
176
177       The alternate format is activated through specification of  the  option
178       -alternate to the various split commands.
179

EXAMPLE

181       Using the regular format the record
182
183       123,"123,521.2","Mary says ""Hello, I am Mary""",""
184
185
186       is parsed into the items
187
188       a) 123
189       b) 123,521.2
190       c) Mary says "Hello, I am Mary"
191       d) (the empty string)
192
193
194       Using the alternate format the result is
195
196       a) 123
197       b) 123,521.2
198       c) Mary says "Hello, I am Mary"
199       d) "
200
201       instead.  As can be seen only item (d) is different, now a " instead of
202       the empty string.
203

SEE ALSO

205       matrix, queue
206

KEYWORDS

208       csv, matrix, package, queue, tcllib
209
211       Copyright (c) 2002-2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>
212
213
214
215
216csv                                   0.7                               csv(n)
Impressum