Module parsecsv

This module implements a simple high performance CSV (comma separated value) parser.

Example: How to use the parser

import os, parsecsv, streams
var s = newFileStream(paramStr(1), fmRead)
if s == nil: quit("cannot open the file" & paramStr(1))
var x: CsvParser
open(x, s, paramStr(1))
while readRow(x):
  echo "new row: "
  for val in items(x.row):
    echo "##", val, "##"
close(x)

For CSV files with a header row, the header can be read and then used as a reference for item access with rowEntry:

import parsecsv
import os
# Prepare a file
let content = """One,Two,Three,Four
1,2,3,4
10,20,30,40
100,200,300,400
"""
writeFile("temp.csv", content)

var p: CsvParser
p.open("temp.csv")
p.readHeaderRow()
while p.readRow():
  echo "new row: "
  for col in items(p.headers):
    echo "##", col, ":", p.rowEntry(col), "##"
p.close()

Imports

lexbase, streams, os, os, strutils

Types

CsvRow = seq[string]

a row in a CSV file

CsvParser = object of BaseLexer
  row*: CsvRow                 ## the current row
  filename: string
  sep, quote, esc: char
  skipWhite: bool
  currRow: int
  headers*: seq[string] ## The columns that are defined in the csv file
                      ## (read using `readHeaderRow <#readHeaderRow.CsvParser>`_).
                      ## Used with `rowEntry <#rowEntry.CsvParser.string>`_).

the parser object.

CsvError = object of IOError

exception that is raised if a parsing error occurs

Procs

proc open(my: var CsvParser; input: Stream; filename: string; separator = ',';
         quote = '\"'; escape = '\x00'; skipInitialSpace = false) {...}{.raises: [Exception],
    tags: [ReadIOEffect].}

initializes the parser with an input stream. Filename is only used for nice error messages. The parser's behaviour can be controlled by the diverse optional parameters:

• separator: character used to separate fields
• quote: Used to quote fields containing special characters like separator, quote or new-line characters. '0' disables the parsing of quotes.
• escape: removes any special meaning from the following character; '0' disables escaping; if escaping is disabled and quote is not '0', two quote characters are parsed one literal quote character.
• skipInitialSpace: If true, whitespace immediately following the separator is ignored.

proc open(my: var CsvParser; filename: string; separator = ','; quote = '\"';
         escape = '\x00'; skipInitialSpace = false) {...}{.raises: [CsvError, Exception],
    tags: [ReadIOEffect].}

same as the other open but creates the file stream for you.

proc processedRows(my: var CsvParser): int {...}{.raises: [], tags: [].}

returns number of the processed rows

proc readRow(my: var CsvParser; columns = 0): bool {...}{.raises: [CsvError, Exception],
    tags: [ReadIOEffect].}

reads the next row; if columns > 0, it expects the row to have exactly this many columns. Returns false if the end of the file has been encountered else true.

Blank lines are skipped.

proc close(my: var CsvParser) {...}{.inline, raises: [Exception], tags: [].}

closes the parser my and its associated input stream.

proc readHeaderRow(my: var CsvParser) {...}{.raises: [CsvError, Exception],
                                    tags: [ReadIOEffect].}

Reads the first row and creates a look-up table for column numbers See also rowEntry.

proc rowEntry(my: var CsvParser; entry: string): var string {...}{.raises: [], tags: [].}

Acceses a specified entry from the current row.

Assumes that readHeaderRow has already been called.