From 0048acc32a6ef07465b3dedfd445a62effd5c9df Mon Sep 17 00:00:00 2001 From: okkez Date: Mon, 20 Sep 2010 17:10:51 +0900 Subject: [PATCH] update csv for Ruby1.9 --- refm/api/src/csv.rd | 1006 ++++++++++++++++++++++++++++++++++++++++++- refm/api/src/csv/CSV__Row | 212 +++++++++- refm/api/src/csv/CSV__Table | 229 ++++++++++ 3 files changed, 1439 insertions(+), 8 deletions(-) create mode 100644 refm/api/src/csv/CSV__Table diff --git a/refm/api/src/csv.rd b/refm/api/src/csv.rd index f55c8f6..64f8a32 100644 --- a/refm/api/src/csv.rd +++ b/refm/api/src/csv.rd @@ -1,4 +1,997 @@ -#@since 1.8.0 +#@since 1.9.1 +CSV (Comma Separated Values) を扱うライブラリです。 + +#@# 説明を記述する +#@# 単なる翻訳ではないものを書く + +このバージョンの CSV ライブラリは FasterCSV から始まりました。 +FasterCSV は Ruby1.8 に標準添付されている CSV ライブラリの置き換えとして開発されました。 +このライブラリはユーザの関心事を解決するためにデザインされています。 +主なゴールが三つあります。 + + (1) ピュア Ruby のままで元の CSV ライブラリよりもかなり速くすること + (2) 小さくメンテナンスしやすいコードベースであること (FasterCSV はかなり大きく + 機能豊かになりました。構文解析部分のコードはかなり小さいままです) + (3) CSV のインターフェイスを改善すること + +明らかに最後のものは主観的です。変更するやむを得ない理由が無い限り、オリジナルの +インターフェイスに従うようにしたので、おそらく旧 CSV ライブラリとはあまり +大きな違いは無いでしょう。 + +=== 古い CSV ライブラリとの違い + +大きな違いについて言及します。 + +==== CSV 構文解析 + + * このパーサは m17n に対応しています。[[c:CSV]] も参照してください + * このライブラリはより厳しいパーサを持っているので、問題のあるデータに対して [[c:MalformedCSVError]] を投げます + * 旧 CSV ライブラリよりも行末に関しては寛容ではありません。あなたが :row_sep としてセットした値が法です。 + しかし、自動検出させることもできます + * 旧ライブラリでは空行に対して [nil] を返しますが、このライブラリは空の配列を返します + * このライブラリはかなり速いパーサを持っています + +==== インターフェイス + + * オプションをセットするのにハッシュ形式の引数を使うようになりました + * CSV#generate_row, CSV#parse_row はなくなりました + * 古い CSV::Reader, CSV::Writer クラスはなくなりました + * [[m:CSV.open]] はより Ruby らしくなりました + * [[c:CSV]] オブジェクトは [[c:IO]] の多くのメソッドをサポートするようになりました + * 文字列や IO のようなオブジェクトを読み書きするためにラップする [[m:CSV.new]] メソッドが追加されました + * [[m:CSV.generate]] は古いものとは異なります + * 部分読み出しはもうサポートしていません。読み込みは行単位で行います + * パフォーマンスのため、インスタンスメソッドでセパレータを上書き出来なくなりました。 + [[m:CSV.new]] でセットするようにしてください。 + +=== CSV とは + +CSV ライブラリは [[RFC:4180]] から直接とられたかなり厳しい定義を維持します。 +一ヶ所だけ定義を緩和することでこのライブラリを使いやすくしています。[[c:CSV]] は +すべての有効な CSV ファイルをパースします。 + +What you don't want to do is feed CSV invalid data. Because of the way the +CSV format works, it's common for a parser to need to read until the end of +the file to be sure a field is invalid. This eats a lot of time and memory. + +Luckily, when working with invalid CSV, Ruby's built-in methods will almost +always be superior in every way. For example, parsing non-quoted fields is as +easy as: + + data.split(",") + += class CSV < Object +extend Forwardable +include Enumerable + +#@# 説明を記述する + +このクラスは 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 + +=== 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, :col_sep, :row_sep, and +:quote_char 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(). + +I try to point out any other Encoding issues in the documentation of methods +as they come up. + +This has been tested to the best of my ability with all non-"dummy" Encodings +Ruby ships with. However, it is brave new code and may have some bugs. +Please feel free to {report}[mailto:james@grayproductions.net] any issues you +find with it. + +== Constants + +--- DateMatcher -> Regexp + +日付 (Date) 形式のデータを発見したり変換したりするための正規表現です。 + +--- DateTimeMatcher -> Regexp + +日時 (DateTime) 形式のデータを発見したり変換したりするための正規表現です。 + +--- ConverterEncoding -> Encoding + +すべての変換器で使用するエンコーディングです。 + +--- Converters -> Hash +#@todo + +このハッシュは名前でアクセスできる組み込みの変換器を保持しています。 + +[[m:CSV#convert]] で使用する変換器として使用できます。 +また [[m:CSV.new]] のオプションとして使用することもできます。 + +: :integer + [[m:Kernel.#Integer]] を使用してフィールドを変換します。 +: :float + [[m:Kernel.#Float]] を使用してフィールドを変換します。 +: :numeric + :integer と :float の組み合わせです。 +: :date + [[m:Date.parse]] を使用してフィールドを変換します。 +: :date_time + [[m:DateTime.parse]] を使用してフィールドを変換します。 +: :all + :date_time と :numeric の組み合わせです。 + +全ての組み込みの変換器は、実際に変換する前にフィールドのデータの +文字エンコーディングを UTF-8 に変換します。そのデータの文字エンコーディング +を UTF-8 に変換出来なかった場合は、変換には失敗しますが、データは変更されません。 + +このハッシュは [[m:Object#freeze]] されていないので、ユーザは自由に値を +追加することが出来ます。 + +To add a combo field, the value should be an Array of names. Combo fields +can be nested with other combo fields. + +--- HeaderConverters -> Hash +#@todo + +このハッシュは名前でアクセスできる組み込みのヘッダ用変換器を保存しています。 + +[[m:CSV#header_convert]] で使用する変換器として使用できます。 +また [[m:CSV.new]] のオプションとして使用することもできます。 + +: :downcase + ヘッダの文字列に対して [[m:String#downcase]] を呼び出します。 +: :symbol + ヘッダの文字列を小文字に変換してから、空白文字列 (\s) をアンダースコアに + 置換し、非英数字 (\W) を削除します。最後に [[m:String#to_sym]] を呼び出します。 + +全ての組み込みのヘッダ用変換器は、実際に変換する前にヘッダのデータの +文字エンコーディングを UTF-8 に変換します。そのヘッダの文字エンコーディング +を UTF-8 に変換できなかった場合は、変換には失敗しますが、データは変更されません。 + +このハッシュは [[m:Object#freeze]] されていないので、ユーザは自由に値を +追加することが出来ます。 + +To add a combo field, the value should be an Array of names. Combo fields +can be nested with other combo fields. + +--- DEFAULT_OPTIONS -> Hash + +このオプションは呼び出し側で上書きしなかったときに使用するオプションです。 + +: :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 + +--- VERSION -> String + +ライブラリのバージョンを表す文字列です。 + +#@if (version == "1.9.1") +2.4.5 +#@end +#@if (version == "1.9.2") +2.4.7 +#@end + +== Singleton Methods + +--- new(data, options = Hash.new) -> CSV +#@todo + +このメソッドは CSV ファイルを読み込んだり、書き出したりするために +[[c:String]] か [[c:IO]] のインスタンスをラップします。 + +ラップされた文字列の先頭から読み込むことになります。 +文字列に追記したい場合は [[m:CSV#generate]] を使用してください。 +他の位置から処理したい場合はあらかじめそのように設定した [[c:StringIO]] を渡してください。 + +Note that a wrapped String will be positioned at at the beginning (for +reading). If you want it at the end (for writing), use CSV::generate(). +If you want any other positioning, pass a preset StringIO object instead. + +@param data [[c:String]] か [[c:IO]] のインスタンスを指定します。 + [[c:String]] のインスタンスを指定した場合、[[m: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, STDIN, STDOUT, or + 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 + An Array of names from the Converters Hash and/or lambdas that handle custom + conversion. A single converter doesn't have to be in an Array. All + built-in converters try to transcode fields to UTF-8 before converting. + The conversion will fail if the data cannot be transcoded, leaving the + field unchanged. +: :unconverted_fields + If set to +true+, an unconverted_fields() method will be + added to all returned rows (Array or CSV::Row) that will return the fields + as they were before conversion. Note that :headers supplied by + Array or String were not fields of the document and thus will have an empty + Array attached. +: :headers + :first_row というシンボルか真を指定すると、CSV ファイルの一行目をヘッダとして扱います。 + 配列を指定するとそれをヘッダとして扱います。文字列を指定すると [[m:CSV.parse_line]] を + 使用してパースした結果をヘッダとして扱います。このとき、:col_sep, :row_sep, :quote_char + はこのインスタンスと同じものを使用します。 + This setting causes CSV#shift() to return + rows as CSV::Row objects instead of Arrays and CSV#read() to return + CSV::Table objects instead of an Array of Arrays. +: :return_headers + When +false+, header rows are silently swallowed. If set to +true+, header + rows are returned in a CSV::Row object with identical headers and + fields (save that the fields do not go through the converters). +: :write_headers + 真を指定して :headers にも値をセットすると、ヘッダを出力します。 +: :header_converters + Identical in functionality to :converters save that the + conversions are only made to header rows. All built-in converters try to + transcode headers to UTF-8 before converting. The conversion will fail + if the data cannot be transcoded, leaving the header unchanged. +: :skip_blanks + 真を指定すると、空行を読み飛ばします。 +: :force_quotes + 真を指定すると、全てのフィールドを作成時にクオートします。 + +@raise CSV::MalformedCSVError 不正な CSV をパースしようとしたときに発生します。 + +@see [[m:CSV::DEFAULT_OPTIONS]], [[m:CSV.open]] + +--- dump(ary_of_objs, io = "", options = Hash.new) -> String | nil +#@todo + +このメソッドは Ruby オブジェクトの配列を文字列や CSV ファイルにシリアライズすることができます。 +[[c:Marshal]] や [[lib:yaml]] よりは不便ですが、スプレッドシートやデータベース +とのやりとりには役に立つでしょう。 + +Out of the box, this method is intended to work with simple data objects or +Structs. It will serialize a list of instance variables and/or +Struct.members(). + +If you need need more complicated serialization, you can control the process +by adding methods to the class to be serialized. + +A class method csv_meta() is responsible for returning the first row of the +document (as an Array). This row is considered to be a Hash of the form +key_1,value_1,key_2,value_2,... CSV::load() expects to find a class key +with a value of the stringified class name and CSV::dump() will create this, +if you do not define this method. This method is only called on the first +object of the Array. + +The next method you can provide is an instance method called csv_headers(). +This method is expected to return the second line of the document (again as +an Array), which is to be used to give each column a header. By default, +CSV::load() will set an instance variable if the field header starts with an +@ character or call send() passing the header as the method name and +the field value as an argument. This method is only called on the first +object of the Array. + +Finally, you can provide an instance method called csv_dump(), which will +be passed the headers. This should return an Array of fields that can be +serialized for this object. This method is called once for every object in +the Array. + +The +io+ parameter can be used to serialize to a File, and +options+ can be +anything CSV::new() accepts. + +@param ary_of_objs 任意の配列を指定します。 + +@param io データの出力先を指定します。デフォルトは文字列です。 + +@param options オプションを指定します。 + +@see [[m:CSV.new]] + +--- filter(options = Hash.new){|row| ... } +--- filter(input, options = Hash.new){|row| ... } +--- filter(input, output, options = Hash.new){|row| ... } +#@todo +#@# -> discard + +このメソッドは CSV データに対して Unix のツール群のようなフィルタを構築するのに便利です。 + +Each row is yielded to the provided block which can alter it as needed. +After the block returns, the row is appended to +output+ altered or not. + +@param input [[c:String]] か [[c:IO]] のインスタンスを指定します。 + デフォルトは [[c:ARGF]] です。 + +@param output [[c:String]] か [[c:IO]] のインスタンスを指定します。 + デフォルトは [[m:$stdout]] です。 + +@param options ":in_", ":input_" で始まるキーは input にだけ適用されます。 + ":out_", ":output_" で始まるキーは output にだけ適用されます。 + それ以外のキーは両方に適用されます。 + ":output_row_sep" のデフォルト値は [[m:$/]] です。 + +@see [[m:CSV.new]] + +--- foreach(path, options = Hash.new){|row| ... } -> nil + +このメソッドは CSV ファイルを読むための主要なインターフェイスです。 +各行が与えられたブロックに渡されます。 + +例: + + # UTF-32BE な CSV ファイルを読み込んで UTF-8 な row をブロックに渡します + CSV.foreach("a.csv", encoding: "UTF-32BE:UTF-8"){|row| p row } + +@param path CSV ファイルのパスを指定します。 + +@param options [[m:CSV.new]] のオプションと同じオプションを指定できます。 + :encoding というキーを使用すると入出力のエンコーディングを指定することができます。 + [[m:Encoding.default_external]] と異なるエンコーディングを持つ入力を使用する場合は、 + 必ずエンコーディングを指定してください。 + +@see [[m:CSV.new]], [[m:File.open]] + +--- generate(str = "", options = Hash.new){|csv| ... } -> String + +このメソッドは与えられた文字列をラップして [[c:CSV]] のオブジェクトとしてブロックに渡します。 +ブロック内で [[c:CSV]] オブジェクトに行を追加することができます。 +ブロックを評価した結果は文字列を返します。 + +このメソッドに与えられた文字列は変更されるので、新しい文字列オブジェクトが必要な +場合は [[m:Object#dup]] で複製してください。 + +@param str 文字列を指定します。デフォルトは空文字列です。 + +@param options [[m:CSV.new]] のオプションと同じオプションを指定できます。 + :encoding というキーを使用すると出力のエンコーディングを指定することができます。 + ASCII と互換性の無い文字エンコーディングを持つ文字列を出力する場合は、このヒントを + 指定する必要があります。 + +@see [[m:CSV.new]] + +--- generate_line(row, options = Hash.new) -> String + +このメソッドは一つの [[c:Array]] オブジェクトを CSV 文字列に変換するためのショートカットです。 + +このメソッドは可能であれば row に含まれる最初の nil でない値を用いて出力の +エンコーディングを推測します。 + +@param row 文字列の配列を指定します。 + +@param options [[m:CSV.new]] のオプションと同じオプションを指定できます。 + :encoding というキーを使用すると出力のエンコーディングを指定することができます。 + :row_sep というキーの値には [[m:$/]] がセットされます。 + +@see [[m:CSV.new]] + +--- instance(data = $stdout, options = Hash.new) -> CSV +--- instance(data = $stdout, options = Hash.new){|csv| ... } -> object + +このメソッドは [[m:CSV.new]] のように [[c:CSV]] のインスタンスを返します。 +しかし、返される値は [[m:Object#object_id]] と与えられたオプションを +キーとしてキャッシュされます。 + +ブロックが与えられた場合、生成されたインスタンスをブロックに渡して評価した +結果を返します。 + +@param data [[c:String]] か [[c:IO]] のインスタンスを指定します。 + +@param options [[m:CSV.new]] のオプションと同じオプションを指定できます。 + +@see [[m:CSV.new]] + +--- load(io_or_str, options = Hash.new) -> Array + +このメソッドは [[m:CSV.dump]] で出力されたデータを読み込みます。 + +csv_load という名前のクラスメソッドを追加すると、データを読み込む方法を +カスタマイズすることができます。csv_load メソッドはメタデータ、ヘッダ、行 +の三つのパラメータを受けとります。そしてそれらを元にして復元したオブジェクトを +返します。 + +Remember that all fields will be Strings after this load. If you need +something else, use +options+ to setup converters or provide a custom +csv_load() implementation. + +#@# カスタマイズの例が必要 + +@param io_or_str [[c:IO]] か [[c:String]] のインスタンスを指定します。 + +@param options [[m:CSV.new]] のオプションと同じオプションを指定できます。 + +@see [[m:CSV.new]], [[m:CSV.dump]] + +--- open(filename, mode = "rb", options = Hash.new){|csv| ... } -> nil +--- open(filename, mode = "rb", options = Hash.new) -> CSV +--- open(filename, options = Hash.new){|csv| ... } -> nil +--- open(filename, options = Hash.new) -> CSV +#@todo + +このメソッドは [[c:IO]] オブジェクトをオープンして [[c:CSV]] でラップします。 +これは CSV ファイルを書くための主要なインターフェイスとして使うことを意図しています。 + +You must pass a +filename+ and may optionally add a +mode+ for Ruby's +open(). You may also pass an optional Hash containing any +options+ +CSV::new() understands as the final argument. + +このメソッドは [[m:IO.open]] と同じように動きます。ブロックが与えられた場合は +ブロックに [[c:CSV]] オブジェクトを渡し、ブロック終了時にそれをクローズします。 +ブロックが与えられなかった場合は [[c:CSV]] オブジェクトを返します。 +この挙動は Ruby1.8 の CSV ライブラリとは違います。Ruby1.8 では行をブロックに渡します。 +Ruby1.9 では [[m:CSV.foreach]] を使うとブロックに行を渡します。 + +データが [[m:Encoding.default_external]] と異なる場合は、mode にエンコーディング +を指定する文字列を埋め込まなければなりません。 + +You must provide a +mode+ with an embedded Encoding designator unless your +data is in Encoding::default_external(). CSV will check the Encoding of the +underlying IO object (set by the +mode+ you pass) to deterime how to parse +the data. You may provide a second Encoding to have the data transcoded as +it is read just as you can with a normal call to IO::open(). For example, +"rb:UTF-32BE:UTF-8" would read UTF-32BE data from the file but +transcode it to UTF-8 before CSV parses it. + +An opened CSV object will delegate to many IO methods for convenience. You +may call: + +* binmode() +* binmode?() +* close() +* close_read() +* close_write() +* closed?() +* eof() +* eof?() +* external_encoding() +* fcntl() +* fileno() +* flock() +* flush() +* fsync() +* internal_encoding() +* ioctl() +* isatty() +* path() +* pid() +* pos() +* pos=() +* reopen() +* seek() +* stat() +* sync() +* sync=() +* tell() +* to_i() +* to_io() +* truncate() +* tty?() + +@param filename ファイル名を指定します。 + +@param mode [[m:IO.open]] に指定できるものと同じものを指定できます。 + +@param options [[m:CSV.new]] のオプションと同じオプションを指定できます。 + +@see [[m:CSV.new]], [[m:IO.open]] + +--- parse(str, options = Hash.new){|row| ... } -> nil +--- parse(str, options = Hash.new) -> Array + +このメソッドは文字列を簡単にパースすることができます。 +ブロックを与えた場合は、ブロックにそれぞれの行を渡します。 +ブロックを省略した場合は、配列の配列を返します。 + +@param str 文字列を指定します。 + +@param options [[m:CSV.new]] のオプションと同じオプションを指定できます。 + +--- parse_line(line, options = Hash.new) -> Array + +このメソッドは一行の CSV 文字列を配列に変換するためのショートカットです。 + +@param line 文字列を指定します。複数行の文字列を指定した場相は、一行目以外は無視します。 + +@param options [[m:CSV.new]] のオプションと同じオプションを指定できます。 + +--- read(path, options = Hash.new) -> [Array] +--- readlines(path, options = Hash.new) -> [Array] + +CSV ファイルを配列の配列にするために使います。 + +#@# 例を追加する + +@param path CSV ファイルのパスを指定します。 + +@param options [[m:CSV.new]] のオプションと同じオプションを指定できます。 + :encoding というキーを使用すると入力のエンコーディングを指定することができます。 + 入力のエンコーディングか [[m:Encoding.default_external]] と異なる場合は + 必ず指定しなければなりません。 + +@see [[m:CSV.new]] + +--- table(path, options = Hash.new) -> Array + +以下の例と同等のことを行うメソッドです。 +日本語の CSV ファイルを扱う場合はあまり使いません。 + +例: + + CSV.read( path, { headers: true, + converters: :numeric, + header_converters: :symbol }.merge(options) ) + +@param path ファイル名を指定します。 + +@param options [[m:CSV.new]] のオプションと同じオプションを指定できます。 + +== Instance Methods + +--- <<(row) -> self +--- add_row(row) -> self +--- puts(row) -> self + +自身に row を追加します。 + +データソースは書き込み用にオープンされていなければなりません。 + +@param row 配列か [[c:CSV::Row]] のインスタンスを指定します。 + [[c:CSV::Row]] のインスタンスが指定された場合は、[[m:CSV::Row#fields]] の値 + のみが追加されます。 + +--- binmode +#@todo +delegate + +--- binmode? +#@todo +delegate + +--- close +#@todo +delegate + +--- close_read +#@todo +delegate + +--- close_write +#@todo +delegate + +--- closed? +#@todo +delegate + +--- col_sep -> String + +カラム区切り文字列として使用する文字列を返します。 + +@see [[m:CSV.new]] + +--- convert(name) +--- convert{|field| ... } +--- convert{|field, field_info| ... } +#@todo +#@# discard + +You can use this method to install a CSV::Converters built-in, or provide a +block that handles a custom conversion. + +If you provide a block that takes one argument, it will be passed the field +and is expected to return the converted value or the field itself. If your +block takes two arguments, it will also be passed a CSV::FieldInfo Struct, +containing details about the field. Again, the block should return a +converted field or the field itself. + +@param name 変換器の名前を指定します。 + +--- converters -> Array + +現在の変換器のリストを返します。 + +@see [[m:CSV::Converters]] + +--- each{|row| ... } -> nil + +各行に対してブロックを評価します。 + +データソースは読み込み用にオープンされていなければなりません。 + +--- encoding -> Encoding + +読み書きするときに使用するエンコーディングを返します。 + +--- eof +#@todo +delegate + +--- eof? +#@todo +delegate + +--- external_encoding +#@todo +delegate + +--- fcntl +#@todo +delegate + +--- field_size_limit -> Fixnum + +フィールドサイズの最大値を返します。 + +@see [[m:CSV.new]] + +--- fileno +#@todo +delegate + +--- flock +#@todo +delegate + +--- flush +#@todo +delegate + +--- force_quotes? -> bool + +出力されるフィールドがクオートされる場合は、真を返します。 + +@see [[m:CSV.new]] + +--- fsync +#@todo +delegate + +--- header_convert(name) +--- header_convert{|field| ... } +--- header_convert{|field, field_info| ... } +#@todo + +Identical to CSV#convert(), but for header rows. + +Note that this method must be called before header rows are read to have any +effect. + +@param name 変換器の名前を指定します。 + +@see [[m:CSV#convert]] + +--- header_converters -> Array +#@todo + +Returns the current list of converters in effect for headers. See CSV::new +for details. Built-in converters will be returned by name, while others +will be returned as is. + +@see [[m:CSV.new]] + +--- header_row? -> bool + +次に読み込まれる行が、ヘッダである場合に真を返します。 +そうでない場合は、偽を返します。 + +--- headers -> Array | true | nil + +nil を返した場合は、ヘッダは使用されません。 +真を返した場合は、ヘッダを使用するが、まだ読み込まれていません。 +配列を返した場合は、ヘッダは既に読み込まれています。 + +@see [[m:CSV.new]] +p +--- inspect -> String + +ASCII 互換文字列で自身の情報を表したものを返します。 + +--- internal_encoding +#@todo +delegate + +--- ioctl +#@todo +delegate + +--- isatty +#@todo +delegate + +--- lineno -> Fixnum + +このファイルから読み込んだ最終行の行番号を返します。 +フィールドに含まれる改行はこの値には影響しません。 + +--- path +#@todo +delegate + + +--- pid +#@todo +delegate + +--- pos +#@todo +delegate + +--- pos= +#@todo +delegate + +--- quote_char -> String + +フィールドをクオートするのに使用する文字列を返します。 + +@see [[m:CSV.new]] + +--- read -> [Array] +--- readlines -> [Array] + +残りの行を読み込んで配列の配列を返します。 + +データソースは読み込み用にオープンされている必要があります。 + +--- reopen +#@todo +delegate + +--- return_headers? -> bool + +ヘッダを返す場合は、真を返します。 +そうでない場合は、偽を返します。 + +@see [[m:CSV.new]] + +--- rewind -> 0 +#@todo +Rewinds the underlying IO object and resets CSV's lineno() counter. + +--- row_sep -> String + +行区切り文字列として使用する文字列を返します。 + +@see [[m:CSV.new]] + +--- seek +#@todo +delegate + +--- shift -> Array | CSV::Row +--- gets -> Array | CSV::Row +--- readline -> Array | CSV::Row + +[[c:String]] や [[c:IO]] をラップしたデータソースから一行だけ読み込んで +フィールドの配列か [[c:CSV::Row]] のインスタンスを返します。 + +データソースは読み込み用にオープンされている必要があります。 + +@return ヘッダを使用しない場合は配列を返します。 + ヘッダを使用する場合は [[c:CSV::Row]] を返します。 + +--- skip_blanks? -> bool + +真である場合は、空行を読み飛ばします。 + +@see [[m:CSV.new]] + +--- stat +#@todo +delegate + +--- string +#@todo +delegate + +--- sync +#@todo +delegate + +--- sync= +#@todo +delegate + +--- tell +#@todo +delegate + +--- to_i +#@todo +delegate + +--- to_io +#@todo +delegate + +--- truncate +#@todo +delegate + +--- tty? +#@todo +delegate + +--- unconverted_fields? -> bool + +パースした結果が unconverted_fields というメソッドを持つ場合に真を返します。 +そうでない場合は、偽を返します。 + +#@# Array, CSV::Row に動的に追加される + +@see [[m:CSV.new]] + +--- write_headers? -> bool + +ヘッダを出力先に書き込む場合は真を返します。 +そうでない場合は偽を返します。 + +@see [[m:CSV.new]] + + += class CSV::FieldInfo < Struct + +行が読み込まれたデータソース内でのフィールドの位置の情報を格納するための +構造体です。 + +[[c:CSV]] クラスではこの構造体はいくつかのメソッドのブロックに渡されます。 + +@see [[m:CSV.convert_fields]] + +== Instance Methods + +--- index -> Fixnum + +行内で何番目のフィールドかわかるゼロベースのインデックスを返します。 + +--- index=(val) + +インデックスの値をセットします。 + +@param val インデックスの値を指定します。 + +--- line -> Fixnum + +行番号を返します。 + +--- line=(val) + +行番号をセットします。 + +@param val 行番号を指定します。 + +--- header -> Array + +利用可能な場合はヘッダを表す配列を返します。 + + +--- header=(val) + +ヘッダを表す配列をセットします。 + +@param val ヘッダを表す配列を指定します。 + += class CSV::MalformedCSVError < RuntimeError + +不正な CSV をパースしようとしたときに発生する例外です。 + +#@include(csv/CSV__Row) +#@include(csv/CSV__Table) +#@else CSV (Comma Separated Values) を扱うライブラリです。 = class CSV < Object @@ -23,8 +1016,7 @@ CSV (Comma Separated Values) == Class Methods --- open(path, mode, fs = nil, rs = nil) {|row| ... } -> nil ---- open(path, mode, fs = nil, rs = nil) -> CSV::Reader ---- open(path, mode, fs = nil, rs = nil) -> CSV::Writer +--- open(path, mode, fs = nil, rs = nil) -> CSV::Reader | CSV::Writer CSVファイルを読み込んでパースします。 @@ -39,8 +1031,8 @@ CSV - 'b' バイナリモード @param fs フィールドセパレータの指定。 nil (デフォルト) で ',' をセパレータとします。 -@param rs 行区切り文字の指定。nil (デフォルト) で CrLf / Lf。 - Cr を行区切りとしたい場合は ?\r を渡します。 +@param rs 行区切り文字の指定。nil (デフォルト) で CRLF / LF。 + CR を行区切りとしたい場合は ?\r を渡します。 ===== 注意 @@ -192,7 +1184,7 @@ src @param rs 行区切り文字の指定。nil (デフォルト) で CrLf / Lf。 Cr を行区切りとしたい場合は ?\r を渡します。 -#@if (version < "1.9.0") +#@until 1.9.1 --- generate_row(src, cells, out_dev, fs = nil, rs = nil) -> Fixnum src で指定された配列をパースして csv形式の文字列として(行区切り文字も含めて) out_dev に出力します。 @@ -284,5 +1276,5 @@ CSV #@include(csv/CSV__StreamBuf) #@include(csv/CSV__StringReader) #@include(csv/CSV__Writer) - #@end + diff --git a/refm/api/src/csv/CSV__Row b/refm/api/src/csv/CSV__Row index c4ace0f..1d7ac85 100644 --- a/refm/api/src/csv/CSV__Row +++ b/refm/api/src/csv/CSV__Row @@ -1,9 +1,218 @@ +#@since 1.9.1 += class CSV::Row < Object +extend Forwardable +include Enumerable + +[[c:CSV::Row]] は配列やハッシュのように似ています。 + +配列のようにフィールドの順序を保持していて、複製する事もできます。 +また、ハッシュのように名前でフィールドにアクセスする事もできます。 + +ヘッダ行の処理が有効である場合は [[c:CSV]] から返される全ての行はこのクラスのインスタンスです。 + +以下のメソッドを [[c:Array]] に委譲します。 + +* empty?() +* length() +* size() + +== Singleton Methods + +--- new(headers, fields, header_row = false) -> CSV::Row + +自身を初期化します。 + +一方の配列が他方の配列よりも短い場合、不足しているところは nil になります。 + +@param headers ヘッダの配列を指定します。 + +@param fields フィールドの配列を指定します。 + +@param header_row ヘッダ行である場合は真を指定します。そうでない場合は偽を指定します。 + デフォルトは偽です。 + +@see [[m:CSV::Row#header_row?]], [[m:CSV::Row#field_row?]] + +== Instance Methods + +--- <<(arg) -> self + +自身に与えられたデータを追加します。 + +@param arg 2 要素の配列か 1 要素のハッシュか任意のオブジェクトを指定します。 + 2 要素の配列を与えた場合は、ヘッダとフィールドのペアを追加します。 + 1 要素のハッシュを与えた場合は、キーをヘッダ、値をフィールドとして追加します。 + それ以外の場合は、ヘッダを nil 、フィールドを与えられた値として追加します。 + +@return メソッドチェーンのために自身を返します。 + +--- ==(other) -> bool + +自身が other と同じヘッダやフィールドを持つ場合に真を返します。 +そうでない場合は偽を返します。 + +@param other 比較対象の [[c:CSV::Row]] のインスタンスを指定します。 + +--- field(header_or_index, minimum_index = 0) -> object | nil +--- [](header_or_index, minimum_index = 0) -> object | nil + +ヘッダの名前かインデックスで値を取得します。フィールドが見つからなかった場合は nil を返します。 + +@param header_or_index ヘッダの名前かインデックスを指定します。 + +@param minimum_index このインデックスより後で、ヘッダの名前を探します。 + 重複しているヘッダがある場合に便利です。 + +--- []=(header_or_index, value) +--- []=(header, offset, value) +#@todo + +ヘッダの名前かインデックスでフィールドを探し、値をセットします。 + +Assigning past the end of the row with an index will set all pairs between +to [nil, nil]. Assigning to an unused header appends the new +pair. + +@param header_or_index ヘッダの名前かインデックスを指定します。 + +@param value 値を指定します。 + +@see [[m:CSV::Row#field]] + +--- []=(header, offset, value) + +ヘッダの名前でフィールドを探し、値をセットします。 + +@param header ヘッダの名前を指定します。 + +@param offset このインデックスより後で、ヘッダの名前を探します。 + 重複しているヘッダがある場合に便利です。 + +@param value 値を指定します。 + +@see [[m:CSV::Row#field]] + +--- delete(header_or_index, minimum_index = 0) -> [object, object] | nil + +ヘッダの名前かインデックスで行からフィールドを削除するために使用します。 + +@param header_or_index ヘッダの名前かインデックスを指定します。 + +@param minimum_index このインデックスより後で、ヘッダの名前を探します。 + 重複しているヘッダがある場合に便利です。 + +@return 削除したヘッダとフィールドの組を返します。削除対象が見つからなかった場合は nil を返します。 + +@see [[m:CSV::Row#field]] + +--- delete_if{|header, field| ... } -> self + +与えられたブロックにヘッダとフィールドのペアを渡して評価します。 +評価した結果が真である場合に、その組を自身から削除します。 + +@return メソッドチェーンのために自身を返します。 + +--- each{|header, field| ... } -> self + +与えられたブロックにヘッダとフィールドの組を渡して評価します。 + +@return メソッドチェーンのために自身を返します。 + +--- empty? -> bool + +内部で保持している @row へ委譲します。 + + +--- field?(data) -> bool + +自身に与えられた値が含まれている場合は真を返します。 +そうでない場合は偽を返します。 + +@param data この行に含まれているかどうか調べたい値を指定します。 + +--- field_row? -> bool +フィールド行であれば真を返します。そうでなければ偽を返します。 + +--- fields(*headers_and_or_indices) -> Array +--- values_at(*headers_and_or_indices) -> Array +#@todo + +This method accepts any number of arguments which can be headers, indices, +Ranges of either, or two-element Arrays containing a header and offset. +Each argument will be replaced with a field lookup as described in +CSV::Row.field(). + +If called with no arguments, all fields are returned. + +#@# 例が必要 + +@param headers_and_or_indices + +--- header?(name) -> bool +--- include?(name) -> bool +自身のヘッダに与えられた値が含まれている場合は真を返します。 +そうでない場合は偽を返します。 + +@param name この行のヘッダに含まれているかどうか調べたい値を指定します。 + +--- header_row? -> bool +ヘッダ行であれば真を返します。そうでなければ偽を返します。 + +--- headers -> Array +この行のヘッダのリストを返します。 + +--- index(header, minimum_index = 0) -> Fixnum + +与えられたヘッダの名前に対応するインデックスを返します。 + +@param header ヘッダの名前を指定します。 + +@param minimum_index このインデックスより後で、ヘッダの名前を探します。 + 重複しているヘッダがある場合に便利です。 + +@see [[m:CSV::Row#field]] + +--- inspect -> String +ASCII 互換であるエンコーディングの文字列で自身の情報を返します。 + +--- length -> Fixnum +--- size -> Fixnum +delegate + +--- push(*args) -> self +複数のフィールドを追加するためのショートカットです。 + +以下とおなじです: + args.each { |arg| csv_row << arg } + +@return メソッドチェーンのために自身を返します。 + +--- to_csv -> String +--- to_s -> String + +自身を CSV な文字列として返します。ヘッダは使用しません。 + +--- to_hash -> Hash + +自身をシンプルなハッシュに変換します。 + +フィールドの順序は無視されます。 +重複したフィールドは削除されます。 + +== Protected Instance Methods + +--- row -> Array + +同値性を比較するために使用する内部的なデータです。 + +#@else = class CSV::Row < Array CSV形式1行分のデータ（Row）を操作するためのクラス。 +#@# 1.8.2 以降で deprecated == Instance Methods -#@if (version <= '1.8.1') +#@until 1.8.2 --- match(rhs) -> bool 自分自身と引数rhsを比較しtrue/falseを返します。 @@ -25,3 +234,4 @@ CSV #@end +#@end diff --git a/refm/api/src/csv/CSV__Table b/refm/api/src/csv/CSV__Table new file mode 100644 index 0000000..e575a59 --- /dev/null +++ b/refm/api/src/csv/CSV__Table @@ -0,0 +1,229 @@ +#@since 1.9.1 += class CSV::Table < Object +extend Forwardable +include Enumerable + +[[c:CSV::Table]] は CSV ドキュメントを表す二次元のデータ構造です。 +行単位や列単位の操作を行うことが出来ます。また必要であれば CSV に +戻すこともできます。 + +ヘッダ行の処理が有効である場合、[[c:CSV]] から返されるテーブルは全てこのクラスから +構築されます。 + +以下のメソッドを [[c:Array]] に委譲します。 + +* empty?() +* length() +* size() + +== Singleton Methods + +--- new(array_of_rows) -> CSV::Table + +自身を初期化します。 + +全ての行が同じヘッダを持つことを仮定しています。 + +@param array_of_rows [[c:CSV::Row]] のインスタンスの配列を指定します。 + +== Instance Methods + +--- <<(row_or_array) -> self + +自身の最後に新しい行を追加します。 + +@param row_or_array [[c:CSV::Row]] のインスタンスか配列を指定します。 + 配列を指定した場合は [[c:CSV::Row]] に変換されます。 + +@return メソッドチェーンのために自身を返します。 + +--- ==(other) -> bool + +自身の全ての行が比較対象と同じである場合は真を返します。 +そうでない場合は偽を返します。 + +@param other [[c:CSV::Table]] を指定します。 + +--- [](index_or_header) -> object +#@todo +In the default mixed mode, this method returns rows for index access and +columns for header access. You can force the index association by first +calling by_col!() or by_row!(). + +Columns are returned as an Array of values. Altering that Array has no +effect on the table. + +--- []=(index_or_header, value) +#@todo + +In the default mixed mode, this method assigns rows for index access and +columns for header access. You can force the index association by first +calling by_col!() or by_row!(). + +Rows may be set to an Array of values (which will inherit the table's +headers()) or a CSV::Row. + +Columns may be set to a single value, which is copied to each row of the +column, or an Array of values. Arrays of values are assigned to rows top +to bottom in row major order. Excess values are ignored and if the Array +does not have a value for each row the extra rows will receive a +nil+. + +Assigning to an existing column or row clobbers the data. Assigning to +new columns creates them at the right end of the table. + +--- by_col -> CSV::Table +#@todo + +カラムモードになっている新しい [[c:CSV::Table]] オブジェクトを返します。 + +元のテーブルモードを変更せずにメソッドチェーンできるので便利です。 +しかし、大きなデータセットに対しても同じだけメモリを消費するので気をつけてください。 + +This method returns the duplicate table for chaining. Don't chain +destructive methods (like []=()) this way though, since you are working +with a duplicate. + +--- by_col! -> self + +自身をカラムモードに変更します。 + +再びモードが変更されるまで、いくつかのメソッドはカラム単位で動きます。 + +--- by_col_or_row -> CSV::Table +#@todo + +ミックスモードになっている新しい [[c:CSV::Table]] オブジェクトを返します。 + +元のテーブルモードを変更せずにメソッドチェーンできるので便利です。 +しかし、大きなデータセットに対しても同じだけメモリを消費するので気をつけてください。 + +This method returns the duplicate table for chaining. Don't chain +destructive methods (like []=()) this way though, since you are working +with a duplicate. + +--- by_col_or_row! -> self +#@todo + +自身をミックスモードに変更します。 + +Switches the mode of this table to mixed mode. All calls to indexing and +iteration methods will use the default intelligent indexing system until +the mode is changed again. In mixed mode an index is assumed to be a row +reference while anything else is assumed to be column access by headers. + +This method returns the table and is safe to chain. + +--- by_row -> CSV::Table +#@todo + +Returns a duplicate table object, in row mode. This is handy for chaining +in a single call without changing the table mode, but be aware that this +method can consume a fair amount of memory for bigger data sets. + +This method returns the duplicate table for chaining. Don't chain +destructive methods (like []=()) this way though, since you are working +with a duplicate. + +--- by_row! -> self +#@todo + +Switches the mode of this table to row mode. All calls to indexing and +iteration methods will work with rows until the mode is changed again. + +This method returns the table and is safe to chain. + +--- delete(index_or_header) -> Object +#@todo + +Removes and returns the indicated column or row. In the default mixed +mode indices refer to rows and everything else is assumed to be a column +header. Use by_col!() or by_row!() to force the lookup. + +--- delete_if{ ... } -> self +#@todo + +Removes any column or row for which the block returns +true+. In the +default mixed mode or row mode, iteration is the standard row major +walking of rows. In column mode, interation will +yield+ two element +tuples containing the column name and an Array of values for that column. + +This method returns the table for chaining. + +--- each{|header, field| ... } -> self +#@todo + +In the default mixed mode or row mode, iteration is the standard row major +walking of rows. In column mode, interation will +yield+ two element +tuples containing the column name and an Array of values for that column. + +This method returns the table for chaining. + +--- empty? -> bool +#@todo + +delegate + +--- headers -> Array +#@todo + +Returns the headers for the first row of this table (assumed to match all +other rows). An empty Array is returned for empty tables. + +--- inspect -> String +#@todo + +Shows the mode and size of this table in a US-ASCII String. + + +--- length -> Fixnum +--- size -> Fixnum +#@todo +delegate + +--- mode -> Symbol + +現在のアクセスモードを返します。 + +#@# アクセスモードについてどこかに書く。 + +--- push(*rows) -> self +#@todo +A shortcut for appending multiple rows. Equivalent to: + + rows.each { |row| self << row } + +This method returns the table for chaining. + +--- to_a -> Array +#@todo + +Returns the table as an Array of Arrays. Headers will be the first row, +then all of the field rows will follow. + +--- to_csv -> String +--- to_s -> String +#@todo +Returns the table as a complete CSV String. Headers will be listed first, +then all of the field rows. + +This method assumes you want the Table.headers(), unless you explicitly +pass :write_headers => false. + +--- values_at(indices_or_headers) -> Array +#@todo +The mixed mode default is to treat a list of indices as row access, +returning the rows indicated. Anything else is considered columnar +access. For columnar access, the return set has an Array for each row +with the values indicated by the headers in each Array. You can force +column or row mode using by_col!() or by_row!(). + +You cannot mix column and row access. + + +== Protected Instance Methods + +--- table -> Array + +同値性を比較するために内部的に使用します。 + +#@end -- 1.7.1