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-fetch’s d3.csv, d3.tsv и d3.dsv.

Установка

Если вы используете NPM, npm install d3-dsv. В противном случае, скачайте последнюю версию. Вы также можете загрузить напрямую с d3js.org, как отдельную библиотеку или как часть D3. Поддерживаются среды 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. Примечание: требуется 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; в противном случае, возвращаемое значение определяет соответствующий объект строки. Например:

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.

Примечание: требуется 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; в противном случае, возвращаемое значение определяет соответствующий объект строки. Например:

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(rows[, columns]) Source

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

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

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

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

dsv.formatBody(rows[, columns]) Source

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

dsv.formatRows(rows) Source

Форматирует указанный массив массивов строк rows как значения, разделённые разделителями, возвращая строку. Эта операция обратна 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
  ];
})));

dsv.formatRow(row) Source

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

dsv.formatValue(value) Source

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

d3.autoType(object) Source

Исходя из object (или массива), представляющего обработанную строку, определяет типы значений в object и соответствующим образом преобразует их, возвращая изменённый object. Эта функция предназначена для использования в качестве функции доступа к строкам вместе с 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. Когда указана строка только с датой, например YYYY-MM-DD, предполагаемое время — полночь по UTC; однако, если указана строка с датой и временем, например YYYY-MM-DDTHH:MM, без часового пояса, она предполагается местным временем.

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

Дополнительную информацию см. в тетради d3.autoType.

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

Если введена политика безопасности содержимого, обратите внимание, что 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 (обычно с другим разделителем или кодировкой). Если файл не указан, по умолчанию читается из стандартного ввода. Например, для преобразования 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. Если файл не указан, по умолчанию используется чтение из стандартного ввода. Например, для преобразования 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 -a
dsv2json --auto-type

Используйте вывод типа при разборе строк. См. d3.autoType для того, как это работает.

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

json2csv [options…] [file]

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

json2tsv [options…] [file]

Эквивалентно 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]) Source

dsv.formatBody(rows[, columns]) Source

dsv.formatRows(rows) Source

dsv.formatRow(row) Source

dsv.formatValue(value) Source

d3.autoType(object) Source

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

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

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

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 [options…] [file]

dsv2json

dsv2json [options…] [file]

dsv2json -h dsv2json --help

dsv2json -V dsv2json --version

dsv2json -o file dsv2json --out file

dsv2json -a dsv2json --auto-type

dsv2json -r delimiter dsv2json --input-delimiter delimiter

dsv2json --input-encoding encoding

dsv2json -r encoding dsv2json --output-encoding encoding

dsv2json -n dsv2json --newline-delimited

csv2json [options…] [file]

tsv2json [options…] [file]

json2dsv

json2dsv [options…] [file]

json2dsv -h json2dsv --help

json2dsv -V json2dsv --version

json2dsv -o file json2dsv --out file

json2dsv --input-encoding encoding

json2dsv -w delimiter json2dsv --output-delimiter delimiter

json2dsv --output-encoding encoding

json2dsv -n json2dsv --newline-delimited

json2csv [options…] [file]

json2tsv [options…] [file]

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 file
dsv2json --out file

dsv2json -a
dsv2json --auto-type

dsv2json -r delimiter
dsv2json --input-delimiter delimiter

dsv2json -r encoding
dsv2json --output-encoding encoding

dsv2json -n
dsv2json --newline-delimited

json2dsv -h
json2dsv --help

json2dsv -V
json2dsv --version

json2dsv -o file
json2dsv --out file

json2dsv -w delimiter
json2dsv --output-delimiter delimiter

json2dsv -n
json2dsv --newline-delimited