The csv-parser Reference Manual

This is the csv-parser Reference Manual, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:39:22 2018 GMT+0.

1 Introduction

CSV parsing/writing utilities, a la Microsoft Excel.

Author: Alain Picard 
         (also alain.picard@memetrics.com)

Notes
-----

  Differences from Faré's CSV reader:

  * this one can import DOS formatted files into a unix image,
    and not have the redundant ^M splattered at the end of the fields.
    This is important when processing a file on a Unix server which
    is being uploaded via HTTP by some poor schmuck on a windoze box.

  * Handles empty trailing fields properly

  * comes with test suite, to see the semantics I've chosen to implement

  * I've included a couple of high-level goodies, like
    do-csv-file and map-csv-file, as well as the ability
    to control the range of line-numbers on which to apply
    your code.  Pretty simple stuff, but useful.

  * You get a CSV-file writer, for free!  :-)

2 Systems

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

2.1 `csv-parser`

Author: Alain Picard <alain.picard@memetrics.com>
License: LLGPL
Description: CSV parsing/writing utilities, a la Microsoft Excel
Source: csv-parser.asd (file)
Component: csv-parser.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 `csv-parser.asd`

Location: csv-parser.asd
Systems: csv-parser (system)

3.1.2 `csv-parser/csv-parser.lisp`

Parent

csv-parser (system)

Location

csv-parser.lisp

Packages

csv-parser

Exported Definitions

*field-separator* (special variable)
*quote-character* (special variable)
do-csv-file (macro)
map-csv-file (function)
read-csv-line (function)
write-csv-line (function)

Internal Definitions

*current-field* (special variable)
*fields* (special variable)
*num-fields* (special variable)
*spaces-gobbled* (special variable)
*state* (special variable)
add-char (function)
change-state (function)
csv-test-blank (function)
csv-test-blanks (function)
csv-test-double-quotes (function)
csv-test-embedded-commas (function)
csv-test-embedded-lines (function)
csv-test-empty (function)
csv-test-empty-1 (function)
csv-test-other-delimiters (function)
csv-test-quoted (function)
csv-test-round-trip1 (function)
csv-test-round-trips (function)
csv-test-simple (function)
csv-test-space-handling (function)
csv-tests (function)
emit-field (function)
end-of-field-char-p (function)
end-of-line-char-p (function)
got-first-quote (function)
got-second-quote (function)
make-empty-field (function)
quote-char-p (function)
regular-field (function)
remove-last-n-chars (function)
skip-white-space (function)
special-char-p (function)
white-space-char-p (function)
write-csv-field (function)
write-csv-line-on-array (function)
write-csv-line-on-cons (function)
write-csv-string-safely (function)
write-protected-copy (function)

4 Packages

Packages are listed by definition order.

4.1 `csv-parser`

Source

csv-parser.lisp (file)

Use List

common-lisp

Exported Definitions

*field-separator* (special variable)
*quote-character* (special variable)
do-csv-file (macro)
map-csv-file (function)
read-csv-line (function)
write-csv-line (function)

Internal Definitions

*current-field* (special variable)
*fields* (special variable)
*num-fields* (special variable)
*spaces-gobbled* (special variable)
*state* (special variable)
add-char (function)
change-state (function)
csv-test-blank (function)
csv-test-blanks (function)
csv-test-double-quotes (function)
csv-test-embedded-commas (function)
csv-test-embedded-lines (function)
csv-test-empty (function)
csv-test-empty-1 (function)
csv-test-other-delimiters (function)
csv-test-quoted (function)
csv-test-round-trip1 (function)
csv-test-round-trips (function)
csv-test-simple (function)
csv-test-space-handling (function)
csv-tests (function)
emit-field (function)
end-of-field-char-p (function)
end-of-line-char-p (function)
got-first-quote (function)
got-second-quote (function)
make-empty-field (function)
quote-char-p (function)
regular-field (function)
remove-last-n-chars (function)
skip-white-space (function)
special-char-p (function)
white-space-char-p (function)
write-csv-field (function)
write-csv-line-on-array (function)
write-csv-line-on-cons (function)
write-csv-string-safely (function)
write-protected-copy (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *field-separator*

The character used to indicate the end of a field in a CSV file.

Package: csv-parser
Source: csv-parser.lisp (file)

Special Variable: *quote-character*

The character used to protect embedded field separators (usually commas) and whitespace within a field.

To import the *quote-character* itself, you must have it printed twice in the input stream.

Package: csv-parser
Source: csv-parser.lisp (file)

5.1.2 Macros

Macro: do-csv-file ((FIELDS NUM-FIELDS) FILE &key LIMIT SKIP-LINES EXTERNAL-FORMAT (FIELD-SEPARATOR *FIELD-SEPARATOR*) (QUOTE-CHARACTER *QUOTE-CHARACTER*)) &body BODY

Repeatedly call BODY on CSV file FILE, binding
FIELDS and NUM-FIELDS to a list containing the parsed fields, and the number of fields.
Code runs inside a block with tagname NIL, so you
may call (RETURN).

*FIELD-SEPARATOR* and *QUOTE-CHARACTER* can be bound to modify what separates fields and delimits fields.

Package: csv-parser
Source: csv-parser.lisp (file)

5.1.3 Functions

Function: map-csv-file FILE FN &key LIMIT SKIP-LINES EXTERNAL-FORMAT (FIELD-SEPARATOR *FIELD-SEPARATOR*) (QUOTE-CHARACTER *QUOTE-CHARACTER*)

Call FN (up to LIMIT times, if specified) with
a list containing the fields parsed from the CSV file FILE.

SKIP-LINES, if provided, is the number of lines to skip before starting to call FN.

*FIELD-SEPARATOR* and *QUOTE-CHARACTER* can be bound to modify what separates fields and delimits fields.

Package: csv-parser
Source: csv-parser.lisp (file)

Function: read-csv-line STREAM

Read one line form a stream containing CSV data. Returns two values; a list of strings parsed, and the number of parsed values.

Package: csv-parser
Source: csv-parser.lisp (file)

Function: write-csv-line STREAM FIELDS

Write one CSV line to STREAM, containing fields.
FIELDS is any (1d) sequence containing strings, symbols or numbers.

Try to write it as esthetically pleasing as possible,
i.e. don’t output the *quote-character* unless necessary
to protect the integrity of the data.

Package: csv-parser
Source: csv-parser.lisp (file)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *current-field*

Holds the field we are currently working on.

Package: csv-parser
Source: csv-parser.lisp (file)

Special Variable: *fields*

Holds the fields we have collected/parsed so far.

Package: csv-parser
Source: csv-parser.lisp (file)

Special Variable: *num-fields*

Package: csv-parser
Source: csv-parser.lisp (file)

Special Variable: *spaces-gobbled*

Keeps track of how many blanks have been skipped. When emitting
a field, we can trim extra right spaces, if appropriate, using this.

Package: csv-parser
Source: csv-parser.lisp (file)

Special Variable: *state*

Holds a function which knows how to handle chars based on what we’ve seen so far.

Package: csv-parser
Source: csv-parser.lisp (file)

5.2.2 Functions

Function: add-char CHAR

Package: csv-parser
Source: csv-parser.lisp (file)

Function: change-state STATE

Package: csv-parser
Source: csv-parser.lisp (file)

Function: csv-test-blank ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: csv-test-blanks ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: csv-test-double-quotes ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: csv-test-embedded-commas ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: csv-test-embedded-lines ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: csv-test-empty ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: csv-test-empty-1 ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: csv-test-other-delimiters ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: csv-test-quoted ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: csv-test-round-trip1 ROW

Package: csv-parser
Source: csv-parser.lisp (file)

Function: csv-test-round-trips ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: csv-test-simple ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: csv-test-space-handling ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: csv-tests ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: emit-field ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: end-of-field-char-p CHAR

Package: csv-parser
Source: csv-parser.lisp (file)

Function: end-of-line-char-p CHAR

Package: csv-parser
Source: csv-parser.lisp (file)

Function: got-first-quote CHAR

Package: csv-parser
Source: csv-parser.lisp (file)

Function: got-second-quote CHAR

Package: csv-parser
Source: csv-parser.lisp (file)

Function: make-empty-field ()

Package: csv-parser
Source: csv-parser.lisp (file)

Function: quote-char-p CHAR

Package: csv-parser
Source: csv-parser.lisp (file)

Function: regular-field CHAR

Package: csv-parser
Source: csv-parser.lisp (file)

Function: remove-last-n-chars N

Package: csv-parser
Source: csv-parser.lisp (file)

Function: skip-white-space CHAR

Package: csv-parser
Source: csv-parser.lisp (file)

Function: special-char-p CHAR

Package: csv-parser
Source: csv-parser.lisp (file)

Function: white-space-char-p CHAR

Package: csv-parser
Source: csv-parser.lisp (file)

Function: write-csv-field STREAM FIELD

Package: csv-parser
Source: csv-parser.lisp (file)

Function: write-csv-line-on-array STREAM FIELDS

Package: csv-parser
Source: csv-parser.lisp (file)

Function: write-csv-line-on-cons STREAM FIELDS

Package: csv-parser
Source: csv-parser.lisp (file)

Function: write-csv-string-safely STREAM STRING

Package: csv-parser
Source: csv-parser.lisp (file)

Function: write-protected-copy STREAM FIELD

Package: csv-parser
Source: csv-parser.lisp (file)

Appendix A Indexes

A.1 Concepts

Jump to:	C F L

	Index Entry	Section

C
	`csv-parser.asd`:	The csv-parser<dot>asd file
	`csv-parser/csv-parser.lisp`:	The csv-parser/csv-parser<dot>lisp file

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

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

Jump to:	C F L

A.2 Functions

Jump to:	A C D E F G M Q R S W

	Index Entry	Section

A
	`add-char`:	Internal functions

C
	`change-state`:	Internal functions
	`csv-test-blank`:	Internal functions
	`csv-test-blanks`:	Internal functions
	`csv-test-double-quotes`:	Internal functions
	`csv-test-embedded-commas`:	Internal functions
	`csv-test-embedded-lines`:	Internal functions
	`csv-test-empty`:	Internal functions
	`csv-test-empty-1`:	Internal functions
	`csv-test-other-delimiters`:	Internal functions
	`csv-test-quoted`:	Internal functions
	`csv-test-round-trip1`:	Internal functions
	`csv-test-round-trips`:	Internal functions
	`csv-test-simple`:	Internal functions
	`csv-test-space-handling`:	Internal functions
	`csv-tests`:	Internal functions

D
	`do-csv-file`:	Exported macros

E
	`emit-field`:	Internal functions
	`end-of-field-char-p`:	Internal functions
	`end-of-line-char-p`:	Internal functions

F
	`Function, add-char`:	Internal functions
	`Function, change-state`:	Internal functions
	`Function, csv-test-blank`:	Internal functions
	`Function, csv-test-blanks`:	Internal functions
	`Function, csv-test-double-quotes`:	Internal functions
	`Function, csv-test-embedded-commas`:	Internal functions
	`Function, csv-test-embedded-lines`:	Internal functions
	`Function, csv-test-empty`:	Internal functions
	`Function, csv-test-empty-1`:	Internal functions
	`Function, csv-test-other-delimiters`:	Internal functions
	`Function, csv-test-quoted`:	Internal functions
	`Function, csv-test-round-trip1`:	Internal functions
	`Function, csv-test-round-trips`:	Internal functions
	`Function, csv-test-simple`:	Internal functions
	`Function, csv-test-space-handling`:	Internal functions
	`Function, csv-tests`:	Internal functions
	`Function, emit-field`:	Internal functions
	`Function, end-of-field-char-p`:	Internal functions
	`Function, end-of-line-char-p`:	Internal functions
	`Function, got-first-quote`:	Internal functions
	`Function, got-second-quote`:	Internal functions
	`Function, make-empty-field`:	Internal functions
	`Function, map-csv-file`:	Exported functions
	`Function, quote-char-p`:	Internal functions
	`Function, read-csv-line`:	Exported functions
	`Function, regular-field`:	Internal functions
	`Function, remove-last-n-chars`:	Internal functions
	`Function, skip-white-space`:	Internal functions
	`Function, special-char-p`:	Internal functions
	`Function, white-space-char-p`:	Internal functions
	`Function, write-csv-field`:	Internal functions
	`Function, write-csv-line`:	Exported functions
	`Function, write-csv-line-on-array`:	Internal functions
	`Function, write-csv-line-on-cons`:	Internal functions
	`Function, write-csv-string-safely`:	Internal functions
	`Function, write-protected-copy`:	Internal functions

G
	`got-first-quote`:	Internal functions
	`got-second-quote`:	Internal functions

M
	`Macro, do-csv-file`:	Exported macros
	`make-empty-field`:	Internal functions
	`map-csv-file`:	Exported functions

Q
	`quote-char-p`:	Internal functions

R
	`read-csv-line`:	Exported functions
	`regular-field`:	Internal functions
	`remove-last-n-chars`:	Internal functions

S
	`skip-white-space`:	Internal functions
	`special-char-p`:	Internal functions

W
	`white-space-char-p`:	Internal functions
	`write-csv-field`:	Internal functions
	`write-csv-line`:	Exported functions
	`write-csv-line-on-array`:	Internal functions
	`write-csv-line-on-cons`:	Internal functions
	`write-csv-string-safely`:	Internal functions
	`write-protected-copy`:	Internal functions

Jump to:	A C D E F G M Q R S W

A.3 Variables

Jump to:	* S

	Index Entry	Section

*
	`current-field`:	Internal special variables
	`field-separator`:	Exported special variables
	`fields`:	Internal special variables
	`num-fields`:	Internal special variables
	`quote-character`:	Exported special variables
	`spaces-gobbled`:	Internal special variables
	`state`:	Internal special variables

S
	`Special Variable, current-field`:	Internal special variables
	`Special Variable, field-separator`:	Exported special variables
	`Special Variable, fields`:	Internal special variables
	`Special Variable, num-fields`:	Internal special variables
	`Special Variable, quote-character`:	Exported special variables
	`Special Variable, spaces-gobbled`:	Internal special variables
	`Special Variable, state`:	Internal special variables

Jump to:	* S

A.4 Data types

Jump to:	C P S

	Index Entry	Section

C
	`csv-parser`:	The csv-parser system
	`csv-parser`:	The csv-parser package

P
	`Package, csv-parser`:	The csv-parser package

S
	`System, csv-parser`:	The csv-parser system

Jump to:	C P S

• Introduction:		What csv-parser is all about
• Systems:		The systems documentation
• Files:		The files documentation
• Packages:		The packages documentation
• Definitions:		The symbols documentation
• Indexes:		Concepts, functions, variables and data types

• Concept index:
• Function index:
• Variable index:
• Data type index:

• The csv-parser.asd file:
• The csv-parser/csv-parser.lisp file:

• Exported special variables:
• Exported macros:
• Exported functions:

The csv-parser Reference Manual

Table of Contents

The csv-parser Reference Manual

1 Introduction

2 Systems

2.1 csv-parser

3 Files

3.1 Lisp

3.1.1 csv-parser.asd

3.1.2 csv-parser/csv-parser.lisp

4 Packages

4.1 csv-parser

5 Definitions

5.1 Exported definitions

5.1.1 Special variables

5.1.2 Macros

5.1.3 Functions

5.2 Internal definitions

5.2.1 Special variables

5.2.2 Functions

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types

2.1 `csv-parser`

3.1.1 `csv-parser.asd`

3.1.2 `csv-parser/csv-parser.lisp`

4.1 `csv-parser`