Standard library · Encoding and data

encoding.csv

Reading and writing CSV files, with correct quoting and conversion to a dynamic value.

import encoding.csv

CSV is the simplest table format: one row per line, fields separated by commas. A field containing a comma, a quote or a line break is wrapped in quotes, and a quote inside it is doubled (RFC 4180). This package reads and writes that format, one row at a time with ReadLine and WriteLine or a whole text with ReadAll and WriteAll, and converts it to and from a Value for encoding.json. The ...With variants take a CSVOptions for another separator, such as ; or a tab.

The readers are throws: broken input stops with a core Error of kind Syntax that carries the line and column, never with a quietly shortened row. Call them with try, or inside a try: block. The writers cannot fail.

Every field is a string; CSV has no numbers or booleans. For spreadsheets with several sheets, formulas or types, see excel; for CSV that feeds a machine learning model, data.

The things people get wrong:

  • The default separator is a comma. A file from a European Excel with ; between fields, or a tab-separated file, reads as one field per line until you pass CSVOptions { separator = ";" } (or "\t") to ReadAllWith.
  • A quoted field must be followed directly by the separator or the end of the line. "Pen" ,blue is an error with the code csv.text_after_quote, pointing at the space; a quote inside an unquoted field (5'11") is csv.bare_quote, and a quote that is never closed is csv.unterminated_quote.
  • A quoted field may hold line breaks, and ReadAll keeps them, so the error line is the line in the file, not the row number. ReadLine reads exactly one row and refuses a second one (csv.multiple_rows).
  • ToValue refuses a header with the same column name twice (csv.duplicate_header), because the second column would overwrite the first.
  • FromValue takes the columns from the keys of the first object, in the order they were added, so a table read with ToValue is written back with its columns in the original order.

Guide: totals from a CSV export

The typical job is a spreadsheet export: read every row, skip the header, convert the number columns and add them up. ReadAll gives a CSVTable whose rows each hold a fields vector, one string per column. A HashMap keeps the totals and a Vector keeps the cities in the order they first appeared.

encoding-csv-guide-report.salam
import encoding.csv

func main throws:
    text := `date,city,product,amount
2026-10-01,Tehran,tea,120
2026-10-01,Shiraz,coffee,90
2026-10-02,Tehran,coffee,75
2026-10-02,Tabriz,tea,40
2026-10-03,Shiraz,tea,60
`
    mut table := try csv.ReadAll(text)
    mut cities := Vector {} as Vector<str>
    mut totals := HashMap {} as HashMap<str, int>
    mut grand := 0
    each i, row in table.rows:
        if i == 0 or row.fields.Len() < 4:
            continue
        end
        city := row.fields.Get(1)
        amount := row.fields.Get(3).ToInt()
        if not totals.Has(city):
            cities.Push(city)
        end
        totals.Put(city, totals.GetOr(city, 0) + amount)
        grand += amount
    end
    each c in cities:
        println c, totals.Get(c)
    end
    println "total", grand
    csv.FreeTable(table)
end
OutputTehran 195 Shiraz 150 Tabriz 40 total 385

Guard against short rows, as the row.fields.len() < 4 check does: a blank line or a hand-edited file can have fewer columns than the header. Free the table with FreeTable when you are done.

Guide: write a CSV file

WriteLine joins one row and adds quotes only where they are needed: around a field with a comma, a quote or a line break, with inner quotes doubled. That is what Excel, LibreOffice and most import tools expect, and writing the rows yourself keeps the columns in the order you choose.

encoding-csv-guide-export.salam
import encoding.csv

struct Contact:
    pub name: str = ""
    pub company: str = ""
    pub note: str = ""
end

func main throws:
    mut people := Vector {} as Vector<Contact>
    people.Push(Contact { name = "Sara Ahmadi", company = "Nik, Ltd.", note = "prefers email" })
    people.Push(Contact { name = "Reza", company = "Pars", note = `said "call me Monday"` })

    mut out := ""
    mut header := Vector {} as Vector<str>
    header.Push("name")
    header.Push("company")
    header.Push("note")
    out = out + csv.WriteLine(header) + "\n"
    each p in people:
        mut f := Vector {} as Vector<str>
        f.Push(p.name)
        f.Push(p.company)
        f.Push(p.note)
        out = out + csv.WriteLine(f) + "\n"
    end
    print out

    row := try csv.ReadLine(`Reza,Pars,"said ""call me Monday"""`)
    println "read back:", row.Get(2)
end
Outputname,company,note Sara Ahmadi,"Nik, Ltd.",prefers email Reza,Pars,"said ""call me Monday""" read back: said "call me Monday"

Write the header row the same way as the data rows. WriteLine does not add the line break, so add "\n" yourself, or "\r\n" for tools that insist on it. To save the result, write out with fs.

Guide: CSV to JSON

ToValue uses the header row as keys and turns every other row into an object, which encoding.json can then print. That is a small CSV to JSON converter in a few lines. FromValue goes back from an array of objects to CSV text.

encoding-csv-guide-json.salam
import encoding.csv
import encoding.json
import encoding.value

func main throws:
    text := "sku,title,stock\nBK-01,Notebook,12\nPN-07,\"Pen, blue\",0\n"
    rows := try csv.ToValue(text)
    println value.ArrayLen(rows), "rows"
    opts := json.JSONOptions { indent = "  ", sort_keys = true }
    println json.Encode(rows, opts)

    first := value.ArrayGet(rows, 0)
    println "stock is a string:", value.IsString(value.ObjectGet(first, "stock"))
end
Output2 rows [ { "sku": "BK-01", "stock": "12", "title": "Notebook" }, { "sku": "PN-07", "stock": "0", "title": "Pen, blue" } ] stock is a string: true

Every field stays a string, even 12, because CSV has no types. Convert the columns you know are numbers with to_int() or to_float(). With CSVOptions { header = false }, ToValueWith reads a file without a header: every row, the first one included, becomes an object with the keys col0, col1 and so on.

Guide: edge cases

The reader keeps fields exactly as they are written, and stops at the first thing it cannot read without guessing. show catches the error so the program can go on with the next line:

encoding-csv-guide-pitfalls.salam
import encoding.csv

func show(line: str):
    try:
        f := csv.ReadLine(line)
        mut s := ""
        each x in f:
            s = s + "[" + x + "]"
        end
        println f.Len(), "fields:", s
    catch e:
        println "error:", e.ToStr(), e.code
    end
end

func main throws:
    show("a,b,c")
    show("a,,c")
    show(" a , b ")
    show(`"x,y",z`)
    show(`"she said ""hi""",ok`)
    show("trailing,")
    show(`"Pen" ,blue,3`)
    show(`5'11",Ali`)
    show(`"never closed,x`)
    show("sku;title;stock")

    semi := try csv.ReadLineWith("sku;title;stock", csv.CSVOptions { separator = ";" })
    println "with a ';' separator:", semi.Len(), "fields"

    mut t := try csv.ReadAll("id,note\r\n1,\"line one\r\nline two\"\r\n\r\n2,plain\r\n")
    println "rows:", t.rows.Len(), "| note 1 has", t.rows.Get(1).fields.Get(1).Len(), "bytes"
    csv.FreeTable(t)
end
Output3 fields: [a][b][c] 3 fields: [a][][c] 2 fields: [ a ][ b ] 2 fields: [x,y][z] 2 fields: [she said "hi"][ok] 2 fields: [trailing][] error: csv: unexpected text after a closing quote; expected ',' or a line break (line 1, column 6) csv.text_after_quote error: csv: a quote inside an unquoted field; quote the whole field and double the quote (line 1, column 5) csv.bare_quote error: csv: unterminated quoted field (line 1, column 1) csv.unterminated_quote 1 fields: [sku;title;stock] with a ';' separator: 3 fields rows: 3 | note 1 has 18 bytes
  • An empty field, including one after a trailing comma, is an empty string, not a missing column.
  • Spaces around a field are kept; trim them with str.Trim if your source pads columns.
  • Windows line endings (\r\n) are handled by every reader; a line break inside quotes is kept byte for byte.
  • ReadAll skips blank lines, so a table never has empty rows; CSVOptions { keep_blank = true } keeps them as rows with one empty field, which matters when row numbers must match the file.
  • A space between a closing quote and the comma is an error, not a silent cut: the message gives the line and column of the space.
  • A line with semicolons is one field with the default options; pass separator = ";" to split it.
  • The error's line and column count from 1 in the text you passed, and code names the problem, so a program can report orders.csv:14:7 or skip the file.

Types

CSVRow

struct CSVRow
One row.
NameTypeDescription
fieldsVectorThe row's fields.
encoding-csv-Table.salam
import encoding.csv
import encoding.value

func main throws:
    text := "name,city\nAli,Tehran\n\"Sara, engineer\",\"Shiraz\"\n"
    mut table := try csv.ReadAll(text)
    println table.rows.Len()
    each row in table.rows:
        println row.fields.Len(), row.fields[0]
    end
    println csv.WriteAll(table)
    csv.FreeTable(table)
    println try csv.ReadLine(`a,"b,c",d`)
    mut fields := Vector {} as Vector<str>
    fields.Push("plain")
    fields.Push(`with "quotes"`)
    println csv.WriteLine(fields)
    v := try csv.ToValue("name,age\nAli,30\n")
    println value.ArrayLen(v), value.AsString(value.ObjectGet(value.ArrayGet(v, 0), "name"))
    println csv.FromValue(v)
    opts := csv.CSVOptions { header = false }
    rows := try csv.ToValueWith("1,2\n3,4\n", opts)
    println value.ArrayLen(rows), csv.FromValueWith(rows, opts)
    semi := csv.CSVOptions { separator = ";" }
    mut eu := try csv.ReadAllWith("name;price\n\"Tea; green\";2,50\n", semi)
    println eu.rows.Get(1).fields, csv.WriteLineWith(eu.rows.Get(1).fields, semi)
    println csv.WriteAllWith(eu, csv.CSVOptions { separator = "\t" }).Len()
    csv.FreeTable(eu)
    blank := try csv.ReadAllWith("a\n\nb\n", csv.CSVOptions { keep_blank = true })
    println blank.rows.Len(), try csv.ReadLineWith("x|y", csv.CSVOptions { separator = "|" })
    try:
        csv.ReadAll("id,note\n1,\"open\n")
    catch e:
        println e.ToStr(), e.code
    end
end
Output3 2 name 2 Ali 2 Sara, engineer name,city Ali,Tehran "Sara, engineer",Shiraz ["a", "b,c", "d"] plain,"with ""quotes""" 1 Ali name,age Ali,30 2 1,2 3,4 ["Tea; green", "2,50"] "Tea; green";2,50 27 3 ["x", "y"] csv: unterminated quoted field (line 2, column 3) csv.unterminated_quote

CSVTable

struct CSVTable
A table.
NameTypeDescription
rowsVectorThe rows, including the header row; blank lines are not included.

The example for this item is shown with the ones above: encoding-csv-Table.salam

CSVOptions

struct CSVOptions
The options for the ...With functions: header row, separator and blank lines.
NameTypeDescription
headerbool = trueThe first row is a header; true by default. When false, every row becomes an object with the keys col0, col1 and so on, and FromValueWith writes no header row.
separatorstr = ","The field separator, one character; "," by default. ";" and "\t" are common. A quote, a line break or more than one character makes the readers throw csv.bad_separator; the writers use a comma instead.
keep_blankbool = falseKeep blank lines as rows with one empty field; false by default, so blank lines are skipped.

The example for this item is shown with the ones above: encoding-csv-Table.salam

Functions

ReadAllWith

func ReadAllWith(text: str, opts: CSVOptions): Throws<CSVTable>
Like ReadAll, with the separator and blank line handling from the options.

The example for this item is shown with the ones above: encoding-csv-Table.salam

ReadAll

func ReadAll(text: str): Throws<CSVTable>
Turns a whole piece of CSV text into a table. Both \n and \r\n line ends work, quoted fields may hold line breaks and blank lines are skipped. Throws a Syntax error with the line and column on an unterminated quote, text after a closing quote or a bare quote. Free the result with FreeTable.

The example for this item is shown with the ones above: encoding-csv-Table.salam

FreeTable

func FreeTable(t &: CSVTable)
Releases the table's memory.

The example for this item is shown with the ones above: encoding-csv-Table.salam

WriteAllWith

func WriteAllWith(table: CSVTable, opts: CSVOptions): str
Like WriteAll, with the separator from the options.

The example for this item is shown with the ones above: encoding-csv-Table.salam

WriteAll

func WriteAll(table: CSVTable): str
Turns a table into CSV text, with \r\n between rows and no line break after the last one.

The example for this item is shown with the ones above: encoding-csv-Table.salam

ToValueWith

func ToValueWith(text: str, opts: CSVOptions): Throws<value.Value>
Turns CSV into a Value with the given options. Throws like ReadAllWith, and with csv.duplicate_header when a header name repeats.

The example for this item is shown with the ones above: encoding-csv-Table.salam

ToValue

func ToValue(text: str): Throws<value.Value>
Turns CSV with a header into an array of objects, one per data row, with every value a string. Throws on text it cannot read and on a repeated header name.

The example for this item is shown with the ones above: encoding-csv-Table.salam

FromValueWith

func FromValueWith(v: value.Value, opts: CSVOptions): str
Turns an array of objects into CSV with the given options. The columns are the keys of the first object, in no fixed order.

The example for this item is shown with the ones above: encoding-csv-Table.salam

FromValue

func FromValue(v: value.Value): str
Turns an array of objects into CSV with a header row. The column order is not fixed; use WriteLine when it matters.

The example for this item is shown with the ones above: encoding-csv-Table.salam

ReadLineWith

func ReadLineWith(line: str, opts: CSVOptions): Throws<Vector<str>>
Like ReadLine, with the separator from the options.

The example for this item is shown with the ones above: encoding-csv-Table.salam

ReadLine

func ReadLine(line: str): Throws<Vector<str>>
Splits one CSV row into its fields, undoing quotes and doubled quotes. Spaces are kept and one trailing line break is ignored. Throws a Syntax error for broken quoting, and csv.multiple_rows when the text holds a second row.

The example for this item is shown with the ones above: encoding-csv-Table.salam

WriteLineWith

func WriteLineWith(fields: Vector<str>, opts: CSVOptions): str
Like WriteLine, with the separator from the options; a field that contains the separator is quoted.

The example for this item is shown with the ones above: encoding-csv-Table.salam

WriteLine

func WriteLine(fields: Vector<str>): str
Turns fields into one CSV line, quoting wherever it has to.

The example for this item is shown with the ones above: encoding-csv-Table.salam