.\" 
.\" Copyright 2003 Michael B. Allen <mba2000 ioplex.com>
.\" 
.TH csv 3m "Apr 29, 2005" "libmba-0.9.1" "MBA Library Functions"
.SH NAME
csv \- parse comma separated values
.SH SYNOPSIS
.nf
.B #include <mba/csv.h>
.sp
.BI "int csv_row_parse(const tchar *" src ",
.BI "            size_t " sn ",
.BI "            tchar *" buf ",
.BI "            size_t " bn ",
.BI "            tchar *" row "[],
.BI "            int " rn ",
.BI "            int " sep ",
.BI "            int " flags ")
.br
.BI "int csv_row_fread(FILE *" in ",
.BI "            unsigned char *" buf ",
.BI "            size_t " bn ",
.BI "            unsigned char *" row "[],
.BI "            int " numcols ",
.BI "            int " sep ",
.BI "            int " flags ")
.br

.fi
.SH DESCRIPTION
The
.BR "csv" (3m)
module parses the popular comma separated values (CSV) format exported by applications like spreadsheets. This parser considers quoted elements, quoted quotes, and preserves carriage returns and newlines within elements. The separator character is specified by the user.
.sp
Please note that escaping a quote requires that the entire element be quoted as well. So a quoted string element would actually look like
.I """foo"""
where the outer quotes quote the element and the remaining quote pairs are each an escape followed by the literal quote. This is consistent with how popular spreadsheets behave and deviating from this behavior will generate an error.
.PP
.TP
.B row_parse
The
.B csv_row_parse
function will parse a line of text at
.I src
for no more than
.I sn
bytes and place pointers to zero terminiated strings allocated from no more than
.I bn
bytes of the memory at
.I buf
into the array
.I row
for at most
.I rn
data elements. The
.I sep
parameter must specify a separator to use (e.g. a comma
.IR "','" )
and must not be a quote, carriage return, or newline. Comma
.IR "','" ,
tab
.IR "'\\t'" ,
colon
.IR "':'" ,
and pipe
.I '|'
are common separators.
.sp
The
.I flags
parameter can be zero or any combination of
.I CSV_TRIM
and
.IR "CSV_QUOTES" .
If
.I CSV_TRIM
is specified, strings will be trimmed of leading and trailing whitespace (but an unquoted carriage-return before a newline is always trimmed regardless). If the
.I CSV_QUOTES
flag is spcecified, quotes will be interpreted. Both flags should be specified when parsing conventional CSV files.
.sp
The
.B csv_row_parse
function is actually a macro for either
.B csv_row_parse_str
or
.BR "csv_row_parse_wcs" .
The
.B csv_row_parse_wcs
function has the same prototype but accepts
.I wchar_t
parameters whereas
.B csv_row_parse_str
accepts
.I unsigned char
parameters.
.TP
.B row_fread
Read a line of text from the stream
.IR "in" ,
process the line with
.B csv_row_parse
and place pointers to zero terminiated strings allocated from no more than
.I bn
bytes of the memory at
.I buf
into the array
.I row
for at most
.I rn
data elements.
.SH RETURNS
.TP
.B row_parse
The
.I csv_row_parse
function returns the number of bytes of
.I src
parsed or -1 if an error occured in which case
.I errno
will be set appropriately.
.TP
.B row_fread
The
.I csv_row_fread
function returns the number of bytes read from the stream
.I in
or -1 if an error occured in which case
.I errno
will be set appropriately.