类 CSV

CSV¶ ↑

CSV Data¶ ↑

CSV（逗号分隔值）数据是表格的文本表示

• 行分隔符分隔表格行。常见的行分隔符是换行符"\n"。

• 列分隔符分隔行中的字段。常见的列分隔符是逗号","。

此 CSV 字符串的行分隔符为"\n"，列分隔符为","，有 3 行和 2 列

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

尽管名称为 CSV，但 CSV 表示可以使用不同的分隔符。

有关表格的更多信息，请参阅维基百科文章“表（信息）”，特别是其“简单表”部分

类 CSV¶ ↑

类 CSV 提供用于以下操作的方法

• 从字符串对象、文件（通过其文件路径）或 IO 对象解析 CSV 数据。

• 生成 CSV 数据到字符串对象。

使 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#parse_csv 扩展类 String，该方法也仅返回第一行

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#to_csv 扩展了类 Array，该方法将数组转换为字符串

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

“筛选”CSV¶ ↑

方法 CSV.filter 为 CSV 数据提供 Unix 风格的筛选器。处理输入数据以形成输出数据

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

CSV 对象¶ ↑

有三种方法可以创建 CSV 对象

• 方法 CSV.new 返回一个新的 CSV 对象。

• 方法 CSV.instance 返回一个新的或缓存的 CSV 对象。

• 方法 CSV() 也返回一个新的或缓存的 CSV 对象。

实例方法¶ ↑

CSV 有三组实例方法

• 它自己内部定义的实例方法。

• 模块 Enumerable 包含的方法。

• 委托给类 IO 的方法。请参见下文。

委托方法¶ ↑

为了方便起见，CSV 对象将委托给类 IO 中的许多方法。（一些方法在 CSV 中有包装“保护代码”。）您可以调用

• IO#binmode

• binmode?

• IO#close

• IO#close_read

• IO#close_write

• IO#closed?

• eof

• eof?

• IO#external_encoding

• IO#fcntl

• IO#fileno

• flock

• IO#flush

• IO#fsync

• IO#internal_encoding

• ioctl

• IO#isatty

• path

• IO#pid

• IO#pos

• IO#pos=

• IO#reopen

• rewind

• IO#seek

• stat

• IO#string

• IO#sync

• IO#sync=

• IO#tell

• to_i

• to_io

• IO#truncate

• IO#tty?

选项¶ ↑

选项的默认值为

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

解析选项¶ ↑

下面详细描述了解析选项，包括

• row_sep：指定行分隔符；用于分隔行。

• col_sep：指定列分隔符；用于分隔字段。

• quote_char：指定引用字符；用于引用字段。

• field_size_limit：指定允许的最大字段大小 + 1。自 3.2.3 起已弃用。请改用 max_field_size。

• max_field_size：指定允许的最大字段大小。

• converters：指定要使用的字段转换器。

• unconverted_fields：指定是否可以使用未转换的字段。

• headers：指定数据是否包含标题，或指定标题本身。

• return_headers：指定是否返回标题。

• header_converters：指定要使用的标题转换器。

• skip_blanks：指定是否忽略空白行。

• skip_lines：指定如何识别注释行。

• strip：指定是否从字段中删除前导和尾随空白。这必须与 col_sep 兼容；如果不兼容，则会引发 ArgumentError 异常。

• liberal_parsing：指定 CSV 是否应尝试解析不兼容的数据。

• nil_value：指定要替换每个空（无文本）字段的对象。

• empty_value：指定要替换每个空字段的对象。

选项 row_sep¶ ↑

指定行分隔符（字符串或符号 :auto（见下文））用于解析和生成。

默认值

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

当 row_sep 为字符串时，该字符串将成为行分隔符。String 在使用前将被转码为数据的 Encoding。

使用 "\n"

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

使用 |（管道）

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

使用 --（两个连字符）

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

使用 ''（空字符串）

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

当 row_sep 是符号 :auto（默认值）时，生成会使用 "\n" 作为行分隔符

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

另一方面，解析会调用行分隔符的自动发现。

自动发现会提前读取数据，寻找下一个 \r\n、\n 或 \r 序列。即使该序列出现在带引号的字段中，也会选择该序列，假设您会在那里有相同的行尾。

示例

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

如果以下任一条件为真，则使用默认的 $INPUT_RECORD_SEPARATOR（$/）

• 未找到任何这些序列。

• Data 是 ARGF、STDIN、STDOUT 或 STDERR。

• 流仅可用于输出。

显然，发现需要一点时间。如果速度很重要，请手动 Set。另请注意，如果要使用此功能，应在 Windows 上以二进制模式打开 IO 对象，因为行尾转换可能会导致将文档位置重置为读取前的位置时出现问题。

选项 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时，每个返回的行（Array 或 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，则使用当前options调用方法CSV::parse_line(str, 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¶ ↑

指定一个对象，用于识别输入中要忽略的注释行

• 如果为正则表达式，则忽略与之匹配的行。

• 如果为字符串，则将其转换为正则表达式，忽略与之匹配的行。

• 如果为 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"]]

使用正则表达式

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

如果给定的对象不是正则表达式、字符串或 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。另请注意，如果要使用此功能，应在 Windows 上以二进制模式打开 IO 对象，因为行尾转换可能会导致将文档位置重置为读取前的位置时出现问题。

选项 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)

选项 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 解析的每个值（字段或标题）都形成一个字符串。你可以使用字段转换器或标题转换器来拦截和修改解析的值

• 请参阅 字段转换器。

• 请参阅 标题转换器。

同样，默认情况下，在生成期间要写入的每个值都将“按原样”写入。你可以使用写入转换器在写入之前修改值。

• 参见 写入转换器。

指定转换器¶ ↑

您可以在各种 CSV 方法的 options 参数中指定用于解析或生成的转换器

• 选项 converters 用于转换已解析的字段值。

• 选项 header_converters 用于转换已解析的头字段值。

• 选项 write_converters 用于转换要写入（生成）的值。

有三种形式可用于指定转换器

• 转换器 proc：用于转换的可执行代码。

• 转换器名称：存储的转换器的名称。

• 转换器列表：转换器 proc、转换器名称和转换器列表的数组。

转换器 Proc¶ ↑

此转换器 proc strip_converter 接受一个值 field 并返回 field.strip

strip_converter = proc {|field| field.strip }

在此对 CSV.parse 的调用中，关键字参数 converters: string_converter 指定

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

转换器 proc 可以接收第二个参数 field_info，其中包含有关该字段的详细信息。此修改后的 strip_converter 显示其参数

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

输出

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

每个 CSV::FieldInfo 对象显示

• 基于 0 的字段索引。

• 基于 1 的行索引。

• 字段头字段（如果存在）。

存储的转换器¶ ↑

可以为转换器指定名称并将其存储在解析方法可以按名称找到它的结构中。

字段转换器的存储结构是哈希 CSV::Converters。它具有多个内置转换器 proc

• :integer：将每个嵌入字符串的整数转换为真正的整数。

• :float：将每个嵌入字符串的浮点数转换为真正的浮点数。

• :date：将每个嵌入字符串的日期转换为真正的日期。

• :date_time：将每个嵌入字符串的日期时间转换为真正的日期时间

. 此示例创建一个转换器 proc，然后将其存储

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 创建之前调用 Ractor.make_shareable(CSV::Converters) 和 Ractor.make_shareable(CSV::HeaderConverters)。（由于使存储结构可共享涉及冻结它们，因此必须首先添加要使用的任何自定义转换器。）

转换器列表¶ ↑

转换器列表是一个数组，其中可能包含任何组合的

• 转换器过程。

• 存储转换器的名称。

• 嵌套转换器列表。

示例

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

• 使用新 CSV 实例的选项 converters

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

你可以在转换器 Hash 中注册转换器，这样你就可以通过名称引用它

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

• 使用新 CSV 实例的选项 header_converters

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

• 方法 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"]
  

内置标题转换器¶ ↑

内置标题转换器在 Hash 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 Hash 中注册转换器，这样你就可以通过名称引用它

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

写入转换器¶ ↑

当您为生成 CSV 指定一个写入转换器时，每个要写入的字段都会传递给转换器；它的返回值成为字段的新值。例如，转换器可能会从字段中去除空格。

不使用写入转换器（所有字段未修改）

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

使用选项 write_converters 和两个自定义写入转换器

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

字符编码（M17n 或多语言化）¶ ↑

这个新的 CSV 解析器精通 m17n。解析器在正在读写 IO 或 String 对象的 Encoding 中工作。您的数据永远不会被转码（除非您要求 Ruby 为您转码），并且将以其所在的 Encoding 进行解析。因此，CSV 将返回 Encoding 中的字符串数组或行。这是通过将解析器本身转码到您的 Encoding 中来实现的。

当然，为了实现这种多编码支持，必须进行一些转码。例如，:col_sep、:row_sep 和 :quote_char 必须转码以匹配您的数据。希望这会让整个过程感觉透明，因为 CSV 的默认值应该只对您的数据起作用。但是，您可以在目标 Encoding 中手动设置这些值以避免翻译。

同样重要的是要注意，虽然 CSV 的所有核心解析器现在都是 Encoding 不可知的，但有些特性不是。例如，内置转换器在进行转换之前会尝试将数据转码为 UTF-8。同样，您可以提供了解您的编码的自定义转换器以避免这种翻译。对于我来说，在 Ruby 的所有编码中支持本机转换实在是太难了。

无论如何，这方面的实际情况很简单：确保传递给 IO 和 String 对象的 CSV 具有正确的 Encoding 设置，一切应该都能正常工作。允许您打开 IO 对象的 CSV 方法（CSV::foreach()、CSV::open()、CSV::read() 和 CSV::readlines()）允许您指定 Encoding。

当使用与 ASCII 不兼容的 Encoding 将 CSV 生成到 String 时，会产生一个轻微的异常。没有现有的数据供 CSV 用来准备自身，因此您可能需要在大多数情况下手动指定所需的 Encoding。不过，在使用 CSV::generate_line() 或 Array#to_csv() 时，它将尝试使用输出行中的字段进行猜测。

我尝试在方法文档中指出任何其他 Encoding 问题，因为它们会不断出现。

我已经尽我所能使用 Ruby 附带的所有非“虚拟”编码对本代码进行了测试。但是，这是一段新颖的代码，可能存在一些错误。如果您发现任何问题，请随时 报告。