d3-dsv

Этот модуль предоставляет парсер и форматировщик для данных, разделенных разделителями, чаще всего разделенных запятыми (CSV) или табулированными (TSV). Эти табличные форматы популярны в программах для работы со электронными таблицами, таких как Microsoft Excel, и часто более компактны, чем JSON. Эта реализация основана на RFC 4180.

Разделители запятыми (CSV) и табуляцией (TSV) встроены. Например, для разбора:

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"]]

Или для форматирования:

d3.csvFormat([{foo: "1", bar: "2"}]); // "foo,bar\n1,2"
d3.tsvFormat([{foo: "1", bar: "2"}]); // "foo\tbar\n1\t2"

Чтобы использовать другой разделитель, например, «|» для данных, разделенных вертикальной чертой, используйте d3.dsvFormat:

var psv = d3.dsvFormat("|");

console.log(psv.parse("foo|bar\n1|2")); // [{foo: "1", bar: "2"}, columns: ["foo", "bar"]]

Для легкой загрузки файлов DSV в браузере, см. методы d3-request’s d3.csv и d3.tsv.

Установка

Если вы используете NPM, npm install d3-dsv. В противном случае загрузите последнюю версию. Вы также можете загрузить напрямую с d3js.org, как отдельную библиотеку или как часть D3 4.0. Поддерживаются среды AMD, CommonJS и vanilla. В vanilla экспортируется глобальная переменная d3:

<script src="https://d3js.org/d3-dsv.v1.min.js"></script>
<script>

var data = d3.csvParse(string);

</script>

Попробуйте d3-dsv в своём браузере.

Справочник API

d3.csvParse(строка[, строка]) Исходный код

Эквивалентно dsvFormat(",").parse.

d3.csvParseRows(строка[, строка]) Исходный код

Эквивалентно dsvFormat(",").parseRows.

d3.csvFormat(строки[, колонки]) Исходный код

Эквивалентно dsvFormat(",").format.

d3.csvFormatRows(строки) Исходный код

Эквивалентно dsvFormat(",").formatRows.

d3.tsvParse(строка[, строка]) Исходный код

Эквивалентно dsvFormat("\t").parse.

d3.tsvParseRows(строка[, строка]) Исходный код

Эквивалентно dsvFormat("\t").parseRows.

d3.tsvFormat(строки[, колонки]) Исходный код

Эквивалентно dsvFormat("\t").format.

d3.tsvFormatRows(строки) Исходный код

Эквивалентно dsvFormat("\t").formatRows.

d3.dsvFormat(разделитель) <>

Создаёт новый парсер и форматировщик DSV для указанного разделителя. Разделитель должен быть одиночным символом (т.е., одиночный 16-битный код); поэтому ASCII разделители подойдут, но эмодзи разделители — нет.

dsv.parse(строка[, строка]) Исходный код

Разбирает указанную строку, которая должна быть в формате данных, разделённых разделителями, с соответствующим разделителем, возвращая массив объектов, представляющих обработанные строки.

В отличие от dsv.parseRows, этот метод требует, чтобы первая строка DSV-контента содержала список столбцов, разделённых разделителями; эти имена столбцов становятся атрибутами возвращаемых объектов. Например, рассмотрим следующий CSV-файл:

Year,Make,Model,Length
1997,Ford,E350,2.34
2000,Mercury,Cougar,2.38

Полученный JavaScript-массив:

[
  {"Year": "1997", "Make": "Ford", "Model": "E350", "Length": "2.34"},
  {"Year": "2000", "Make": "Mercury", "Model": "Cougar", "Length": "2.38"}
]

Возвращаемый массив также раскрывает свойство columns, содержащее имена столбцов в порядке ввода (в отличие от Object.keys, порядок итерации которого произволен). Например:

data.columns; // ["Year", "Make", "Model", "Length"]

Если функция преобразования строки не указана, значения полей являются строками. Для безопасности нет автоматического преобразования в числа, даты или другие типы. В некоторых случаях JavaScript может автоматически привести строки к числам (например, используя оператор +), но лучше указать функцию преобразования строки.

Если функция преобразования строки указана, указанная функция вызывается для каждой строки, получая объект, представляющий текущую строку (d), индекс (i) , начиная с нуля для первой строки без заголовка, и массив имён столбцов. Если возвращаемое значение равно null или undefined, строка пропускается и будет исключена из массива, возвращаемого dsv.parse; в противном случае, возвращаемое значение определяет соответствующий объект строки. Например:

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
  };
});

Примечание: использование + вместо parseInt или parseFloat обычно быстрее, хотя и более ограничено. Например, "30px" при приведении с помощью + возвращает NaN, в то время как parseInt и parseFloat возвращают 30.

dsv.parseRows(строка[, строка]) Исходный код

Разбирает указанную строку, которая должна быть в формате данных, разделённых разделителями, с соответствующим разделителем, возвращая массив массивов, представляющих обработанные строки.

В отличие от dsv.parse, этот метод обрабатывает строку заголовка как стандартную строку и должен использоваться всякий раз, когда DSV-контент не содержит заголовка. Каждая строка представлена как массив, а не как объект. Строки могут иметь переменную длину. Например, рассмотрим следующий CSV-файл, который, в частности, не содержит строки заголовка:

1997,Ford,E350,2.34
2000,Mercury,Cougar,2.38

Полученный JavaScript-массив:

[
  ["1997", "Ford", "E350", "2.34"],
  ["2000", "Mercury", "Cougar", "2.38"]
]

Если функция преобразования строки не указана, значения полей являются строками. Для безопасности нет автоматического преобразования в числа, даты или другие типы. В некоторых случаях JavaScript может автоматически привести строки к числам (например, используя оператор +), но лучше указать функцию преобразования строки.

Если функция преобразования строки указана, указанная функция вызывается для каждой строки, получая массив, представляющий текущую строку (d), индекс (i) , начиная с нуля для первой строки, и массив имён столбцов. Если возвращаемое значение равно null или undefined, строка пропускается и будет исключена из массива, возвращаемого dsv.parse; в противном случае, возвращаемое значение определяет соответствующий объект строки. Например:

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
  };
});

По сути, строка аналогична применению операторов map и filter к возвращаемым строкам.

dsv.format(строки[, колонки]) Исходный код

Форматирует указанный массив объектов строки в виде данных, разделённых разделителями, возвращая строку. Эта операция является обратной dsv.parse. Каждая строка будет разделена новой строкой (\n), а каждый столбец в каждой строке будет разделён разделителем (таким как запятая, ,). Значения, содержащие либо разделитель, двойную кавычку (") или новую строку, будут экранированы с помощью двойных кавычек.

Если колонки не указаны, список имён столбцов, формирующих строку заголовка, определяется объединением всех свойств всех объектов в строках; порядок столбцов не определён. Если колонки указаны, это массив строк, представляющих имена столбцов. Например:

var string = d3.csvFormat(data, ["year", "make", "model", "length"]);

Все поля каждого объекта строки будут приведены к строкам. Для большего контроля над тем, какие и как поля форматируются, сначала отобразите строки в массив массивов строк, а затем используйте dsv.formatRows.

dsv.formatRows(строки) Исходный код

Форматирует указанный массив массивов строк строки в виде данных, разделённых разделителями, возвращая строку. Эта операция является обратной dsv.parseRows. Каждая строка будет разделена новой строкой (\n), а каждый столбец в каждой строке будет разделён разделителем (таким как запятая, ,). Значения, содержащие либо разделитель, двойную кавычку (") или новую строку, будут экранированы с помощью двойных кавычек.

Чтобы преобразовать массив объектов в массив массивов с явным указанием столбцов, используйте массив.map. Например:

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
  ];
}));

Если вам нужно, вы также можете массив.concat этот результат с массивом имён столбцов для создания первой строки:

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
  ];
})));

Политика безопасности содержимого

Если политика безопасности содержимого введена в действие, обратите внимание, что dsv.parse требует unsafe-eval в директиве script-src, из-за безопасного использования динамической генерации кода для быстрого разбора. (См. исходный код.) В качестве альтернативы используйте dsv.parseRows.

Символы порядка байтов

Файлы DSV иногда начинаются с метки порядка байтов (BOM); например, сохранение электронных таблиц в формате CSV UTF-8 из Microsoft Excel включает BOM. В веб-приложениях это обычно не проблема, потому что алгоритм декодирования UTF-8, определенный в стандарте кодирования, удаляет BOM. В Node.js, с другой стороны, BOM не удаляется при декодировании UTF-8.

Если BOM не удален, первый символ текста — это пробел с нулевой шириной и без переноса строки. Поэтому, если файл CSV с BOM парсится с помощью d3.csvParse, имя первой колонки будет начинаться с пробела с нулевой шириной и без переноса строки. Это трудно заметить, поскольку этот символ обычно невидим при печати.

Чтобы удалить BOM перед парсингом, можно использовать strip-bom.

Справочник командной строки

dsv2dsv

dsv2dsv [options…] [file]

Преобразует указанный входной файл DSV в DSV (обычно с другим разделителем или кодировкой). Если file не указан, по умолчанию считывается со стандартного ввода. Например, для преобразования CSV в TSV:

csv2tsv < example.csv > example.tsv

Для преобразования CSV windows-1252 в CSV utf-8:

dsv2dsv --input-encoding windows-1252 < latin1.csv > utf8.csv

dsv2dsv -h
dsv2dsv --help

Выводит информацию об использовании.

dsv2dsv -V
dsv2dsv --version

Выводит номер версии.

dsv2dsv -o file
dsv2dsv --out file

Указывает имя выходного файла. По умолчанию «-» для стандартного вывода.

dsv2dsv -r delimiter
dsv2dsv --input-delimiter delimiter

Указывает символ разделителя входных данных. По умолчанию «,» для чтения CSV. (Введите табуляцию в командной строке, нажав ⌃V.)

dsv2dsv --input-encoding encoding

Указывает кодировку символов входных данных. По умолчанию «utf8».

dsv2dsv -w delimiter
dsv2dsv --output-delimiter delimiter

Указывает символ разделителя выходных данных. По умолчанию «,» для записи CSV. (Введите табуляцию в командной строке, нажав ⌃V.)

dsv2dsv --output-encoding encoding

Указывает кодировку символов выходных данных. По умолчанию «utf8».

csv2tsv [options…] [file]

Эквивалентно dsv2dsv, но разделитель выходных данных по умолчанию — символ табуляции (\t).

tsv2csv [options…] [file]

Эквивалентно dsv2dsv, но разделитель входных данных по умолчанию — символ табуляции (\t).

dsv2json

dsv2json [options…] [file]

Преобразует указанный входной файл DSV в JSON. Если file не указан, по умолчанию считывается со стандартного ввода. Например, для преобразования CSV в JSON:

csv2json < example.csv > example.json

Или для преобразования CSV в поток JSON с новой строкой:

csv2json -n < example.csv > example.ndjson

dsv2json -h
dsv2json --help

Выводит информацию об использовании.

dsv2json -V
dsv2json --version

Выводит номер версии.

dsv2json -o file
dsv2json --out file

Указывает имя выходного файла. По умолчанию «-» для стандартного вывода.

dsv2json -r delimiter
dsv2json --input-delimiter delimiter

Указывает символ разделителя входных данных. По умолчанию «,» для чтения CSV. (Введите табуляцию в командной строке, нажав ⌃V.)

dsv2json --input-encoding encoding

Указывает кодировку символов входных данных. По умолчанию «utf8».

dsv2json -r encoding
dsv2json --output-encoding encoding

Указывает кодировку символов выходных данных. По умолчанию «utf8».

dsv2json -n
dsv2json --newline-delimited

Вывести JSON с разделителями новых строк вместо одного JSON-массива.

csv2json [options…] [file]

Эквивалентно dsv2json.

tsv2json [options…] [file]

Эквивалентно dsv2json, но разделитель входных данных по умолчанию — символ табуляции (\t).

json2dsv

json2dsv [options…] [file]

Преобразует указанный входной файл JSON в DSV. Если file не указан, по умолчанию считывается со стандартного ввода. Например, для преобразования JSON в CSV:

json2csv < example.json > example.csv

Или для преобразования потока JSON с новой строкой в CSV:

json2csv -n < example.ndjson > example.csv

json2dsv -h
json2dsv --help

Выводит информацию об использовании.

json2dsv -V
json2dsv --version

Выводит номер версии.

json2dsv -o file
json2dsv --out file

Указывает имя выходного файла. По умолчанию «-» для стандартного вывода.

json2dsv --input-encoding encoding

Указывает кодировку символов входных данных. По умолчанию «utf8».

json2dsv -w delimiter
json2dsv --output-delimiter delimiter

Указывает символ разделителя выходных данных. По умолчанию «,» для записи CSV. (Введите табуляцию в командной строке, нажав ⌃V.)

json2dsv --output-encoding encoding

Указывает кодировку символов выходных данных. По умолчанию «utf8».

json2dsv -n
json2dsv --newline-delimited

Читать JSON с разделителями новых строк вместо одного JSON-массива.

csv2json [options…] [file]

Эквивалентно json2dsv.

tsv2json [options…] [file]

Эквивалентно json2dsv, но разделитель выходных данных по умолчанию — символ табуляции (\t).