singleton method CSV.new

このメソッドは 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

クオートされたフィールドの閉じクオートを探すときに先読みする大きさの上限を指定します。この上限の範囲内に閉じクオートが見つからなかった場合、データが壊れているものとみなして CSV::MalformedCSVError が発生します。パーサへの事実上の DoS 攻撃を防ぐために使えますが、正当なデータのパースも失敗する可能性があるため、デフォルトは 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 にエンコーディング変換を試みます。エンコーディング変換に失敗した場合はヘッダは変換されません。

: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)
  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