The fare-csv Reference Manual

Table of Contents

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 2.3 "Robert April" on Tue Jan 09 14:33:38 2018 GMT+0.


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

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.


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

2 Systems

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


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

2.1 fare-csv

Author

Francois-Rene Rideau

License

BSD or bugroff

Description

Robust CSV parser and printer

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 (file)

Components

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

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 files   [Contents][Index]

3.1.1 fare-csv.asd

Location

fare-csv.asd

Systems

fare-csv (system)


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

3.1.2 fare-csv/package.lisp

Parent

fare-csv (system)

Location

package.lisp

Packages

fare-csv


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

3.1.3 fare-csv/csv.lisp

Dependency

package.lisp (file)

Parent

fare-csv (system)

Location

csv.lisp

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 fare-csv

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *allow-binary*

do we accept non-ascii data?

Package

fare-csv

Source

csv.lisp (file)

Special Variable: *eol*

line ending when exporting CSV

Package

fare-csv

Source

csv.lisp (file)

Special Variable: *line-endings*

acceptable line endings when importing CSV

Package

fare-csv

Source

csv.lisp (file)

Special Variable: *loose-quote*

can quotes appear anywhere in a field?

Package

fare-csv

Source

csv.lisp (file)

Special Variable: *quote*

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

Package

fare-csv

Source

csv.lisp (file)

Special Variable: *separator*

Separator between CSV fields

Package

fare-csv

Source

csv.lisp (file)

Special Variable: *skip-whitespace*

shall we skip unquoted whitespace around separators?

Package

fare-csv

Source

csv.lisp (file)

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 (file)

Special Variable: +cr+

String containing a CR (Carriage Return)

Package

fare-csv

Source

csv.lisp (file)

Special Variable: +crlf+

String containing a CRLF line termination

Package

fare-csv

Source

csv.lisp (file)

Special Variable: +lf+

String containing a LF (Linefeed)

Package

fare-csv

Source

csv.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

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 (file)

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 (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 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 (file)

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 (file)

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 (file)

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 (file)

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 (file)


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

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *accept-cr*

internal: do we accept cr?

Package

fare-csv

Source

csv.lisp (file)

Special Variable: *accept-crlf*

internal: do we accept crlf?

Package

fare-csv

Source

csv.lisp (file)

Special Variable: *accept-lf*

internal: do we accept lf?

Package

fare-csv

Source

csv.lisp (file)

Special Variable: *csv-variables*
Package

fare-csv

Source

csv.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: defsubst NAME ARGLIST &body BODY

Declare an inline defun.

Package

fare-csv

Source

csv.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: accept X STREAM
Package

fare-csv

Source

csv.lisp (file)

Function: accept-eof STREAM
Package

fare-csv

Source

csv.lisp (file)

Function: accept-eol STREAM
Package

fare-csv

Source

csv.lisp (file)

Function: accept-p X STREAM
Package

fare-csv

Source

csv.lisp (file)

Function: accept-quote STREAM
Package

fare-csv

Source

csv.lisp (file)

Function: accept-separator STREAM
Package

fare-csv

Source

csv.lisp (file)

Function: accept-space STREAM
Package

fare-csv

Source

csv.lisp (file)

Function: accept-spaces STREAM
Package

fare-csv

Source

csv.lisp (file)

Function: call-with-creativyst-csv-syntax THUNK
Package

fare-csv

Source

csv.lisp (file)

Function: call-with-rfc4180-csv-syntax THUNK
Package

fare-csv

Source

csv.lisp (file)

Function: call-with-strict-rfc4180-csv-syntax THUNK
Package

fare-csv

Source

csv.lisp (file)

Function: char-ascii-text-p C
Package

fare-csv

Source

csv.lisp (file)

Function: char-needs-quoting X
Package

fare-csv

Source

csv.lisp (file)

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 (file)

Function: string-needs-quoting X
Package

fare-csv

Source

csv.lisp (file)

Function: valid-eol-p X
Package

fare-csv

Source

csv.lisp (file)

Function: validate-csv-parameters ()
Package

fare-csv

Source

csv.lisp (file)

Function: write-csv-field FIELD STREAM
Package

fare-csv

Source

csv.lisp (file)

Function: write-csv-string-safely STRING STREAM
Package

fare-csv

Source

csv.lisp (file)

Function: write-quoted-string STRING STREAM
Package

fare-csv

Source

csv.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L  
Index Entry  Section

F
fare-csv.asd: The fare-csv<dot>asd file
fare-csv/csv.lisp: The fare-csv/csv<dot>lisp file
fare-csv/package.lisp: The fare-csv/package<dot>lisp file
File, Lisp, fare-csv.asd: The fare-csv<dot>asd file
File, Lisp, fare-csv/csv.lisp: The fare-csv/csv<dot>lisp file
File, Lisp, fare-csv/package.lisp: The fare-csv/package<dot>lisp file

L
Lisp File, fare-csv.asd: The fare-csv<dot>asd file
Lisp File, fare-csv/csv.lisp: The fare-csv/csv<dot>lisp file
Lisp File, fare-csv/package.lisp: The fare-csv/package<dot>lisp file

Jump to:   F   L  

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: Internal functions
accept-eof: Internal functions
accept-eol: Internal functions
accept-p: Internal functions
accept-quote: Internal functions
accept-separator: Internal functions
accept-space: Internal functions
accept-spaces: Internal functions

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

D
defsubst: Internal macros

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

M
Macro, defsubst: Internal macros
Macro, with-creativyst-csv-syntax: Exported macros
Macro, with-rfc4180-csv-syntax: Exported macros
Macro, with-strict-rfc4180-csv-syntax: Exported macros

R
read-csv-file: Exported functions
read-csv-line: Exported functions
read-csv-stream: Exported functions

S
string-needs-quoting: Internal functions

V
valid-eol-p: Internal functions
validate-csv-parameters: Internal functions

W
with-creativyst-csv-syntax: Exported macros
with-rfc4180-csv-syntax: Exported macros
with-strict-rfc4180-csv-syntax: Exported macros
write-csv-field: Internal functions
write-csv-line: Exported functions
write-csv-lines: Exported functions
write-csv-string-safely: Internal functions
write-quoted-string: Internal 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*: Internal special variables
*accept-crlf*: Internal special variables
*accept-lf*: Internal special variables
*allow-binary*: Exported special variables
*csv-variables*: Internal special variables
*eol*: Exported special variables
*line-endings*: Exported special variables
*loose-quote*: Exported special variables
*quote*: Exported special variables
*separator*: Exported special variables
*skip-whitespace*: Exported special variables
*unquoted-quotequote*: Exported special variables

+
+cr+: Exported special variables
+crlf+: Exported special variables
+lf+: Exported special variables

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

Jump to:   *   +  
S  

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

A.4 Data types

Jump to:   F   P   S  
Index Entry  Section

F
fare-csv: The fare-csv system
fare-csv: The fare-csv package

P
Package, fare-csv: The fare-csv package

S
System, fare-csv: The fare-csv system

Jump to:   F   P   S