名前¶
Text::CSV_XS - CSV形式の操作ルーチン
概要¶
use Text::CSV_XS;
$csv = Text::CSV_XS->new(); # 新しいオブジェクトを作る
$csv = Text::CSV_XS->new(\%attr); # 新しいオブジェクトを作る
$status = $csv->combine(@columns); # 縦列を連結して一つの文字列にする
$line = $csv->string(); # 連結したその文字列を得る
$status = $csv->parse($line); # CSV文字列をパースしてフィールド群に切り分ける
@columns = $csv->fields(); # パースされたそのフィールド群を得る
$status = $csv->status(); # 直前のステータスを得る
$bad_argument = $csv->error_input(); # 直前の不正引数を得る
$status = $csv->print($io, $columns); # $io ファイルへ、
# すぐさまフィールド群を書き込む
$columns = $csv->getline($io); # ＄io ファイルから１行を読み込み、パース
# した後にフィールド群の配列リファレンスを返す
$csv->types(\@t_array); # 縦列の形式を設定する説明¶
コンマ区切り文字列 CSV を組み立てたり切り分けたりするのに、Text::CSV_XS は便利な機能を提供します。Text::CSV_XS クラスのインスタンスでは、フィールド群を連結して CSV 文字列にしたり、その反対にCSV文字列をパースしてフィールド群にすることができます。
関数群¶
- version()
-
(クラスメソッド) 使用しているモジュールのバージョンを返す。
- new(\%attr)
-
(クラスメソッド) 新しい Text::CSV_XS インスタンスを返す。オブジェクトの属性値は、ハッシュリファレンス
\%attrで（随意に）指定する。次の属性値を指定できる：- quote_char
-
空白文字を含むフィールドをクオートするための文字で、デフォルトは二重引用符 (
")。undef を指定すると、文字列がクオートされない（空白文字を使わないような簡素な場合のみ使用すること）。 - eol
-
横行に加える行の終わりを示す文字で、一般的には
undef（無、デフォルト）、"\012"(ラインフィード) もしくは"\015\012"(キャリッジリターン+ラインフィード) である。 - escape_char
-
クオートしたフィールドの中でエスケープを施す文字で、デフォルトではクオート文字 (
") と同じ。 - sep_char
-
フィールドを区切る文字で、デフォルトはコンマ (
,)。 - binary
-
この属性値が真 (TRUE) ならば、クオートしたフィールドの中でバイナリ文字を使用することができる。このバイナリ文字にはラインフィード、キャリッジリターン、そして NUL バイトが含まれている（ NUL バイトは
"0としてエスケープしなくてはならない）。デフォルトで、この機能はオフ。 - types
-
カラムの形式；この属性値はすぐさま後述の types メソッドに渡される。types メソッドを使用する場合を除き、この属性値を設定してはならない。詳しくは、後述の types メソッドの説明を参照。
- always_quote
-
フィールド内のテキストが区切り文字を含むような場合など、その必要がある際にのみデフォルトではフィールドはクオートで区切られる。この属性値を真 TRUE に設定すると、全てのフィールドがクオートされる。この機能は外部アプリケーションを用いる場合に便利である。（ Text::CSV_XS を使わない可哀想なプログラマのために :-)
これらをまとめると、
$csv = Text::CSV_XS->new();は、以下と同じである；
$csv = Text::CSV_XS->new({ 'quote_char' => '"', 'escape_char' => '"', 'sep_char' => ',', 'binary' => 0 }); - combine
-
$status = $csv->combine(@columns);このオブジェクト関数は、引数から CSV 文字列を組み立て、成功か失敗のステータスを返す。失敗するのは、おそらく引数が足らないか不正な文字列を引数が含むからであろう。成功した場合、
string()によって組み立てた CSV 文字列を得ることができる。失敗した場合、string()は 未定義を返しerror_input()によって無効だった引数を得ることができる。 -
$status = $csv->print($io, $columns);combine と似ているが、このメソッドは配列リファレンス（配列ではない）が入力されることを期待する；組み立てた CSV 文字列をまったく作らない；$io オブジェクトへ直ちに書き込む。ここで、print メソッドに与えるのは通常、$io オブジェクトか 類似した他のオブジェクトである。注意すべき事として、この呼び出しで次の方法は間違いである；
open(FILE, ">whatever"); $status = $csv->print(\*FILE, $columns);\*FILEグロブはオブジェクトではないので、print メソッドを実行することができない。解決方法は IO:File オブジェクトを使用するか IO::Wrap オブジェクトの中へグロブを隠蔽してしまうことである。詳細は、IO::File(3) と IO::Wrap(3) を参照。パフォーマンス上の理由から、この print メソッドは組み立てた CSV 文字列を外部へ提供しない。とりわけ $csv->string(), $csv->status(), $csv-fields()>, そして $csv->error_input() は、このメソッドの後で意味をなさない。
- string
-
$line = $csv->string();このオブジェクト関数は、
parse()への入力したものかcombine()で組み立てられた CSV 文字列か、それが何であれ直前のものを返す。 - parse
-
$status = $csv->parse($line);このオブジェクト関数は CSV 文字列をフィールドに切り分けて、しかる後に成功か失敗のステータスを返す。失敗するのは、引数の不足か与えられた CSV 文字列が不適切なフォーマットだからであろう。成功した場合には、
fields()メソッドによって切り分けられたフィールドが得られる。失敗の場合には、fields()は未定義値を返しerror_input()によって不正な引数を得ることができる。カラムの形式を設定するために、types() メソッドを使うべきである。後述の説明を参照。
- getline
-
$columns = $csv->getline($io);これは print と対をなすもので、parse が combine の対となるようなものだ： IO オブジェクト $IOにおいて $IO->getline() を用いて１行を読み出し、この１行をパースして配列リファレンスに納める。この配列リファレンスが返されるか、失敗した場合には undef が返される。
繰り返しになるが、 $csv->string(), $csv->fields(), そして $csv->status() メソッドはこのメソッドの後では意味をなさない。
- types
-
$csv->types(\@tref);このメソッドは、縦行を指定された形式へ強制的に変換するのに用いる。たとえば、整数値で表現された１カラム、倍精度数形式の２カラム、文字列の１カラムがあった場合は、次を実行することになるだろう
$csv->types([Text::CSV_XS::IV(), Text::CSV_XS::NV(), Text::CSV_XS::NV(), Text::CSV_XS::PV()]);カラム形式をデコードするときのみ、言い換えると parse() と getline() メソッドを使うときにのみ、このカラム形式が用いられる。
カラムタイプを解除するのは次のようにする
$csv->types(undef);あるいはまた、現在の形式を得るには次の方法を採る
$types = $csv->types(); - fields
-
@columns = $csv->fields();このオブジェクト関数は、
combine()への入力値かparse()から得られる切り分けられたフィールド群か、それが何であれ直前のものを返す。 - status
-
$status = $csv->status();This object function returns success (or failure) of
combine()orparse(), whichever was called more recently. このオブジェクト関数は、combine()かparse()かそれが何であれ直前のメソッドが成功（もしくは失敗）したかどうかを返す。 - error_input
-
$bad_argument = $csv->error_input();このオブジェクト関数は、
combine()かparse()か、それが何であれ直前のメソッドがエラーとなった引数（もしあれば）を返す。
例¶
require Text::CSV_XS;
my $csv = Text::CSV_XS->new;
my $column = '';
my $sample_input_string = '"I said, ""Hi!""",Yes,"",2.34,,"1.09"';
if ($csv->parse($sample_input_string)) {
my @field = $csv->fields;
my $count = 0;
for $column (@field) {
print ++$count, " => ", $column, "\n";
}
print "\n";
} else {
my $err = $csv->error_input;
print "parse() failed on argument: ", $err, "\n";
}
my @sample_input_fields = ('You said, "Hello!"',
5.67,
'Surely',
'',
'3.14159');
if ($csv->combine(@sample_input_fields)) {
my $string = $csv->string;
print $string, "\n";
} else {
my $err = $csv->error_input;
print "combine() failed on argument: ", $err, "\n";
}注意¶
このモジュールは策定中の CSV フォーマットを元にしているが、そのフォーマットが最も一般的なものとは言い難いかもしれない。
CSV フィールドの中に納めることができる文字には、 0x09 (tab) と of 0x20 (space) から 0x7E (tilde)の包括的な範囲とを含む。バイナリモードではクオートされたフィールドの中において全ての文字を受け付ける。
CSV のフィールドは、二重引用符（quote char）で挟まれるべきである。
CSV のフィールドの中にコンマ(separator char)がある場合は、二重引用符で挟まれなければならない。
CSV フィールドの中に二重引用符を埋め込む場合は、一対となった二重引用符の間に挟まれなければならない。バイナリモードでは特に、 NUL バイトを示す
"0を用いるべきである。CSV 文字列は、 0x0A (ラインフィード) もしくは 0x0D + 0x0A(キャリッジリターン + ラインフィード)で終わるべきである。
作者¶
Alan Citterman <alan@mfgrtl.com> が、この Perl モジュールを最初に書いた。Alan へ Text::CSV_XS に関するメールをどうか送らないで欲しい。なぜなら、今ではこのモジュールの主要部分を占める C コード部分について、彼は関与していないからである。
Jochen Wiedmann <joe@ispsoft.de> が、エンコードとデコードのルーチンを有限状態マシンを実装する C コードで書き直し、クオート、エスケープ、そしてセパレーター文字変数、バイナリモード、そして print と getline メソッドを加えた。
SEE ALSO¶
perl(1), IO::File(3), IO::Wrap(3)
Translator into Japanese (翻訳者)¶
anahori (at users.sourceforge.jp)
Japanized Perl Resources Project (http://sourceforge.jp/projects/perldocjp/)