@eryx/data/csv Module

CSV reading and writing utilities.

Summary

Functions

csv.parse(input: string, opts: ParseOptions?) → { { string } }
csv.generate(rows: { { string } }, opts: GenerateOptions?) → string
csv.parseDict(input: string, opts: DictParseOptions?) → ({ { [string]: string } }, { string })
csv.generateDict(rows: { { [string]: string } }, fieldnames: { string }, opts: DictGenerateOptions?) → string
csv.registerDialect(name: string, dialect: Dialect) → ()
csv.getDialect(name: string) → Dialect?
csv.unregisterDialect(name: string) → ()
csv.listDialects() → { string }
csv.sniff(input: string, candidates: { string }?) → SniffResult

API Reference

Functions

csv.parse

Parse a CSV/TSV string into a list of rows. Each row is a list of string field values. Automatically strips a leading UTF-8 BOM and normalises all line-ending styles.

csv.parse(input: string, opts: ParseOptions?) → { { string } }

Parameters

input: string

-- The raw CSV text to parse.

opts: ParseOptions?

-- Parsing options. See ParseOptions for available fields.

Returns

{ { string } }

The parsed rows.

csv.generate

Serialize a list of rows into a CSV/TSV string. A line terminator is appended after every row, including the last

csv.generate(rows: { { string } }, opts: GenerateOptions?) → string

Parameters

rows: { { string } }

-- List of rows, where each row is a list of string field values.

opts: GenerateOptions?

-- Generation options. See GenerateOptions for available fields.

Returns

string

The serialized CSV text.

csv.parseDict

Parse CSV input and return each row as a dictionary keyed by field name. Field names come from the first data row unless opts.columns is set, in which case the first row is treated as data. Missing fields are filled with restval; extra fields beyond the header are discarded.

csv.parseDict(input: string, opts: DictParseOptions?) → ({ { [string]: string } }, { string })

Parameters

input: string

-- The raw CSV text to parse.

opts: DictParseOptions?

-- Parsing options. See DictParseOptions for available fields.

Returns

{ { [string]: string } }

The parsed rows as dictionaries.

{ string }

The resolved field names.

csv.generateDict

Serialize dictionary rows into CSV, optionally prepending a header row built from fieldnames. Each row is a table keyed by field name.

csv.generateDict(rows: { { [string]: string } }, fieldnames: { string }, opts: DictGenerateOptions?) → string

Parameters

rows: { { [string]: string } }

-- List of dictionary rows to serialize.

fieldnames: { string }

-- Ordered column names that control output column order.

opts: DictGenerateOptions?

-- Generation options. See DictGenerateOptions for available fields.

Returns

string

The serialized CSV text.

csv.registerDialect

Register (or overwrite) a named dialect.

csv.registerDialect(name: string, dialect: Dialect) → ()

Parameters

name: string

-- The dialect name to register under.

dialect: Dialect

-- The dialect definition.

csv.getDialect

Retrieve a named dialect table, or nil if not registered.

csv.getDialect(name: string) → Dialect?

Parameters

name: string

-- The dialect name to look up.

Returns

Dialect?

Dialect?

csv.unregisterDialect

Remove a named dialect. No-op if the name is not registered.

csv.unregisterDialect(name: string) → ()

Parameters

name: string

-- The dialect name to remove.

csv.listDialects

Return a sorted list of all registered dialect names.

csv.listDialects() → { string }

Returns

{ string }

{ string }

csv.sniff

Examine the first 20 non-empty lines of input and return a best-guess dialect. The heuristic prefers the delimiter that produces a consistent column count across all sample lines, breaking ties by column count.

csv.sniff(input: string, candidates: { string }?) → SniffResult

Parameters

input: string

-- The raw CSV text to analyse.

candidates: { string }?

-- Delimiter characters to consider. Defaults to { ",", "\t", "|", ";", ":" }.

Returns

SniffResult

SniffResult

Types

Dialect

Core format description shared between parsing and generation. Dialect presets contain only these fields -- parse- and generate-specific options live on their respective option types.

type Dialect = { delimiter: string?, quotechar: string?, escapechar: string?, doublequote: boolean?, quoting: number?, lineterminator: string? }
delimiter: string?

Field separator (single byte). Default ",".

quotechar: string?

Character used to quote fields (single byte). Default '"'.

escapechar: string?

Character used to escape special characters (single byte). Default nil (disabled).

doublequote: boolean?

Whether a quote character inside a quoted field is escaped by doubling it. Default true.

quoting: number?

One of the csv.QUOTE_* constants controlling quoting behaviour. Default QUOTE_MINIMAL.

lineterminator: string?

String appended after each row during generation. Default "\r\n".

ParseOptions

Options for csv.parse

type ParseOptions = { dialect: (string | Dialect)?, skipinitialspace: boolean?, strict: boolean?, comment: string?, trimfields: boolean?, maxfieldsize: number?, skipblanklines: boolean? }
dialect: (string | Dialect)?

Base dialect -- a registered name or an inline Dialect table.

skipinitialspace: boolean?

Skip whitespace immediately following the delimiter. Default false.

strict: boolean?

Error on malformed input (bare quotes, unterminated fields, etc.). Default false.

comment: string?

Single-byte prefix that marks an entire line as a comment. Default nil (disabled).

trimfields: boolean?

Trim leading/trailing whitespace from unquoted fields. Default false.

maxfieldsize: number?

Maximum number of characters allowed per field. Default nil (unlimited).

skipblanklines: boolean?

Discard rows that consist of a single empty field. Default false.

GenerateOptions

Options for csv.generate

type GenerateOptions = { dialect: (string | Dialect)? }
dialect: (string | Dialect)?

Base dialect -- a registered name or an inline Dialect table.

DictParseOptions

Additional options for csv.parseDict, on top of ParseOptions.

type DictParseOptions = ParseOptions & { columns: { string }?, restval: string? }
Implements: ParseOptions
columns: { string }?

Explicit column names. When set, the first row is treated as data, not a header.

restval: string?

Value used for missing fields when a row is shorter than the header. Default "".

DictGenerateOptions

Additional options for csv.generateDict, on top of GenerateOptions.

type DictGenerateOptions = GenerateOptions & { restval: string?, writeheader: boolean? }
Implements: GenerateOptions
restval: string?

Value used for missing keys when a dict row lacks a field name. Default "".

writeheader: boolean?

Whether to emit a header row from the field names. Default true.

SniffResult

Result returned by csv.sniff.

type SniffResult = { delimiter: string, quotechar: string?, doublequote: boolean? }
delimiter: string

The best-guess field delimiter.

quotechar: string?

The detected quote character, or nil if none was found.

doublequote: boolean?

Whether doubled-quote escaping is assumed.

Constants