|
ActiveTcl User Guide
|
|
|
csv(n) 0.3 csv "CSV processing"
NAME
csv - Procedures to handle CSV data.
SYNOPSIS
package require Tcl 8.3
package require csv ?0.3?
::csv::join values {sepChar ,} |
::csv::joinlist values
{sepChar ,} |
::csv::read2matrix chan m
{sepChar ,} {expand
none} |
::csv::read2queue chan q
{sepChar ,} |
::csv::report cmd matrix
?chan? |
::csv::split line {sepChar ,} |
::csv::split2matrix m
line {sepChar ,} {expand
none} |
::csv::split2queue q line
{sepChar ,} |
::csv::writematrix m chan
{sepChar ,} |
::csv::writequeue q chan
{sepChar ,} |
|
DESCRIPTION
The csv package provides commands to manipulate
information in CSV FORMAT (CSV = Comma
Separated Values).
COMMANDS
The following commands are available:
- ::csv::join values {sepChar ,}
- Takes a list of values and returns a string in CSV format
containing these values. The separator character can be defined by
the caller, but this is optional. The default is ",".
- ::csv::joinlist values
{sepChar ,}
- Takes a list of lists of values and returns a string in CSV
format containing these values. The separator character can be
defined by the caller, but this is optional. The default is ",".
Each element of the outer list is considered a record, these are
separated by newlines in the result. The elements of each record
are formatted as usual (via ::csv::join).
- ::csv::read2matrix chan m
{sepChar ,} {expand
none}
- A wrapper around ::csv::split2matrix (see
below) reading CSV-formatted lines from the specified channel
(until EOF) and adding them to the given matrix. For an explanation
of the expand argument see ::csv::split2matrix.
- ::csv::read2queue chan q
{sepChar ,}
- A wrapper around ::csv::split2queue (see
below) reading CSV-formatted lines from the specified channel
(until EOF) and adding them to the given queue.
- ::csv::report cmd matrix
?chan?
- A report command which can be used by the matrix methods format 2string and format 2chan.
For the latter this command delegates the work to ::csv::writematrix. cmd is expected to
be either printmatrix or
printmatrix2channel. The channel argument, chan, has to be present for the latter and must not
be present for the first.
- ::csv::split line {sepChar ,}
- converts a line in CSV format into a list of
the values contained in the line. The character used to separate
the values from each other can be defined by the caller, via sepChar, but this is optional. The default is
",".
- ::csv::split2matrix m
line {sepChar ,} {expand
none}
- The same as ::csv::split, but appends the
resulting list as a new row to the matrix m,
using the method add row. The expansion mode
specified via expand determines how the command
handles a matrix with less columns than contained in line. The allowed modes are:
- none
- This is the default mode. In this mode it is the responsibility
of the caller to ensure that the matrix has enough columns to
contain the full line. If there are not enough columns the list of
values is silently truncated at the end to fit.
- empty
- In this mode the command expands an empty matrix to hold all
columns of the specified line, but goes no further. The overall
effect is that the first of a series of lines determines the number
of columns in the matrix and all following lines are truncated to
that size, as if mode none was set.
- auto
- In this mode the command expands the matrix as needed to hold
all columns contained in line. The overall
effect is that after adding a series of lines the matrix will have
enough columns to hold all columns of the longest line encountered
so far.
- ::csv::split2queue q line
{sepChar ,}
- The same as ::csv::split, but appending the
resulting list as a single item to the queue q,
using the method put.
- ::csv::writematrix m chan
{sepChar ,}
- A wrapper around ::csv::join taking all rows
in the matrix m and writing them CSV formatted
into the channel chan.
- ::csv::writequeue q chan
{sepChar ,}
- A wrapper around ::csv::join taking all
items in the queue q (assumes that they are
lists) and writing them CSV formatted into the channel chan.
FORMAT
Each record of a csv file (comma-separated values, as exported
e.g. by Excel) is a set of ASCII values separated by ",". For other
languages it may be ";" however, although this is not important for
this case (The functions provided here allow any separator
character).
If a value contains itself the separator ",", then it (the
value) is put between "".
If a value contains ", it is replaced by "".
EXAMPLE
The record
|
123,"123,521.2","Mary says ""Hello, I am Mary"""
|
is parsed as follows:
|
a) 123
b) 123,521.2
c) Mary says "Hello, I am Mary"
|
SEE ALSO
matrix, queue
KEYWORDS
csv, matrix, queue, package, tcllib