This module provides a parser and formatter for delimiter-separated values, most commonly comma- (CSV) or tab-separated values (TSV). These tabular formats are popular with spreadsheet programs such as Microsoft Excel, and are often more space-efficient than JSON. This implementation is based on RFC 4180.
Comma (CSV) and tab (TSV) delimiters are built-in. For example, to parse:
d3.csvParse("foo,bar\n1,2"); // [{foo: "1", bar: "2"}, columns: ["foo", "bar"]]
d3.tsvParse("foo\tbar\n1\t2"); // [{foo: "1", bar: "2"}, columns: ["foo", "bar"]]
Or to format:
d3.csvFormat([{foo: "1", bar: "2"}]); // "foo,bar\n1,2"
d3.tsvFormat([{foo: "1", bar: "2"}]); // "foo\tbar\n1\t2"
To use a different delimiter, such as “|” for pipe-separated values, use d3.dsvFormat:
var psv = d3.dsvFormat("|");
console.log(psv.parse("foo|bar\n1|2")); // [{foo: "1", bar: "2"}, columns: ["foo", "bar"]]
For easy loading of DSV files in a browser, see d3-request’s d3.csv and d3.tsv methods.
If you use NPM, npm install d3-dsv
. Otherwise, download the latest release. You can also load directly from d3js.org, either as a standalone library or as part of D3 4.0. AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3
global is exported:
<script src="https://d3js.org/d3-dsv.v1.min.js"></script>
<script>
var data = d3.csvParse(string);
</script>
# d3.csvParse(string[, row]) <>
Equivalent to dsvFormat(",").parse.
# d3.csvParseRows(string[, row]) <>
Equivalent to dsvFormat(",").parseRows.
# d3.csvFormat(rows[, columns]) <>
Equivalent to dsvFormat(",").format.
Equivalent to dsvFormat(",").formatRows.
# d3.tsvParse(string[, row]) <>
Equivalent to dsvFormat("\t").parse.
# d3.tsvParseRows(string[, row]) <>
Equivalent to dsvFormat("\t").parseRows.
# d3.tsvFormat(rows[, columns]) <>
Equivalent to dsvFormat("\t").format.
Equivalent to dsvFormat("\t").formatRows.
Constructs a new DSV parser and formatter for the specified delimiter. The delimiter must be a single character (i.e., a single 16-bit code unit); so, ASCII delimiters are fine, but emoji delimiters are not.
Parses the specified string, which must be in the delimiter-separated values format with the appropriate delimiter, returning an array of objects representing the parsed rows.
Unlike dsv.parseRows, this method requires that the first line of the DSV content contains a delimiter-separated list of column names; these column names become the attributes on the returned objects. For example, consider the following CSV file:
Year,Make,Model,Length
1997,Ford,E350,2.34
2000,Mercury,Cougar,2.38
The resulting JavaScript array is:
[
{"Year": "1997", "Make": "Ford", "Model": "E350", "Length": "2.34"},
{"Year": "2000", "Make": "Mercury", "Model": "Cougar", "Length": "2.38"}
]
The returned array also exposes a columns
property containing the column names in input order (in contrast to Object.keys, whose iteration order is arbitrary). For example:
data.columns; // ["Year", "Make", "Model", "Length"]
If a row conversion function is not specified, field values are strings. For safety, there is no automatic conversion to numbers, dates, or other types. In some cases, JavaScript may coerce strings to numbers for you automatically (for example, using the +
operator), but better is to specify a row conversion function.
If a row conversion function is specified, the specified function is invoked for each row, being passed an object representing the current row (d
), the index (i
) starting at zero for the first non-header row, and the array of column names. If the returned value is null or undefined, the row is skipped and will be ommitted from the array returned by dsv.parse; otherwise, the returned value defines the corresponding row object. For example:
var data = d3.csvParse(string, function(d) {
return {
year: new Date(+d.Year, 0, 1), // lowercase and convert "Year" to Date
make: d.Make, // lowercase
model: d.Model, // lowercase
length: +d.Length // lowercase and convert "Length" to number
};
});
Note: using +
rather than parseInt or parseFloat is typically faster, though more restrictive. For example, "30px"
when coerced using +
returns NaN
, while parseInt and parseFloat return 30
.
# dsv.parseRows(string[, row]) <>
Parses the specified string, which must be in the delimiter-separated values format with the appropriate delimiter, returning an array of arrays representing the parsed rows.
Unlike dsv.parse, this method treats the header line as a standard row, and should be used whenever DSV content does not contain a header. Each row is represented as an array rather than an object. Rows may have variable length. For example, consider the following CSV file, which notably lacks a header line:
1997,Ford,E350,2.34
2000,Mercury,Cougar,2.38
The resulting JavaScript array is:
[
["1997", "Ford", "E350", "2.34"],
["2000", "Mercury", "Cougar", "2.38"]
]
If a row conversion function is not specified, field values are strings. For safety, there is no automatic conversion to numbers, dates, or other types. In some cases, JavaScript may coerce strings to numbers for you automatically (for example, using the +
operator), but better is to specify a row conversion function.
If a row conversion function is specified, the specified function is invoked for each row, being passed an array representing the current row (d
), the index (i
) starting at zero for the first row, and the array of column names. If the returned value is null or undefined, the row is skipped and will be ommitted from the array returned by dsv.parse; otherwise, the returned value defines the corresponding row object. For example:
var data = d3.csvParseRows(string, function(d, i) {
return {
year: new Date(+d[0], 0, 1), // convert first colum column to Date
make: d[1],
model: d[2],
length: +d[3] // convert fourth column to number
};
});
In effect, row is similar to applying a map and filter operator to the returned rows.
# dsv.format(rows[, columns]) <>
Formats the specified array of object rows as delimiter-separated values, returning a string. This operation is the inverse of dsv.parse. Each row will be separated by a newline (\n
), and each column within each row will be separated by the delimiter (such as a comma, ,
). Values that contain either the delimiter, a double-quote ("
) or a newline will be escaped using double-quotes.
If columns is not specified, the list of column names that forms the header row is determined by the union of all properties on all objects in rows; the order of columns is nondeterministic. If columns is specified, it is an array of strings representing the column names. For example:
var string = d3.csvFormat(data, ["year", "make", "model", "length"]);
All fields on each row object will be coerced to strings. For more control over which and how fields are formatted, first map rows to an array of array of string, and then use dsv.formatRows.
Formats the specified array of array of string rows as delimiter-separated values, returning a string. This operation is the reverse of dsv.parseRows. Each row will be separated by a newline (\n
), and each column within each row will be separated by the delimiter (such as a comma, ,
). Values that contain either the delimiter, a double-quote (") or a newline will be escaped using double-quotes.
To convert an array of objects to an array of arrays while explicitly specifying the columns, use array.map. For example:
var string = d3.csvFormatRows(data.map(function(d, i) {
return [
d.year.getFullYear(), // Assuming d.year is a Date object.
d.make,
d.model,
d.length
];
}));
If you like, you can also array.concat this result with an array of column names to generate the first row:
var string = d3.csvFormatRows([[
"year",
"make",
"model",
"length"
]].concat(data.map(function(d, i) {
return [
d.year.getFullYear(), // Assuming d.year is a Date object.
d.make,
d.model,
d.length
];
})));
If a content security policy is in place, note that dsv.parse requires unsafe-eval
in the script-src
directive, due to the (safe) use of dynamic code generation for fast parsing. (See source.) Alternatively, use dsv.parseRows.
This module comes with a few binaries to convert DSV files:
These programs either take a single file as an argument or read from stdin, and write to stdout. For example, these statements are all equivalent:
csv2json file.csv > file.json
csv2json < file.csv > file.json
csv2json - < file.csv > file.json
cat file.csv | csv2json - > file.json
Use --help for more.