File: //usr/share/slsh/help/csvfuns.hlp
csv_decoder_new
SYNOPSIS
Instantiate a parser for CSV data
USAGE
obj = csv_decoder_new (filename|File_Type|Strings[])
DESCRIPTION
This function instantiates an object that may be used to parse and
read so-called comma-separated-value (CSV) data. It requires a
single argument, which may be the name of a file, an open file
pointer, or an array of strings.
QUALIFIERS
; delim: character used for the delimiter (default: ',')
; quote: character used for the quoting fields (default: '"')
; skiplines: number of lines to skip before parsing (default: 0)
; comment: lines beginning with this string will be skipped
; blankrows: default for how blank rows should be handled (default: "skip")
METHODS
.readrow : Read and parse a row from the CSV object
.readcol : Read one or more columns from the CSV object
EXAMPLE
See the documentation for the `csv.readcol' and
`csv.readrow' methods for examples.
NOTES
The current implementation assumes the CSV format specified according
to RFC 4180.
It is important to understand the difference between a ROW and a LINE
in a CSV formatted file: a row may span more than one line in a file.
The `skiplines' qualifier specifies the number of LINES to be
skipped, not ROWS.
CSV files have no notion of data-types: all field values are strings.
For this reason, the `type' qualifier introduces an extra layer
that is not part CSV format.
SEE ALSO
csv.readcol, csv.readrow
--------------------------------------------------------------
csv.readcol
SYNOPSIS
Read one or more columns from a CSV file
USAGE
datastruct = csv.readcol([columns])
DESCRIPTION
This function method may be used to read one or more columns from a
comma-separated-value file. If passed with no arguments, all columns
of the file will be returned. Otherwise, only those columns
specified by the columns argument will be returned.
The return value is a structure with fields that correspond to the
desired columns. The default is for the structure to have field
names `col1', `col2', etc., where the integer suffix
specifies the column number. The `fields' and `header'
qualifiers may be used to specify a different set of names.
QUALIFIERS
; fields: An array of field names to use for the returned structure
; header: Array of strings that correspond to the header row
; type: An scalar or array type-specifier, see below
; typeN: Type-specifier for column N
; snan: String value to use for an empty string element (default: "")
; inan: Integer value to use for an empty integer element (default: 0)
; lnan: Long int value to use for an empty long int element (default: 0L)
; fnan: Float value to use for an empty float element (default: _NaN)
; dnan: Double value to use for an empty double element (default: _NaN)
; nanN: Value used for an empty element in the column N
; blankrows: How a blank row should be handled (default: "skip")
The type-specifier is used to specify the type of a field. It must
be one of the following characters:
's' (String_Type)
'i' (Int_Type)
'l' (Long_Type)
'f' (Float_Type)
'd' (Double_Type)
If the value of the `type' qualifier is scalar, then all
columns will default to use the corresponding type. If different
types are desired, then an array of type-specifiers may be used.
The length of the array must be the same as the number of columns to
be returned. The `typeN' qualifier may be used to give the
type of column N.
If the `columns' argument is string-valued, then the
`header' qualifier must be supplied to provide a mapping
from column names to column numbers. If it is present, it will also
be used to give normalized field names to the returned structure.
For normalization, the column name is first lower-cased, then all
non-alphanumeric values are converted to "_", and excess underscore
characters removed.
See the documentation for the `csv.readrow' for more
information about how blank rows should be handled.
EXAMPLE
Suppose that `data.csv' is a file that contains
# The data below are from runs 6 and 7
x,y,errx,erry,Notes - or - Comments
10.2,0.5,,0.1,
13.4,0.9,0.1,0.16,
20.7,18.2,,0.3,Vacuum leak in beam line
29.6,1.3,,0.31,
31.2,1.2,0.11,0.33,"This data point
taken from run 7"
This file consists of 8 lines and forms a CSV file with 6 rows.
The first row consists of a single column, and the subsequent rows of
consist of 5 columns. columns. Note that the last row is split
across two lines. The row with the single column will be regarded as
a comment in what follows.
The first step is to instantiate a parser object using:
csv = csv_decoder_new ("data.csv" ;comment="#");
The use of the `comment' qualifier will cause all lines
beginning with `"#"' to be skipped. Alternatively, the first
line could have been skipped using
csv = csv_decoder_new ("data.csv" ;skiplines=1);
The second row (also second line) in the file is the header line:
it gives the names of the columns. It may be read using
header = csv.readrow ();
The rest of the file consists of the data values. We want to read
the first 4 columns as single precision (Float_Type) values,
and the 5th as a string. One way to do this is
table = csv.readcol (;type=['f','f','f','f','s']);
This will result in `table' set to a structure of the form
struct { col1 = Float_Type[5],
col2 = Float_Type[5],
col3 = Float_Type[5],
col4 = Float_Type[5],
col5 = String_Type[5]
}
The same result could also have been achieved using
table = csv.readcol (;type='f', type5='s');
If the `header' qualifier is used, then
table = csv.readcol (;type='f', type5='s', header=header);
would produce the structure
struct {x=Float_Type[5],
y=Float_Type[5],
errx=Float_Type[5],
erry=Float_Type[5],
notes_or_comments=String_Type[5]
}
Note how the "Notes -or- Comments" value was normalized.
To read just the `x' and `y' columns, either of the
following may be used:
table = csv.readcol ([1,2] ;type='f');
table = csv.readcol (["x","y"] ;type='f', header=header);
The `header' qualifier was required in the last form to map the
column names to numbers.
SEE ALSO
csv_decoder_new, csv_readcol, readascii
--------------------------------------------------------------
csv.readrow
SYNOPSIS
Read a row from a CSV file
USAGE
row = csv.readrow ()
DESCRIPTION
The `csv.readrow' function method may be used to read the next
row from the underlying CSV (comma-separated-value) parser object.
The object must have already been instantiated using the
`csv_decoder_new' function. It returns the row data in the form
of an array of strings. If the end of input it reached, NULL will
be returned.
QUALIFIERS
; blankrows: How a blank row should be handled (default: "skip")
The `blankrows' qualifier is used to specify how a blank row
should be handled. A blankrow is defined as a row made up of no
characters except for the newline or carriage-return sequence. For
example, the following 9 lines has one blank row that occurs on
line 8:
"12.3"
"4
5"
"5.1"
""
"7.2"
"6.2"
If the value of `"blankrow"' is `"skip"', then blank rows
will be ignored by the parser. If the value is `"stop"', then the row
will be returned as an empty array of strings (length equal to 0).
Otherwise the row will be treated as if it contained the empty
string and returned as an array of length 1 with a value of "".
The default behavior is to skip such rows.
SEE ALSO
csv_decoder_new, csv.readcol, csv_readcol
--------------------------------------------------------------
csv_readcol
SYNOPSIS
Read one or more columns from a CSV file
USAGE
Struct_Type csv_readcol (file|fp [,columns] ;qualifiers)
DESCRIPTION
This function may be used to read one or more of the columns in the specified
CSV file. If the `columns' argument is present, then only those
columns will be read; otherwise all columns in the file will be read.
The columns will be returned in the form of a structure.
QUALIFIERS
This function supports all of the qualifiers supported by the
`csv_decoder_new' function and the `csv.readcol' method.
In addition, if the `has_header' qualifier is present, the first
line processed (after skipping any lines implied by the
`skiplines' and `comment' qualifiers) will be regarded as
the header.
If the `rdb' qualifier is present, then assume that the file is
in the so-called RDB file format. This is a tab-delimited format
that consists of a line that contains the names of the fields,
followed by a line that specifies the data types of the columns.
EXAMPLE
data = csv_readcol ("mirror.csv" ;comment="#", has_header, delim='|');
data = csv_readcol ("foo.rdb" ; rdb);
SEE ALSO
csv_decoder_new, csv.readcol, csv.readrow, csv.writecol, csv_encoder_new
--------------------------------------------------------------
csv_encoder_new
SYNOPSIS
Create an object for writing CSV files
USAGE
csv = csv_encoder_new ()
DESCRIPTION
The `csv_encoder_new' function returns an object that may
be used for creating a CSV file.
QUALIFIERS
; delim: Character used for the field delimiter (default: ',')
; quote: Character used for quoting fields (default: '"')
; quoteall: Quote all field values
; quotesome: Quote only those fields where quoting is necessary
METHODS
.writecol : write one or more columns to a file. For more information
about this method, see the documentation for `csv.writecol'.
EXAMPLE
x = [0:2*PI:#100];
csv = csv_encoder_new (;delim='|');
csv.writecol ("sinx.csv", x, sin(x) ; names=["x", "sin of x"]);
NOTES
The `set_float_format' function may be used to specify the
format used where writing floating point numbers to the CSV file.
SEE ALSO
csv_writecol, csv_encoder_new, csv_readcol
--------------------------------------------------------------
csv_writecol
SYNOPSIS
Write to a file using a CSV format
USAGE
csv_writecol(file|fp, datalist | datastruct | col1,...,colN)
DESCRIPTION
This function write a one or more data columns to a file or open
file descriptor using a comma-separated-value format. The data
values may be expressed in several ways: as a list of a column
values (`datalist'), a structure whose fields specify the
column values (`datastruct'), or passed explicitly as
individual values (`col1',...`colN').
QUALIFIERS
; delim: character used for the delimiter (default: ',')
; names: An array of strings used to name the columns
; noheader: Do not write a header to the file
; quote: character used for the quoting fields (default: '"')
; quoteall: Quote all field values
; quotesome: Quote only those fields where quoting is necessary
; rdb: Write in an rdb-style TAB delimited format
Unless the `noheader' qualifier is given, a header containing
the names of the columns will be written if either the `names'
qualifier is present, or the data values are passed as a structure.
In the latter case, the structure field names will be used for the
column names.
The function will throw an `IOError' exception if a write error occurs.
EXAMPLE
For the purposes of this example, assume that three arrays are
given: `time', `temp', `humidity', which represent a
time series of temperature and humidity. Here are three equivalent
ways of writing the arrays to a CSV file:
% Via a structure
data = struct {time=time, temperature=temp, humidity=humidity};
csv_writecol ("weather.dat", data);
% Via a list
data = {time, temp, humidity};
csv_writecol ("weather.dat", data
;names=["time","temperature","humidity"]);
% Via explicit arguments
csv_writecol ("weather.dat", time, temp, humidity
;names=["time","temperature","humidity"]);
NOTES
This function is a simple wrapper around `csv_encoder_new' and
`csv.writecol'.
SEE ALSO
csv_encoder_new, csv.writecol, csv_readcol
--------------------------------------------------------------
csv.writecol
SYNOPSIS
Write to a file using a CSV format
USAGE
csv.writecol(file|fp, datalist | datastruct | col1,...,colN)
DESCRIPTION
The `csv.writecol' function method may be used to write one of
more data columns to a file or file descriptor via a CSV encoder
object instantiated using the `csv_encoder_new' function.
The data values may be expressed in several ways: as a list of a
column values (`datalist'), a structure whose fields specify
the column values (`datastruct'), or passed explicitly as
individual values (`col1',...`colN').
An `IOError' exception will be thrown if a write error occurs.
QUALIFIERS
; delim: character used for the delimiter (default: ',')
; names: An array of strings used for names of the columns
; noheader: Do not write a header to the file
; quoteall: Quote all field values
; quotesome: Quote only those fields where quoting is necessary
; rdb: Write in an rdb-style TAB delimited format
Unless the `noheader' qualifier is given, a header containing
the names of the columns will be written if either the `names'
qualifier is present, or the data values are passed as a structure.
In the latter case, the structure field names will be used for the
column names.
EXAMPLE
For the purposes of this example, assume that three arrays are
given: `time', `temp', `humidity', which represent a
time series of temperature and humidity. Here are three equivalent
ways of writing the arrays to a TAB delimited file:
csv = csv_encoder_new (;quote='\t');
% Via a structure
data = struct {time=time, temperature=temp, humidity=humidity};
csv.writecol ("weather.dat", data);
% Via a list
data = {time, temp, humidity};
csv.writecol ("weather.dat", data
;names=["time","temperature","humidity"]);
% Via explicit arguments
csv.writecol ("weather.dat", time, temp, humidity
;names=["time","temperature","humidity"]);
SEE ALSO
csv_encoder_new, csv_writecol, csv_readcol
--------------------------------------------------------------