
Q-CSV - Comma Separated Value interface for the Q programming language
===== = ===== ========= ===== ========= === === ============= ========

The CSV library provides an interface to read and write comma separated value
files. The reading and writing functions are loosely based on Python's CSV
module (http://docs.python.org/lib/module-csv.html)

INSTALLATION

This module is (or will soon be) included in the binary "all in one" packages
available from the Q website. Use these if you can. To install from the
sources, run 'make' to compile the module and 'make install' (as root) to
install it under the default prefix (/usr/local). If your Q installation lives
elsewhere (e.g., under /usr), you can specify the installation prefix as
follows: 'make prefix=/usr install'. (It is recommended to install the module
under the same prefix as the Q interpreter so that the interpreter can find
the module. Otherwise you might have to modify your QPATH accordingly.)

USAGE

Data records are represented as tuples of strings and numeric data. Dialects
are created using csv_dialect with a list of specifications outlined in csv.q.

- sreadcsv reads a CSV formatted string and converts it to a tuple of fields
  according to the dialect specified. If no dialect is specified, conversion
  is performed using RFC 4180 rules (http://www.ietf.org/rfc/rfc4180.txt).
  Invalidly formatted CSV causes return of a 'csv_error MSG' term
  (see NOTES below).

- swritecsv converts a tuple of fields, which includes only strings, integers,
  and floats to a CSV formatted string according to the dialect specified. If
  no dialect is specified, conversion is performed using RFC 4180 rules
  (http://www.ietf.org/rfc/rfc4180.txt). Tuples that are not strings, integers,
  or floats invoke a 'csv_error MSG' term (see NOTES below).

- freadcsv is equivalent to sreadcsv except that reading is from a file.

- fwritecsv is equivalent to swritecsv except that writing is to a file.

The routines described above read/write one record at a time. Additional
functions (sreadcsvlist, swritecsvlist, freadcsvlist and fwritecsvlist) are
provided to convert between entire CSV files and lists of tuples. Note that
these require that the entire data fits into RAM and will thus be inefficient
for huge datasets.

NOTES

- Errors in the conversion routines (input that does not abide by the
  dialect rules; records containing field types other than strings, integers
  and floats) cause a special 'csv_error MSG' term to be returned, where MSG
  is a string describing the particular error. To handle error conditions,
  your application should either check for these, or define csv_error to
  directly handle the error in some way (e.g., provide a default value, or
  raise an exception). For instance:

  csv_error MSG = throw MSG;

- MS Excel files should be written using "=""0004""" if leading 0s are 
  significant. Use the same technique if leading space is significant. Use this
  quirk only if written files are going to be imported to MS Excel.

EXAMPLES

Examples are provided in the examples subdirectory. See "readsamples.q" for
reading csv files and "writesamples.q" for writing.

Mar 6 2008
Eddie Rucker
erucker@bmc.edu
