Linear TSV is a line-oriented, portable tabular data format. Tabular data -- rows of tuples, each of the same length -- is commonly stored as CSV and is the lingua franca of spreadsheets, databases and analysis tools.

CSV is almost but not quite line-oriented, because newlines are quoted, not escaped. In the TSV format presented here, escape codes are used for newlines and tabs in field data, allowing naive filtering with line-oriented shell tools like sort, fgrep and cut to work as expected. In all of its details, the format derives from the TEXT serialization mode of Postgres and MySQL.

from collections import namedtuple
import sys

import tsv


# Simplest access mode: parse a text stream (strings are okay, too) to a
# generator of lists of strings.
lists = tsv.un(sys.stdin)


# Parse each row as a particular class derived with namedtuple()
class Stats(namedtuple('Stats', ['state', 'city', 'population', 'area'])):
    pass

tuples = tsv.un(sys.stdin, Stats)


# Format a collection of rows, getting back a generator of strings, one
# each row. Any parseable type is okay.
strings = tsv.to(lists)
strings = tsv.to(tuples)

# Write the rows to a handle:
strings = tsv.to(tuples, sys.stdout)


# CSV compatible API (reader/writer)
with open('eggs.tsv', 'w') as tsvfile:
    spamwriter = tsv.writer(tsvfile)
    spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])
    spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])

with open('eggs.tsv') as tsvfile:
    spamreader = tsv.reader(tsvfile)
    for row in spamreader:
        print(', '.join(row))


# CSV compatible API (DictReader/DictWriter)
with open('names.tsv', 'w') as tsvfile:
    fieldnames = ['first_name', 'last_name']
    writer = tsv.DictWriter(tsvfile, fieldnames=fieldnames)

    writer.writeheader()
    writer.writerow({'first_name': 'Baked', 'last_name': 'Beans'})
    writer.writerow({'first_name': 'Lovely', 'last_name': 'Spam'})
    writer.writerow({'first_name': 'Wonderful', 'last_name': 'Spam'})

with open('names.tsv') as tsvfile:
    reader = tsv.DictReader(tsvfile)
    for row in reader:
        print(row['first_name'], row['last_name'])

In this format, all records are separated by ASCII newlines (0x0a) and fields within a record are separated with ASCII tab (0x09). It is permitted but discouraged to separate records with \r\n.

To include newlines, tabs, carriage returns and backslashes in field data, the following escape sequences must be used:

• \n for newline,
• \t for tab,
• \r for carriage return,
• \\ for backslash.

To indicate missing data for a field, the character sequence \N (bytes 0x5c and 0x4e) is used. Note that the N is capitalized. This character sequence is exactly that used by SQL databases to indicate SQL NULL in their tab-separated output mode.

There are no header lines specified by this format. One objection to them is that they break the naive concantenation of files. Another is that they are anithetical to stream processing. Yet another is that one generally wants more than column names -- one wants at least column types. Better to do nothing than too little.

In advocating a shift to a line-oriented, tab-separated serialization format, we are endorsing an existing format: the default serialization format of both Postgres and MySQL. We propose to standardize a subset of the format common to both database systems.

A truly line-oriented format for tabular data, where newline, carriage return and the separator are always represented by escape sequences, offers many practical advantages, among them:

• The parsers are simple and fast.
• First pass filtering and sorting for line-oriented formats is easy to implement in high-level languages, like Python and Java.
• Analysis and transformation of line-oriented data with command line tools is simple, dependable and often surprisingly efficient.
• By requiring escape sequences when newlines and tabs are in field text, the format allows parsers to naively and efficiently split data on raw byte values: 0x09 for fields and 0x0a for records.

CSV is almost right and it's worth talking about the disadvantages of CSV that motivate the author to promote another tabular data format:

• In some locales, , is the decimal separator; whereas the ASCII tab never collides with the decimal separator. More generally, the tab is not a centuries old glyph that one encounters in natural language.
• CSV is not truly line-oriented -- newlines are quoted, not escaped. A single record can span multiple physical lines. In consequence, line-oriented processing almost works until it doesn't, and then simple tricks -- sorting on the first column to optimize insertion order or batching records in to groups of a few thousand to get better insert performance -- require relatively complicated code to get right.
• CSV's quoting style requires one to mingle field data parsing and record splitting. Taking every third record still requires one to parse the prior two, since a newline inside quotes is not a record separator.
• CSV is ambiguous in many small areas -- the presence or absence of a header line, the choice of quote character (single or double?) and even the choice of separator character are all axes of variability.

A few sample parsers are included in the distribution.

Bash

tsv.bash < cities10.tsv

Python

example.py < cities10.tsv

This grammar is presented in the W3C EBNF format.

TSV        ::= Row (NL Row)*

/* This form may be read but not written by conforming implementations. */
TSVInput   ::= Row (CR? NL Row)*

Row        ::= Field (Tab Field)*
Field      ::= (Escape|NoOpEscape|PlainChar)*

Char       ::= [http://www.w3.org/TR/xml#NT-Char]
PlainChar  ::= Char - (NL|Tab|CR|'\')
NL         ::= #x0A
CR         ::= #x0D
Tab        ::= #x09

Escape     ::= '\n' | '\r' | '\t' | '\\'
NoOpEscape ::= '\' (Char - ('n'|'r'|'t'|'\'))

A diagram of the grammar can be generated online with the Bottlecaps Railroad Diagram generator.