类 CSV

CSV¶ ↑

CSV 数据¶ ↑

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

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

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

此 CSV 字符串，行分隔符为 "\n"，列分隔符为 ","，具有三行和两列

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

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

有关表的更多信息，请参阅 Wikipedia 文章“表（信息）”，尤其是其“简单表”部分

类 CSV¶ ↑

类 CSV 提供以下方法：

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

• 将 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#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 返回一个 String；此示例使用方法 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 类，该方法将 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¶ ↑

指定行分隔符，一个 String 或符号 :auto（请参见下文），用于解析和生成。

默认值

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

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

使用 "\n"

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

使用 | (管道)

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

使用 -- (两个连字符)

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

使用 '' (空字符串)

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

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

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

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

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

示例

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

如果满足以下任一条件，则使用默认的 $INPUT_RECORD_SEPARATOR ($/)：

• 未找到这些序列中的任何一个。

• 数据为 ARGF、STDIN、STDOUT 或 STDERR。

• 流仅可用于输出。

显然，发现需要一些时间。如果速度很重要，请手动设置。另请注意，如果将使用此功能，则应在 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 时，每个返回的行（数组或 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¶ ↑

指定行分隔符，一个 String 或符号 :auto（请参见下文），用于解析和生成。

默认值

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

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

使用 "\n"

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

使用 | (管道)

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

使用 -- (两个连字符)

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

使用 '' (空字符串)

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

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

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

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

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

示例

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

如果满足以下任一条件，则使用默认的 $INPUT_RECORD_SEPARATOR ($/)：

• 未找到这些序列中的任何一个。

• 数据为 ARGF、STDIN、STDOUT 或 STDERR。

• 流仅可用于输出。

显然，发现需要一些时间。如果速度很重要，请手动设置。另请注意，如果将使用此功能，则应在 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：将每个嵌入在字符串中的整数转换为真正的 Integer。

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

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

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

• :time：将每个嵌入在字符串中的时间转换为真正的 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，其工作方式相同。它也有内置的转换器 Proc：

• :downcase：将每个标题转换为小写。

• :symbol：将每个标题转换为 Symbol。

写入标题没有这样的存储结构。

为了使解析方法能够在非主 Ractor 中访问存储的转换器，必须首先使存储结构可共享。因此，必须在创建使用存储在这些结构中的转换器的 Ractor 之前调用 Ractor.make_shareable(CSV::Converters) 和 Ractor.make_shareable(CSV::HeaderConverters)。（由于使存储结构可共享涉及到冻结它们，因此必须首先添加要使用的任何自定义转换器。）

转换器列表¶ ↑

转换器列表是一个数组，其中可能包含以下任意组合：

• 转换器 Proc。

• 已存储转换器的名称。

• 嵌套的转换器列表。

示例

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

像转换器 Proc 一样，可以命名转换器列表，并将其存储在 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。（实际上，这就是内置字段转换器 :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 中。

• 每个键都是一个字段转换器名称。

• 每个值都是以下之一：

  • Proc 字段转换器。

  • 字段转换器名称的数组。

显示

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

输出

[:integer, Proc]
[:float, Proc]
[:numeric, [:integer, :float]]
[:date, Proc]
[:date_time, Proc]
[: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"]

转换器 time 转换 Time::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: :time)
csv # => [2020-05-07 14:59:00 -0500, "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"]
  

• 带有新 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"]
  

内置标题转换器¶ ↑

内置的标题转换器位于哈希表 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 通过将每个标题转换为 Symbol 来转换它。

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

详细信息

• 删除开头和结尾的空格。

• 将标题转换为小写。

• 将嵌入的空格替换为下划线。

• 删除非单词字符。

• 将字符串转换为 Symbol。

自定义标题转换器¶ ↑

您可以定义自定义标题转换器。

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

您可以在 HeaderConverters 哈希表中注册转换器，这使您可以通过名称引用它。

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

写入转换器¶ ↑

指定用于生成 CSV 的写入转换器时，每个要写入的字段都会传递给转换器；其返回值将成为该字段的新值。例如，转换器可以从字段中删除空格。

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

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

使用带有两个自定义写入转换器的选项 write_converters。

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

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

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

当然，必须进行一些转码才能实现此多编码支持。例如，必须将 :col_sep、:row_sep 和 :quote_char 转码以匹配您的数据。希望这使整个过程感觉透明，因为 CSV 的默认值应该只是神奇地为您的数据工作。但是，您可以在目标编码中手动设置这些值以避免转换。

同样重要的是要注意，尽管 CSV 的所有核心解析器现在都与编码无关，但某些功能并非如此。例如，内置的转换器将尝试在进行转换之前将数据转码为 UTF-8。同样，您可以提供了解您的编码的自定义转换器，以避免这种转换。对于我来说，要支持 Ruby 所有编码中的本机转换太难了。

无论如何，这方面的实际操作很简单：确保传递到 CSV 中的 IO 和 String 对象设置了正确的编码，一切都应该可以正常工作。CSV 允许您打开 IO 对象的方法（CSV::foreach()、CSV::open()、CSV::read() 和 CSV::readlines()）允许您指定编码。

当使用与 ASCII 不兼容的编码将 CSV 生成到 String 中时，会出现一个小例外。没有 CSV 可以用来准备自己的现有数据，因此您可能需要在大多数情况下手动指定所需的编码。但是，当使用 CSV::generate_line() 或 Array#to_csv() 时，它会尝试使用输出行中的字段进行猜测。

当我发现任何其他编码问题时，我都会在方法的文档中指出。

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