std/data/csv

Standard Library documentation

CSV/TSV and delimited text data handling.

Back to Stdlib View Source

Module

Name
std/data/csv
Area
Standard Library
Source
modules/std/data/csv.zzm

NAME

std/data/csv - CSV/TSV and delimited text data handling.

SYNOPSIS

  from std/data/csv import CSV;
  from std/io import Path;

  let csv := new CSV(
    headers: true,
    sep_char: ",",
  );

  let rows := csv.load( Path.tempfile() );

  let reader := csv.open( new Path("people.csv") );
  for ( let row in reader ) {
    say( row{name} );
  }

  let writer := csv.open_writer( new Path("people-out.csv") );
  writer.write_header( [ "name", "age" ] );
  writer.write_row( { name: "Ada", age: 32 } );
  writer.close();

IMPLEMENTATION SUPPORT

This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and Electron. It is partially supported by zuzu-js in the browser: in-memory CSV encode/decode coverage passes, but file-backed load/dump coverage is unsupported because browser filesystem capability is unavailable.

DESCRIPTION

This module provides CSV-style parsing and writing backed by the runtime. Its options are designed so the same API can also handle TSV and other character-delimited formats.

EXPORTS

Classes

  • CSV

    Constructor options include: sep_char, quote_char, escape_char, eol, binary, always_quote, allow_whitespace, blank_is_undef, empty_is_undef, quote_empty, quote_space, quote_null, verbatim, headers, columns, encoding, append, skip_empty_rows, comment_char, skip_lines, trim_headers, lowercase_headers, rename_headers, duplicate_headers, ragged, fill_value, types, parsers, formatters, defaults, required_columns, unknown_columns, and on_error.

    Instance methods:

    • csv.decode(text)

      Parameters: text is delimited text. Returns: Array. Parses a whole string into rows, returning Dict rows when headers are enabled.

    • csv.decode_binarystring(bytes)

      Parameters: bytes is UTF-8 delimited text as BinaryString. Returns: Array. Parses a whole byte string into rows.

    • csv.decode_report(text)

      Parameters: text is delimited text. Returns: Dict. Decodes while collecting parse errors in rows and errors.

    • csv.decode_report_binarystring(bytes)

      Parameters: bytes is UTF-8 delimited text as BinaryString. Returns: Dict. Decodes while collecting parse errors in rows and errors.

    • csv.encode(rows)

      Parameters: rows is an array of row values. Returns: String. Encodes rows into a delimited text string.

    • csv.encode_binarystring(rows)

      Parameters: rows is an array of row values. Returns: BinaryString. Encodes rows into UTF-8 delimited text bytes.

    • csv.encode_row(row)

      Parameters: row is an array, dictionary, or row-like value. Returns: String. Encodes a single row as delimited text.

    • csv.encode_row_binarystring(row)

      Parameters: row is an array, dictionary, or row-like value. Returns: BinaryString. Encodes a single row as UTF-8 delimited text bytes.

    • csv.load(path)

      Parameters: path is a std/io Path. Returns: Array. Reads and parses a full delimited file.

    • csv.load_report(path)

      Parameters: path is a std/io Path. Returns: Dict. Loads a file while collecting parse errors in rows and errors.

    • csv.dump(path, rows)

      Parameters: path is a std/io Path and rows is an array of row values. Returns: null. Writes rows to a delimited file.

    • csv.open(path)

      Parameters: path is a std/io Path. Returns: CSVReader. Opens a streaming reader.

    • csv.open_writer(path, options?)

      Parameters: path is a std/io Path and options overrides writer settings. Returns: CSVWriter. Opens a streaming writer.

    • csv.sniff(text_or_path)

      Parameters: text_or_path is delimited text or a Path. Returns: Dict. Guesses delimiter and likely header presence.

    • csv.sniff_binarystring(bytes)

      Parameters: bytes is UTF-8 delimited text as BinaryString. Returns: Dict. Guesses delimiter and likely header presence.

    • csv.transpose(rows)

      Parameters: rows is an array of arrays. Returns: Array. Transposes a table represented as nested arrays.

    • dump_table(path, dbh, table, options?)

      Parameters: path is output path, dbh is a database handle, table is a table name, and options controls export. Returns: null. Exports a database table to a delimited file.

    • dump_query(path, dbh, sql, bind?, options?)

      Parameters: path is output path, dbh is a database handle, sql is SQL text, bind contains bind values, and options controls export. Returns: null. Exports query results to a delimited file.

    • load_table(path, dbh, table, options?)

      Parameters: path is input path, dbh is a database handle, table is a table name, and options controls import. Returns: Dict. Imports a delimited file into a database table.

  • CSVReader

    Streaming reader returned by CSV.open.

    Methods:

    • reader.next_array()

      Parameters: none. Returns: Array or null. Reads the next row as an array.

    • reader.next_dict()

      Parameters: none. Returns: Dict or null. Reads the next row as a dictionary using configured columns.

    • reader.next()

      Parameters: none. Returns: Array, Dict, or null. Reads the next row using the reader's configured row shape.

    • reader.all_array()

      Parameters: none. Returns: Array. Reads all remaining rows as arrays.

    • reader.all_dict()

      Parameters: none. Returns: Array. Reads all remaining rows as dictionaries.

    • reader.headers()

      Parameters: none. Returns: Array or null. Returns the detected or configured header row.

    • reader.columns()

      Parameters: none. Returns: Array or null. Returns the current column names.

    • reader.set_columns(columns)

      Parameters: columns is an array of column names. Returns: CSVReader. Replaces the reader's column names.

    • reader.row_number()

      Parameters: none. Returns: Number. Returns the number of rows read from the stream.

    • reader.skip_lines(count)

      Parameters: count is a number of input lines. Returns: CSVReader. Skips raw input lines before further parsing.

    • reader.errors()

      Parameters: none. Returns: Array. Returns parse errors collected by the reader.

    • reader.close()

      Parameters: none. Returns: null. Closes the reader.

    • reader.to_Iterator()

      Parameters: none. Returns: Function. Returns an iterator suitable for for loops.

  • CSVWriter

    Streaming writer returned by CSV.open_writer.

    Methods:

    • writer.write_header(columns?)

      Parameters: columns is an optional array of column names. Returns: CSVWriter. Writes a header row.

    • writer.write_row(row)

      Parameters: row is an array, dictionary, or row-like value. Returns: CSVWriter. Writes one row.

    • writer.print_row(row)

      Parameters: row is an array, dictionary, or row-like value. Returns: CSVWriter. Alias for writing one row.

    • writer.columns()

      Parameters: none. Returns: Array or null. Returns the configured writer columns.

    • writer.row_number()

      Parameters: none. Returns: Number. Returns the number of rows written.

    • writer.close()

      Parameters: none. Returns: null. Closes the writer.

COPYRIGHT AND LICENCE

std/data/csv is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.