csv_decoder_new

 SYNOPSIS
  Instantiate a parser for CSV data

 USAGE
  obj = cvs_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 CVS object

 EXAMPLE
  See the documentation for the `cvs.readcol' and
  `cvs.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
  cvs_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
  `cvs_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

--------------------------------------------------------------