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 passCSVOptions { separator = ";" }(or"\t") toReadAllWith. - A quoted field must be followed directly by the separator or the end of the line.
"Pen" ,blueis an error with the codecsv.text_after_quote, pointing at the space; a quote inside an unquoted field (5'11") iscsv.bare_quote, and a quote that is never closed iscsv.unterminated_quote. - A quoted field may hold line breaks, and
ReadAllkeeps them, so the error line is the line in the file, not the row number.ReadLinereads exactly one row and refuses a second one (csv.multiple_rows). ToValuerefuses a header with the same column name twice (csv.duplicate_header), because the second column would overwrite the first.FromValuetakes the columns from the keys of the first object, in the order they were added, so a table read withToValueis 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.
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)
endGuard 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.
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)
endWrite 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.
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"))
endEvery 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:
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- 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.Trimif your source pads columns. - Windows line endings (
\r\n) are handled by every reader; a line break inside quotes is kept byte for byte. ReadAllskips 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
lineandcolumncount from 1 in the text you passed, andcodenames the problem, so a program can reportorders.csv:14:7or skip the file.
Types
CSVRow
struct CSVRow| Name | Type | Description |
|---|---|---|
fields | Vector | The row's fields. |
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
endCSVTable
struct CSVTable| Name | Type | Description |
|---|---|---|
rows | Vector | The 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...With functions: header row, separator and blank lines.| Name | Type | Description |
|---|---|---|
header | bool = true | The 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. |
separator | str = "," | 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_blank | bool = false | Keep 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>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>\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)The example for this item is shown with the ones above: encoding-csv-Table.salam
WriteAllWith
func WriteAllWith(table: CSVTable, opts: CSVOptions): strWriteAll, 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\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>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>The example for this item is shown with the ones above: encoding-csv-Table.salam
FromValueWith
func FromValueWith(v: value.Value, opts: CSVOptions): strThe example for this item is shown with the ones above: encoding-csv-Table.salam
FromValue
func FromValue(v: value.Value): strWriteLine 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>>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>>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): strWriteLine, 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>): strThe example for this item is shown with the ones above: encoding-csv-Table.salam