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:

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

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

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

Установка

Если вы используете npm, npm install d3-dsv. Вы также можете загрузить последнюю версию на GitHub. Для обычного HTML в современных браузерах импортируйте d3-dsv из Skypack:

<script type="module">

import {csvParse} from "https://cdn.skypack.dev/d3-dsv@3";

const data = csvParse(string);

</script>

Для устаревших сред вы можете загрузить пакет UMD d3-dsv с CDN на основе npm, например, jsDelivr; экспортируется глобальная переменная d3:

<script src="https://cdn.jsdelivr.net/npm/d3-dsv@3"></script>
<script>

const data = d3.csvParse(string);

</script>

Справочник по API

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

Эквивалентно dsvFormat(",").parse. Примечание: требует unsafe-eval политики безопасности контента.

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

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

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

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

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

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

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

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

d3.csvFormatRow(строка) Исходный код

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

d3.csvFormatValue(значение) Исходный код

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

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

Эквивалентно dsvFormat("\t").parse. Примечание: требует unsafe-eval политики безопасности контента.

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

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

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

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

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

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

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

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

d3.tsvFormatRow(строка) Исходный код

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

d3.tsvFormatValue(значение) Исходный код

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

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

Если имена столбцов не уникальны, для каждого имени возвращается только последнее значение; для доступа ко всем значениям используйте dsv.parseRows вместо этого (см. пример).

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

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

const data = d3.csvParse(string, (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.

Примечание: требует unsafe-eval политики безопасности контента.

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

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

const data = d3.csvParseRows(string, (d, i) => {
  return {
    year: new Date(+d[0], 0, 1), // convert first column to Date
    make: d[1],
    model: d[2],
    length: +d[3] // convert fourth column to number
  };
});

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

dsv.format(rows[, columns]) Источник

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

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

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

Все поля каждого объекта строки будут приведены к строковому типу. Если значение поля равно null или undefined, используется пустая строка. Если значение поля является датой, используется формат строки даты и времени ECMAScript (ECMAScript date-time string format) (подмножество ISO 8601): например, даты в полночь по UTC форматируются как YYYY-MM-DD. Для большего контроля над тем, какие и как форматируются поля, сначала отобразите rows в массив массивов строк, а затем используйте dsv.formatRows.

dsv.formatBody(rows[, columns]) Источник

Эквивалентно dsv.format, но без строки заголовка. Это полезно, например, при добавлении строк к существующему файлу.

dsv.formatRows(rows) Источник

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

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

const string = d3.csvFormatRows(data.map((d, i) => {
  return [
    d.year.getFullYear(), // Assuming d.year is a Date object.
    d.make,
    d.model,
    d.length
  ];
}));

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

const string = d3.csvFormatRows([[
    "year",
    "make",
    "model",
    "length"
  ]].concat(data.map((d, i) => {
  return [
    d.year.getFullYear(), // Assuming d.year is a Date object.
    d.make,
    d.model,
    d.length
  ];
})));

dsv.formatRow(row) Источник

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

dsv.formatValue(value) Источник

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

d3.autoType(object) Источник

Учитывая объект object (или массив), представляющий проанализированную строку, определяет типы значений в object и принудительно приводит их соответственно, возвращая изменённый object. Эта функция предназначена для использования в качестве функции-обработчика row в сочетании с dsv.parse и dsv.parseRows. Например, рассмотрим следующий CSV-файл:

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

При использовании с d3.csvParse,

d3.csvParse(string, d3.autoType)

результирующий массив JavaScript будет:

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

Автоматическое определение типов выполняется следующим образом. Для каждого значения value в данном object вычисляется обрезанное значение; затем значение переприсваивается следующим образом:

Если пустое, то null.
Если точно "true", то true.
Если точно "false", то false.
Если точно "NaN", то NaN.
В противном случае, если преобразуемо в число, то число.
В противном случае, если строка только с датой или строка с датой и временем, то дата.
В противном случае, строка (исходное значение без обрезки).

Значения с ведущими нулями могут быть приведены к числам; например, "08904" приводится к 8904. Однако дополнительные символы, такие как запятые или единицы (например, "$1.00", "(123)", "1,234" или "32px"), не позволят выполнить приведение к числу, что приведёт к строковому типу.

Строки дат должны быть в подмножестве ECMAScript формата ISO 8601. Когда указана строка только с датой, например, ГГГГ-ММ-ДД, предполагаемое время — полночь по UTC; однако, если указана строка с датой и временем, например, ГГГГ-ММ-ДДТЧЧ:ММ, без часового пояса, она предполагается как местное время.

Автоматическое определение типов в основном предназначено для обеспечения безопасного и предсказуемого поведения в сочетании с dsv.format и dsv.formatRows для распространённых типов JavaScript. Если вам требуется другое поведение, вы должны реализовать свою собственную функцию-обработчик строк.

Подробнее см. блокнот d3.autoType.

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

Если политика безопасности контента 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 file в 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 [параметры…] [файл]

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

dsv2json

dsv2json [параметры…] [файл]

Преобразует указанный входной файл DSV в JSON. Если файл не указан, по умолчанию считывает данные со стандартного ввода. Например, для преобразования 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 файл
dsv2json --out файл

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

dsv2json -a
dsv2json --auto-type

Использует вывод типа при разборе строк. См. d3.autoType для получения информации о его работе.

dsv2json -r разделитель
dsv2json --input-delimiter разделитель

dsv2json --input-encoding кодировка

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

dsv2json -r кодировка
dsv2json --output-encoding кодировка

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

dsv2json -n
dsv2json --newline-delimited

Выводит newline-delimited JSON вместо одного JSON массива.

csv2json [параметры…] [файл]

Равносильно dsv2json.

tsv2json [параметры…] [файл]

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

json2dsv

json2dsv [параметры…] [файл]

Преобразует указанный входной файл JSON в DSV. Если файл не указан, по умолчанию считывает данные со стандартного ввода. Например, для преобразования 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 файл
json2dsv --out файл

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

json2dsv --input-encoding кодировка

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

json2dsv -w разделитель
json2dsv --output-delimiter разделитель

json2dsv --output-encoding кодировка

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

json2dsv -n
json2dsv --newline-delimited

Считывает newline-delimited JSON вместо одного JSON массива.

json2csv [параметры…] [файл]

Равносильно json2dsv.

json2tsv [параметры…] [файл]

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

d3-dsv

Установка

Справочник по API

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

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

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

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

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

d3.csvFormatRow(строка) Исходный код

d3.csvFormatValue(значение) Исходный код

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

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

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

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

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

d3.tsvFormatRow(строка) Исходный код

d3.tsvFormatValue(значение) Исходный код

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

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

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

dsv.format(rows[, columns]) Источник

dsv.formatBody(rows[, columns]) Источник

dsv.formatRows(rows) Источник

dsv.formatRow(row) Источник

dsv.formatValue(value) Источник

d3.autoType(object) Источник

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

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

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

dsv2dsv

dsv2dsv [options…] [file]

dsv2dsv -h dsv2dsv --help

dsv2dsv -V dsv2dsv --version

dsv2dsv -o file dsv2dsv --out file

dsv2dsv -r delimiter dsv2dsv --input-delimiter delimiter

dsv2dsv --input-encoding encoding

dsv2dsv -w delimiter dsv2dsv --output-delimiter delimiter

dsv2dsv --output-encoding encoding

csv2tsv [options…] [file]

tsv2csv [параметры…] [файл]

dsv2json

dsv2json [параметры…] [файл]

dsv2json -h dsv2json --help

dsv2json -V dsv2json --version

dsv2json -o файл dsv2json --out файл

dsv2json -a dsv2json --auto-type

dsv2json -r разделитель dsv2json --input-delimiter разделитель

dsv2json --input-encoding кодировка

dsv2json -r кодировка dsv2json --output-encoding кодировка

dsv2json -n dsv2json --newline-delimited

csv2json [параметры…] [файл]

tsv2json [параметры…] [файл]

json2dsv

json2dsv [параметры…] [файл]

json2dsv -h json2dsv --help

json2dsv -V json2dsv --version

json2dsv -o файл json2dsv --out файл

json2dsv --input-encoding кодировка

json2dsv -w разделитель json2dsv --output-delimiter разделитель

json2dsv --output-encoding кодировка

json2dsv -n json2dsv --newline-delimited

json2csv [параметры…] [файл]

json2tsv [параметры…] [файл]

dsv2dsv -h
dsv2dsv --help

dsv2dsv -V
dsv2dsv --version

dsv2dsv -o file
dsv2dsv --out file

dsv2dsv -r delimiter
dsv2dsv --input-delimiter delimiter

dsv2dsv -w delimiter
dsv2dsv --output-delimiter delimiter

dsv2json -h
dsv2json --help

dsv2json -V
dsv2json --version

dsv2json -o файл
dsv2json --out файл

dsv2json -a
dsv2json --auto-type

dsv2json -r разделитель
dsv2json --input-delimiter разделитель

dsv2json -r кодировка
dsv2json --output-encoding кодировка

dsv2json -n
dsv2json --newline-delimited

json2dsv -h
json2dsv --help

json2dsv -V
json2dsv --version

json2dsv -o файл
json2dsv --out файл

json2dsv -w разделитель
json2dsv --output-delimiter разделитель

json2dsv -n
json2dsv --newline-delimited