класс CSV

CSV

Данные CSV (comma-separated variables) представляют собой текстовое представление таблицы:

• Разделитель строк определяет строки таблицы. Общим разделителем строк является символ новой строки "\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:        "",
  # For generating.
  write_headers:      nil,
  quote_empty:        true,
  force_quotes:       false,
  write_converters:   nil,
  write_nil_value:    nil,
  write_empty_value:  "",
  strip:              false,
}

Параметры для разбора

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

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

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

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

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

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

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

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

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

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

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

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

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

• 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 ($/), если выполняется любое из следующих условий:

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

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

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

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

Использование "\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 ($/) используется, если выполняется одно из следующих условий:

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

• Данные являются ARGF, STDIN, STDOUT или STDERR.

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

Очевидно, обнаружение занимает некоторое время. Установите вручную, если скорость важна. Также обратите внимание, что объекты 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::Info отображает:

• Индекс поля (нумерация с 0).

• Индекс строки (нумерация с 1).

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

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

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

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

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

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

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

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

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

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: Преобразует каждый заголовок в символ.

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

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

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

• Процедуры-конвертеры.

• Имена сохранённых конвертеров.

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

Примеры:

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

Конвертеры заголовков

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

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

• Параметр 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, из которого или в который считывается или записывается информация. Ваши данные никогда не преобразуются (если вы не попросите 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. Однако, это новый, смелый код, и в нём могут быть ошибки. Будьте добры, сообщите мне о любых проблемах, которые вы найдёте.