CSV

A file whose first line is exactly sep= followed by one ASCII character (Excel writes sep=;) takes that character as its delimiter without further detection; the line is not a record, so it is neither shown in the grid nor taken for a header, and it is kept in the file as it is. A sep= line with nothing after it names no delimiter. An Emacs mode line first (# -*- mode: csv -*-, which makes a file of any name CSV) is not a record either (csv::preamble): the commands, the filter, the sorts and the pinned header row start after either line. An Emacs Local Variables: block ending the file (its lines up to one with End:, in the last 3000 bytes) is not records (csv::body_end): the records end before it, and rows added go before it.

The dialect's CR LF flag is set when the sample contains a carriage return followed by a line feed anywhere. It decides the line ending of rows Kalem adds and of Sort File. Independently, the file layer decides the document's line ending for saving: CR LF only when every line feed in the file follows a carriage return (as Emacs chooses between dos and unix), CR when the file has carriage returns and no line feed (Emacs's mac: classic Mac OS files), otherwise LF with every carriage return kept in the text as it is. A CR file is read with each carriage return turned into a line feed and saved with each line feed turned back, so its records are lines like any other file's.

Each candidate is tried in the order , ; tab and vertical bar. For a candidate, the sample is scanned with the full scanner (so delimiters inside quotes do not count) for at most 50 records; an empty record at the very end (the line after a final line feed) is not counted. Let m be the most common number of fields among those records, counting only numbers above one (the larger number on a tie), and s the number of records with m fields. A candidate for which no record has more than one field is out. The others are compared, in this order, by

1. how many fields of those records read as malformed (below), fewer is better;
2. s, more is better; the first record takes no part of its own, so a title or metadata first line of one field does not decide the delimiter;
3. how many fields of the first twenty records read as numbers (with . or , as the decimal separator), more is better;
4. how many of those fields are not numbers and hold another candidate delimiter, fewer is better;
5. m, more is better;

and a tie on all five goes to the one tried first. When every candidate is out the delimiter is the comma.

So ürün;fiyat followed by elma;1,5 is read with ;: under , the fields ürün;fiyat and elma;1 hold a semicolon and 5 is the only number, while under ; the field 1,5 is a number. Likewise 1,5;2,5;3,5 splits at ; into three numbers.

The quote is ". It is ' only when no field of the first 50 records, read with the delimiter found for ", is quoted with ", some field is quoted with ' when the file is read with ' and the delimiter found for it, and that reading splits at least as many records into the same number of fields. So 'name','note' followed by 'Ali','a, b' is read with ', and a file where both quotes occur, or neither, keeps ". Set Quote Character chooses another by hand.

The first record is taken for a header (looks_like_header) as follows:

1. When the sample holds a single record, there is no header.
2. A value looks like a number when it reads as one as the column statistics read numbers (csv::number, below): 1,234.5, 1.234,5 and 1 234,5 do; dates, version numbers, phone numbers and integers with leading zeros do not.
3. When any value of the first record looks like a number, there is no header; but a year (1800 to 2199) beside a value that is text names a column, as in name,2024,2025.
4. Otherwise, when any value of the next twenty records looks like a number, there is a header.
5. Otherwise there is a header when every value of the first record is not blank and no two are equal.

The header matters to the grid (bold, pinned), to row moves and sorting (it stays first), to the statistics and the filter (it is not data), and to Convert to Org Table (a rule under it). First Row Is a Header sets it by hand.

The lenient reading keeps every byte, but three things are reported (csv::problems), each as a warning with a code:

In both editors the status bar shows the first problem of the record at the cursor in place of the column's numbers. kalem check reports them all for a CSV file (as FILE:LINE:COLUMN: warning[CODE]: MESSAGE, or in JSON), and --deny-warnings makes them fail; a CSV file is not checked as Org.

Records are found from the top only as far as a view asks (csv::Index): drawing the first screen of a 100,000-row file scans only its first records, and the whole file is scanned only by what needs all of it (the column operations, sorting, statistics, the filter and the conversions). The unit test large_files_open_lazily and the integration test large_files_lay_out_lazily check this.

With a filter or a sort on, the records the view shows, their order and what the filter keeps are worked out once for each version of the file, so moving the cursor reads nothing again; the status bar's numbers read the cursor's column of each record, not every field. The integration test a_large_file_at_each_keystroke_and_step times twenty steps of the cursor and a keystroke in a 100,000-row file with a filter and a sort on, against ceilings: the twenty steps take some 40 ms in a release build.

Where Kalem writes a value it produced itself (a pasted spreadsheet row, Copy as Tab-Separated Values), it encodes it with csv::encode: the value is written in quotes, with every quote doubled, when it contains the delimiter, a quote, a carriage return or a line feed, or when it starts or ends with a space or a tab. Otherwise it is written as it is.

Blanks at the ends are quoted because spreadsheets drop them otherwise; RFC 4180 permits quoting any field.

Typing in the grid inserts and deletes characters in the file at the cursor, as in plain text, with one exception: a delimiter, a quote or a line break typed inside a field belongs to the field's value (csv::typed, DocumentState::type_in_grid). In an unquoted field the field is rewritten quoted, the characters before the cursor and the typed ones inside the quotes, every quote doubled, and the cursor after what was typed; inside the quotes of a quoted field the characters are inserted with their quotes doubled. Other characters, blanks included, are inserted as they are, so a field is quoted only when it has to be. A line break goes into a value with Line Break in Cell (csv.lineBreak: Alt+Enter, as in Excel; Ctrl+J in a terminal, where Alt+Enter is Shift+Enter's), at the caret, or after the cell's text from Ready mode. With Vim's keys there are no Excel modes (below): typing in insert mode inserts at the cursor, a delimiter or a quote still going into the value. In the source view (Ctrl+/) typing is raw: a comma typed there is a delimiter. Enter inserts a line break, without copying the line's leading blanks or tabs as edit.newline does in other files (they are part of a value or empty fields), which starts a new record unless the cursor is inside quotes. The grid and the layout follow the new text at once.

The library also has a cell setter, csv::set_cell, which replaces only the field's bytes with the encoded value and pads a short record with empty fields; the round-trip tests use it to edit a cell.

The commands are in the category CSV and apply only in CSV documents (scope csv). Tab and Shift+Tab move between fields, and the keys of Org tables move, insert and delete rows and columns (Alt with the arrows, Alt+Shift with them); in the Emacs keymap, C-c ^ sorts by columns, C-c + sums the column and C-c ? names the cell, as in an Org table. The others are in the graphical editor's Table menu (rows, columns, filter, sorts and the spreadsheet habits below), on its toolbar (insert and delete row and column, Sort File, Filter Rows), in the File menu (Copy as Tab-Separated Values, Convert to Org Table, Open as Plain Text) and in the palette of both editors.

Arguments: csv.sortFile and csv.sortView take reverse (boolean); csv.filter takes text (string, required) and column (integer, from 0: the records whose value in that column is the text, an empty one too); csv.setDelimiter takes delimiter and csv.setQuote takes quote (strings, required: one ASCII character, and for the delimiter also tab, \t, space or a space; the delimiter and the quote must differ; anything else is refused with a message). The dialect set by hand lasts until the document is closed; it is not written to the file.

• Next Field goes to the next field of the record; from the last field, to the first field of the next record; from the last field of the last record, it inserts a new row (as Insert Row does) and goes to its first field, as Tab does in an Org table.
• Previous Field goes to the previous field; from the first field, to the last field of the previous record; in the first field of the first record it does nothing.
• The grid edits as Excel does, in three modes the status bar names. In Ready mode a cell is selected, framed and without a caret: typing replaces it (and enters Enter mode), Delete clears the selected cells, Backspace clears the cell and types into it, the arrows go from cell to cell (into a short record's missing cells and the empty columns too), Ctrl with them to the edge of the data, Shift with them extends the selection, Home goes to column A and Ctrl+Home and Ctrl+End to the first and the last cell. In Enter mode typing goes on after the text, and an arrow, Enter or Tab enters it and moves; Enter after a run of Tabs along a row goes to the row below in the column the Tabs started from. F2 or a double click is Edit mode: Left, Right, Home and End (and Ctrl+Home and Ctrl+End) move within the cell, Backspace and Delete delete within its value (never a delimiter or a quote), and Enter or Tab enters it. Escape, in Enter or Edit mode, puts the cell back as it was, undoing the entry's own steps, so that Undo afterwards does not bring it back. Quotes an entry put around a value (for a delimiter or a blank at an end, typed) go when a deletion leaves the value without need of them, unless the field had them in the file. Shift with Left and Right in Edit mode selects within the cell. A paste into a cell being edited goes in at the caret, its line breaks too; a paste in Ready mode leaves the cell selected, as in Excel. Each entry is an undo step of its own. The arrows and Tab skip hidden columns, and Right stops at the first empty column right of the data. The source view edits the text as text.
• With Vim's keys (DocumentState::csv_vim) the grid has no Excel modes and the status bar names none: the cursor shows in the cell, Vim's motions and operators work on the text, insert mode inserts at the cursor, and j and k (and the arrows) go to the same column of the row shown below or above, a record of several lines being one row and a filter's or a sorted view's rows those shown (csv::view_vertical; with an operator they take the text's lines).
• Cell Below (Enter) and Cell Above (Shift+Enter; Alt+Enter in a terminal) go to the same column of the next and previous record, as in a spreadsheet; Enter on the last record adds an empty one. In the source view Enter breaks the line as in any text. Up, Down and the page keys go by the rows shown too, in both editors, and stay on the first and the last row.
• A selection from a cell in one row to a cell in another covers the rows the grid shows between them (csv::rows_between): with a filter on, the rows it hides between them are not selected, and with a sorted view on, rows shown elsewhere are not either; the commands on a selection (Delete Row, Fill, Delete, Copy, Cut, Paste) change those rows alone. With cells of several rows or columns selected, Delete Row and Delete Column delete every row or column the selection covers, and typing goes into the cell the selection started from, as a spreadsheet types into the active cell; Backspace clears that cell alone and types into it; typed over a selection within one cell, the text replaces it. Enter and Shift+Enter move the active cell down and up each column of the selection, Tab and Shift+Tab along each row, wrapping at the ends, as Excel moves in a selected range: the cells stay selected (DocumentState::csv_rect), typing goes into the active cell, and Delete clears them all, until an arrow, a click or a command ends them.
• Backspace and Delete delete within a cell's value: at the start of a cell Backspace (at its end Delete) does nothing rather than delete the delimiter and merge two cells, the quotes of a quoted field stay, and a doubled quote goes as one character. A selection over more than one cell clears the cells, keeping the rows and the delimiters.
• A short record's missing cells and the empty columns right of the data can be selected (by a click, Tab, Enter, Up and Down, Shift with the arrows, or Go to Cell) without a change to the file; typing there, in any mode, adds the empty fields up to the cell, then the value.

Insert Row (csv::insert_row) inserts, right after the cursor's record (before its line ending), a line ending followed by an empty record of n fields, that is n − 1 delimiters, where n is the larger of the number of columns in the layout and the number of fields of the cursor's record. The line ending inserted is CR LF when the text after the record starts with CR LF, or when the dialect is CR LF and the record ends the text; otherwise LF. A record of one empty field (a file of one column) at the end of the text gets a line ending after it too, as a final line feed alone starts no record. The cursor goes to the same column of the new row. With cells of several rows selected, as many empty records go after the last of them (csv::insert_rows), as Excel inserts.

id,name,note          id,name,note
1,"Ada",keep          1,"Ada",keep
2,Alan,x        →     2,Alan,x
                      ,,

Delete Row (csv::delete_row_list) removes the cursor's record, or the records a selection covers, each together with its line ending. When the record is the last one and has no line ending after it, the line ending before it goes instead. The cursor goes to the same column of the row shown after them, or of the one before when there is none.

Move Row Up and Move Row Down (csv::swap_rows) exchange the bytes of the cursor's record and the one shown above or below it (with a filter on, past the rows it hides); the line endings between them stay where they are, and so does every byte inside each record. When a header was detected, the header cannot move and no row can move above it. At the first or last record the command fails with "No row to move past"; in a sorted view, which has no order of the file's to move in, it is refused.

The column operations change every record of the file, each by the smallest edit, in one transaction.

Insert Column (csv::insert_column) inserts a delimiter at the start of field c (the cursor's column) in every record that has it, which makes an empty field there. A record with fewer than c + 1 fields gets delimiters at its end until it has c + 1 fields. With cells of several columns selected, as many columns go before the first of them (csv::insert_columns).

Delete Column (csv::delete_column) removes, in every record that has field c, that field and the delimiter after it; for the last field of a record, the delimiter before it; for a record with a single field, just the field's text. Records without field c are left alone. The cursor stays in column c, or moves one left when c was the last column.

Move Column Left and Right (csv::swap_columns) exchange the bytes of fields c and its neighbour in every record that has both; other records are left alone. They fail with "No column to move past" at the first column (left) or at the last field of the cursor's record (right).

id,name,note                 Insert Column at 1:  id,,name,note
1,"Ada",keep␣␣               1,,"Ada",keep␣␣
2,Alan,x                     2,,Alan,x

Delete Column 1:  id,note    Delete Column 2:     id,name
                  1,keep␣␣                        1,"Ada"
                  2,x                             2,Alan

Move Column Right at 0:  name,id,note
                         "Ada",1,keep␣␣
                         Alan,2,x

(␣ marks a space; the fields' quoting and trailing blanks stay as they were.)

Sort File by Column (csv::sort_file) reorders the records of the file by the cursor's column; with reverse, in descending order. When a header was detected it stays first. Two values compare (csv::compare), in a total order whatever the column mixes:

1. numbers (read as the column statistics read them, below, and amounts with a percent sign after them, in hundredths, a currency symbol before or after them, or in parentheses, negative: 10%, $20, ₺5, (5)) first, two numbers by value;
2. then dates (2026-09-29, 29.09.2026, 9/29/2026, or 29/9/2026 when the first part is past 12), by date;
3. then text, letter by letter without case in the alphabet's order, Turkish's letters where the alphabet has them (ç after c, ğ after g, ı before i, ö after o, ş after s, ü after u); I lowercases to ı when the interface is in Turkish, to i otherwise. There is no other locale collation.

Each value's key is worked out once a sort. The sort is stable, a missing field compares as an empty value, and blank lines go after every other record, in their file order, in both directions (a blank line ending the file gets a line ending, so that it stays a record). The file is rewritten from its first record (a sep= line stays) to the end of its last record as the records' own bytes, unchanged, joined with the dialect's line ending; the line ending after the last record, if any, stays. So quoting inside records is kept, while line endings between records are made uniform. The cursor goes to the first data row, same column.

name,n            name,n
b,10       →      c,100       (column 0, reverse)
a,9               b,10
c,100             a,9

These commands borrow what people miss beside a spreadsheet; each is an ordinary edit of cell text (kalem_core::csv_tools), so the file keeps its dialect and every byte the command does not name.

• Fill Down copies the first row of the selection into the same column of the other rows it covers (the rows shown, with a filter or a sorted view on); without a selection, the cell shown above into the cell at the cursor (a missing cell above empties it). Fill Series continues instead: numbers by the step of the two cells above (1 when there is one, or with a selection), with as many decimals as the values write and their decimal separator (1.50, 1.75; 0.125, 0.250, 0.375; 1,5 in a file ; delimits; integers past 2^53 exact); dates by days (2026-01-31, 2026-02-01; 28.02.2026, 01.03.2026; the step of two dates above in days); text ending in a number counts on, up or down (Item 9, Item 10; 007, 008; Item 2, Item 1, Item 0). A value that cannot continue is refused with a message, as is a fill with no cell above.
• Remove Duplicate Rows deletes every data record equal, field by field after unquoting, to an earlier one, with its line ending; the header and blank lines stay, and the message counts the rows removed.
• Transpose makes rows columns, padding short rows with empty fields, and writes the records with the dialect's delimiter and line ending.
• Split Column (separator, a space when empty) splits the cursor's column into as many columns as the most parts a value has; values with fewer parts get empty fields. Join with Next Column (separator) writes the two values with the separator between them, or the one that is not empty. Both show a preview first: the first eight records as they would be, in the palette; choosing one makes the edit (the command again with confirmed), Escape leaves the file as it is.
• Edit Field (SPC m b e in Vim; no key otherwise, so that Ctrl+C copies) edits the cursor's field in a one-line editor in the palette, its value unquoted; Set Field (value, and row and column counted from 0, the cursor's when left out) writes it quoted as the dialect needs.
• Replace in Column (find, replace) replaces the text in every field of the cursor's column but the header, and says how many fields changed.
• Kill Field empties the cursor's field and copies its value (a cell past the record's end stays as it is); Yank Field writes the last copied text into it, and with nothing copied is refused.
• Paste as Block writes the clipboard over the cells from the cursor's down and to the right, as a spreadsheet pastes a range: lines of tab-separated values (what spreadsheets copy), or of the dialect's delimiter when no line has a tab; records past the last are added, short records get the fields they lack, and only the cells the block covers change (csv_tools::paste_block); with a filter or a sorted view on, the block goes down the rows shown. In the grid an ordinary paste does the same with text of several lines or with tabs, from the cursor's cell (a selection's top left one); a single value goes into the cell, quoted when it needs it (DocumentState::paste_in_grid). Paste as Plain Text inserts the text as it is; in the source view an ordinary paste goes in at the cursor, rows copied from a spreadsheet still converted to the file's delimiter (The clipboard, below).
• A click on a column's letter selects the whole column (Select Column, csv.selectColumn), one on a row's number the row (Select Row, csv.selectRow), as in a spreadsheet. The edge between two letters still drags the column's width.
• A selection from a cell in one row to a cell in another is a rectangle of cells, as in a spreadsheet: both editors paint the cells between the two corners, not the text between them. Copy (and Copy Cells) copies them as tab-separated values, a line a row, a value with a tab or a line break, or starting with a quote, in quotes, what a spreadsheet pastes as a range and what Paste as Block writes back (a single quoted cell pasted alone is unquoted); Cut (and Cut Cells) copies them and empties them, the rows and columns staying; so does a selection over cells of one row. Without a selection Copy and Cut take the cursor's cell, as in a spreadsheet. A selection within one cell stays text. In the source view a selection is always text.
• Sort File by Columns (columns) sorts by several columns in order, named by the header's name (without case), by letter or by number, with - for descending (B, -A, 2 -1 or city -age); a name of no column is refused. Values compare as Sort File by Column compares them.
• Sum Column shows the sum of the column's numbers (read as the statistics read them; the header left out; with a filter on, the rows shown) and copies it, as C-c + does in an Org table, with a decimal comma in a file ; delimits; with insert, it writes the sum of the other rows into the cell at the cursor (not on the header row).
• Cell Coordinates names the cell as a spreadsheet and as an Org table do, B3 (@3$2), with the column's header; Go to Cell (cell) takes either form, or 3,2, and refuses a cell past the last row or column.

A command that leaves the text as it was (a sorted file sorted again, a field set to its value) leaves the document unmodified and makes no undo step.

The columns the grid shows, and their widths, are view state too (csv::Columns): never written to the file, kept while the document is open. Insert, Delete and Move Column carry them, and a sorted view's column, along with their columns (csv::remap_columns); Transpose starts them again.

• Hide Column takes the cursor's column out of sight, with its delimiters; the cursor goes to the next column that shows. The last column that shows cannot be hidden. Show All Columns shows them again.
• Autosize Column makes the cursor's column as wide as its widest value (of the first ten thousand records), however long; Autosize All Columns does it for every column. Widen Column and Narrow Column change the width drawn by two characters, and Column Width (width, 2 to 500) sets it. A value longer than a width set so shows cut, its last character …, but whole in the cell at the cursor. Reset Column Widths goes back to the widths the grid chooses (the widest value of the first thousand records, at most forty characters). In the graphical editor a column's right edge in the letters bar sets its width by dragging, and fits it to its values by a double click.
• Freeze First Column keeps the first column that shows, with the row numbers, at the left edge when the rows scroll sideways, as a frozen pane in a spreadsheet; its letter stays over it in the letters bar. With it on, rows do not wrap. In the graphical editor a column is not yet widened by dragging its edge.

With Vim keys, Doom's local leader has the keys of its csv-mode (:lang data) and of Org tables: SPC m a autosizes the columns, SPC m u resets their widths, SPC m s and SPC m S sort by columns and by the cursor's column, SPC m k deletes the column, SPC m t transposes; SPC m b a, SPC m b e, SPC m b s, SPC m b i c, SPC m b i r, SPC m b d c and SPC m b d r align, edit the field, sort, and insert and delete columns and rows.