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 d3.csv и d3.tsv.

Установка

Если вы используете NPM, npm install d3-dsv. В противном случае, скачайте последнюю версию. Вы также можете загрузить напрямую с d3js.org, как автономную библиотеку standalone library или в качестве части D3 4.0. Поддерживаются AMD, CommonJS и стандартные среды JavaScript. В стандартных средах JavaScript экспортируется глобальная переменная 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), а каждый столбец в каждой строке будет разделен разделителем (например, запятой, ,). Значения, содержащие разделитель, двойную кавычку (") или символ новой строки, будут экранированы с помощью двойных кавычек.

Для преобразования массива объектов в массив массивов, явно указывая столбцы, используйте array.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
  ];
}));

Если хотите, вы также можете array.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
  ];
})));

Политика безопасности контента

Если политика безопасности контента (CSP) установлена, обратите внимание, что 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).