Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the fare-csv Reference Manual, version 1.0.3, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 04:31:42 2022 GMT+0.
Next: Systems, Previous: The fare-csv Reference Manual, Up: The fare-csv Reference Manual [Contents][Index]
This library allows you to read and write CSV files, according to any of the prevailing "standards" and their popular variants.
(ql:quickload :fare-csv)
(fare-csv:with-rfc4180-csv-syntax ()
(let ((fare-csv:*separator* #\;))
(fare-csv:read-csv-file "/tmp/semicolon-separated.csv")))
CSV means "Comma-Separated Values". It's a vastly underspecified "standard",
as each and every implementation seems to behave differently, and sometimes,
even major implementations (e.g. Microsoft Excel) change their behavior
from one version to the next. Moreover, programs using CSV often explicitly
allow for variants, whereby another character can be used instead of
the standard comma U+2C #\,
as a separator (typically, a tab, U+09
, or
a semi-colon, U+3B #\;
), and another character can be used for quoting
instead of the standard double-quote U+22 #\"
(typically, a single-quote
U+27 #\'
). Finally, some implementations don't handle quotation properly
when printing, and different implementations do different things with
respect to line-ending. We try to handle all sensible such variants.
However, one thing we do not try to do is encoding or decoding complex
objects, as there is no standard whatsoever that covers this.
The only standardized type for entries is strings, and
we parse everything as (properly quoted) strings.
We print strings by properly quoting them, and we PRINC
numbers:
it is up to you to make sure numbers are printed as you desire,
or else to pass a string if CL's PRINC
doesn't do what you want.
By default, we follow the specification from creativyst, that seems to describe popular usage: http://www.creativyst.com/Doc/Articles/CSV/CSV01.htm
This document says about the same: http://edoceo.com/utilitas/csv-file-format
There is now an RFC that tries to standardize CSV, and we support it as well: http://www.rfc-editor.org/rfc/rfc4180.txt
Finally, here's what Perl hackers think CSV is: http://search.cpan.org/~hmbrand/Text-CSV_XS-0.59/CSV_XS.pm
fare-csv defines and uses package FARE-CSV
.
Function READ-CSV-STREAM (STREAM)
Read lines from STREAM
in CSV format, using the current syntax parameters.
Return a list of list of strings, one entry for each line,
that contains one entry for each field.
Entries are read as strings;
it is up to you to interpret the strings as whatever you want.
Function READ-CSV-LINE (STREAM)
Read one line from STREAM
in CSV format, using the current syntax parameters.
Return a list of strings, one for each field in the line.
Entries are read as strings;
it is up to you to interpret the strings as whatever you want.
Function READ-CSV-FILE (PATHNAME &KEY ELEMENT-TYPE EXTERNAL-FORMAT)
Open the file designated by PATHNAME
, using the provided keys if any,
and call READ-CSV-STREAM
on it.
Function WRITE-CSV-LINES (LINES STREAM)
Given a list of LINES
, each of them a list of fields, and a STREAM
,
format those lines as CSV according to the current syntax parameters.
Function WRITE-CSV-LINE (FIELDS STREAM)
Format one line of FIELDS
to STREAM
in CSV format,
using the current syntax parameters.
Take a list of FIELDS
, and format them as follows:
if it's a string, write it,
only using quotes if needed for escaping;
if it's null, write an empty field;
if it's a different symbol, write its name as if a string,
only using quotes if needed for escaping;
if it's a number, format it as per PRINC
.
Constant +CR+
a string with the ASCII character 13 (Carriage Return).
It's the standard line termination for text on MacOS.
Constant +LF+
a string with the ASCII character 10 (Line Feed).
It's the standard line termination for text on Unix.
Constant +CRLF+
a string with the ASCII characters 13 and 10 (CR, LF).
It's the standard line termination for text on Windows, and many RFCs.
Variable *SEPARATOR*
The separator to use when reading or writing CSV files.
A character. By default, a comma: #\,
Variable *QUOTE*
The quote character to use when reading or writing CSV files.
A character. By default, a double-quote: #\"
Variable *UNQUOTED-QUOTEQUOTE*
A boolean that is true iff a pair of quotes
represents a quote outside of quotes.
Microsoft and RFC4180 says NIL
, csv.3tcl says T
.
A boolean. By default, NIL
.
Variable *LOOSE-QUOTE*
A boolean that is true iff quotes appear anywhere in a field?
By default, NIL
.
Variable *ALLOW-BINARY*
A boolean that is true iff we accept non-ASCII data.
A boolean. By default, T
.
Variable *KEEP-META-INFO*
A boolean that when true causes the reader functions to return
for each entry, instead of a string, a list of a string and a plist;
the plist currently only has one property, :quoted, that has a boolean value
which is true iff the string included quotes.
A boolean. By default, NIL
.
Variable *EOL*
Line ending to use when writing CSV files.
A string. By default, +CRLF+
as specified by creativyst.
Variable *LINE-ENDINGS*
A list of line endings accepted when parsing a CSV file.
Valid elements of that list are the constants +CRLF+
, +LF+
and +CR+
.
By default, contains all three values, as specified by creativyst.
Variable *SKIP-WHITESPACE*
A boolean that when true causes initial and final (unquoted) spaces
to be ignored while parsing CSV.
A boolean. By default, T
as specified by creativyst.
Macro WITH-CREATIVYST-CSV-SYNTAX () &BODY BODY
A macro in which to wrap a program BODY
, around which
all the above parameters will be bound to their default value,
as specified by creativyst.
Macro WITH-RFC4180-CSV-SYNTAX () &BODY BODY
A macro in which to wrap a program BODY
, around which
all the above parameters will be bound as per the RFC4180 specification.
As compared to creativyst, *EOL*
is +LF+
,
*LINE-ENDINGS*
doesn't contain +CR+
but only +CRLF+
and +LF+
and *SKIP-WHITESPACE*
is NIL
.
Macro WITH-STRICT-RFC4180-CSV-SYNTAX () &BODY BODY
A macro in which to wrap a program BODY
, around which
all the above parameters will be bound as per the RFC4180 specification,
but with a stricter interpretation:
only +CRLF+
is accepted as *LINE-ENDINGS*
, and we don't *ALLOW-BINARY*
data.
Next: Files, Previous: Introduction, Up: The fare-csv Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Robust CSV parser and printer
Francois-Rene Rideau
BSD or bugroff
Robust CSV (Comma-separated values) parser and printer, tries to follow the fine print of de facto standards, can be configured to choose which standard exactly.
1.0.3
Next: Packages, Previous: Systems, Up: The fare-csv Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: fare-csv/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
fare-csv (system).
Next: fare-csv/csv.lisp, Previous: fare-csv/fare-csv.asd, Up: Lisp [Contents][Index]
fare-csv (system).
Previous: fare-csv/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
fare-csv (system).
Next: Definitions, Previous: Files, Up: The fare-csv Reference Manual [Contents][Index]
Packages are listed by definition order.
common-lisp.
Next: Indexes, Previous: Packages, Up: The fare-csv Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Macros, Previous: Public Interface, Up: Public Interface [Contents][Index]
acceptable line endings when importing CSV
can quotes appear anywhere in a field?
delimiter of string data; pascal-like quoted as double itself in a string.
shall we skip unquoted whitespace around separators?
does a pair of quotes represent a quote outside of quotes? M$, RFC says NIL, csv.3tcl says T
String containing a CR (Carriage Return)
String containing a CRLF line termination
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [Contents][Index]
bind CSV syntax parameters to the CREATIVYST standard around evaluation of BODY
bind CSV syntax parameters to the RFC 4180 standard around evaluation of BODY
bind CSV syntax parameters to the strict RFC 4180 standard around evaluation of BODY, forcing CRLF as line ending and disallowing binary data amongst values
Previous: Macros, Up: Public Interface [Contents][Index]
Open the file designated by PATHNAME, using the provided keys if any, and call READ-CSV-STREAM on it.
Read one line from STREAM in CSV format, using the current syntax parameters.
Return a list of strings, one for each field in the line.
Entries are read as strings;
it is up to you to interpret the strings as whatever you want.
Read lines from STREAM in CSV format, using the current syntax parameters.
Return a list of list of strings, one entry for each line,
that contains one entry for each field.
Entries are read as strings;
it is up to you to interpret the strings as whatever you want.
Format one line of FIELDS to STREAM in CSV format, using the current syntax parameters.
Given a list of LINES, each of them a list of fields, and a STREAM, format those lines as CSV according to the current syntax parameters.
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Special variables, Up: Internals [Contents][Index]
Declare an inline defun.
Is character C some kind of white space?
NB: this only handles a tiny subset of whitespace characters,
even if restricted to ASCII. However, it’s rather portable,
and is what the creativyst document specifies.
Be careful to not skip a separator, as it could be e.g. a tab!
Previous: Definitions, Up: The fare-csv Reference Manual [Contents][Index]
Jump to: | A C D F M R S V W |
---|
Jump to: | A C D F M R S V W |
---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
Jump to: | *
+
S |
---|
Jump to: | *
+
S |
---|
Jump to: | C F P S |
---|
Jump to: | C F P S |
---|