CSV

Parse CSV text into raw records without decoding them.

expect CSV.parse_records("a,\"b,c\"\n") == Ok([["a".to_utf8(), "b,c".to_utf8()]])

A parser for a whole CSV file, for use inside larger parsers.

It reads records until its input ends, so it consumes all of it or fails with the offset of the malformed field. It accepts any bytes.

Split off the first record as column names.

Names are decoded lossily and kept verbatim. Empty input gives no names and no rows.

expect {
    records = CSV.parse_records("name,age\nAda,36\n")?
    CSV.split_header(records) == { header: ["name", "age"], rows: [["Ada".to_utf8(), "36".to_utf8()]] }
}

Parse CSV text and decode every record with a hand-built record parser.

Fails with InvalidCsv(error) at the first problem: text that is not valid CSV, a field that does not decode, a record with too few fields, or a record with fields the parser did not read.

user : Parser(CSV.Record, { name : Str, age : U64 })
user = CSV.record(|name| |age| { name, age }).keep(CSV.field(CSV.string)).keep(CSV.field(CSV.u64))

expect CSV.parse_with(user, "Ada,36\nAlan,41\n") == Ok([{ name: "Ada", age: 36 }, { name: "Alan", age: 41 }])

Decode already parsed records with a hand-built record parser.

Errors are as for CSV.parse_with, numbered from the first record given, with line and column set to 0.

Start a record parser with a curried constructor for the desired value.

Add one .keep(CSV.field(...)) per column, in column order:

Name : { first : Str, last : Str }

name : Parser(CSV.Record, Name)
name = CSV.record(|first| |last| { first, last }).keep(CSV.field(CSV.string)).keep(CSV.field(CSV.string))

expect CSV.parse_with(name, "Ada,Lovelace") == Ok([{ first: "Ada", last: "Lovelace" }])

Consume the next field of a CSV.Record using a parser for its bytes.

The field parser must consume the whole field. Fails when the record has no fields left.

Parse one field as a valid UTF-8 string, kept verbatim (no trimming).

Parse one field as an unsigned 64-bit integer.

The field must be ASCII decimal digits with an optional leading +, and fit in a U64 (the grammar of Rust's u64::from_str). Whitespace, underscores, signs other than + and 0x-style prefixes are rejected.

Parse one field as a 64-bit floating-point number.

The field is an optional sign followed by inf, infinity or nan in any case, or by a decimal number with an optional fraction and exponent (12, 1.5, .5, 5., 1e-3, 2.5E+10); this is the grammar of Rust's f64::from_str. Magnitudes too large for an F64 become infinity and too small ones become zero. Whitespace, underscores and hexadecimal forms are rejected.

Decode CSV text whose first record is a header row into rows of an inferred type, usually a record.

Each record field reads the column whose header is exactly its name; columns no field names are ignored, and when two columns share a name the last one wins. A field of type Try(a, [Missing]) is Err(Missing) when its column is absent, and a field of type Try(a, [Null]) is Err(Null) when its cell is empty. A required field with no column fails with MissingRequiredField(name), which the compiler adds to the error type.

Cells decode as Str (verbatim), Bool (true or false in any letter case), integers (ASCII digits with an optional sign, - only for signed types), Dec (an optional sign, digits and an optional fraction), F32 and F64 (as CSV.f64), and tags without payloads (the cell is the tag name). A field that is a record, a tuple or a tag with a payload fails when it is decoded; a field that is a list or a dictionary does not compile.

Blank lines are skipped. Every other record must have exactly as many fields as the header; a shorter or longer record is an error naming it.

Item : { sku : Str, count : U64, note : Try(Str, [Missing]), price : Try(Dec, [Null]) }

items : Try(List(Item), [InvalidCsv(CSV.Error), MissingRequiredField(Str)])
items = CSV.parse("price,sku,count\n1.50,A1,3\n,B2,0\n")

expect items == Ok([
    { sku: "A1", count: 3, note: Err(Missing), price: Ok(1.50) },
    { sku: "B2", count: 0, note: Err(Missing), price: Err(Null) },
])

Like CSV.parse, but header names are normalized before they are matched: surrounding spaces are removed, ASCII letters are lowercased, and runs of spaces, - and _ become one _. A column headed First Name, first-name or FIRST_NAME fills a field first_name.

names : Try(List({ first_name : Str }), [InvalidCsv(CSV.Error), MissingRequiredField(Str)])
names = CSV.parse_normalized(" First Name \nAda\n")

expect names == Ok([{ first_name: "Ada" }])

Decode CSV text without a header row into tuples, one element per column.

Every record (blank lines excepted) must have exactly as many fields as the tuple has elements. Cells decode as in CSV.parse.

pairs : Try(List((Str, U64)), [InvalidCsv(CSV.Error)])
pairs = CSV.parse_headerless("Ada,36\nAlan,41\n")

expect pairs == Ok([("Ada", 36), ("Alan", 41)])