The fare-csv Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The fare-csv Reference Manual

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.

Table of Contents


1 Introduction

fare-csv

This library allows you to read and write CSV files, according to any of the prevailing "standards" and their popular variants.

Example usage

(ql:quickload :fare-csv)
(fare-csv:with-rfc4180-csv-syntax ()
  (let ((fare-csv:*separator* #\;))
   (fare-csv:read-csv-file "/tmp/semicolon-separated.csv")))

Competing standards

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

Exported Functionality

fare-csv defines and uses package FARE-CSV.


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 fare-csv

Robust CSV parser and printer

Author

Francois-Rene Rideau

License

BSD or bugroff

Long Description

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.

Version

1.0.3

Source

fare-csv.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 fare-csv/fare-csv.asd

Source

fare-csv.asd.

Parent Component

fare-csv (system).

ASDF Systems

fare-csv.


3.1.2 fare-csv/package.lisp

Source

fare-csv.asd.

Parent Component

fare-csv (system).

Packages

fare-csv.


Previous: , Up: Lisp   [Contents][Index]

3.1.3 fare-csv/csv.lisp

Dependency

package.lisp (file).

Source

fare-csv.asd.

Parent Component

fare-csv (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 fare-csv

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.1 Special variables

Special Variable: *allow-binary*

do we accept non-ascii data?

Package

fare-csv.

Source

csv.lisp.

Special Variable: *eol*

line ending when exporting CSV

Package

fare-csv.

Source

csv.lisp.

Special Variable: *line-endings*

acceptable line endings when importing CSV

Package

fare-csv.

Source

csv.lisp.

Special Variable: *loose-quote*

can quotes appear anywhere in a field?

Package

fare-csv.

Source

csv.lisp.

Special Variable: *quote*

delimiter of string data; pascal-like quoted as double itself in a string.

Package

fare-csv.

Source

csv.lisp.

Special Variable: *separator*

Separator between CSV fields

Package

fare-csv.

Source

csv.lisp.

Special Variable: *skip-whitespace*

shall we skip unquoted whitespace around separators?

Package

fare-csv.

Source

csv.lisp.

Special Variable: *unquoted-quotequote*

does a pair of quotes represent a quote outside of quotes? M$, RFC says NIL, csv.3tcl says T

Package

fare-csv.

Source

csv.lisp.

Special Variable: +cr+

String containing a CR (Carriage Return)

Package

fare-csv.

Source

csv.lisp.

Special Variable: +crlf+

String containing a CRLF line termination

Package

fare-csv.

Source

csv.lisp.

Special Variable: +lf+

String containing a LF (Linefeed)

Package

fare-csv.

Source

csv.lisp.


5.1.2 Macros

Macro: with-creativyst-csv-syntax ((&optional) &body body)

bind CSV syntax parameters to the CREATIVYST standard around evaluation of BODY

Package

fare-csv.

Source

csv.lisp.

Macro: with-rfc4180-csv-syntax ((&optional) &body body)

bind CSV syntax parameters to the RFC 4180 standard around evaluation of BODY

Package

fare-csv.

Source

csv.lisp.

Macro: with-strict-rfc4180-csv-syntax ((&optional) &body 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

Package

fare-csv.

Source

csv.lisp.


Previous: , Up: Public Interface   [Contents][Index]

5.1.3 Ordinary functions

Function: read-csv-file (pathname &rest keys &key element-type external-format)

Open the file designated by PATHNAME, using the provided keys if any, and call READ-CSV-STREAM on it.

Package

fare-csv.

Source

csv.lisp.

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.

Package

fare-csv.

Source

csv.lisp.

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.

Package

fare-csv.

Source

csv.lisp.

Function: write-csv-line (fields stream)

Format one line of FIELDS to STREAM in CSV format, using the current syntax parameters.

Package

fare-csv.

Source

csv.lisp.

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.

Package

fare-csv.

Source

csv.lisp.


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Special variables

Special Variable: *accept-cr*

internal: do we accept cr?

Package

fare-csv.

Source

csv.lisp.

Special Variable: *accept-crlf*

internal: do we accept crlf?

Package

fare-csv.

Source

csv.lisp.

Special Variable: *accept-lf*

internal: do we accept lf?

Package

fare-csv.

Source

csv.lisp.

Special Variable: *csv-variables*
Package

fare-csv.

Source

csv.lisp.


5.2.2 Macros

Macro: defsubst (name arglist &body body)

Declare an inline defun.

Package

fare-csv.

Source

csv.lisp.


Previous: , Up: Internals   [Contents][Index]

5.2.3 Ordinary functions

Function: accept (x stream)
Package

fare-csv.

Source

csv.lisp.

Function: accept-eof (stream)
Package

fare-csv.

Source

csv.lisp.

Function: accept-eol (stream)
Package

fare-csv.

Source

csv.lisp.

Function: accept-p (x stream)
Package

fare-csv.

Source

csv.lisp.

Function: accept-quote (stream)
Package

fare-csv.

Source

csv.lisp.

Function: accept-separator (stream)
Package

fare-csv.

Source

csv.lisp.

Function: accept-space (stream)
Package

fare-csv.

Source

csv.lisp.

Function: accept-spaces (stream)
Package

fare-csv.

Source

csv.lisp.

Function: call-with-creativyst-csv-syntax (thunk)
Package

fare-csv.

Source

csv.lisp.

Function: call-with-rfc4180-csv-syntax (thunk)
Package

fare-csv.

Source

csv.lisp.

Function: call-with-strict-rfc4180-csv-syntax (thunk)
Package

fare-csv.

Source

csv.lisp.

Function: char-ascii-text-p (c)
Package

fare-csv.

Source

csv.lisp.

Function: char-needs-quoting (x)
Package

fare-csv.

Source

csv.lisp.

Function: char-space-p (c)

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!

Package

fare-csv.

Source

csv.lisp.

Function: string-needs-quoting (x)
Package

fare-csv.

Source

csv.lisp.

Function: valid-eol-p (x)
Package

fare-csv.

Source

csv.lisp.

Function: validate-csv-parameters ()
Package

fare-csv.

Source

csv.lisp.

Function: write-csv-field (field stream)
Package

fare-csv.

Source

csv.lisp.

Function: write-csv-string-safely (string stream)
Package

fare-csv.

Source

csv.lisp.

Function: write-quoted-string (string stream)
Package

fare-csv.

Source

csv.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   C   D   F   M   R   S   V   W  
Index Entry  Section

A
accept: Private ordinary functions
accept-eof: Private ordinary functions
accept-eol: Private ordinary functions
accept-p: Private ordinary functions
accept-quote: Private ordinary functions
accept-separator: Private ordinary functions
accept-space: Private ordinary functions
accept-spaces: Private ordinary functions

C
call-with-creativyst-csv-syntax: Private ordinary functions
call-with-rfc4180-csv-syntax: Private ordinary functions
call-with-strict-rfc4180-csv-syntax: Private ordinary functions
char-ascii-text-p: Private ordinary functions
char-needs-quoting: Private ordinary functions
char-space-p: Private ordinary functions

D
defsubst: Private macros

F
Function, accept: Private ordinary functions
Function, accept-eof: Private ordinary functions
Function, accept-eol: Private ordinary functions
Function, accept-p: Private ordinary functions
Function, accept-quote: Private ordinary functions
Function, accept-separator: Private ordinary functions
Function, accept-space: Private ordinary functions
Function, accept-spaces: Private ordinary functions
Function, call-with-creativyst-csv-syntax: Private ordinary functions
Function, call-with-rfc4180-csv-syntax: Private ordinary functions
Function, call-with-strict-rfc4180-csv-syntax: Private ordinary functions
Function, char-ascii-text-p: Private ordinary functions
Function, char-needs-quoting: Private ordinary functions
Function, char-space-p: Private ordinary functions
Function, read-csv-file: Public ordinary functions
Function, read-csv-line: Public ordinary functions
Function, read-csv-stream: Public ordinary functions
Function, string-needs-quoting: Private ordinary functions
Function, valid-eol-p: Private ordinary functions
Function, validate-csv-parameters: Private ordinary functions
Function, write-csv-field: Private ordinary functions
Function, write-csv-line: Public ordinary functions
Function, write-csv-lines: Public ordinary functions
Function, write-csv-string-safely: Private ordinary functions
Function, write-quoted-string: Private ordinary functions

M
Macro, defsubst: Private macros
Macro, with-creativyst-csv-syntax: Public macros
Macro, with-rfc4180-csv-syntax: Public macros
Macro, with-strict-rfc4180-csv-syntax: Public macros

R
read-csv-file: Public ordinary functions
read-csv-line: Public ordinary functions
read-csv-stream: Public ordinary functions

S
string-needs-quoting: Private ordinary functions

V
valid-eol-p: Private ordinary functions
validate-csv-parameters: Private ordinary functions

W
with-creativyst-csv-syntax: Public macros
with-rfc4180-csv-syntax: Public macros
with-strict-rfc4180-csv-syntax: Public macros
write-csv-field: Private ordinary functions
write-csv-line: Public ordinary functions
write-csv-lines: Public ordinary functions
write-csv-string-safely: Private ordinary functions
write-quoted-string: Private ordinary functions

Jump to:   A   C   D   F   M   R   S   V   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *   +  
S  
Index Entry  Section

*
*accept-cr*: Private special variables
*accept-crlf*: Private special variables
*accept-lf*: Private special variables
*allow-binary*: Public special variables
*csv-variables*: Private special variables
*eol*: Public special variables
*line-endings*: Public special variables
*loose-quote*: Public special variables
*quote*: Public special variables
*separator*: Public special variables
*skip-whitespace*: Public special variables
*unquoted-quotequote*: Public special variables

+
+cr+: Public special variables
+crlf+: Public special variables
+lf+: Public special variables

S
Special Variable, *accept-cr*: Private special variables
Special Variable, *accept-crlf*: Private special variables
Special Variable, *accept-lf*: Private special variables
Special Variable, *allow-binary*: Public special variables
Special Variable, *csv-variables*: Private special variables
Special Variable, *eol*: Public special variables
Special Variable, *line-endings*: Public special variables
Special Variable, *loose-quote*: Public special variables
Special Variable, *quote*: Public special variables
Special Variable, *separator*: Public special variables
Special Variable, *skip-whitespace*: Public special variables
Special Variable, *unquoted-quotequote*: Public special variables
Special Variable, +cr+: Public special variables
Special Variable, +crlf+: Public special variables
Special Variable, +lf+: Public special variables

Jump to:   *   +  
S