Ruby 4.0 リファレンスマニュアル

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)

CSV のパーサは、読み込み元または書き込み先の IO や String のエンコーディングのまま動作します。データは (Ruby にエンコーディングを変換させない限り) エンコーディングを変換されず、そのエンコーディングのままパースされます。そのため、CSV が返す Array や CSV::Row の文字列は、データと同じエンコーディングになります。これは、パーサ自身をデータのエンコーディングに変換することで実現しています。

複数のエンコーディングに対応するために、いくつかの値はエンコーディングの変換が必要です。たとえば :col_sep、:row_sep、:quote_char は、データのエンコーディングに合わせて変換されます。このため、CSV のデフォルト値はデータのエンコーディングを意識せずにそのまま使えます。この変換を避けたい場合は、これらの値を対象のエンコーディングで直接指定してください。

CSV のパーサの中核部分はエンコーディングに依存しませんが、一部の機能は依存します。たとえば、組み込みの変換器は、すべてのエンコーディングでネイティブに変換するのは難しいため、変換の前にデータを UTF-8 に変換しようとします。この変換を避けたい場合は、使用するエンコーディングに対応した独自の変換器を指定してください。

実際に必要な作業は単純で、CSV に渡す IO や String に正しいエンコーディングが設定されていれば、そのまま動作します。 IO を開く CSV のメソッド (CSV.foreach、CSV.open、CSV.read、CSV.readlines) では、エンコーディングを指定できます。

ただし、ASCII 互換でないエンコーディングの String に CSV を生成するときは少し事情が異なります。この場合は CSV が準備のために参照できるデータがないため、ほとんどの場合は目的のエンコーディングを明示的に指定する必要があります。なお、CSV.generate_line や Array#to_csv では、出力する行のフィールドからエンコーディングを推測します。

目次

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

継承しているメソッド

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

特異メソッド

filter(options = Hash.new) {|row| ... }Ruby 1.9.3 から[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 ファイルのパス(文字列)、または StringIO オブジェクトを指定します。StringIO を渡した場合はその内容から読み込みます。
[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']
p CSV.generate_line(taro, col_sep: '|') # => "1|taro|tanaka|20\n"

[SEE_ALSO] CSV.new

instance(data = $stdout, **options) -> CSVRuby 1.9.3 から[permalink][rdoc][edit]
instance(data = $stdout, **options) {|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)
p 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) -> CSVRuby 1.9.3 から[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" の並びまでを読みます。この並びはクオートされたフィールドの中にあっても選ばれます(そこでも同じ行末が使われているものとみなします)。どの並びも見つからなかった場合、data が ARGF・Object::STDIN・Object::STDOUT・Object::STDERR の場合、またはストリームが出力専用の場合は、デフォルトの $INPUT_RECORD_SEPARATOR($/)を使います。自動検出には多少の時間がかかるので、速度が重要な場合は明示的に指定してください。また、Windows でこの機能を使う場合は IO オブジェクトをバイナリモードで開いてください。改行の変換によって、先読みする前の位置に戻す処理に問題が起きることがあるためです。指定した文字列はパースする前にデータのエンコーディングに変換されます。

:quote_char

フィールドをクオートする文字を指定します。長さ 1 の文字列でなければなりません。正しいダブルクオートではなく間違ったシングルクオートを使用しているアプリケーションで便利です。この文字を 2 つ続けたものは、常にエスケープされたクオート文字とみなします。この文字列はパースする前にデータのエンコーディングに変換されます。

:field_size_limit

:max_field_size の古い形で、非推奨です。:max_field_size を指定しなかった場合、:max_field_size に field_size_limit - 1 を指定したものとして扱います。

:max_field_size

フィールドの最大の長さ(文字数)を指定します。これより長いフィールドがあると CSV::MalformedCSVError が発生します。デフォルトは nil(制限なし)です。

: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 にエンコーディング変換を試みます。変換後のヘッダの文字エンコーディングと、UTF-8 に変換できなかった場合の例外については CSV::HeaderConverters を参照してください。

:skip_blanks

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

:force_quotes

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

:skip_lines

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

[EXCEPTION] CSV::MalformedCSVError:
不正な CSV をパースしようとしたときに発生します。
[EXCEPTION] CSV::InvalidEncodingError:
入力に不正なバイト列が含まれていたときに発生します。CSV::MalformedCSVError のサブクラスです。
例: ファイルの読み込み
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)
  p csv.class # => CSV
  p 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:
ファイル名、または StringIO オブジェクトを指定します。StringIO を渡した場合は、読み込み・書き込みともにその StringIO に対して行われます。
[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)
p csv.class # => CSV
p 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|
  p csv.class # => CSV
  p 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 ファイルのパス(文字列)、または StringIO オブジェクトを指定します。StringIO を渡した場合はその内容から読み込みます。
[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]Ruby 1.9.3 から[permalink][rdoc][edit]

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

CSV.read( path, { headers:           true,
                  converters:        :numeric,
                  header_converters: :symbol }.merge(options) )
[PARAM] path:
CSV ファイルのパス(文字列)、または StringIO オブジェクトを指定します。StringIO を渡した場合はその内容から読み込みます。
[PARAM] options:
CSV.new のオプションと同じオプションを指定できます。

[SEE_ALSO] CSV.read

インスタンスメソッド

self << row -> selfRuby 1.9.3 から[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 -> selfRuby 1.9.3 から[permalink][rdoc][edit]

IO#binmode に委譲します。

[SEE_ALSO] IO#binmode

binmode? -> boolRuby 1.9.3 から[permalink][rdoc][edit]

IO#binmode? に委譲します。

[SEE_ALSO] IO#binmode?

close -> nilRuby 1.9.3 から[permalink][rdoc][edit]

IO#close に委譲します。

[SEE_ALSO] IO#close

close_read -> nilRuby 1.9.3 から[permalink][rdoc][edit]

IO#close_read に委譲します。

[SEE_ALSO] IO#close_read

close_write -> nilRuby 1.9.3 から[permalink][rdoc][edit]

IO#close_write に委譲します。

[SEE_ALSO] IO#close_write

closed? -> boolRuby 1.9.3 から[permalink][rdoc][edit]

IO#closed? に委譲します。

[SEE_ALSO] IO#closed?

col_sep -> StringRuby 1.9.3 から[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: "|")
p csv.col_sep # => "|"
p csv.first.to_a # => [["id", "1"], ["first name", "taro"], ["last name", "tanaka"], ["age", "20"]]

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

[SEE_ALSO] CSV.new

convert(name)Ruby 1.9.3 から[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)
p 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 -> ArrayRuby 1.9.3 から[permalink][rdoc][edit]

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

例
require "csv"

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

[SEE_ALSO] CSV::Converters

each {|row| ... } -> nilRuby 1.9.3 から[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 -> EncodingRuby 1.9.3 から[permalink][rdoc][edit]

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

例
require "csv"

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

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

[SEE_ALSO] IO#eof, IO#eof?

external_encoding -> Encoding | nilRuby 1.9.3 から[permalink][rdoc][edit]

IO#external_encoding に委譲します。

fcntl(cmd, arg = 0) -> IntegerRuby 1.9.3 から[permalink][rdoc][edit]

IO#fcntl に委譲します。

field_size_limit -> Integer | nilRuby 1.9.3 から[permalink][rdoc][edit]

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

3.2 以降は CSV#max_field_size に 1 を足した値(:max_field_size が nil なら nil)を返します。

例
require "csv"

text = <<~CSV
  "a","b"
  "
  2
  2
  ",""
CSV

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

csv = CSV.new(text, field_size_limit: 4)
p csv.field_size_limit # => 4
csv.read # ~> CSV::MalformedCSVError: Field size exceeded: 5 > 3 in line 2.

[SEE_ALSO] CSV.new

fileno -> IntegerRuby 1.9.3 から[permalink][rdoc][edit]
to_i -> Integer

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

flock(operation) -> 0 | falseRuby 1.9.3 から[permalink][rdoc][edit]

File#flock に委譲します。

flush -> selfRuby 1.9.3 から[permalink][rdoc][edit]

IO#flush に委譲します。

force_quotes? -> boolRuby 1.9.3 から[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 }
  p 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 }
  p csv.force_quotes? # => true
end
print result

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

[SEE_ALSO] CSV.new

fsync -> 0 | nilRuby 1.9.3 から[permalink][rdoc][edit]

IO#fsync に委譲します。

shift -> Array | CSV::RowRuby 1.9.3 から[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)
p csv.readline # => ["header1", "header2"]
p csv.readline # => ["row1_1", "row1_2"]

__END__
header1,header2
row1_1,row1_2
header_convert(name)Ruby 1.9.3 から[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)
p 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
p csv.first.headers # => [:header1, :header2]

[SEE_ALSO] CSV#header_converters, CSV#convert

header_converters -> ArrayRuby 1.9.3 から[permalink][rdoc][edit]

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

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

例
require "csv"

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

[SEE_ALSO] CSV.new

header_row? -> boolRuby 1.9.3 から[permalink][rdoc][edit]

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

例
require "csv"

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

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

例
require "csv"

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

[SEE_ALSO] CSV.new

inspect -> StringRuby 1.9.3 から[permalink][rdoc][edit]

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

例
require "csv"

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

IO#internal_encoding に委譲します。

[SEE_ALSO] IO#internal_encoding

ioctl(cmd, arg = 0) -> IntegerRuby 1.9.3 から[permalink][rdoc][edit]

IO#ioctl に委譲します。

[SEE_ALSO] IO#ioctl

isatty -> boolRuby 1.9.3 から[permalink][rdoc][edit]
tty? -> bool

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

[SEE_ALSO] IO#isatty, IO#tty?

lineno -> IntegerRuby 1.9.3 から[permalink][rdoc][edit]

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

例
require "csv"

csv = CSV.new("header1,header2\nrow1_1,row1_2")
p csv.lineno # => 0
csv.readline
p csv.lineno # => 1
max_field_size -> Integer | nilRuby 3.2 から[permalink][rdoc][edit]

フィールドの長さ(文字数)の上限を返します。制限していない場合は nil を返します。

CSV.new の :max_field_size オプション、または :field_size_limit オプション(この場合は指定した値から 1 を引いた値)で設定します。

[SEE_ALSO] CSV#field_size_limit

例
require "csv"

csv = CSV.new("a,b\n")
p csv.max_field_size # => nil

csv = CSV.new("a,b\n", max_field_size: 3)
p csv.max_field_size # => 3
p csv.field_size_limit # => 4

csv = CSV.new("a,b\n", field_size_limit: 4)
p csv.max_field_size # => 3
path -> StringRuby 1.9.3 から[permalink][rdoc][edit]

IO#path に委譲します。

[SEE_ALSO] IO#path

pid -> Integer | nilRuby 1.9.3 から[permalink][rdoc][edit]

IO#pid に委譲します。

[SEE_ALSO] IO#pid

pos -> IntegerRuby 1.9.3 から[permalink][rdoc][edit]
tell -> Integer

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

[SEE_ALSO] IO#pos, IO#tell

pos=(n)Ruby 1.9.3 から[permalink][rdoc][edit]

IO#pos= に委譲します。

[SEE_ALSO] IO#pos=

quote_char -> StringRuby 1.9.3 から[permalink][rdoc][edit]

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

例
require "csv"

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

[SEE_ALSO] CSV.new

read -> [Array] | CSV::TableRuby 1.9.3 から[permalink][rdoc][edit]
readlines -> [Array] | CSV::Table

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

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

例 headers: false
require "csv"

csv = CSV.new(DATA.read)
p 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)
p csv.read
# => #<CSV::Table mode:col_or_row row_count:3>

__END__
header1,header2
row1_1,row1_2
row2_1,row2_2
reopen(io) -> selfRuby 1.9.3 から[permalink][rdoc][edit]

IO#reopen に委譲します。

[SEE_ALSO] IO#reopen

return_headers? -> boolRuby 1.9.3 から[permalink][rdoc][edit]

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

例
require "csv"

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

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

[SEE_ALSO] CSV.new

rewind -> 0Ruby 1.9.3 から[permalink][rdoc][edit]

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

例
require "csv"

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

[SEE_ALSO] IO#rewind

row_sep -> StringRuby 1.9.3 から[permalink][rdoc][edit]

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

例
require "csv"

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

[SEE_ALSO] CSV.new

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

IO#seek に委譲します。

[SEE_ALSO] IO#seek

skip_blanks? -> boolRuby 1.9.3 から[permalink][rdoc][edit]

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

例
require "csv"

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

[SEE_ALSO] CSV.new

stat -> File::StatRuby 1.9.3 から[permalink][rdoc][edit]

IO#stat に委譲します。

[SEE_ALSO] IO#stat

string -> StringRuby 1.9.3 から[permalink][rdoc][edit]

StringIO#string に委譲します。

[SEE_ALSO] StringIO#string

sync -> boolRuby 1.9.3 から[permalink][rdoc][edit]

IO#sync に委譲します。

[SEE_ALSO] IO#sync

sync=(newstate)Ruby 1.9.3 から[permalink][rdoc][edit]

IO#sync= に委譲します。

[SEE_ALSO] IO#sync=

to_io -> selfRuby 1.9.3 から[permalink][rdoc][edit]

IO#to_io に委譲します。

[SEE_ALSO] IO#to_io

truncate(path, length) -> 0Ruby 1.9.3 から[permalink][rdoc][edit]

File#truncate に委譲します。

[SEE_ALSO] File#truncate

unconverted_fields? -> boolRuby 1.9.3 から[permalink][rdoc][edit]

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

例
require "csv"

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

[SEE_ALSO] CSV.new

write_headers? -> boolRuby 1.9.3 から[permalink][rdoc][edit]

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

例
require "csv"

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

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

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

[SEE_ALSO] CSV.new

定数

ConverterEncoding -> EncodingRuby 1.9.3 から[permalink][rdoc][edit]

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

Converters -> HashRuby 1.9.3 から[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 -> HashRuby 1.9.3 から[permalink][rdoc][edit]

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

:col_sep

","

:row_sep

:auto

:quote_char

'"'

:field_size_limit

nil

:max_field_size

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

:write_headers

nil

:quote_empty

true

:force_quotes

false

:write_converters

nil

:write_nil_value

nil

:write_empty_value

""

DateMatcher -> RegexpRuby 1.9.3 から[permalink][rdoc][edit]

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

DateTimeMatcher -> RegexpRuby 1.9.3 から[permalink][rdoc][edit]

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

HeaderConverters -> HashRuby 1.9.3 から[permalink][rdoc][edit]

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

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

:downcase

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

:symbol

ヘッダの文字列を小文字に変換してから、英数字・アンダースコア・空白文字 (\s) 以外の文字を削除し、前後の空白文字を取り除いて、残った空白文字の並びをアンダースコアに置換します。最後に String#to_sym を呼び出します。英数字は ASCII の範囲の文字だけなので、日本語などの文字は削除されます。

:symbol_raw

ヘッダの文字列に対して String#to_sym を呼び出します。:symbol と違い、小文字への変換や文字の削除はしません。

日本語だけのヘッダは :symbol では :"" になります。そのようなヘッダには :symbol_raw を使ってください。

例 日本語のヘッダをシンボルに変換する
require "csv"

data = "名前,First Name!\n太郎,1\n"
p CSV.parse(data, headers: true, header_converters: :symbol).headers     # => [:"", :first_name]
p CSV.parse(data, headers: true, header_converters: :symbol_raw).headers # => [:名前, :"First Name!"]

全ての組み込みのヘッダ用変換器は、実際に変換する前にヘッダのデータの文字エンコーディングを UTF-8 に変換します。:downcase が返すヘッダは UTF-8 に変換した文字列のままで、元の文字エンコーディングには戻しません。ヘッダの文字エンコーディングを UTF-8 に変換できなかった場合は、String#encode の例外(Encoding::UndefinedConversionError など)が発生します。

例 Shift_JIS のヘッダを変換する
require "csv"

data = "名前,Count\n太郎,1\n".encode("Shift_JIS")
table = CSV.parse(data, headers: true, header_converters: :downcase)
p table.headers                 # => ["名前", "count"]
p table.headers.map(&:encoding) # => [#<Encoding:UTF-8>, #<Encoding:UTF-8>]

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

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

VERSION -> StringRuby 1.9.3 から[permalink][rdoc][edit]

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