CSV patch format

Version:

0.2

This page describes the CSV patch format generated by "ssdiff --format-csv". This format is easier to parse than the human-readable patch format. In fact it is quite straightforward to read and write by hand too, if one is careful to produce a valid CSV file (it is important to have the same number of columns on all lines).

General structure

A file consists of a series of lines in CSV format:

cell00,cell01,cell02
cell10,cell11,cell12
cell20,cell21,cell22

Here's an actual example:

dtbl,csv,version,0.2,,,
config,empty_tag,*,,,,
config,row_tag,ROW,,,,
column,name,ROW,[0],[1],,
column,move,ROW,[1],[0],,
column,insert,ROW,[1],[0],{4},
column,insert,ROW,{3},[1],[0],{4}
column,delete,ROW,{3},[0],{4},
row,select,*,*,three,*,
row,update,*,yo,*,*,

Since the CSV format has some variability, here are some notes on the variant expected. In summary, keep to RFC4180 as closely as you can.

• If a cell begins with a double quote, the extent of the cell is determined by quoting rules. It is important to note that a cell may extend across line boundaries. The cell will extend to the next unpaired double quote in the patch. A pair of double quotes ("") found by scanning forwards through the file is interpreted as the double quote character, and not used to delimit the cell's extent. Once the extent of a cell is determined, if a double quote is present at the beginnning of that cell, it is stripped, along with the matching quote at the end.
• Otherwise, a cell extends until a comma, CR, or LF character, or the end of the file.
• An unquoted CRLF sequence is treated as a single delimiter.
• Cells should be quoted if they contain any whitespace or the comma character.

The width of the patch in cells has no significance. Extra empty columns can be added to the end of rows without affecting the interpretation of the patch.

First row

The first row contains at least four non-empty cells.

• The first cell of the first row should have the value "dtbl" (a four-character string). The representation of that value may be quoted or unquoted.
• The second cell of the first row should have the value "csv" (a three-character string). The representation of that value may be quoted or unquoted.
• The third cell of the first row should have the value "version" (a seven-character string). The representation of that value may be quoted or unquoted.
• The fourth cell of the first row may have any value non-empty value. The representation of that value may be quoted or unquoted.

This means that a CSV format patch file will begin with one of the following seqence of bytes (ascii/utf8 encoding):

• dtbl,csv,...
• "dtbl","csv",...
• "dtbl",csv,...
• dtbl,"csv"...

Here's an example of a first row:

dtbl,csv,version,0.2,,,

Config rows

The first row may be followed by a series of rows whose first cells have the value "config". The second and third cells on such rows are interpreted as key-value pairs. The values of keys may affect the interpretation of the rest of the patch. For example:

config,empty_tag,*,,,,
config,row_tag,ROW,,,,

Remaining Rows

The remaining rows describe properties and transformations of a table. Transformations assume that the rows are considered in order from the beginning of the file to the end.

The values of the first and second cells may be:

• column name
• column insert
• delete column
• column move
• row insert
• row delete
• row select
• row update

column name

This gives arbitrary labels for the columns in the table. The labels are those used to refer to the columns within the patch file. The first label is special, referring to a row identifier rather than a column. Trailing blank cells are ignored: For example:

column,name,ROW,[0],[1],,

This specifies that two columns are expected, and those columns are labeled "[0]" and "[1]". Rows are identified by the label "ROW".

column move

This row specifies the movement of a single column. The move is specified by giving the resultant order after the move. For example:

column,name,ROW,[0],[1],,
column,move,ROW,[1],[0],,

column insert

This row specifies the insertion of a single column. It has the same format as a "column move" row. The point of insertion is specified by giving the resulting column order, with a new column label inserted appropriately. Example:

column,name,ROW,[0],[1],,
column,insert,ROW,[0],{4},[1],

delete column

This row specifies the removal of a single column. It has the same format as the "column move" row. The point of insertion is specified by giving the resulting column order, with the unwanted column removed. Example:

column,name,ROW,{3},[1],[0],{4}
column,delete,ROW,{3},[0],{4},

row insert

Inserts a row with the given values. If not preceeded by a row select, the insertion is done after the last existing row. Values are specified as for row update.

row delete

Deletes a row matching the given values. Values are specified as for row select.

row select

Selects a row matching the given values. This example selects a row whose first column is "Paul":

column,name,ROW,first,last,age
row,select,*,Paul,*,*,

row update

Modifies the values of the row selected using row select. Here's an example which would change a row whose first column contains "Paul" such that the second column becomes "Fitzpatrick".

column,name,ROW,first,last,age
row,select,*,Paul,*,*,
row,update,*,*,Fitzpatrick,*,