CSV Parsing and Printing

One common data encoding is the humble CSV (comma separated values) file. With East you can read and write CSV formatted blobs.

CSV decoding

Suppose you had the following data inside the variable blob:

id,name
1,Alice
2,Bob

Imagine you would like to decode that a tabular data form. CSV files contain a collection of rows, but do not necessarily have a "primary" key. East reads CSV into an array of structs. The above CSV could be decoded to the East value:

[
    (id = 1, name = "Alice"),
    (id = 2, name = "Bob"),
]

The CsvDecode function accepts a blob and returns an array of structs representing the tabular data.

East function	Description	Example usage	Result
CsvDecode	Read tabular data from a CSV file	CsvDecode(blob, { id: IntegerType, name: StringType } )	[(id = 1, name = "Alice"), (id = 2, name = "Bob")]

The second argument specifies the column names and types. The order has to match that in the CSV file header.

An optional third argument allows you to define parsers for each column. Each parser accepts a string (directly extracted from the CSV) and returns a value with the East type nominated for that column. This is particularly useful for parsing custom date and time formats.

An optional fourth argument allows for CSV parsing options, such as the delimiters or null sentinel value. Here is an example:

CsvDecode(
    blob,
    {
        id: IntegerType,
        name: StringType
        date: DateTimeType
    }
    {
        // put any custom parsers here,
        date: str => Parse(DateTime, str, 'MM-DD-YYYY'),
    },
    {
        // these are the default values
        nullString: '',
        quoteChar: '"',
        escapeChar: '"',
        delimiter: [','],
        newline: ['\r\n', '\n'], // accept either
        header: true,
    }
)

CSV encoding

You can perform the reverse operation with CsvEncode, which takes an array of structs and returns a blob.

East function	Description	Example usage	Result
CsvEncode	Write tabular data to a CSV file	CsvEncode(array_of_structs)	0x69642c6e616d650a312c416c6963650a322c426f62

Here the column names and types are known from the East type of the input.

You can specify custom printers for each column as an optional second argument. Each printer accepts a value of that column type and returns a string. This is often used for custom date and time formats.

An optional fourth argument allows for CSV parsing options, such as the delimiters or null sentinel value. Here is an example:

CsvDecode(
    blob,
    {
        id: IntegerType,
        name: StringType
    }
    {
        // put any custom printers here,
        date: datetime => Print(datetime, 'MM-DD-YYYY'),
    },
    {
        // these are the default values
        nullString: '',
        quoteChar: '"',
        escapeChar: '"',
        delimiter: ',',
        newline: '\r\n',
        header: true,
    }
)

Next steps

Continue to the next section to understand some more advanced topics for East and Elara.