1csv(n) CSV processing csv(n)
2______________________________________________________________________________
6
8 csv - Procedures to handle CSV data.
9
11 package require Tcl 8.3
12 package require csv ?0.7.1?
14 ::csv::iscomplete data
16 ::csv::join values {sepChar ,} {delChar "}
18 ::csv::joinlist values {sepChar ,} {delChar "}
20 ::csv::joinmatrix matrix {sepChar ,} {delChar "}
22 ::csv::read2matrix ?-alternate? chan m {sepChar ,} {expand none}
24 ::csv::read2queue ?-alternate? chan q {sepChar ,}
26 ::csv::report cmd matrix ?chan?
28 ::csv::split ?-alternate? line {sepChar ,} {delChar "}
30 ::csv::split2matrix ?-alternate? m line {sepChar ,} {expand none}
32 ::csv::split2queue ?-alternate? q line {sepChar ,}
34 ::csv::writematrix m chan {sepChar ,} {delChar "}
36 ::csv::writequeue q chan {sepChar ,} {delChar "}
38_________________________________________________________________
40
42 The csv package provides commands to manipulate information in CSV FOR‐
43 MAT (CSV = Comma Separated Values).
44
46 The following commands are available:
47 ::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 ::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 ::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 ::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 ::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 ::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 ::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 ::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 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 ::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 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 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 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 ::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 ::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 ::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
152 The format of regular CSV files is specified as
153 [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 [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 [3] If a value contains the character ", that character is repre‐
165 sented by "".
166 [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 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 The alternate format is activated through specification of the option
178 -alternate to the various split commands.
179
181 Using the regular format the record
182 123,"123,521.2","Mary says ""Hello, I am Mary""",""
184 is parsed into the items
187 a) 123
189 b) 123,521.2
190 c) Mary says "Hello, I am Mary"
191 d) (the empty string)
192 Using the alternate format the result is
195 a) 123
197 b) 123,521.2
198 c) Mary says "Hello, I am Mary"
199 d) "
200 instead. As can be seen only item (d) is different, now a " instead of
202 the empty string.
203
205 This document, and the package it describes, will undoubtedly contain
206 bugs and other problems. Please report such in the category csv of the
207 Tcllib SF Trackers [http://sourceforge.net/tracker/?group_id=12883].
208 Please also report any ideas for enhancements you may have for either
209 package and/or documentation.
210
212 matrix, queue
213
215 csv, matrix, package, queue, tcllib
216
218 Copyright (c) 2002-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>
219csv 0.7.1 csv(n)