класс CSV

CSV

В спешке?

Если вы знакомы с данными CSV и у вас есть конкретная задача, вы можете перейти непосредственно к:

• Рецепты для CSV.

В противном случае, продолжайте чтение о данном API: классах, методах и константах.

CSV

Данные CSV (значения, разделённые запятыми) представляют таблицу в текстовом формате:

• Разделитель строк отделяет строки таблицы. Общим разделителем строк является символ новой строки "\n".

• Разделитель столбцов отделяет поля в строке. Общим разделителем столбцов является запятая ",".

Эта строка CSV с разделителем строк "\n" и разделителем столбцов ",", имеет три строки и два столбца:

"foo,0\nbar,1\nbaz,2\n"

Несмотря на название CSV, представление CSV может использовать разные разделители.

Дополнительную информацию о таблицах см. в статье Википедии «Таблица (информация)», особенно в разделе «Простая таблица»

Класс CSV

Class Класс CSV предоставляет методы для:

• Разбора данных CSV из объекта String, файла (через его путь) или объекта IO.

• Генерации данных CSV в объект String.

Чтобы использовать CSV:

require 'csv'

Все примеры здесь предполагают, что это сделано.

Упрощение

Объект CSV имеет десятки методов экземпляров, которые обеспечивают точный контроль над разбором и генерацией данных CSV. Однако для многих задач достаточно более простых подходов.

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

Простой разбор

Методы разбора обычно возвращают:

• Массив массивов строк:

  • Внешний массив — вся «таблица».

  • Каждый внутренний массив — строка.

  • Каждая строка — поле.

• Объект CSV::Table. Подробности см. в разделе CSV с заголовками.

Разбор строки

Вводимые данные для разбора могут быть строкой:

string = "foo,0\nbar,1\nbaz,2\n"

Метод CSV.parse возвращает все данные CSV:

CSV.parse(string) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Метод CSV.parse_line возвращает только первую строку:

CSV.parse_line(string) # => ["foo", "0"]

CSV расширяет класс String методом экземпляра String#parse_csv, который также возвращает только первую строку:

string.parse_csv # => ["foo", "0"]

Разбор по пути к файлу

Вводимые данные для разбора могут быть в файле:

string = "foo,0\nbar,1\nbaz,2\n"
path = 't.csv'
File.write(path, string)

Метод CSV.read возвращает все данные CSV:

CSV.read(path) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Метод CSV.foreach итерируется, передавая каждую строку в заданный блок:

CSV.foreach(path) do |row|
  p row
end

Результат:

["foo", "0"]
["bar", "1"]
["baz", "2"]

Метод CSV.table возвращает все данные CSV как объект CSV::Table:

CSV.table(path) # => #<CSV::Table mode:col_or_row row_count:3>

Разбор из открытого потока IO

Вводимые данные для разбора могут находиться в открытом потоке IO:

Метод CSV.read возвращает все данные CSV:

File.open(path) do |file|
  CSV.read(file)
end # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Также как и метод CSV.parse:

File.open(path) do |file|
  CSV.parse(file)
end # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Метод CSV.parse_line возвращает только первую строку:

File.open(path) do |file|
 CSV.parse_line(file)
end # => ["foo", "0"]

Метод CSV.foreach итерируется, передавая каждую строку в заданный блок:

File.open(path) do |file|
  CSV.foreach(file) do |row|
    p row
  end
end

Результат:

["foo", "0"]
["bar", "1"]
["baz", "2"]

Метод CSV.table возвращает все данные CSV как объект CSV::Table:

File.open(path) do |file|
  CSV.table(file)
end # => #<CSV::Table mode:col_or_row row_count:3>

Простая генерация

Метод CSV.generate возвращает строку; в этом примере используется метод CSV#<< для добавления строк, которые должны быть сгенерированы:

output_string = CSV.generate do |csv|
  csv << ['foo', 0]
  csv << ['bar', 1]
  csv << ['baz', 2]
end
output_string # => "foo,0\nbar,1\nbaz,2\n"

Метод CSV.generate_line возвращает строку, содержащую единственную строку, составленную из массива:

CSV.generate_line(['foo', '0']) # => "foo,0\n"

CSV расширяет класс Array методом экземпляра Array#to_csv, который преобразует массив в строку:

['foo', '0'].to_csv # => "foo,0\n"

Фильтрация CSV

Метод CSV.filter обеспечивает функциональность фильтра CSV в стиле Unix. Входные данные обрабатываются для получения выходных данных:

in_string = "foo,0\nbar,1\nbaz,2\n"
out_string = ''
CSV.filter(in_string, out_string) do |row|
  row[0] = row[0].upcase
  row[1] *= 4
end
out_string # => "FOO,0000\nBAR,1111\nBAZ,2222\n"

Объекты CSV

Существует три способа создания объекта CSV:

• Метод CSV.new возвращает новый объект CSV.

• Метод CSV.instance возвращает новый или кэшированный объект CSV.

• Метод CSV() также возвращает новый или кэшированный объект CSV.

Методы экземпляров

Класс CSV имеет три группы методов экземпляров:

• Внутренние методы экземпляров.

• Методы, включенные модулем Enumerable.

• Методы, делегированные классу IO. См. ниже.

Делегированные методы

Для удобства объект CSV делегирует многие методы классу IO. (Несколько имеют обёртку «защитного кода» в CSV.) Вы можете вызвать:

• IO#binmode

• binmode?

• IO#close

• IO#close_read

• IO#close_write

• IO#closed?

• eof

• eof?

• IO#external_encoding

• IO#fcntl

• IO#fileno

• flock

• IO#flush

• IO#fsync

• IO#internal_encoding

• ioctl

• IO#isatty

• path

• IO#pid

• IO#pos

• IO#pos=

• IO#reopen

• rewind

• IO#seek

• stat

• IO#string

• IO#sync

• IO#sync=

• IO#tell

• to_i

• to_io

• IO#truncate

• IO#tty?

Параметры

Значения параметров по умолчанию:

DEFAULT_OPTIONS = {
  # For both parsing and generating.
  col_sep:            ",",
  row_sep:            :auto,
  quote_char:         '"',
  # For parsing.
  field_size_limit:   nil,
  converters:         nil,
  unconverted_fields: nil,
  headers:            false,
  return_headers:     false,
  header_converters:  nil,
  skip_blanks:        false,
  skip_lines:         nil,
  liberal_parsing:    false,
  nil_value:          nil,
  empty_value:        "",
  strip:              false,
  # For generating.
  write_headers:      nil,
  quote_empty:        true,
  force_quotes:       false,
  write_converters:   nil,
  write_nil_value:    nil,
  write_empty_value:  "",
}

Параметры разбора

Параметры разбора, подробно описанные ниже, включают:

• row_sep: Указывает разделитель строк; используется для разделения строк.

• col_sep: Указывает разделитель столбцов; используется для разделения полей.

• quote_char: Указывает символ кавычки; используется для кавычек полей.

• field_size_limit: Указывает максимальный размер поля + 1, разрешённый. Устарело с версии 3.2.3. Используйте max_field_size вместо этого.

• max_field_size: Указывает максимальный размер поля.

• converters: Указывает преобразователи полей, которые должны быть использованы.

• unconverted_fields: Указывает, должны ли быть доступны необработанные поля.

• headers: Указывает, содержит ли данные заголовки, или задаёт сами заголовки.

• return_headers: Указывает, должны ли возвращаться заголовки.

• header_converters: Указывает преобразователи заголовков, которые должны быть использованы.

• skip_blanks: Указывает, должны ли игнорироваться пустые строки.

• skip_lines: Указывает, как должны распознаваться строки комментариев.

• strip: Указывает, должны ли удаляться ведущие и хвостовые пробелы из полей. Это должно быть совместимо с col_sep; если это не так, будет поднято исключение ArgumentError.

• liberal_parsing: Указывает, должен ли CSV пытаться разобрать несовместимые данные.

• nil_value: Указывает объект, который должен быть подставлен вместо каждого нулевого (без текста) поля.

• empty_value: Указывает объект, который должен быть подставлен вместо каждого пустого поля.

Параметр row_sep

Указывает разделитель строк, строку или символ :auto (см. ниже), который будет использоваться как при разборе, так и при генерации.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:row_sep) # => :auto

Когда row_sep является строкой, эта строка становится разделителем строк. String будет преобразовано в Encoding данных перед использованием.

Использование "\n":

row_sep = "\n"
str = CSV.generate(row_sep: row_sep) do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo,0\nbar,1\nbaz,2\n"
ary = CSV.parse(str)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Использование | (пайп):

row_sep = '|'
str = CSV.generate(row_sep: row_sep) do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo,0|bar,1|baz,2|"
ary = CSV.parse(str, row_sep: row_sep)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Использование -- (два дефиса):

row_sep = '--'
str = CSV.generate(row_sep: row_sep) do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo,0--bar,1--baz,2--"
ary = CSV.parse(str, row_sep: row_sep)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Использование '' (пустая строка):

row_sep = ''
str = CSV.generate(row_sep: row_sep) do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo,0bar,1baz,2"
ary = CSV.parse(str, row_sep: row_sep)
ary # => [["foo", "0bar", "1baz", "2"]]

Когда row_sep является символом :auto (по умолчанию), генерация использует "\n" в качестве разделителя строк:

str = CSV.generate do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo,0\nbar,1\nbaz,2\n"

С другой стороны, парсинг вызывает автоматическое определение разделителя строк.

Автоматическое определение считывает данные впереди, ища следующую последовательность \r\n, \n, или \r. Последовательность будет выбрана, даже если она встречается в цитируемом поле, предполагая, что там будут те же окончания строк.

Пример:

str = CSV.generate do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo,0\nbar,1\nbaz,2\n"
ary = CSV.parse(str)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Значение $INPUT_RECORD_SEPARATOR ($/) используется по умолчанию, если выполняется любое из следующих условий:

• Ни одна из этих последовательностей не найдена.

• Data является ARGF, STDIN, STDOUT, или STDERR.

• Поток доступен только для вывода.

Очевидно, обнаружение занимает некоторое время. Set вручную, если скорость важна. Также обратите внимание, что объекты IO должны открываться в двоичном режиме в Windows, если эта функция будет использоваться, так как перевод окончания строки может вызвать проблемы с возвратом позиции документа к тому месту, где она была до предварительного чтения.

Выбрасывает исключение, если заданное значение не может быть преобразовано в строку:

row_sep = BasicObject.new
# Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
CSV.generate(ary, row_sep: row_sep)
# Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
CSV.parse(str, row_sep: row_sep)

Параметр col_sep

Указывает строковый разделитель полей, используемый как для парсинга, так и для генерации. Строка будет преобразована в кодировку данных перед использованием.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:col_sep) # => "," (comma)

Использование значения по умолчанию (запятая):

str = CSV.generate do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo,0\nbar,1\nbaz,2\n"
ary = CSV.parse(str)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Использование : (двоеточие):

col_sep = ':'
str = CSV.generate(col_sep: col_sep) do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo:0\nbar:1\nbaz:2\n"
ary = CSV.parse(str, col_sep: col_sep)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Использование :: (два двоеточия):

col_sep = '::'
str = CSV.generate(col_sep: col_sep) do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo::0\nbar::1\nbaz::2\n"
ary = CSV.parse(str, col_sep: col_sep)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Использование '' (пустая строка):

col_sep = ''
str = CSV.generate(col_sep: col_sep) do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo0\nbar1\nbaz2\n"

Выбрасывает исключение при парсинге с пустой строкой:

col_sep = ''
# Raises ArgumentError (:col_sep must be 1 or more characters: "")
CSV.parse("foo0\nbar1\nbaz2\n", col_sep: col_sep)

Выбрасывает исключение, если заданное значение не может быть преобразовано в строку:

col_sep = BasicObject.new
# Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
CSV.generate(line, col_sep: col_sep)
# Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
CSV.parse(str, col_sep: col_sep)

Параметр quote_char

Указывает символ (строка длиной 1), используемый для цитирования полей как при парсинге, так и при генерации. Эта String будет преобразована в кодировку данных перед использованием.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:quote_char) # => "\"" (double quote)

Это полезно для приложения, которое неправильно использует ' (одинарную кавычку) для цитирования полей вместо правильного " (двойной кавычки).

Использование значения по умолчанию (двойная кавычка):

str = CSV.generate do |csv|
  csv << ['foo', 0]
  csv << ["'bar'", 1]
  csv << ['"baz"', 2]
end
str # => "foo,0\n'bar',1\n\"\"\"baz\"\"\",2\n"
ary = CSV.parse(str)
ary # => [["foo", "0"], ["'bar'", "1"], ["\"baz\"", "2"]]

Использование ' (одинарная кавычка):

quote_char = "'"
str = CSV.generate(quote_char: quote_char) do |csv|
  csv << ['foo', 0]
  csv << ["'bar'", 1]
  csv << ['"baz"', 2]
end
str # => "foo,0\n'''bar''',1\n\"baz\",2\n"
ary = CSV.parse(str, quote_char: quote_char)
ary # => [["foo", "0"], ["'bar'", "1"], ["\"baz\"", "2"]]

Выбрасывает исключение, если длина строки больше 1:

# Raises ArgumentError (:quote_char has to be nil or a single character String)
CSV.new('', quote_char: 'xx')

Выбрасывает исключение, если значение не является строкой:

# Raises ArgumentError (:quote_char has to be nil or a single character String)
CSV.new('', quote_char: :foo)

Параметр field_size_limit

Указывает целочисленный предел размера поля.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:field_size_limit) # => nil

Это максимальный размер CSV, который будет читать впереди, ища закрывающую кавычку поля. (На самом деле, он читает до первого окончания строки за пределами этого размера.) Если кавычка не может быть найдена в пределах ограничения CSV будет выброшено исключение MalformedCSVError, предполагая, что данные неверны. Вы можете использовать этот предел, чтобы предотвратить то, что по сути является атакой типа DoS на парсер. Однако это ограничение может привести к отказу от законного парсинга; поэтому значение по умолчанию равно nil (без ограничения).

Для примеров в этом разделе:

str = <<~EOT
  "a","b"
  "
  2345
  ",""
EOT
str # => "\"a\",\"b\"\n\"\n2345\n\",\"\"\n"

Использование значения по умолчанию nil:

ary = CSV.parse(str)
ary # => [["a", "b"], ["\n2345\n", ""]]

Использование 50:

field_size_limit = 50
ary = CSV.parse(str, field_size_limit: field_size_limit)
ary # => [["a", "b"], ["\n2345\n", ""]]

Выбрасывает исключение, если поле слишком длинное:

big_str = "123456789\n" * 1024
# Raises CSV::MalformedCSVError (Field size exceeded in line 1.)
CSV.parse('valid,fields,"' + big_str + '"', field_size_limit: 2048)

Параметр converters

Указывает преобразователи, которые будут использоваться при парсинге полей. См. Преобразователи полей

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:converters) # => nil

Значение может быть именем преобразователя поля (см. Предопределённые преобразователи):

str = '1,2,3'
# Without a converter
array = CSV.parse_line(str)
array # => ["1", "2", "3"]
# With built-in converter :integer
array = CSV.parse_line(str, converters: :integer)
array # => [1, 2, 3]

Значение может быть списком преобразователей (см. Списки преобразователей):

str = '1,3.14159'
# Without converters
array = CSV.parse_line(str)
array # => ["1", "3.14159"]
# With built-in converters
array = CSV.parse_line(str, converters: [:integer, :float])
array # => [1, 3.14159]

Значение может быть пользовательским преобразователем Proc: (см. Пользовательские преобразователи полей):

str = ' foo  ,  bar  ,  baz  '
# Without a converter
array = CSV.parse_line(str)
array # => [" foo  ", "  bar  ", "  baz  "]
# With a custom converter
array = CSV.parse_line(str, converters: proc {|field| field.strip })
array # => ["foo", "bar", "baz"]

См. также Пользовательские преобразователи полей

Выбрасывает исключение, если преобразователь не является именем преобразователя или Proc:

str = 'foo,0'
# Raises NoMethodError (undefined method `arity' for nil:NilClass)
CSV.parse(str, converters: :foo)

Параметр unconverted_fields

Указывает булевое значение, определяющее, должны ли быть доступны значения полей без преобразования.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:unconverted_fields) # => nil

Значения полей без преобразования — это значения, найденные в исходных данных до выполнения любых преобразований, выполненных с помощью параметра converters.

Когда параметр unconverted_fields имеет значение true, каждый возвращённый ряд (массив или CSV::Row) имеет добавленный метод unconverted_fields, который возвращает значения полей без преобразования:

str = <<-EOT
foo,0
bar,1
baz,2
EOT
# Without unconverted_fields
csv = CSV.parse(str, converters: :integer)
csv # => [["foo", 0], ["bar", 1], ["baz", 2]]
csv.first.respond_to?(:unconverted_fields) # => false
# With unconverted_fields
csv = CSV.parse(str, converters: :integer, unconverted_fields: true)
csv # => [["foo", 0], ["bar", 1], ["baz", 2]]
csv.first.respond_to?(:unconverted_fields) # => true
csv.first.unconverted_fields # => ["foo", "0"]

Параметр headers

Указывает булево значение, символ, массив или строку, используемые для определения заголовков столбцов.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:headers) # => false

Без headers:

str = <<-EOT
Name,Count
foo,0
bar,1
bax,2
EOT
csv = CSV.new(str)
csv # => #<CSV io_type:StringIO encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\n" quote_char:"\"">
csv.headers # => nil
csv.shift # => ["Name", "Count"]

Если установлено значение true или символ :first_row, первая строка данных рассматривается как строка заголовков:

str = <<-EOT
Name,Count
foo,0
bar,1
bax,2
EOT
csv = CSV.new(str, headers: true)
csv # => #<CSV io_type:StringIO encoding:UTF-8 lineno:2 col_sep:"," row_sep:"\n" quote_char:"\"" headers:["Name", "Count"]>
csv.headers # => ["Name", "Count"]
csv.shift # => #<CSV::Row "Name":"bar" "Count":"1">

Если задан массив, элементы массива рассматриваются как заголовки:

str = <<-EOT
foo,0
bar,1
bax,2
EOT
csv = CSV.new(str, headers: ['Name', 'Count'])
csv
csv.headers # => ["Name", "Count"]
csv.shift # => #<CSV::Row "Name":"bar" "Count":"1">

Если задана строка str, вызывается метод CSV::parse_line(str, options) с текущим options, и возвращённый массив рассматривается как заголовки:

str = <<-EOT
foo,0
bar,1
bax,2
EOT
csv = CSV.new(str, headers: 'Name,Count')
csv
csv.headers # => ["Name", "Count"]
csv.shift # => #<CSV::Row "Name":"bar" "Count":"1">

Параметр return_headers

Указывает булевое значение, определяющее, возвращает ли метод shift строку заголовков или игнорирует её.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:return_headers) # => false

Примеры:

str = <<-EOT
Name,Count
foo,0
bar,1
bax,2
EOT
# Without return_headers first row is str.
csv = CSV.new(str, headers: true)
csv.shift # => #<CSV::Row "Name":"foo" "Count":"0">
# With return_headers first row is headers.
csv = CSV.new(str, headers: true, return_headers: true)
csv.shift # => #<CSV::Row "Name":"Name" "Count":"Count">

Параметр header_converters

Указывает преобразователи, используемые при парсинге заголовков. См. Преобразователи заголовков

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:header_converters) # => nil

Функционально идентично параметру converters, за исключением:

• Преобразователи применяются только к строке заголовков.

• Встроенные преобразователи заголовков — это :downcase и :symbol.

Этот раздел предполагает предварительное выполнение:

str = <<-EOT
Name,Value
foo,0
bar,1
baz,2
EOT
# With no header converter
table = CSV.parse(str, headers: true)
table.headers # => ["Name", "Value"]

Значение может быть именем преобразователя заголовка (см. Предопределённые преобразователи):

table = CSV.parse(str, headers: true, header_converters: :downcase)
table.headers # => ["name", "value"]

Значение может быть списком преобразователей (см. Списки преобразователей):

header_converters = [:downcase, :symbol]
table = CSV.parse(str, headers: true, header_converters: header_converters)
table.headers # => [:name, :value]

Значение может быть пользовательским преобразователем Proc (см. Пользовательские преобразователи заголовков):

upcase_converter = proc {|field| field.upcase }
table = CSV.parse(str, headers: true, header_converters: upcase_converter)
table.headers # => ["NAME", "VALUE"]

См. также Пользовательские преобразователи заголовков

Параметр skip_blanks

Указывает булево значение, определяющее, будут ли игнорироваться пустые строки в вводе; строка, содержащая разделитель столбцов, не считается пустой.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:skip_blanks) # => false

См. также параметр skiplines.

Для примеров в этом разделе:

str = <<-EOT
foo,0

bar,1
baz,2

,
EOT

Использование значения по умолчанию, false:

ary = CSV.parse(str)
ary # => [["foo", "0"], [], ["bar", "1"], ["baz", "2"], [], [nil, nil]]

Использование true:

ary = CSV.parse(str, skip_blanks: true)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"], [nil, nil]]

Использование истинного значения:

ary = CSV.parse(str, skip_blanks: :foo)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"], [nil, nil]]

Параметр skip_lines

Указывает объект для определения строк комментариев во вводе, которые должны быть пропущены:

• Если Regexp, игнорируются строки, которые соответствуют ему.

• Если String, он преобразуется в Regexp, игнорируются строки, которые соответствуют ему.

• Если nil, никакие строки не считаются комментариями.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:skip_lines) # => nil

Для примеров в этом разделе:

str = <<-EOT
# Comment
foo,0
bar,1
baz,2
# Another comment
EOT
str # => "# Comment\nfoo,0\nbar,1\nbaz,2\n# Another comment\n"

Использование значения по умолчанию, nil:

ary = CSV.parse(str)
ary # => [["# Comment"], ["foo", "0"], ["bar", "1"], ["baz", "2"], ["# Another comment"]]

Использование Regexp:

ary = CSV.parse(str, skip_lines: /^#/)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Использование String:

ary = CSV.parse(str, skip_lines: '#')
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Выбрасывает исключение, если задан объект, который не является Regexp, String или nil:

# Raises ArgumentError (:skip_lines has to respond to #match: 0)
CSV.parse(str, skip_lines: 0)

Параметр strip

Указывает булево значение, определяющее, удаляется ли пробел из каждого входного поля.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:strip) # => false

При значении по умолчанию false:

ary = CSV.parse_line(' a , b ')
ary # => [" a ", " b "]

При значении true:

ary = CSV.parse_line(' a , b ', strip: true)
ary # => ["a", "b"]

Параметр liberal_parsing

Указывает булево значение, определяющее, будет ли CSV пытаться разобрать входной данные, не соответствующие RFC 4180, такие как двойные кавычки в нецитируемых полях.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:liberal_parsing) # => false

Для примеров в этом разделе:

str = 'is,this "three, or four",fields'

Без liberal_parsing:

# Raises CSV::MalformedCSVError (Illegal quoting in str 1.)
CSV.parse_line(str)

С liberal_parsing:

ary = CSV.parse_line(str, liberal_parsing: true)
ary # => ["is", "this \"three", " or four\"", "fields"]

Параметр nil_value

Указывает объект, который должен быть подставлен для каждого нулевого (без текста) поля.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:nil_value) # => nil

При значении по умолчанию nil:

CSV.parse_line('a,,b,,c') # => ["a", nil, "b", nil, "c"]

С другим объектом:

CSV.parse_line('a,,b,,c', nil_value: 0) # => ["a", 0, "b", 0, "c"]

Параметр empty_value

Указывает объект, который должен быть подставлен для каждого поля, содержащего пустую строку.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:empty_value) # => "" (empty string)

При значении по умолчанию "":

CSV.parse_line('a,"",b,"",c') # => ["a", "", "b", "", "c"]

С другим объектом:

CSV.parse_line('a,"",b,"",c', empty_value: 'x') # => ["a", "x", "b", "x", "c"]

Параметры для генерации

Параметры для генерации, подробно описанные ниже, включают:

• row_sep: Указывает разделитель строк; используется для разделения строк.

• col_sep: Указывает разделитель столбцов; используется для разделения полей.

• quote_char: Указывает символ кавычек; используется для кавычек полей.

• write_headers: Указывает, должны ли быть записаны заголовки.

• force_quotes: Указывает, должно ли каждое выходное поле заключаться в кавычки.

• quote_empty: Указывает, должны ли заключаться в кавычки пустые выходные поля.

• write_converters: Указывает преобразователи полей, которые должны быть использованы при записи.

• write_nil_value: Указывает объект, который должен быть подставлен для каждого поля со значением nil.

• write_empty_value: Указывает объект, который должен быть подставлен для каждого пустого поля.

Параметр row_sep

Указывает разделитель строк, строку или символ :auto (см. ниже), используемый как для разбора, так и для генерации.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:row_sep) # => :auto

Если row_sep является строкой, эта строка становится разделителем строк. Строка будет транскодирована в кодировку данных String перед использованием.

Использование "\n":

row_sep = "\n"
str = CSV.generate(row_sep: row_sep) do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo,0\nbar,1\nbaz,2\n"
ary = CSV.parse(str)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Использование | (пайп):

row_sep = '|'
str = CSV.generate(row_sep: row_sep) do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo,0|bar,1|baz,2|"
ary = CSV.parse(str, row_sep: row_sep)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Использование -- (два дефиса):

row_sep = '--'
str = CSV.generate(row_sep: row_sep) do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo,0--bar,1--baz,2--"
ary = CSV.parse(str, row_sep: row_sep)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Использование '' (пустая строка):

row_sep = ''
str = CSV.generate(row_sep: row_sep) do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo,0bar,1baz,2"
ary = CSV.parse(str, row_sep: row_sep)
ary # => [["foo", "0bar", "1baz", "2"]]

Если row_sep является символом :auto (по умолчанию), для генерации используется "\n" как разделитель строк:

str = CSV.generate do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo,0\nbar,1\nbaz,2\n"

Разбор, с другой стороны, вызывает автоматическое определение разделителя строк.

Автоматическое определение считывает данные вперёд, в поисках последовательности \r\n, \n, или \r. Последовательность будет выбрана, даже если она встречается в цитируемом поле, предполагая, что у вас там будут одинаковые символы конца строки.

Пример:

str = CSV.generate do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo,0\nbar,1\nbaz,2\n"
ary = CSV.parse(str)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

По умолчанию $INPUT_RECORD_SEPARATOR ($/) используется, если выполняется одно из следующих условий:

• Ни одна из этих последовательностей не найдена.

• Data является ARGF, STDIN, STDOUT, или STDERR.

• Поток доступен только для вывода.

Очевидно, обнаружение занимает некоторое время. Используйте Set вручную, если скорость важна. Обратите также внимание, что объекты IO должны открываться в двоичном режиме в Windows, если эта функция будет использоваться, так как перевод символов конца строки может вызвать проблемы с возвратом положения документа к тому, где оно было до считывания вперед.

Выбрасывает исключение, если заданное значение не может быть преобразовано в строку:

row_sep = BasicObject.new
# Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
CSV.generate(ary, row_sep: row_sep)
# Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
CSV.parse(str, row_sep: row_sep)

Параметр col_sep

Указывает строковый разделитель полей, используемый как для разбора, так и для генерации. Строка будет транскодирована в кодировку данных перед использованием.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:col_sep) # => "," (comma)

Использование значения по умолчанию (запятая):

str = CSV.generate do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo,0\nbar,1\nbaz,2\n"
ary = CSV.parse(str)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Использование : (двоеточие):

col_sep = ':'
str = CSV.generate(col_sep: col_sep) do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo:0\nbar:1\nbaz:2\n"
ary = CSV.parse(str, col_sep: col_sep)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Использование :: (два двоеточия):

col_sep = '::'
str = CSV.generate(col_sep: col_sep) do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo::0\nbar::1\nbaz::2\n"
ary = CSV.parse(str, col_sep: col_sep)
ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Использование '' (пустая строка):

col_sep = ''
str = CSV.generate(col_sep: col_sep) do |csv|
  csv << [:foo, 0]
  csv << [:bar, 1]
  csv << [:baz, 2]
end
str # => "foo0\nbar1\nbaz2\n"

Выбрасывает исключение при разборе с пустой строкой:

col_sep = ''
# Raises ArgumentError (:col_sep must be 1 or more characters: "")
CSV.parse("foo0\nbar1\nbaz2\n", col_sep: col_sep)

Выбрасывает исключение, если заданное значение не может быть преобразовано в строку:

col_sep = BasicObject.new
# Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
CSV.generate(line, col_sep: col_sep)
# Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
CSV.parse(str, col_sep: col_sep)

Параметр quote_char

Указывает символ (строка длиной 1), используемый для цитирования полей как при разборе, так и при генерации. Эта строка будет транскодирована в кодировку данных перед использованием.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:quote_char) # => "\"" (double quote)

Это полезно для приложения, которое неправильно использует ' (одинарную кавычку) для цитирования полей вместо правильного " (двойной кавычки).

Использование значения по умолчанию (двойная кавычка):

str = CSV.generate do |csv|
  csv << ['foo', 0]
  csv << ["'bar'", 1]
  csv << ['"baz"', 2]
end
str # => "foo,0\n'bar',1\n\"\"\"baz\"\"\",2\n"
ary = CSV.parse(str)
ary # => [["foo", "0"], ["'bar'", "1"], ["\"baz\"", "2"]]

Использование ' (одинарная кавычка):

quote_char = "'"
str = CSV.generate(quote_char: quote_char) do |csv|
  csv << ['foo', 0]
  csv << ["'bar'", 1]
  csv << ['"baz"', 2]
end
str # => "foo,0\n'''bar''',1\n\"baz\",2\n"
ary = CSV.parse(str, quote_char: quote_char)
ary # => [["foo", "0"], ["'bar'", "1"], ["\"baz\"", "2"]]

Выбрасывает исключение, если длина строки больше 1:

# Raises ArgumentError (:quote_char has to be nil or a single character String)
CSV.new('', quote_char: 'xx')

Выбрасывает исключение, если значение не является строкой:

# Raises ArgumentError (:quote_char has to be nil or a single character String)
CSV.new('', quote_char: :foo)

Параметр write_headers

Указывает булево значение, определяющее, включать ли строку заголовков в вывод; игнорируется, если заголовков нет.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:write_headers) # => nil

Без write_headers:

file_path = 't.csv'
CSV.open(file_path,'w',
    :headers => ['Name','Value']
  ) do |csv|
    csv << ['foo', '0']
end
CSV.open(file_path) do |csv|
  csv.shift
end # => ["foo", "0"]

С write_headers:

CSV.open(file_path,'w',
    :write_headers=> true,
    :headers => ['Name','Value']
  ) do |csv|
    csv << ['foo', '0']
end
CSV.open(file_path) do |csv|
  csv.shift
end # => ["Name", "Value"]

Параметр force_quotes

Указывает булево значение, определяющее, должно ли каждое выходное поле заключаться в двойные кавычки.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:force_quotes) # => false

Примеры в этом разделе:

ary = ['foo', 0, nil]

Использование значения по умолчанию, false:

str = CSV.generate_line(ary)
str # => "foo,0,\n"

Использование true:

str = CSV.generate_line(ary, force_quotes: true)
str # => "\"foo\",\"0\",\"\"\n"

Параметр quote_empty

Указывает булево значение, определяющее, должно ли пустое значение заключаться в двойные кавычки.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:quote_empty) # => true

Со значением по умолчанию true:

CSV.generate_line(['"', ""]) # => "\"\"\"\",\"\"\n"

Со значением false:

CSV.generate_line(['"', ""], quote_empty: false) # => "\"\"\"\",\n"

Параметр write_converters

Указывает преобразователи, которые будут использоваться при генерации полей. См. Преобразователи для записи

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:write_converters) # => nil

Без преобразователя для записи:

str = CSV.generate_line(["\na\n", "\tb\t", " c "])
str # => "\"\na\n\",\tb\t, c \n"

С преобразователем для записи:

strip_converter = proc {|field| field.strip }
str = CSV.generate_line(["\na\n", "\tb\t", " c "], write_converters: strip_converter)
str # => "a,b,c\n"

С двумя преобразователями для записи (вызываются в порядке):

upcase_converter = proc {|field| field.upcase }
downcase_converter = proc {|field| field.downcase }
write_converters = [upcase_converter, downcase_converter]
str = CSV.generate_line(['a', 'b', 'c'], write_converters: write_converters)
str # => "a,b,c\n"

См. также Преобразователи для записи

Выбрасывает исключение, если преобразователь возвращает значение, которое не является nil или не может быть преобразовано в строку:

bad_converter = proc {|field| BasicObject.new }
# Raises NoMethodError (undefined method `is_a?' for #<BasicObject:>)
CSV.generate_line(['a', 'b', 'c'], write_converters: bad_converter)#

Параметр write_nil_value

Указывает объект, который должен быть подставлен для каждого поля со значением nil.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:write_nil_value) # => nil

Без параметра:

str = CSV.generate_line(['a', nil, 'c', nil])
str # => "a,,c,\n"

С параметром:

str = CSV.generate_line(['a', nil, 'c', nil], write_nil_value: "x")
str # => "a,x,c,x\n"

Параметр write_empty_value

Указывает объект, который должен быть подставлен для каждого поля со значением пустой строки.

Значение по умолчанию:

CSV::DEFAULT_OPTIONS.fetch(:write_empty_value) # => ""

Без параметра:

str = CSV.generate_line(['a', '', 'c', ''])
str # => "a,\"\",c,\"\"\n"

С параметром:

str = CSV.generate_line(['a', '', 'c', ''], write_empty_value: "x")
str # => "a,x,c,x\n"

CSV с заголовками

CSV позволяет указать имена столбцов файла CSV, либо взяв их из данных, либо предоставив отдельно. Если заголовки указаны, методы чтения возвращают экземпляр CSV::Table, состоящий из CSV::Row.

# Headers are part of data
data = CSV.parse(<<~ROWS, headers: true)
  Name,Department,Salary
  Bob,Engineering,1000
  Jane,Sales,2000
  John,Management,5000
ROWS

data.class      #=> CSV::Table
data.first      #=> #<CSV::Row "Name":"Bob" "Department":"Engineering" "Salary":"1000">
data.first.to_h #=> {"Name"=>"Bob", "Department"=>"Engineering", "Salary"=>"1000"}

# Headers provided by developer
data = CSV.parse('Bob,Engineering,1000', headers: %i[name department salary])
data.first      #=> #<CSV::Row name:"Bob" department:"Engineering" salary:"1000">

Преобразователи

По умолчанию каждое значение (поле или заголовок), прочитанное из CSV, преобразуется в строку. Вы можете использовать преобразователь полей или преобразователь заголовков для перехвата и изменения прочитанных значений:

• См. Преобразователи полей.

• См. Преобразователи заголовков.

Также по умолчанию каждое значение, которое должно быть записано во время генерации, записывается «как есть». Вы можете использовать преобразователь записи для изменения значений перед записью.

• См. Преобразователи для записи.

Указание преобразователей

Преобразователи для разбора или генерации можно указать в аргументе options различных методов CSV:

• Параметр converters для преобразования прочитанных значений полей.

• Параметр header_converters для преобразования прочитанных значений заголовков.

• Параметр write_converters для преобразования значений, которые будут записаны (сгенерированы).

Существуют три формы указания преобразователей:

• Процедура преобразования: исполняемый код, используемый для преобразования.

• Имя преобразователя: имя сохранённого преобразователя.

• Список преобразователей: массив процедур преобразования, имён преобразователей и списков преобразователей.

Процедуры преобразования

Эта процедура преобразования, strip_converter, принимает значение field и возвращает field.strip:

strip_converter = proc {|field| field.strip }

В этом вызове CSV.parse, ключевой аргумент converters: string_converter указывает, что:

• Процедура string_converter должна вызываться для каждого прочитанного поля.

• Возвращаемое значение преобразователя должно заменить значение field.

Пример:

string = " foo , 0 \n bar , 1 \n baz , 2 \n"
array = CSV.parse(string, converters: strip_converter)
array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Процедура преобразования может принимать второй аргумент, field_info, содержащий информацию о поле. Эта модифицированная strip_converter демонстрирует свои аргументы:

strip_converter = proc do |field, field_info|
  p [field, field_info]
  field.strip
end
string = " foo , 0 \n bar , 1 \n baz , 2 \n"
array = CSV.parse(string, converters: strip_converter)
array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Вывод:

[" foo ", #<struct CSV::FieldInfo index=0, line=1, header=nil>]
[" 0 ", #<struct CSV::FieldInfo index=1, line=1, header=nil>]
[" bar ", #<struct CSV::FieldInfo index=0, line=2, header=nil>]
[" 1 ", #<struct CSV::FieldInfo index=1, line=2, header=nil>]
[" baz ", #<struct CSV::FieldInfo index=0, line=3, header=nil>]
[" 2 ", #<struct CSV::FieldInfo index=1, line=3, header=nil>]

Каждый объект CSV::FieldInfo показывает:

• Индекс поля (от 0).

• Индекс строки (от 1).

• Заголовок поля, если он есть.

Сохранённые преобразователи

Преобразователь может получить имя и быть сохранён в структуре, где методы разбора могут найти его по имени.

Структура хранения преобразователей полей — хеш CSV::Converters. Она содержит несколько встроенных процедур преобразования:

• :integer: преобразует каждое целое число, встроенное в строку, в истинное целое число.

• :float: преобразует каждое дробное число, встроенное в строку, в истинное дробное число.

• :date: преобразует каждую дату, встроенную в строку, в истинную дату.

• :date_time: преобразует каждую дату и время, встроеные в строку, в истинное DateTime.

. В этом примере создаётся процедура преобразования, а затем она сохраняется:

strip_converter = proc {|field| field.strip }
CSV::Converters[:strip] = strip_converter

Затем метод разбора может сослаться на преобразователь по его имени, :strip:

string = " foo , 0 \n bar , 1 \n baz , 2 \n"
array = CSV.parse(string, converters: :strip)
array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Структура хранения преобразователей заголовков — хеш CSV::HeaderConverters, которая работает аналогично. Она также содержит встроенные процедуры преобразования:

• :downcase: принудительно приводит каждый заголовок к нижнему регистру.

• :symbol: преобразует каждый заголовок в символ.

Для структуры хранения заголовков записи такой структуры нет.

Для того, чтобы методы парсинга получили доступ к сохранённым преобразователям в неглавных Ractors, структура хранения должна быть сначала сделана совместной. Поэтому, Ractor.make_shareable(CSV::Converters) и Ractor.make_shareable(CSV::HeaderConverters) должны быть вызваны перед созданием Ractors, которые используют преобразователи, сохранённые в этих структурах. (Поскольку преобразование структур хранения в общие включает их заморозку, все пользовательские преобразователи, которые должны быть использованы, должны быть добавлены в первую очередь.)

Списки преобразователей

Список преобразователей — это массив, который может включать в себя любой набор:

• Процедуры преобразования.

• Имена сохранённых преобразователей.

• Вложенные списки преобразователей.

Примеры:

numeric_converters = [:integer, :float]
date_converters = [:date, :date_time]
[numeric_converters, strip_converter]
[strip_converter, date_converters, :float]

Как и процедура преобразования, список преобразователей может быть назван и сохранён как в CSV::Converters, так и в CSV::HeaderConverters:

CSV::Converters[:custom] = [strip_converter, date_converters, :float]
CSV::HeaderConverters[:custom] = [:downcase, :symbol]

Существует два встроенных списка преобразователей:

CSV::Converters[:numeric] # => [:integer, :float]
CSV::Converters[:all] # => [:date_time, :numeric]

Преобразователи полей

Без преобразования все парсированные поля во всех строках становятся строками:

string = "foo,0\nbar,1\nbaz,2\n"
ary = CSV.parse(string)
ary # => # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Когда вы указываете преобразователь поля, каждое парсированное поле передаётся в преобразователь; его возвращаемое значение становится сохранённым значением для поля. Преобразователь может, например, преобразовать целое число, встроенное в строку, в истинное целое число. (На самом деле, именно это делает встроенный преобразователь полей :integer.)

Есть три способа использования преобразователей полей.

• Использование параметра converters с методом парсинга:

  ary = CSV.parse(string, converters: :integer)
  ary # => [0, 1, 2] # => [["foo", 0], ["bar", 1], ["baz", 2]]
  

• Использование параметра converters с новым экземпляром CSV:

  csv = CSV.new(string, converters: :integer)
  # Field converters in effect:
  csv.converters # => [:integer]
  csv.read # => [["foo", 0], ["bar", 1], ["baz", 2]]
  

• Использование метода convert для добавления преобразователя поля к экземпляру CSV:

  csv = CSV.new(string)
  # Add a converter.
  csv.convert(:integer)
  csv.converters # => [:integer]
  csv.read # => [["foo", 0], ["bar", 1], ["baz", 2]]
  

Установка преобразователя поля не влияет на уже прочитанные строки:

csv = CSV.new(string)
csv.shift # => ["foo", "0"]
# Add a converter.
csv.convert(:integer)
csv.converters # => [:integer]
csv.read # => [["bar", 1], ["baz", 2]]

Есть дополнительные встроенные преобразователи, а также поддерживаются пользовательские преобразователи.

Встроенные преобразователи полей

Встроенные преобразователи полей находятся в хэше CSV::Converters:

• Каждый ключ — имя преобразователя поля.

• Каждое значение — одно из:

  • Преобразователь поля Proc.

  • Массив имён преобразователей полей.

Вывод:

CSV::Converters.each_pair do |name, value|
  if value.kind_of?(Proc)
    p [name, value.class]
  else
    p [name, value]
  end
end

Выход:

[:integer, Proc]
[:float, Proc]
[:numeric, [:integer, :float]]
[:date, Proc]
[:date_time, Proc]
[:all, [:date_time, :numeric]]

Каждый из этих преобразователей преобразует значения в UTF-8 перед попыткой преобразования. Если значение не может быть преобразовано в UTF-8, преобразование завершится неудачно, и значение останется не преобразованным.

Преобразователь :integer преобразует каждое поле, которое принимает Integer():

data = '0,1,2,x'
# Without the converter
csv = CSV.parse_line(data)
csv # => ["0", "1", "2", "x"]
# With the converter
csv = CSV.parse_line(data, converters: :integer)
csv # => [0, 1, 2, "x"]

Преобразователь :float преобразует каждое поле, которое принимает Float():

data = '1.0,3.14159,x'
# Without the converter
csv = CSV.parse_line(data)
csv # => ["1.0", "3.14159", "x"]
# With the converter
csv = CSV.parse_line(data, converters: :float)
csv # => [1.0, 3.14159, "x"]

Преобразователь :numeric преобразует с помощью :integer и :float.

Преобразователь :date преобразует каждое поле, которое принимает Date::parse:

data = '2001-02-03,x'
# Without the converter
csv = CSV.parse_line(data)
csv # => ["2001-02-03", "x"]
# With the converter
csv = CSV.parse_line(data, converters: :date)
csv # => [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, "x"]

Преобразователь :date_time преобразует каждое поле, которое принимает DateTime::parse:

data = '2020-05-07T14:59:00-05:00,x'
# Without the converter
csv = CSV.parse_line(data)
csv # => ["2020-05-07T14:59:00-05:00", "x"]
# With the converter
csv = CSV.parse_line(data, converters: :date_time)
csv # => [#<DateTime: 2020-05-07T14:59:00-05:00 ((2458977j,71940s,0n),-18000s,2299161j)>, "x"]

Преобразователь :numeric преобразует с помощью :date_time и :numeric.

Как показано выше, метод convert добавляет преобразователи к экземпляру CSV, а метод converters возвращает массив действующих преобразователей:

csv = CSV.new('0,1,2')
csv.converters # => []
csv.convert(:integer)
csv.converters # => [:integer]
csv.convert(:date)
csv.converters # => [:integer, :date]

Пользовательские преобразователи полей

Вы можете определить пользовательский преобразователь поля:

strip_converter = proc {|field| field.strip }
string = " foo , 0 \n bar , 1 \n baz , 2 \n"
array = CSV.parse(string, converters: strip_converter)
array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Вы можете зарегистрировать преобразователь в хэше Converters, что позволяет ссылаться на него по имени:

CSV::Converters[:strip] = strip_converter
string = " foo , 0 \n bar , 1 \n baz , 2 \n"
array = CSV.parse(string, converters: :strip)
array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]

Преобразователи заголовков

Преобразователи заголовков работают только с заголовками (а не с другими строками).

Существует три способа использования преобразователей заголовков; эти примеры используют встроенный преобразователь заголовков :downcase, который преобразует каждый парсированный заголовок в нижний регистр.

• Параметр header_converters с методом парсинга singleton:

  string = "Name,Count\nFoo,0\n,Bar,1\nBaz,2"
  tbl = CSV.parse(string, headers: true, header_converters: :downcase)
  tbl.class # => CSV::Table
  tbl.headers # => ["name", "count"]
  

• Параметр header_converters с новым экземпляром CSV:

  csv = CSV.new(string, header_converters: :downcase)
  # Header converters in effect:
  csv.header_converters # => [:downcase]
  tbl = CSV.parse(string, headers: true)
  tbl.headers # => ["Name", "Count"]
  

• Method header_convert добавляет преобразователь заголовка в экземпляр CSV:

  csv = CSV.new(string)
  # Add a header converter.
  csv.header_convert(:downcase)
  csv.header_converters # => [:downcase]
  tbl = CSV.parse(string, headers: true)
  tbl.headers # => ["Name", "Count"]
  

Встроенные преобразователи заголовков

Встроенные преобразователи заголовков находятся в хэше CSV::HeaderConverters. Ключи там — имена преобразователей:

CSV::HeaderConverters.keys # => [:downcase, :symbol]

Преобразователь :downcase преобразует каждый заголовок в нижний регистр:

string = "Name,Count\nFoo,0\n,Bar,1\nBaz,2"
tbl = CSV.parse(string, headers: true, header_converters: :downcase)
tbl.class # => CSV::Table
tbl.headers # => ["name", "count"]

Преобразователь :symbol преобразует каждый заголовок в символ:

string = "Name,Count\nFoo,0\n,Bar,1\nBaz,2"
tbl = CSV.parse(string, headers: true, header_converters: :symbol)
tbl.headers # => [:name, :count]

Детали:

• Удаляет начальные и конечные пробелы.

• Преобразует заголовок в нижний регистр.

• Заменяет вложенные пробелы на подчёркивания.

• Удаляет небуквенно-цифровые символы.

• Преобразует строку в символ.

Пользовательские преобразователи заголовков

Вы можете определить пользовательский преобразователь заголовка:

upcase_converter = proc {|header| header.upcase }
string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
table = CSV.parse(string, headers: true, header_converters: upcase_converter)
table # => #<CSV::Table mode:col_or_row row_count:4>
table.headers # => ["NAME", "VALUE"]

Вы можете зарегистрировать преобразователь в хэше HeaderConverters, что позволит ссылаться на него по имени:

CSV::HeaderConverters[:upcase] = upcase_converter
table = CSV.parse(string, headers: true, header_converters: :upcase)
table # => #<CSV::Table mode:col_or_row row_count:4>
table.headers # => ["NAME", "VALUE"]

Преобразователи записи

Когда вы указываете преобразователь записи для генерации CSV, каждое поле, которое должно быть записано, передаётся преобразователю; его возвращаемое значение становится новым значением для поля. Преобразователь может, например, убрать пробелы из поля.

Использование без преобразователя записи (все поля без изменений):

output_string = CSV.generate do |csv|
  csv << [' foo ', 0]
  csv << [' bar ', 1]
  csv << [' baz ', 2]
end
output_string # => " foo ,0\n bar ,1\n baz ,2\n"

Использование параметра write_converters с двумя пользовательскими преобразователями записи:

strip_converter = proc {|field| field.respond_to?(:strip) ? field.strip : field }
upcase_converter = proc {|field| field.respond_to?(:upcase) ? field.upcase : field }
write_converters = [strip_converter, upcase_converter]
output_string = CSV.generate(write_converters: write_converters) do |csv|
  csv << [' foo ', 0]
  csv << [' bar ', 1]
  csv << [' baz ', 2]
end
output_string # => "FOO,0\nBAR,1\nBAZ,2\n"

Кодировки символов (M17n или многоязычность)

Этот новый парсер CSV умеет обрабатывать m17n. Парсер работает в кодировке Encoding объекта IO или String, считываемого или записываемого. Ваши данные никогда не преобразуются (если вы не попросите Ruby это сделать) и будут буквально обработаны в кодировке Encoding, в которой они находятся. Таким образом, CSV вернёт массивы или строки строк в кодировке Encoding ваших данных. Это достигается за счёт перекодирования самого парсера в вашу кодировку Encoding.

Конечно, необходимо выполнить некоторые преобразования кодировки, чтобы реализовать эту поддержку многокодировки. Например, :col_sep, :row_sep, и :quote_char должны быть перекодированы в соответствии с вашими данными. Надеюсь, весь процесс покажется прозрачным, так как значения по умолчанию CSV должны просто магически работать с вашими данными. Однако, вы можете установить эти значения вручную в целевой кодировке Encoding, чтобы избежать преобразования.

Важно также отметить, что, хотя весь ядро парсера CSV теперь игнорирует кодировку Encoding, некоторые функции не поддерживают это. Например, встроенные преобразователи попытаются перекодировать данные в UTF-8 перед выполнением преобразований. Снова, вы можете предоставить пользовательские преобразователи, которые знают о ваших кодировках, чтобы избежать этого преобразования. Для меня слишком сложно поддерживать родные преобразования во всех кодировках Ruby.

В любом случае, практический аспект этого прост: убедитесь, что объекты IO и String, передаваемые в CSV, имеют установленную соответствующую кодировку Encoding, и всё должно работать. Методы CSV, которые позволяют открывать объекты IO (CSV::foreach(), CSV::open(), CSV::read() и CSV::readlines()), позволяют вам указать кодировку Encoding.

Одно небольшое исключение возникает при генерации CSV в String с кодировкой Encoding, которая несовместима с ASCII. Нет имеющихся данных для CSV, чтобы подготовиться, и поэтому, вероятно, вам нужно будет вручную указать желаемую кодировку Encoding в большинстве этих случаев. При использовании CSV::generate_line() или Array#to_csv() она попытается угадать, используя поля в строке вывода.

Я пытаюсь указывать любые другие проблемы с Encoding в документации методов по мере их появления.

Это было протестировано по возможности с всеми кодировками (кроме «фиктивных») Ruby. Однако, это новый и смелый код, и могут быть некоторые ошибки. Пожалуйста, не стесняйтесь сообщать о любых обнаруженных проблемах.