Name

   csv.sqh

 Description

   A collection of routines that are very useful for reading and
   writing .csv files (i.e., comma-separated, variable length files).
   .csv files are often used for importing into spreadsheet programs.
   In csv files, text strings are enclosed in double-quotes, and to
   include a double-quote, it is stuttered (i.e., repeated).  Numeric
   values are bare (i.e., no quotes).

   Does not yet make any special provision for date values.  These
   can usually be quoted.


   csv_get_field( :$line , :$field )

     Gets the first comma-separated field from $line and moves it
     to $field.  Upon completion the field and comma separator are
     removed from $line.

     If the value is in quotes, the quotations are removed.
     If a value contains two double-quotes ("), these are reduced to
     a single double-quote.

     For example,

       let $line = '"You ""send"" me.",5'
       do csv_get_field( $line , $field )

     results in $field having the value 'You "send" me.'
     and $line having the value '5'.


   csv_set_string( $s , $:t )

     sets $t to the quoted value of $s.  If $s contains
     double-quotes, each is replaced with two double-quotes.
     This routine is used to put a string as the the first
     field of a line to be written to a csv file.

     For example,

       do csv_set_string( $name , $line )
       do csv_add_string( $city , $line )
       write {OUT_FILE} from $line


   csv_add_string( $s , $:t )

     appends a comma to $t, followed by the value of $s in double-quotes.
     If $s contains double-quotes, these are treated as two double-quotes.
     This procedure is used to add a string field to a line that will
     be subsequently written to a csv file.

     For example,

       do csv_set_string( $last_name , $line )
       do csv_add_string( $first_name , $line )
       write {OUT_FILE} from $line


   csv_set_number( #n , $e , $:t )

     sets the a string variable $t to an edited numeric value #n using
     the edit string $e. This is used to set the first field of a line
     to a numeric value using an edit mask, where the intent is to
     subsequently write the line to a csv file.

     For example,

       do csv_set_number( #emp_id , '888888888' , $line )
       do csv_add_string( $emp_name , $line )
       write {OUT_FILE} from $line


   csv_add_number( #n , $e , $:t )

     appends a numeric field value #n to a line $t using edit mask $e.
     This is used to append a numeric field value to a line using an
     edit mask, where the intent is to subsequently write the line to
     a csv file.

     For example,

       do csv_set_string( $name , $line )
       do csv_add_number( #salary , '8888888.88' , $line )
       write {OUT_FILE} from $line