class CSV

[edit]

extend: Forwardable

要約

このクラスは CSV ファイルやデータに対する完全なインターフェイスを提供します。

読み込み


require "csv"

csv_text = <<~CSV_TEXT
  Ruby,1995
  Rust,2010
CSV_TEXT

IO.write "sample.csv", csv_text

# ファイルから一行ずつ
CSV.foreach("sample.csv") do |row|
  p row
end
# => ["Ruby", "1995"]
#    ["Rust", "2010"]

# ファイルから一度に
p CSV.read("sample.csv")
# => [["Ruby", "1995"], ["Rust", "2010"]]

# 文字列から一行ずつ
CSV.parse(csv_text) do |row|
  p row
end
# => ["Ruby", "1995"]
#    ["Rust", "2010"]

# 文字列から一度に
p CSV.parse(csv_text)
# => [["Ruby", "1995"], ["Rust", "2010"]]

書き込み


require 'csv'

# ファイルへ書き込み
CSV.open("path/to/file.csv", "wb") do |csv|
  csv << ["row", "of", "CSV", "data"]
  csv << ["another", "row"]
  # ...
end

# 文字列へ書き込み
csv_string = CSV.generate do |csv|
  csv << ["row", "of", "CSV", "data"]
  csv << ["another", "row"]
  # ...
end

一行変換


require 'csv'

csv_string = ["CSV", "data"].to_csv   # => "CSV,data"
csv_array  = "CSV,String".parse_csv   # => ["CSV", "String"]

ショートカット


require 'csv'

CSV             { |csv_out| csv_out << %w{my data here} }  # to $stdout
CSV(csv = "")   { |csv_str| csv_str << %w{my data here} }  # to a String
CSV($stderr)    { |csv_err| csv_err << %w{my data here} }  # to $stderr

CSV と文字エンコーディング (M17n or Multilingualization)

This new CSV parser is m17n savvy. The parser works in the Encoding of the IO or String object being read from or written to. Your data is never transcoded (unless you ask Ruby to transcode it for you) and will literally be parsed in the Encoding it is in. Thus CSV will return Arrays or Rows of Strings in the Encoding of your data. This is accomplished by transcoding the parser itself into your Encoding.

Some transcoding must take place, of course, to accomplish this multiencoding support. For example, <tt>:col_sep</tt>, <tt>:row_sep</tt>, and <tt>:quote_char</tt> must be transcoded to match your data. Hopefully this makes the entire process feel transparent, since CSV's defaults should just magically work for you data. However, you can set these values manually in the target Encoding to avoid the translation.

It's also important to note that while all of CSV's core parser is now Encoding agnostic, some features are not. For example, the built-in converters will try to transcode data to UTF-8 before making conversions. Again, you can provide custom converters that are aware of your Encodings to avoid this translation. It's just too hard for me to support native conversions in all of Ruby's Encodings.

Anyway, the practical side of this is simple: make sure IO and String objects passed into CSV have the proper Encoding set and everything should just work. CSV methods that allow you to open IO objects (CSV::foreach(), CSV::open(), CSV::read(), and CSV::readlines()) do allow you to specify the Encoding.

One minor exception comes when generating CSV into a String with an Encoding that is not ASCII compatible. There's no existing data for CSV to use to prepare itself and thus you will probably need to manually specify the desired Encoding for most of those cases. It will try to guess using the fields in a row of output though, when using CSV::generate_line() or Array#to_csv().

目次

特異メソッド
インスタンスメソッド
定数

継承しているメソッド

Enumerableから継承しているメソッド

特異メソッド

filter(options = Hash.new) {|row| ... }[permalink][rdoc][edit]
filter(input, options = Hash.new) {|row| ... }
filter(input, output, options = Hash.new) {|row| ... }

このメソッドは CSV データに対して Unix のツール群のようなフィルタを構築するのに便利です。

与えられたブロックに一行ずつ渡されます。ブロックに渡された行は必要であれば変更することができます。ブロックの評価後に行を全て output に書き込みます。

[PARAM] input:
String か IO のインスタンスを指定します。デフォルトは ARGF です。
[PARAM] output:
String か IO のインスタンスを指定します。デフォルトは $stdout です。
[PARAM] options:
":in_", ":input_" で始まるキーは input にだけ適用されます。 ":out_", ":output_" で始まるキーは output にだけ適用されます。それ以外のキーは両方に適用されます。 ":output_row_sep" のデフォルト値は $/ です。 
例: input, output は初期値

# $ echo "header1,header2\nrow1_1,row1_2" > in.csv; ruby test.rb in.csv

require "csv"

options = { headers: true, return_headers: true, write_headers: true }

CSV.filter(options) do |row|
  if row.header_row?
    row << "header3"
    next
  end
  row << "row1_3"
end

# => header1,header2,header3
# row1_1,row1_2,row1_3

例: input, output を指定する

require "csv"
content = <<EOS
id,first name,last name,age
1,taro,tanaka,20
2,jiro,suzuki,18
3,ami,sato,19
4,yumi,adachi,21
EOS

File.write('test.csv',content)
options = { headers: true, return_headers: true, write_headers: true }

CSV.filter(File.open("test.csv"), File.open("out.csv", "w"), options) do |row|
  if row.header_row?
    row << "full name"
    next
  end
  row << row["first name"] + " " + row["last name"]
end

# out.csv の内容
# => id,first name,last name,age,full name
#    1,taro,tanaka,20,taro tanaka
#    2,jiro,suzuki,18,jiro suzuki
#    3,ami,sato,19,ami sato
#    4,yumi,adachi,21,yumi adachi

[SEE_ALSO] CSV.new

foreach(path, options = Hash.new) -> Enumerator[permalink][rdoc][edit]
foreach(path, options = Hash.new) {|row| ... } -> nil

このメソッドは CSV ファイルを読むための主要なインターフェイスです。各行が与えられたブロックに渡されます。ブロックが与えられていない場合、Enumeratorを返します。 

例

require 'csv'

# UTF-32BE な CSV ファイルを読み込んで UTF-8 な row をブロックに渡します
CSV.foreach("a.csv", encoding: "UTF-32BE:UTF-8"){|row| p row }
[PARAM] path:
CSV ファイルのパスを指定します。
[PARAM] options:
CSV.new のオプションと同じオプションを指定できます。 :encoding というキーを使用すると入出力のエンコーディングを指定することができます。 Encoding.default_external と異なるエンコーディングを持つ入力を使用する場合は、必ずエンコーディングを指定してください。

[SEE_ALSO] CSV.new, File.open

generate(str = "", options = Hash.new) {|csv| ... } -> String[permalink][rdoc][edit]

このメソッドは与えられた文字列をラップして CSV のオブジェクトとしてブロックに渡します。ブロック内で CSV オブジェクトに行を追加することができます。ブロックを評価した結果は文字列を返します。

このメソッドに与えられた文字列は変更されるので、新しい文字列オブジェクトが必要な場合は Object#dup で複製してください。

[PARAM] str:
文字列を指定します。デフォルトは空文字列です。
[PARAM] options:
CSV.new のオプションと同じオプションを指定できます。 :encoding というキーを使用すると出力のエンコーディングを指定することができます。 ASCII と互換性の無い文字エンコーディングを持つ文字列を出力する場合は、このヒントを指定する必要があります。 
例

require "csv"

text =<<-EOS
id,first name,last name,age
1,taro,tanaka,20
2,jiro,suzuki,18
3,ami,sato,19
4,yumi,adachi,21
EOS

csv = CSV.generate(text, headers: true) do |csv|
  csv.add_row(["5", "saburo", "kondo", "34"])
end

print csv
# => id,first name,last name,age
# 1,taro,tanaka,20
# 2,jiro,suzuki,18
# 3,ami,sato,19
# 4,yumi,adachi,21
# 5,saburo,kondo,34

[SEE_ALSO] CSV.new

generate_line(row, options = Hash.new) -> String[permalink][rdoc][edit]

このメソッドは一つの Array オブジェクトを CSV 文字列に変換するためのショートカットです。複数行のCSVを扱う際はCSV#<<を使うとより高速です。

このメソッドは可能であれば row に含まれる最初の nil でない値を用いて出力のエンコーディングを推測します。

[PARAM] row:
文字列の配列を指定します。
[PARAM] options:
CSV.new のオプションと同じオプションを指定できます。 :encoding というキーを使用すると出力のエンコーディングを指定することができます。 :row_sep というキーの値には $/ がセットされます。 
例

require "csv"

taro = ['1', 'taro', 'tanaka', '20']
CSV.generate_line(taro, col_sep: '|') # => "1|taro|tanaka|20\n"

[SEE_ALSO] CSV.new

instance(data = $stdout, options = Hash.new) -> CSV[permalink][rdoc][edit]
instance(data = $stdout, options = Hash.new) {|csv| ... } -> object

このメソッドは CSV.new のように CSV のインスタンスを返します。しかし、返される値は Object#object_id と与えられたオプションをキーとしてキャッシュされます。

ブロックが与えられた場合、生成されたインスタンスをブロックに渡して評価した結果を返します。

[PARAM] data:
String か IO のインスタンスを指定します。
[PARAM] options:
CSV.new のオプションと同じオプションを指定できます。 
例

require "csv"

options = { headers: true }

text =<<-EOS
id,first name,last name,age
1,taro,tanaka,20
2,jiro,suzuki,18
3,ami,sato,19
4,yumi,adachi,21
EOS

csv = CSV.instance(text, options)
csv2 = CSV.instance(text, options)
csv.object_id == csv2.object_id # => true
print csv.read

# => id,first name,last name,age
# 1,taro,tanaka,20
# 2,jiro,suzuki,18
# 3,ami,sato,19
# 4,yumi,adachi,21

[SEE_ALSO] CSV.new

new(data, options = Hash.new) -> CSV[permalink][rdoc][edit]

このメソッドは CSV ファイルを読み込んだり、書き出したりするために String か IO のインスタンスをラップします。

ラップされた文字列の先頭から読み込むことになります。文字列に追記したい場合は CSV.generate を使用してください。他の位置から処理したい場合はあらかじめそのように設定した StringIO を渡してください。

[PARAM] data:
String か IO のインスタンスを指定します。 String のインスタンスを指定した場合、CSV#string を使用して後からデータを取り出すことが出来ます。
[PARAM] options:
CSV をパースするためのオプションをハッシュで指定します。パフォーマンス上の理由でインスタンスメソッドではオプションを上書きすることが出来ないので、上書きしたい場合は必ずここで上書きするようにしてください。
:col_sep

フィールドの区切り文字列を指定します。この文字列はパースする前にデータのエンコーディングに変換されます。

:row_sep

行区切りの文字列を指定します。:auto という特別な値をセットすることができます。 :auto を指定した場合データから自動的に行区切りの文字列を見つけ出します。このときデータの先頭から次の "\r\n", "\n", "\r" の並びまでを読みます。 A sequence will be selected even if it occurs in a quoted field, assuming that you would have the same line endings there. If none of those sequences is found, +data+ is ARGF, Object::STDIN, Object::STDOUT, or Object::STDERR, or the stream is only available for output, the default $INPUT_RECORD_SEPARATOR ($/) is used. Obviously, discovery takes a little time. Set manually if speed is important. Also note that IO objects should be opened in binary mode on Windows if this feature will be used as the line-ending translation can cause problems with resetting the document position to where it was before the read ahead. This String will be transcoded into the data's Encoding before parsing.

:quote_char

フィールドをクオートする文字を指定します。長さ 1 の文字列でなければなりません。正しいダブルクオートではなく間違ったシングルクオートを使用しているアプリケーションで便利です。 CSV will always consider a double sequence this character to be an escaped quote. この文字列はパースする前にデータのエンコーディングに変換されます。

:field_size_limit

This is a maximum size CSV will read ahead looking for the closing quote for a field. (In truth, it reads to the first line ending beyond this size.) If a quote cannot be found within the limit CSV will raise a MalformedCSVError, assuming the data is faulty. You can use this limit to prevent what are effectively DoS attacks on the parser. However, this limit can cause a legitimate parse to fail and thus is set to +nil+, or off, by default.

:converters

CSV::Converters から取り出した名前の配列です。変換器が一つだけの場合は配列に格納する必要はありません。全ての組み込みの変換器は、値を変換する前に UTF-8 にエンコーディング変換を試みます。エンコーディング変換に失敗した場合はフィールドは変換されません。

:unconverted_fields

真をセットすると CSV::Row#unconverted_fields という変換前のフィールドを返すメソッドを全ての行に追加します。headers オプションによって追加したヘッダはフィールドではないので CSV::Row#unconverted_fields は空の配列を返します。

:headers

:first_row というシンボルか真を指定すると、CSV ファイルの一行目をヘッダとして扱います。配列を指定するとそれをヘッダとして扱います。文字列を指定すると CSV.parse_line を使用してパースした結果をヘッダとして扱います。このとき、:col_sep, :row_sep, :quote_char はこのインスタンスと同じものを使用します。この設定は CSV#shift の返り値を配列のかわりに CSV::Row のインスタンスに変更します。 CSV#read の返り値を配列の配列のかわりに CSV::Table のインスタンスに変更します。

:return_headers

偽を指定すると、ヘッダ行を無視します。真を指定すると、ヘッダ行をヘッダと値が同一の CSV::Row のインスタンスとして返します。

:write_headers

真を指定して :headers にも値をセットすると、ヘッダを出力します。

:header_converters

:converters オプションに似ていますが、ヘッダ専用の変換器を定義します。全ての組み込みの変換器は、値を変換する前に UTF-8 にエンコーディング変換を試みます。エンコーディング変換に失敗した場合はヘッダは変換されません。

:skip_blanks

真を指定すると、空行を読み飛ばします。

:force_quotes

真を指定すると、全てのフィールドを作成時にクオートします。

:skip_lines

指定した正規表現にマッチしたそれぞれの行をコメントとして読み飛ばします。

[EXCEPTION] CSV::MalformedCSVError:
不正な CSV をパースしようとしたときに発生します。 
例: ファイルの読み込み

require "csv"

users =<<-EOS
id,first name,last name,age
1,taro,tanaka,20
2,jiro,suzuki,18
3,ami,sato,19
4,yumi,adachi,21
EOS

File.write("test.csv", users)

File.open("test.csv", "r") do |f|
  csv = CSV.new(f, headers: true)
  csv.class # => CSV
  csv.first # => #<CSV::Row "id":"1" "first name":"taro" "last name":"tanaka" "age":"20">
end

例 文字列の読み込み

require "csv"

users =<<-EOS
id|first name|last name|age
1|taro|tanaka|20
2|jiro|suzuki|18
3|ami|sato|19
4|yumi|adachi|21
EOS

csv = CSV.new(users, headers: true, col_sep: "|")
p csv.class # => CSV
p csv.first # => #<CSV::Row "id":"1" "first name":"taro" "last name":"tanaka" "age":"20">

[SEE_ALSO] CSV::DEFAULT_OPTIONS, CSV.open

open(filename, mode = "rb", options = Hash.new) {|csv| ... } -> nil[permalink][rdoc][edit]
open(filename, mode = "rb", options = Hash.new) -> CSV
open(filename, options = Hash.new) {|csv| ... } -> nil
open(filename, options = Hash.new) -> CSV

このメソッドは IO オブジェクトをオープンして CSV でラップします。これは CSV ファイルを書くための主要なインターフェイスとして使うことを意図しています。

このメソッドは IO.open と同じように動きます。ブロックが与えられた場合はブロックに CSV オブジェクトを渡し、ブロック終了時にそれをクローズします。ブロックが与えられなかった場合は CSV オブジェクトを返します。

データが Encoding.default_external と異なる場合は、mode にエンコーディングを指定する文字列を埋め込まなければなりません。データをどのように解析するか決定するために CSV ライブラリはユーザが mode に指定したエンコーディングをチェックします。"rb:UTF-32BE:UTF-8" のように mode を指定すると UTF-32BE のデータを読み込んでUTF-8 に変換してから解析します。

また "rb:BOM|UTF-8" のように mode を指定すると BOM を自動的に取り除きます。

CSV オブジェクトは多くのメソッドを IO や File に委譲します。

[PARAM] filename:
ファイル名を指定します。
[PARAM] mode:
IO.open に指定できるものと同じものを指定できます。
[PARAM] options:
CSV.new のオプションと同じオプションを指定できます。 
例 読み取り・ブロック指定なし

require "csv"

File.write("test.csv", <<CSV)
id,first name,last name,age
1,taro,tanaka,20
2,jiro,suzuki,18
3,ami,sato,19
4,yumi,adachi,21
CSV
csv = CSV.open("test.csv", headers: true)
csv.class # => CSV
csv.first # => #<CSV::Row "id":"1" "first name":"taro" "last name":"tanaka" "age":"20">

例 読み取り・ブロック指定あり

require "csv"

users =<<-EOS
id,first name,last name,age
1,taro,tanaka,20
2,jiro,suzuki,18
3,ami,sato,19
4,yumi,adachi,21
EOS

File.write("test.csv", users)
CSV.open("test.csv", headers: true) do |csv|
  csv.class # => CSV
  csv.first # => #<CSV::Row "id":"1" "first name":"taro" "last name":"tanaka" "age":"20">
end

例 書き込み・ブロック指定あり

require "csv"

CSV.open("test.csv", "w") do |csv|
  csv << ["id", "first name", "last name", "age"]
  csv << ["1", "taro", "tanaka", "20"]
  csv << ["2", "jiro", "suzuki", "18"]
  csv << ["3", "ami", "sato", "19"]
  csv << ["4", "yumi", "adachi", "21"]
end
print File.read("test.csv")

# => id,first name,last name,age
#    1,taro,tanaka,20
#    2,jiro,suzuki,18
#    3,ami,sato,19
#    4,yumi,adachi,21

[SEE_ALSO] CSV.new, IO.open

parse(str, options = Hash.new) {|row| ... } -> nil[permalink][rdoc][edit]
parse(str, options = Hash.new) -> Array

このメソッドは文字列を簡単にパースすることができます。ブロックを与えた場合は、ブロックにそれぞれの行を渡します。ブロックを省略した場合は、配列の配列を返します。

[PARAM] str:
文字列を指定します。
[PARAM] options:
CSV.new のオプションと同じオプションを指定できます。 
例

require 'csv'
require 'pp'

s = <<EOS
id,first name,last name,age
1,taro,tanaka,20
2,jiro,suzuki,18
EOS

pp CSV.parse(s)
# => [["id", "first name", "last name", "age"],
#     ["1", "taro", "tanaka", "20"],
#     ["2", "jiro", "suzuki", "18"]]

CSV.parse(s, headers: true).each do |row|
  p [row['first name'], row['age']]
end
# => ["taro", "20"]
#    ["jiro", "18"]

例

require "csv"

csv = "id|first name|last name|age\n1|taro|tanaka|20\n2|jiro|suzuki|18"
CSV.parse(csv, col_sep: '|') do |row|
  p [row[1], row[2]]
end
# => ["first name", "last name"]
# => ["taro", "tanaka"]
# => ["jiro", "suzuki"]
parse_line(line, options = Hash.new) -> Array[permalink][rdoc][edit]

このメソッドは一行の CSV 文字列を配列に変換するためのショートカットです。

[PARAM] line:
文字列を指定します。複数行の文字列を指定した場合は、一行目以外は無視します。
[PARAM] options:
CSV.new のオプションと同じオプションを指定できます。 
例

require 'csv'

p CSV.parse_line("1,taro,tanaka,20")
# => ["1", "taro", "tanaka", "20"]

p CSV.parse_line("1|taro|tanaka|20", col_sep: '|')
# => ["1", "taro", "tanaka", "20"]

# 列をダブルクオートで囲むとその中にカンマや改行を含める事もできる。
# 他の仕様も含め詳しくはRFC4180を参照。
p CSV.parse_line("1,\"ta,ro\",\"tana\nka\", 20")
# => ["1", "ta,ro", "tana\nka", " 20"]
read(path, options = Hash.new) -> [Array] | CSV::Table[permalink][rdoc][edit]
readlines(path, options = Hash.new) -> [Array] | CSV::Table

CSV ファイルを配列の配列にするために使います。 headers オプションに偽でない値を指定した場合は CSV::Table オブジェクトを返します。

[PARAM] path:
CSV ファイルのパスを指定します。
[PARAM] options:
CSV.new のオプションと同じオプションを指定できます。 :encoding というキーを使用すると入力のエンコーディングを指定することができます。入力のエンコーディングか Encoding.default_external と異なる場合は必ず指定しなければなりません。 
例

require "csv"
require "pp"

File.write("test.csv", <<CSV)
id,first name,last name,age
1,taro,tanaka,20
2,jiro,suzuki,18
3,ami,sato,19
4,yumi,adachi,21
CSV

pp CSV.read("test.csv")

# => [["id", "first name", "last name", "age"],
#    ["1", "taro", "tanaka", "20"],
#    ["2", "jiro", "suzuki", "18"],
#    ["3", "ami", "sato", "19"],
#    ["4", "yumi", "adachi", "21"]]

例

require "csv"

File.write("test.csv", <<CSV)
id,first name,last name,age
1,taro,tanaka,20
2,jiro,suzuki,18
3,ami,sato,19
4,yumi,adachi,21
CSV

table = CSV.read("test.csv", headers: true)
p table.class # => CSV::Table
p table[0]    # => #<CSV::Row "id":"1" "first name":"taro" "last name":"tanaka" "age":"20">

[SEE_ALSO] CSV.new, CSV.table

table(path, options = Hash.new) -> CSV::Table | [Array][permalink][rdoc][edit]

以下と同等のことを行うメソッドです。 


CSV.read( path, { headers:           true,
                  converters:        :numeric,
                  header_converters: :symbol }.merge(options) )
[PARAM] path:
ファイル名を指定します。
[PARAM] options:
CSV.new のオプションと同じオプションを指定できます。

[SEE_ALSO] CSV.read

インスタンスメソッド

self << row -> self[permalink][rdoc][edit]
add_row(row) -> self
puts(row) -> self

自身に row を追加します。

データソースは書き込み用にオープンされていなければなりません。

[PARAM] row:
配列か CSV::Row のインスタンスを指定します。 CSV::Row のインスタンスが指定された場合は、CSV::Row#fields の値のみが追加されます。 
例 配列を指定

require "csv"

File.write("test.csv", <<CSV)
id,first name,last name,age
1,taro,tanaka,20
2,jiro,suzuki,18
3,ami,sato,19
4,yumi,adachi,21
CSV
CSV.open("test.csv", "a") do |csv|
  csv.puts(["5", "saburo", "kondo", "34"])
end

print File.read("test.csv")
# => id,first name,last name,age
#    1,taro,tanaka,20
#    2,jiro,suzuki,18
#    3,ami,sato,19
#    4,yumi,adachi,21
#    5,saburo,kondo,34

例 CSV::Row を指定

require "csv"

File.write("test.csv", <<CSV)
id,first name,last name,age
1,taro,tanaka,20
2,jiro,suzuki,18
3,ami,sato,19
4,yumi,adachi,21
CSV
CSV.open("test.csv", "a") do |csv|
  row = CSV::Row.new(["id", "first name", "last name", "age"], ["5", "saburo", "kondo", "34"])
  csv.add_row(row)
end

print File.read("test.csv")
# => "id", first name,last name,age
#    1,taro,tanaka,20
#    2,jiro,suzuki,18
#    3,ami,sato,19
#    4,yumi,adachi,21
#    5,saburo,kondo,34
binmode -> self[permalink][rdoc][edit]

IO#binmode に委譲します。

[SEE_ALSO] IO#binmode

binmode? -> bool[permalink][rdoc][edit]

IO#binmode? に委譲します。

[SEE_ALSO] IO#binmode?

close -> nil[permalink][rdoc][edit]

IO#close に委譲します。

[SEE_ALSO] IO#close

close_read -> nil[permalink][rdoc][edit]

IO#close_read に委譲します。

[SEE_ALSO] IO#close_read

close_write -> nil[permalink][rdoc][edit]

IO#close_write に委譲します。

[SEE_ALSO] IO#close_write

closed? -> bool[permalink][rdoc][edit]

IO#closed? に委譲します。

[SEE_ALSO] IO#closed?

col_sep -> String[permalink][rdoc][edit]

カラム区切り文字列として使用する文字列を返します。 

例

require "csv"

users =<<-EOS
id|first name|last name|age
1|taro|tanaka|20
2|jiro|suzuki|18
3|ami|sato|19
4|yumi|adachi|21
EOS

csv = CSV.new(users, headers: true, col_sep: "|")
csv.col_sep # => "|"
csv.first.to_a # => [["id", "1"], ["first name", "taro"], ["last name", "tanaka"], ["age", "20"]]

csv = CSV.new(users, headers: true)
csv.col_sep # => ","
csv.first.to_a # => [["id|first name|last name|age", "1|taro|tanaka|20"]]

[SEE_ALSO] CSV.new

convert(name)[permalink][rdoc][edit]
convert {|field| ... }
convert {|field, field_info| ... }

引数 name で指定した変換器かブロックに各フィールドを渡して文字列から別のオブジェクトへと変換します。

引数 name を指定した場合は、組み込みの CSV::Converters を変換器として利用するために使います。また、独自の変換器を追加することもできます。

ブロックパラメータを一つ受け取るブロックを与えた場合は、そのブロックはフィールドを受け取ります。ブロックパラメータを二つ受け取るブロックを与えた場合は、そのブロックは、フィールドと CSV::FieldInfo のインスタンスを受け取ります。ブロックは変換後の値かフィールドそのものを返さなければなりません。

[PARAM] name:
変換器の名前を指定します。 
例 name で Converter を指定

require "csv"

csv = CSV.new("date1,date2\n2018-07-09,2018-07-10")
csv.convert(:date)
csv.read # => [["date1", "date2"], [#<Date: 2018-07-09 ((2458309j,0s,0n),+0s,2299161j)>, #<Date: 2018-07-10 ((2458310j,0s,0n),+0s,2299161j)>]]

例 ブロックを指定

require "csv"

csv = CSV.new("date1,date2\n2018-07-09,2018-07-10", headers: true)
csv.convert do |field,field_info|
  p field
  p field_info
  Date.parse(field)
end
p csv.first

# => "2018-07-09"
# => <struct CSV::FieldInfo index=0, line=2, header="date1">
# => "2018-07-10"
# => #<struct CSV::FieldInfo index=1, line=2, header="date2">
# => #<CSV::Row "date1":#<Date: 2018-07-09 ((2458309j,0s,0n),+0s,2299161j)> "date2":#<Date: 2018-07-10 ((2458310j,0s,0n),+0s,2299161j)>>

[SEE_ALSO] CSV#converters, CSV#header_convert

converters -> Array[permalink][rdoc][edit]

現在の変換器のリストを返します。 

例

require "csv"

csv = CSV.new("header1,header2\nrow1_1,row1_2", converters: CSV::Converters.keys)
csv.converters  # => [:integer, :float, :integer, :float, :date, :date_time, :date_time, :integer, :float]

[SEE_ALSO] CSV::Converters

each {|row| ... } -> nil[permalink][rdoc][edit]

各行に対してブロックを評価します。

データソースは読み込み用にオープンされていなければなりません。 

例 CSV.new 時に :header => true を指定した場合

require "csv"

users = <<CSV
id,first name,last name,age
1,taro,tanaka,20
2,jiro,suzuki,18
3,ami,sato,19
4,yumi,adachi,21
CSV
csv = CSV.new(users, headers: true)
csv.each do |row|
  p row
end

# => #<CSV::Row "id":"1" "first name":"taro" "last name":"tanaka" "age":"20">
# => #<CSV::Row "id":"2" "first name":"jiro" "last name":"suzuki" "age":"18">
# => #<CSV::Row "id":"3" "first name":"ami" "last name":"sato" "age":"19">
# => #<CSV::Row "id":"4" "first name":"yumi" "last name":"adachi" "age":"21">

例 CSV.new 時に :header => true を指定しない場合

require "csv"

users = <<CSV
id,first name,last name,age
1,taro,tanaka,20
2,jiro,suzuki,18
3,ami,sato,19
4,yumi,adachi,21
CSV
csv = CSV.new(users)
csv.each do |row|
  p row
end

# => ["id", "first name", "last name", "age"]
# => ["1", "taro", "tanaka", "20"]
# => ["2", "jiro", "suzuki", "18"]
# => ["3", "ami", "sato", "19"]
# => ["4", "yumi", "adachi", "21"]
encoding -> Encoding[permalink][rdoc][edit]

読み書きするときに使用するエンコーディングを返します。 

例

require "csv"

csv = CSV.new("header1,header2\nrow1_1,row1_2", headers: true)
csv.encoding # => #<Encoding:UTF-8>
eof -> bool[permalink][rdoc][edit]
eof? -> bool

IO#eof, IO#eof? に委譲します。

[SEE_ALSO] IO#eof, IO#eof?

external_encoding -> Encoding | nil[permalink][rdoc][edit]

IO#external_encoding に委譲します。

fcntl(cmd, arg = 0) -> Integer[permalink][rdoc][edit]

IO#fcntl に委譲します。

field_size_limit -> Integer[permalink][rdoc][edit]

フィールドサイズの最大値を返します。 

例

require "csv"

csv = CSV.new(DATA)
csv.field_size_limit # => nil
p csv.read # => [["a", "b"], ["\n2\n2\n", ""]]

DATA.rewind
csv = CSV.new(DATA, field_size_limit: 4)
p csv.field_size_limit # => 4
csv.read # => #<CSV::MalformedCSVError: Field size exceeded on line 2.>

__END__
"a","b"
"
2
2
",""

[SEE_ALSO] CSV.new

fileno -> Integer[permalink][rdoc][edit]
to_i -> Integer

IO#fileno, IO#to_i に委譲します。

flock(operation) -> 0 | false[permalink][rdoc][edit]

File#flock に委譲します。

flush -> self[permalink][rdoc][edit]

IO#flush に委譲します。

force_quotes? -> bool[permalink][rdoc][edit]

出力される全てのフィールドがクオートされる場合は、真を返します。 

例

require "csv"

rows = [["header1", "header2"], ["row1_1,", "row1_2"]]
result = CSV.generate(force_quotes: false) do |csv|
  rows.each { |row| csv << row }
  csv.force_quotes? # => false
end
print result

# => header1,header2
#    "row1_1,",row1_2

例

require "csv"

rows = [["header1", "header2"], ["row1_1,", "row1_2"]]
result = CSV.generate(force_quotes: true) do |csv|
  rows.each { |row| csv << row }
  csv.force_quotes? # => true
end
print result

# => true
# => "header1","header2"
#    "row1_1,","row1_2"

[SEE_ALSO] CSV.new

fsync -> 0 | nil[permalink][rdoc][edit]

IO#fsync に委譲します。

shift -> Array | CSV::Row[permalink][rdoc][edit]
gets -> Array | CSV::Row
readline -> Array | CSV::Row

String や IO をラップしたデータソースから一行だけ読み込んでフィールドの配列か CSV::Row のインスタンスを返します。

データソースは読み込み用にオープンされている必要があります。

[RETURN]
ヘッダを使用しない場合は配列を返します。ヘッダを使用する場合は CSV::Row を返します。 
例

require "csv"

csv = CSV.new(DATA.read)
csv.readline # => ["header1", "header2"]
csv.readline # => ["row1_1", "row1_2"]

__END__
header1,header2
row1_1,row1_2
header_convert(name)[permalink][rdoc][edit]
header_convert {|field| ... }
header_convert {|field, field_info| ... }

CSV#convert に似ていますが、ヘッダ行用のメソッドです。

このメソッドはヘッダ行を読み込む前に呼び出さなければなりません。

[PARAM] name:
変換器の名前を指定します。 
例 name を指定

require "csv"

csv = CSV.new("header1,header2\nrow1_1,row1_2", headers: true)
csv.header_convert(:symbol)
csv.first.headers # => [:header1, :header2]

例 ブロックを指定

require "csv"

csv = CSV.new("header1,header2\nrow1_1,row1_2", headers: true)
csv.header_convert do |field|
  field.to_sym
end
csv.first.headers # => [:header1, :header2]

[SEE_ALSO] CSV#header_converters, CSV#convert

header_converters -> Array[permalink][rdoc][edit]

現在有効なヘッダ用変換器のリストを返します。

組込みの変換器は名前を返します。それ以外は、オブジェクトを返します。 

例

require "csv"

csv = CSV.new("HEADER1,HEADER2\nrow1_1,row1_2", headers: true, header_converters: CSV::HeaderConverters.keys)
csv.header_converters # => [:downcase, :symbol]
csv.read.to_a         # => [[:header1, :header2], ["row1_1", "row1_2"]]

[SEE_ALSO] CSV.new

header_row? -> bool[permalink][rdoc][edit]

次に読み込まれる行が、ヘッダである場合に真を返します。そうでない場合は、偽を返します。 

例

require "csv"

csv = CSV.new("header1,header2\nrow1_1,row1_2", headers: true)
csv.header_row? # => true
csv.readline
csv.header_row? # => false
headers -> Array | true | nil[permalink][rdoc][edit]

nil を返した場合は、ヘッダは使用されません。真を返した場合は、ヘッダを使用するが、まだ読み込まれていません。配列を返した場合は、ヘッダは既に読み込まれています。 

例

require "csv"

csv = CSV.new("header1,header2\nrow1_1,row1_2")
csv.headers # => nil
csv = CSV.new("header1,header2\nrow1_1,row1_2", headers: true)
csv.headers # => true
csv.read
csv.headers # =>["header1", "header2"]

[SEE_ALSO] CSV.new

inspect -> String[permalink][rdoc][edit]

ASCII 互換文字列で自身の情報を表したものを返します。 

例

require "csv"

csv = CSV.new("header1,header2\nrow1_1,row1_2")
csv.inspect # => "<#CSV io_type:StringIO encoding:UTF-8 lineno:0 col_sep:\",\" row_sep:\"\\n\" quote_char:\"\\\"\">"
internal_encoding -> Encoding | nil[permalink][rdoc][edit]

IO#internal_encoding に委譲します。

[SEE_ALSO] IO#internal_encoding

ioctl(cmd, arg = 0) -> Integer[permalink][rdoc][edit]

IO#ioctl に委譲します。

[SEE_ALSO] IO#ioctl

isatty -> bool[permalink][rdoc][edit]
tty? -> bool

IO#isatty, IO#tty? に委譲します。

[SEE_ALSO] IO#isatty, IO#tty?

lineno -> Integer[permalink][rdoc][edit]

このファイルから読み込んだ最終行の行番号を返します。フィールドに含まれる改行はこの値には影響しません。 

例

require "csv"

csv = CSV.new("header1,header2\nrow1_1,row1_2")
csv.lineno # => 0
csv.readline
csv.lineno # => 1
path -> String[permalink][rdoc][edit]

IO#path に委譲します。

[SEE_ALSO] IO#path

pid -> Integer | nil[permalink][rdoc][edit]

IO#pid に委譲します。

[SEE_ALSO] IO#pid

pos -> Integer[permalink][rdoc][edit]
tell -> Integer

IO#pos, IO#tell に委譲します。

[SEE_ALSO] IO#pos, IO#tell

pos=(n)[permalink][rdoc][edit]

IO#pos= に委譲します。

[SEE_ALSO] IO#pos=

quote_char -> String[permalink][rdoc][edit]

フィールドをクオートするのに使用する文字列を返します。 

例

require "csv"

csv = CSV.new("header1,header2\nrow1_1,row1_2", quote_char: "'")
csv.quote_char # => "'"

[SEE_ALSO] CSV.new

read -> [Array] | CSV::Table[permalink][rdoc][edit]
readlines -> [Array] | CSV::Table

残りの行を読み込んで配列の配列を返します。 self の生成時に headers オプションに偽でない値が指定されていた場合は CSV::Table オブジェクトを返します。

データソースは読み込み用にオープンされている必要があります。 

例 headers: false

require "csv"

csv = CSV.new(DATA.read)
csv.read
# => [["header1", "header2"], ["row1_1", "row1_2"], ["row2_1", "row2_2"]]

__END__
header1,header2
row1_1,row1_2
row2_1,row2_2

例 headers: true

require "csv"

csv = CSV.new(DATA.read, headers: true)
csv.read
# => #<CSV::Table mode:col_or_row row_count:3>

__END__
header1,header2
row1_1,row1_2
row2_1,row2_2
reopen(io) -> self[permalink][rdoc][edit]

IO#reopen に委譲します。

[SEE_ALSO] IO#reopen

return_headers? -> bool[permalink][rdoc][edit]

ヘッダを返す場合は、真を返します。そうでない場合は、偽を返します。 

例

require "csv"

csv = CSV.new("header1,header2\nrow1_1,row1_2", headers: true, return_headers: false)
csv.return_headers? # => false
csv.shift # => #<CSV::Row "header1":"row1_1" "header2":"row1_2">

csv = CSV.new("header1,header2\nrow1_1,row1_2", headers: true, return_headers: true)
csv.return_headers? # => true
csv.shift # => #<CSV::Row "header1":"header1" "header2":"header2">

[SEE_ALSO] CSV.new

rewind -> 0[permalink][rdoc][edit]

IO#rewind に似ています。CSV#lineno を 0 にします。 

例

require "csv"

csv = CSV.new("header1,header2\nrow1_1,row1_2")
csv.lineno # => 0
csv.readline
csv.lineno # => 1
csv.rewind
csv.lineno # => 0

[SEE_ALSO] IO#rewind

row_sep -> String[permalink][rdoc][edit]

行区切り文字列として使用する文字列を返します。 

例

require "csv"

csv = CSV.new("header1,header2|row1_1,row1_2", row_sep: "|")
csv.row_sep # => "|"
csv.read    # => [["header1", "header2"], ["row1_1", "row1_2"]]

[SEE_ALSO] CSV.new

seek(offset, whence = IO::SEEK_SET) -> 0[permalink][rdoc][edit]

IO#seek に委譲します。

[SEE_ALSO] IO#seek

skip_blanks? -> bool[permalink][rdoc][edit]

真である場合は、空行を読み飛ばします。 

例

require "csv"

csv = CSV.new("header1,header2\n\nrow1_1,row1_2")
csv.skip_blanks? # => false
csv.read         # => [["header1", "header2"], [], ["row1_1", "row1_2"]]
csv = CSV.new("header1,header2\n\nrow1_1,row1_2", skip_blanks: true)
csv.skip_blanks? # => true
csv.read         # => [["header1", "header2"], ["row1_1", "row1_2"]]

[SEE_ALSO] CSV.new

stat -> File::Stat[permalink][rdoc][edit]

IO#stat に委譲します。

[SEE_ALSO] IO#stat

string -> String[permalink][rdoc][edit]

StringIO#string に委譲します。

[SEE_ALSO] StringIO#string

sync -> bool[permalink][rdoc][edit]

IO#sync に委譲します。

[SEE_ALSO] IO#sync

sync=(newstate)[permalink][rdoc][edit]

IO#sync= に委譲します。

[SEE_ALSO] IO#sync=

to_io -> self[permalink][rdoc][edit]

IO#to_io に委譲します。

[SEE_ALSO] IO#to_io

truncate(path, length) -> 0[permalink][rdoc][edit]

File#truncate に委譲します。

[SEE_ALSO] File#truncate

unconverted_fields? -> bool[permalink][rdoc][edit]

パースした結果が unconverted_fields というメソッドを持つ場合に真を返します。そうでない場合は、偽を返します。 

例

require "csv"

csv = CSV.new("date1,date2\n2018-07-09,2018-07-10")
csv.unconverted_fields? # => nil
csv = CSV.new("date1,date2\n2018-07-09,2018-07-10", unconverted_fields: false)
csv.unconverted_fields? # => false
csv = CSV.new("date1,date2\n2018-07-09,2018-07-10", headers: true, unconverted_fields: true)
csv.unconverted_fields? # => true
csv.convert(:date)
row = csv.readline
row.fields              # => [#<Date: 2018-07-09 ((2458309j,0s,0n),+0s,2299161j)>, #<Date: 2018-07-10 ((2458310j,0s,0n),+0s,2299161j)>]
row.unconverted_fields  # => ["2018-07-09", "2018-07-10"]

[SEE_ALSO] CSV.new

write_headers? -> bool[permalink][rdoc][edit]

ヘッダを出力先に書き込む場合は真を返します。そうでない場合は偽を返します。 

例

require "csv"

csv = CSV.new("date1,date2\n2018-07-09,2018-07-10")
csv.write_headers? # => nil

header = ["header1", "header2"]
row = ["row1_1", "row1_2"]
result = CSV.generate(headers: header, write_headers: false) do |csv|
  csv.write_headers? # => false
  csv << row
end
result # => "row1_1,row1_2\n"

result = CSV.generate(headers: header, write_headers: true) do |csv|
  csv.write_headers? # => true
  csv << row
end
result # => "header1,header2\nrow1_1,row1_2\n"

[SEE_ALSO] CSV.new

定数

ConverterEncoding -> Encoding[permalink][rdoc][edit]

すべての変換器で使用するエンコーディングです。

Converters -> Hash[permalink][rdoc][edit]

このハッシュは名前でアクセスできる組み込みの変換器を保持しています。

CSV#convert で使用する変換器として使用できます。また CSV.new のオプションとして使用することもできます。

:integer

Kernel.#Integer を使用してフィールドを変換します。

:float

Kernel.#Float を使用してフィールドを変換します。

:numeric

:integer と :float の組み合わせです。

:date

Date.parse を使用してフィールドを変換します。

:date_time

DateTime.parse を使用してフィールドを変換します。

:all

:date_time と :numeric の組み合わせです。

全ての組み込みの変換器は、実際に変換する前にフィールドのデータの文字エンコーディングを UTF-8 に変換します。そのデータの文字エンコーディングを UTF-8 に変換出来なかった場合は、変換には失敗しますが、データは変更されません。

このハッシュは Object#freeze されていないので、ユーザは自由に値を追加することが出来ます。

複数の変換器を持つ要素を追加するときは、値に名前の配列を指定する必要があります。この要素の値には他の複数の変換器を持つ要素の名前を指定することもできます。

DEFAULT_OPTIONS -> Hash[permalink][rdoc][edit]

このオプションは呼び出し側で上書きしなかったときに使用するオプションです。

:col_sep

","

:row_sep

:auto

:quote_char

'"'

:field_size_limit

nil

:converters

nil

:unconverted_fields

nil

:headers

false

:return_headers

false

:header_converters

nil

:skip_blanks

false

:force_quotes

false

:skip_lines

nil

DateMatcher -> Regexp[permalink][rdoc][edit]

日付 (Date) 形式のデータを発見したり変換したりするための正規表現です。

DateTimeMatcher -> Regexp[permalink][rdoc][edit]

日時 (DateTime) 形式のデータを発見したり変換したりするための正規表現です。

HeaderConverters -> Hash[permalink][rdoc][edit]

このハッシュは名前でアクセスできる組み込みのヘッダ用変換器を保存しています。

CSV#header_convert で使用する変換器として使用できます。また CSV.new のオプションとして使用することもできます。

:downcase

ヘッダの文字列に対して String#downcase を呼び出します。

:symbol

ヘッダの文字列を小文字に変換してから、空白文字列 (\s) をアンダースコアに置換し、非英数字 (\W) を削除します。最後に String#to_sym を呼び出します。

全ての組み込みのヘッダ用変換器は、実際に変換する前にヘッダのデータの文字エンコーディングを UTF-8 に変換します。そのヘッダの文字エンコーディングを UTF-8 に変換できなかった場合は、変換には失敗しますが、データは変更されません。

このハッシュは Object#freeze されていないので、ユーザは自由に値を追加することが出来ます。

複数の変換器を持つ要素を追加するときは、値に名前の配列を指定する必要があります。この要素の値には他の複数の変換器を持つ要素の名前を指定することもできます。

VERSION -> String[permalink][rdoc][edit]

ライブラリのバージョンを表す文字列です。