Ruby 2.0.0 リファレンスマニュアル > ライブラリ一覧 > csvライブラリ > CSVクラス
クラスの継承リスト: CSV
< Enumerable
< Object
< Kernel
< BasicObject
extend: Forwardable
このクラスは CSV ファイルやデータに対する完全なインターフェイスを提供します。
# ファイルから一行ずつ CSV.foreach("path/to/file.csv") do |row| # use row here... end # ファイルから一度に arr_of_arrs = CSV.read("path/to/file.csv") # 文字列から一行ずつ CSV.parse("CSV,data,String") do |row| # use row here... end # 文字列から一行ずつ arr_of_arrs = CSV.parse("CSV,data,String")
# ファイルへ書き込み 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
csv_string = ["CSV", "data"].to_csv # => "CSV,data" csv_array = "CSV,String".parse_csv # => ["CSV", "String"]
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
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().
filter(options = Hash.new) {|row| ... }
[permalink][rdoc]filter(input, options = Hash.new) {|row| ... }
filter(input, output, options = Hash.new) {|row| ... }
このメソッドは CSV データに対して Unix のツール群のようなフィルタを構築 するのに便利です。
与えられたブロックに一行ずつ渡されます。ブロックに渡された行は必要であ れば変更することができます。ブロックの評価後に行を全て output に書き込 みます。
[SEE_ALSO] CSV.new
foreach(path, options = Hash.new) {|row| ... } -> nil
[permalink][rdoc]このメソッドは CSV ファイルを読むための主要なインターフェイスです。 各行が与えられたブロックに渡されます。
例:
# UTF-32BE な CSV ファイルを読み込んで UTF-8 な row をブロックに渡します CSV.foreach("a.csv", encoding: "UTF-32BE:UTF-8"){|row| p row }
generate(str = "", options = Hash.new) {|csv| ... } -> String
[permalink][rdoc]このメソッドは与えられた文字列をラップして CSV のオブジェクトとしてブロックに渡します。 ブロック内で CSV オブジェクトに行を追加することができます。 ブロックを評価した結果は文字列を返します。
このメソッドに与えられた文字列は変更されるので、新しい文字列オブジェクトが必要な 場合は Object#dup で複製してください。
[SEE_ALSO] CSV.new
generate_line(row, options = Hash.new) -> String
[permalink][rdoc]このメソッドは一つの Array オブジェクトを CSV 文字列に変換するためのショートカットです。
このメソッドは可能であれば row に含まれる最初の nil でない値を用いて出力の エンコーディングを推測します。
[SEE_ALSO] CSV.new
instance(data = $stdout, options = Hash.new) -> CSV
[permalink][rdoc]instance(data = $stdout, options = Hash.new) {|csv| ... } -> object
このメソッドは CSV.new のように CSV のインスタンスを返します。 しかし、返される値は Object#object_id と与えられたオプションを キーとしてキャッシュされます。
ブロックが与えられた場合、生成されたインスタンスをブロックに渡して評価した 結果を返します。
[SEE_ALSO] CSV.new
new(data, options = Hash.new) -> CSV
[permalink][rdoc]このメソッドは CSV ファイルを読み込んだり、書き出したりするために String か IO のインスタンスをラップします。
ラップされた文字列の先頭から読み込むことになります。 文字列に追記したい場合は CSV.generate を使用してください。 他の位置から処理したい場合はあらかじめそのように設定した StringIO を渡してください。
フィールドの区切り文字列を指定します。この文字列はパースする前にデータの エンコーディングに変換されます。
行区切りの文字列を指定します。: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.
フィールドをクオートする文字を指定します。長さ 1 の文字列でなければなりません。 正しいダブルクオートではなく間違ったシングルクオートを使用しているアプリケーション で便利です。 CSV will always consider a double sequence this character to be an escaped quote. この文字列はパースする前にデータのエンコーディングに変換されます。
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.
CSV::Converters から取り出した名前の配列です。変換器が一つだけ の場合は配列に格納する必要はありません。 全ての組み込みの変換器は、値を変換する前に UTF-8 にエンコーディング変 換を試みます。エンコーディング変換に失敗した場合はフィールドは変換さ れません。
真をセットすると CSV::Row#unconverted_fields という変換前のフィー ルドを返すメソッドを全ての行に追加します。headers オプションによって 追加したヘッダはフィールドではないので CSV::Row#unconverted_fields は空の配列を返します。
:first_row というシンボルか真を指定すると、CSV ファイルの一行目をヘッダとして扱います。 配列を指定するとそれをヘッダとして扱います。文字列を指定すると CSV.parse_line を 使用してパースした結果をヘッダとして扱います。このとき、:col_sep, :row_sep, :quote_char はこのインスタンスと同じものを使用します。この設定は CSV#shift の返り値を配列のかわりに CSV::Row のインスタンスに変更します。 CSV#read の返り値を配列の配列のかわりに CSV::Table のイン スタンスに変更します。
偽を指定すると、ヘッダ行を無視します。真を指定すると、ヘッダ行を ヘッダと値が同一の CSV::Row のインスタンスとして返します。
真を指定して :headers にも値をセットすると、ヘッダを出力します。
:converters オプションに似ていますが、ヘッダ専用の変換器を定義します。 全ての組み込みの変換器は、値を変換する前に UTF-8 にエンコーディング変 換を試みます。エンコーディング変換に失敗した場合はヘッダは変換されま せん。
真を指定すると、空行を読み飛ばします。
真を指定すると、全てのフィールドを作成時にクオートします。
指定した正規表現にマッチしたそれぞれの行をコメントとして読み飛ばします。
[SEE_ALSO] CSV::DEFAULT_OPTIONS, CSV.open
open(filename, mode = "rb", options = Hash.new) {|csv| ... } -> nil
[permalink][rdoc]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 オブジェクトを返します。 この挙動は Ruby1.8 の CSV ライブラリとは違います。Ruby1.8 では行をブロックに渡します。 Ruby1.9 以降では CSV.foreach を使うとブロックに行を渡します。
データが 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 に委譲します。
parse(str, options = Hash.new) {|row| ... } -> nil
[permalink][rdoc]parse(str, options = Hash.new) -> Array
このメソッドは文字列を簡単にパースすることができます。 ブロックを与えた場合は、ブロックにそれぞれの行を渡します。 ブロックを省略した場合は、配列の配列を返します。
parse_line(line, options = Hash.new) -> Array
[permalink][rdoc]このメソッドは一行の CSV 文字列を配列に変換するためのショートカットです。
read(path, options = Hash.new) -> [Array] | CSV::Table
[permalink][rdoc]readlines(path, options = Hash.new) -> [Array] | CSV::Table
CSV ファイルを配列の配列にするために使います。 headers オプションに偽でない値を指定した場合は CSV::Table オブジェクトを返します。
table(path, options = Hash.new) -> CSV::Table | [Array]
[permalink][rdoc]以下の例と同等のことを行うメソッドです。 日本語の CSV ファイルを扱う場合はあまり使いません。
例:
CSV.read( path, { headers: true, converters: :numeric, header_converters: :symbol }.merge(options) )
[SEE_ALSO] CSV.read
self << row -> self
[permalink][rdoc]add_row(row) -> self
puts(row) -> self
自身に row を追加します。
データソースは書き込み用にオープンされていなければなりません。
binmode -> self
[permalink][rdoc]IO#binmode に委譲します。
binmode? -> bool
[permalink][rdoc]IO#binmode? に委譲します。
close -> nil
[permalink][rdoc]IO#close に委譲します。
close_read -> nil
[permalink][rdoc]IO#close_read に委譲します。
close_write -> nil
[permalink][rdoc]IO#close_write に委譲します。
closed? -> bool
[permalink][rdoc]IO#closed? に委譲します。
col_sep -> String
[permalink][rdoc]カラム区切り文字列として使用する文字列を返します。
[SEE_ALSO] CSV.new
convert(name)
[permalink][rdoc]convert {|field| ... }
convert {|field, field_info| ... }
組み込みの CSV::Converters を変換器として利用するために使います。 また、独自の変換器を追加することもできます。
ブロックパラメータを一つ受け取るブロックを与えた場合は、そのブロックは フィールドを受け取ります。ブロックパラメータを二つ受け取るブロックを与 えた場合は、そのブロックは、フィールドと CSV::FieldInfo のインス タンスを受け取ります。ブロックは変換後の値かフィールドそのものを返さな ければなりません。
converters -> Array
[permalink][rdoc]現在の変換器のリストを返します。
[SEE_ALSO] CSV::Converters
each {|row| ... } -> nil
[permalink][rdoc]各行に対してブロックを評価します。
データソースは読み込み用にオープンされていなければなりません。
encoding -> Encoding
[permalink][rdoc]読み書きするときに使用するエンコーディングを返します。
eof -> bool
[permalink][rdoc]eof? -> bool
external_encoding -> Encoding | nil
[permalink][rdoc]IO#external_encoding に委譲します。
fcntl(cmd, arg = 0) -> Integer
[permalink][rdoc]IO#fcntl に委譲します。
field_size_limit -> Fixnum
[permalink][rdoc]フィールドサイズの最大値を返します。
[SEE_ALSO] CSV.new
fileno -> Integer
[permalink][rdoc]to_i -> Integer
flock(operation) -> 0 | false
[permalink][rdoc]File#flock に委譲します。
flush -> self
[permalink][rdoc]IO#flush に委譲します。
force_quotes? -> bool
[permalink][rdoc]出力されるフィールドがクオートされる場合は、真を返します。
[SEE_ALSO] CSV.new
fsync -> 0 | nil
[permalink][rdoc]IO#fsync に委譲します。
shift -> Array | CSV::Row
[permalink][rdoc]gets -> Array | CSV::Row
readline -> Array | CSV::Row
String や IO をラップしたデータソースから一行だけ読み込んで フィールドの配列か CSV::Row のインスタンスを返します。
データソースは読み込み用にオープンされている必要があります。
header_convert(name)
[permalink][rdoc]header_convert {|field| ... }
header_convert {|field, field_info| ... }
CSV#convert に似ていますが、ヘッダ行用のメソッドです。
このメソッドはヘッダ行を読み込む前に呼び出さなければなりません。
[SEE_ALSO] CSV#convert
header_converters -> Array
[permalink][rdoc]現在有効なヘッダ用変換器のリストを返します。
組込みの変換器は名前を返します。それ以外は、オブジェクトを返します。
[SEE_ALSO] CSV.new
header_row? -> bool
[permalink][rdoc]次に読み込まれる行が、ヘッダである場合に真を返します。 そうでない場合は、偽を返します。
headers -> Array | true | nil
[permalink][rdoc]nil を返した場合は、ヘッダは使用されません。 真を返した場合は、ヘッダを使用するが、まだ読み込まれていません。 配列を返した場合は、ヘッダは既に読み込まれています。
[SEE_ALSO] CSV.new
inspect -> String
[permalink][rdoc]ASCII 互換文字列で自身の情報を表したものを返します。
internal_encoding -> Encoding | nil
[permalink][rdoc]IO#internal_encoding に委譲します。
ioctl(cmd, arg = 0) -> Integer
[permalink][rdoc]IO#ioctl に委譲します。
isatty -> bool
[permalink][rdoc]tty? -> bool
lineno -> Fixnum
[permalink][rdoc]このファイルから読み込んだ最終行の行番号を返します。 フィールドに含まれる改行はこの値には影響しません。
path -> String
[permalink][rdoc]IO#path に委譲します。
pid -> Integer | nil
[permalink][rdoc]IO#pid に委譲します。
pos -> Integer
[permalink][rdoc]tell -> Integer
pos=(n)
[permalink][rdoc]IO#pos= に委譲します。
quote_char -> String
[permalink][rdoc]フィールドをクオートするのに使用する文字列を返します。
[SEE_ALSO] CSV.new
read -> [Array] | CSV::Table
[permalink][rdoc]readlines -> [Array] | CSV::Table
残りの行を読み込んで配列の配列を返します。 self の生成時に headers オプションに偽でない値が指定されていた場合は CSV::Table オブジェクトを返します。
データソースは読み込み用にオープンされている必要があります。
reopen(io) -> self
[permalink][rdoc]IO#reopen に委譲します。
return_headers? -> bool
[permalink][rdoc]ヘッダを返す場合は、真を返します。 そうでない場合は、偽を返します。
[SEE_ALSO] CSV.new
rewind -> 0
[permalink][rdoc]IO#rewind に似ています。CSV#lineno を 0 にします。
[SEE_ALSO] IO#rewind
row_sep -> String
[permalink][rdoc]行区切り文字列として使用する文字列を返します。
[SEE_ALSO] CSV.new
seek(offset, whence = IO::SEEK_SET) -> 0
[permalink][rdoc]IO#seek に委譲します。
skip_blanks? -> bool
[permalink][rdoc]真である場合は、空行を読み飛ばします。
[SEE_ALSO] CSV.new
stat -> File::Stat
[permalink][rdoc]IO#stat に委譲します。
string -> String
[permalink][rdoc]StringIO#string に委譲します。
sync -> bool
[permalink][rdoc]IO#sync に委譲します。
sync=(newstate)
[permalink][rdoc]IO#sync= に委譲します。
to_io -> self
[permalink][rdoc]IO#to_io に委譲します。
truncate(path, length) -> 0
[permalink][rdoc]File#truncate に委譲します。
unconverted_fields? -> bool
[permalink][rdoc]パースした結果が unconverted_fields というメソッドを持つ場合に真を返します。 そうでない場合は、偽を返します。
[SEE_ALSO] CSV.new
write_headers? -> bool
[permalink][rdoc]ヘッダを出力先に書き込む場合は真を返します。 そうでない場合は偽を返します。
[SEE_ALSO] CSV.new
ConverterEncoding -> Encoding
[permalink][rdoc]すべての変換器で使用するエンコーディングです。
Converters -> Hash
[permalink][rdoc]このハッシュは名前でアクセスできる組み込みの変換器を保持しています。
CSV#convert で使用する変換器として使用できます。 また CSV.new のオプションとして使用することもできます。
Kernel.#Integer を使用してフィールドを変換します。
Kernel.#Float を使用してフィールドを変換します。
:integer と :float の組み合わせです。
Date.parse を使用してフィールドを変換します。
DateTime.parse を使用してフィールドを変換します。
:date_time と :numeric の組み合わせです。
全ての組み込みの変換器は、実際に変換する前にフィールドのデータの 文字エンコーディングを UTF-8 に変換します。そのデータの文字エンコーディング を UTF-8 に変換出来なかった場合は、変換には失敗しますが、データは変更されません。
このハッシュは Object#freeze されていないので、ユーザは自由に値を 追加することが出来ます。
複数の変換器を持つ要素を追加するときは、値に名前の配列を指定する必要が あります。この要素の値には他の複数の変換器を持つ要素の名前を指定するこ ともできます。
DEFAULT_OPTIONS -> Hash
[permalink][rdoc]このオプションは呼び出し側で上書きしなかったときに使用するオプションです。
","
:auto
'"'
nil
nil
nil
false
false
nil
false
false
nil
DateMatcher -> Regexp
[permalink][rdoc]日付 (Date) 形式のデータを発見したり変換したりするための正規表現です。
DateTimeMatcher -> Regexp
[permalink][rdoc]日時 (DateTime) 形式のデータを発見したり変換したりするための正規表現です。
HeaderConverters -> Hash
[permalink][rdoc]このハッシュは名前でアクセスできる組み込みのヘッダ用変換器を保存しています。
CSV#header_convert で使用する変換器として使用できます。 また CSV.new のオプションとして使用することもできます。
ヘッダの文字列に対して String#downcase を呼び出します。
ヘッダの文字列を小文字に変換してから、空白文字列 (\s) をアンダースコアに 置換し、非英数字 (\W) を削除します。最後に String#to_sym を呼び出します。
全ての組み込みのヘッダ用変換器は、実際に変換する前にヘッダのデータの 文字エンコーディングを UTF-8 に変換します。そのヘッダの文字エンコーディング を UTF-8 に変換できなかった場合は、変換には失敗しますが、データは変更されません。
このハッシュは Object#freeze されていないので、ユーザは自由に値を 追加することが出来ます。
複数の変換器を持つ要素を追加するときは、値に名前の配列を指定する必要が あります。この要素の値には他の複数の変換器を持つ要素の名前を指定するこ ともできます。
VERSION -> String
[permalink][rdoc]ライブラリのバージョンを表す文字列です。