# 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: TCsvParser
    open(x, s, ParamStr(1))
    while readRow(x):
      Echo "new row: "
      for val in items(x.row):
        Echo "##", val, "##"
    close(x)

# Imports

lexbase, streams, os

# Types

    TCsvRow = seq[string]

  a row in a CSV file

    TCsvParser = object of TBaseLexer
      row*: TCsvRow               ## the current row
      filename: string
      sep, quote, esc: char
      skipWhite: bool
      currRow: int

  the parser object.

    EInvalidCsv = object of EIO

  exception that is raised if a parsing error occurs

# Procs

    proc open(my: var TCsvParser; input: PStream; filename: string; separator = ',';
              quote = '\"'; escape = '\0'; skipInitialSpace = false) {.
        raises: [E_Base], tags: [FReadIO].}

  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 processedRows(my: var TCsvParser): int {.raises: [], tags: [].}

  returns number of the processed rows

    proc readRow(my: var TCsvParser; columns = 0): bool {.
        raises: [EInvalidCsv, E_Base], tags: [FReadIO].}

  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.

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

  closes the parser my and its associated input stream.

Generated: 2013-05-21 09:55:11 UTC