класс CSV

CSV

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 предоставляет фильтр в стиле Unix для данных CSV. Данные входных данных обрабатываются для формирования данных выходных данных:

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

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

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

Параметр 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)

Параметр 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, игнорирует строки, которые ему соответствуют.

• Если строка, преобразует её в 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"]]

Использование строки:

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

Возникает исключение, если задан объект, который не является Regexp, строкой или 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"]

Используйте подпараметр backslash_quote для парсинга значений, в которых символ обратного слэша используется для экранирования символа двойной кавычки. Это заставит парсер рассматривать \" как "".

Для следующих двух примеров:

str = 'Show,"Harry \"Handcuff\" Houdini, the one and only","Tampa Theater"'

Со значением liberal_parsing, но без подпараметра backslash_quote:

# Incorrect interpretation of backslash; incorrectly interprets the quoted comma as a field separator.
ary = CSV.parse_line(str, liberal_parsing: true)
ary # => ["Show", "\"Harry \\\"Handcuff\\\" Houdini", " the one and only\"", "Tampa Theater"]
puts ary[1] # => "Harry \"Handcuff\" Houdini

Со значением liberal_parsing и его подпараметром backslash_quote:

ary = CSV.parse_line(str, liberal_parsing: { backslash_quote: true })
ary # => ["Show", "Harry \"Handcuff\" Houdini, the one and only", "Tampa Theater"]
puts ary[1] # => Harry "Handcuff" Houdini, the one and only

Параметр 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 будет преобразована в 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, если эта функция будет использоваться, так как преобразование окончания строк может вызвать проблемы с возвращением позиции документа к исходному состоянию до считывания.

Параметр col_sep

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

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

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)

Параметр 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)

Параметр 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"

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

Параметр 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 отображает:

• Индекс поля с нулевым основанием.

• Индекс строки с единичным основанием.

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

Хранимые преобразователи

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

Структура хранения для преобразователей полей — хэш 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: Преобразует каждый заголовок в символ.

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

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

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

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

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

• Имена хранящихся преобразователей.

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

Примеры:

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:

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

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

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

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

Вывод:

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 с методом парсинга экземпляра:

  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 парсер умеет работать с кодировками. Парсер работает в кодировке Encoding объекта IO или String, из которого или в который он считывается/записывается. Ваши данные никогда не транскодируются (если вы не попросите Руби их транскодировать), а будут буквально обработаны в Encoding кодировке. Таким образом, CSV вернёт массивы или строки строк в Encoding кодировке ваших данных. Это достигается путём транскодирования самого парсера в Encoding кодировку.

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

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

В любом случае, практическая сторона этого проста: убедитесь, что объекты 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 проблемы в документации методов по мере их возникновения.

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