Text::CSV_XS 0.23 と 0.23 の差分

1	1
2	2	=encoding utf8
3	3
4	4	=head1 名前
5	5
6	6	Text::CSV_XS - CSV形式の操作ルーチン
7	7
8	8	=head1 概要
9	9
10	10	use Text::CSV_XS;
11	11
12	12	$csv = Text::CSV_XS->new(); # 新しいオブジェクトを作る
13	13	$csv = Text::CSV_XS->new(\%attr); # 新しいオブジェクトを作る
14	14
15	15	$status = $csv->combine(@columns); # 縦列を連結して一つの文字列にする
16	16	$line = $csv->string(); # 連結したその文字列を得る
17	17
18	18	$status = $csv->parse($line); # CSV文字列をパースしてフィールド群に切り分ける
19	19	@columns = $csv->fields(); # パースされたそのフィールド群を得る
20	20
21	21	$status = $csv->status(); # 直前のステータスを得る
22	22	$bad_argument = $csv->error_input(); # 直前の不正引数を得る
23	23
24	24	$status = $csv->print($io, $columns); # $io ファイルへ、
25	25	# すぐさまフィールド群を書き込む
26	26
27	27	$columns = $csv->getline($io); # ＄io ファイルから１行を読み込み、パース
28	28	# した後にフィールド群の配列リファレンスを返す
29	29
30	30	$csv->types(\@t_array); # 縦列の形式を設定する
31	31
32	32	=head1 説明
33	33
34		コンマ区切り文字列 CSV を組み立てたり切り分けたりするのに、Text::CSV_XS は便利な機能を提供します。Text::CSV_XS クラスのインスタンスでは、フィールド群を連結して CSV 文字列にしたり、その反対にCSV文字列をパースしてフィールド群にすることができます。
	34	コンマ区切り文字列 CVS を組み立てたり切り分けたりするのに、Text::CVS_XS は便利な機能を提供します。Text::CVS_XS クラスのインスタンスでは、フィールド群を連結して CSV 文字列にしたり、その反対にCSV文字列をパースしてフィールド群にすることができます。
35	35
36	36
37	37	=head1 関数群
38	38
39	39	=over 4
40	40
41	41	=item version()
42	42
43	43	(クラスメソッド) 使用しているモジュールのバージョンを返す。
44	44
45	45	=item new(\%attr)
46	46
47	47	(クラスメソッド) 新しい Text::CSV_XS インスタンスを返す。オブジェクトの属性値は、ハッシュリファレンス C<\%attr> で（随意に）指定する。次の属性値を指定できる：
48	48
49	49	=over 8
50	50
51	51	=item quote_char
52	52
53	53	空白文字を含むフィールドをクオートするための文字で、デフォルトは二重引用符 (C<">)。undef を指定すると、文字列がクオートされない（空白文字を使わないような簡素な場合のみ使用すること）。
54	54
55	55	=item eol
56	56
57	57	横行に加える行の終わりを示す文字で、一般的には C<undef> （無、デフォルト）、 C<"\012"> (ラインフィード) もしくは C<"\015\012"> (キャリッジリターン+ラインフィード) である。
58	58
59	59	=item escape_char
60	60
61	61	クオートしたフィールドの中でエスケープを施す文字で、デフォルトではクオート文字 (C<">) と同じ。
62	62
63	63	=item sep_char
64	64
65	65	フィールドを区切る文字で、デフォルトはコンマ (C<,>)。
66	66
67	67	=item binary
68	68
69	69	この属性値が真 (TRUE) ならば、クオートしたフィールドの中でバイナリ文字を使用することができる。このバイナリ文字にはラインフィード、キャリッジリターン、そして NUL バイトが含まれている（ NUL バイトは C<"0> としてエスケープしなくてはならない）。デフォルトで、この機能はオフ。
70	70
71	71	=item types
72	72
73	73	カラムの形式；この属性値はすぐさま後述の I<types> メソッドに渡される。I<types> メソッドを使用する場合を除き、この属性値を設定してはならない。詳しくは、後述の I<types> メソッドの説明を参照。
74	74
75	75	=item always_quote
76	76
77		フィールド内のテキストが区切り文字を含むような場合など、その必要がある際にのみデフォルトではフィールドはクオートで区切られる。この属性値を真 TRUE に設定すると、全てのフィールドがクオートされる。この機能は外部アプリケーションを用いる場合に便利である。（ Text::CSV_XS を使わない可哀想なプログラマのために　:-)
	77	フィールド内のテキストが区切り文字を含むような場合など、その必要がある際にのみデフォルトではフィールドはクオートで区切られる。この属性値を真 TRUE に設定すると、全てのフィールドがクオートされる。この機能は外部アプリケーションを用いる場合に便利である。（ Text::CVS_XS を使わない可哀想なプログラマのために　:-)
78	78
79	79	=back
80	80
81	81	これらをまとめると、
82	82
83	83	$csv = Text::CSV_XS->new();
84	84
85	85	は、以下と同じである；
86	86
87	87	$csv = Text::CSV_XS->new({
88	88	'quote_char' => '"',
89	89	'escape_char' => '"',
90	90	'sep_char' => ',',
91	91	'binary' => 0
92	92	});
93	93
94	94	=item combine
95	95
96	96	$status = $csv->combine(@columns);
97	97
98		このオブジェクト関数は、引数から CSV 文字列を組み立て、成功か失敗のステータスを返す。失敗するのは、おそらく引数が足らないか不正な文字列を引数が含むからであろう。成功した場合、 C<string()> によって組み立てた CSV 文字列を得ることができる。失敗した場合、C<string()> は未定義を返し C<error_input()> によって無効だった引数を得ることができる。
	98	このオブジェクト関数は、引数から CVS 文字列を組み立て、成功か失敗のステータスを返す。失敗するのは、おそらく引数が足らないか不正な文字列を引数が含むからであろう。成功した場合、 C<string()> によって組み立てた CSV 文字列を得ることができる。失敗した場合、C<string()> は未定義を返し C<error_input()> によって無効だった引数を得ることができる。
99	99
100	100	=item print
101	101
102	102	$status = $csv->print($io, $columns);
103	103
104	104	combine と似ているが、このメソッドは配列リファレンス（配列ではない）が入力されることを期待する；組み立てた CSV 文字列をまったく作らない；I<$io> オブジェクトへ直ちに書き込む。ここで、I<print> メソッドに与えるのは通常、I<$io> オブジェクトか類似した他のオブジェクトである。注意すべき事として、この呼び出しで次の方法は間違いである；
105	105
106	106
107	107	open(FILE, ">whatever");
108	108	$status = $csv->print(\*FILE, $columns);
109	109
110	110	C<\*FILE> グロブはオブジェクトではないので、print メソッドを実行することができない。解決方法は IO:File オブジェクトを使用するか IO::Wrap オブジェクトの中へグロブを隠蔽してしまうことである。詳細は、L<IO::File(3)> と L<IO::Wrap(3)> を参照。
111	111
112	112	パフォーマンス上の理由から、この print メソッドは組み立てた CSV 文字列を外部へ提供しない。とりわけ I<$csv-E<gt>string()>, I<$csv-E<gt>status()>, I<$csv->fields()>, そして I<$csv-E<gt>error_input()> は、このメソッドの後で意味をなさない。
113	113
114	114	=item string
115	115
116	116	$line = $csv->string();
117	117
118	118	このオブジェクト関数は、 C<parse()> への入力したものか C<combine()> で組み立てられた CSV 文字列か、それが何であれ直前のものを返す。
119	119
120	120	=item parse
121	121
122	122	$status = $csv->parse($line);
123	123
124	124	このオブジェクト関数は CSV 文字列をフィールドに切り分けて、しかる後に成功か失敗のステータスを返す。失敗するのは、引数の不足か与えられた CSV 文字列が不適切なフォーマットだからであろう。成功した場合には、C<fields()> メソッドによって切り分けられたフィールドが得られる。失敗の場合には、 C<fields()> は未定義値を返し C<error_input()> によって不正な引数を得ることができる。
125	125
126	126	カラムの形式を設定するために、I<types()> メソッドを使うべきである。後述の説明を参照。
127	127
128	128
129	129	=item getline
130	130
131	131	$columns = $csv->getline($io);
132	132
133	133	これは print と対をなすもので、parse が combine の対となるようなものだ： IO オブジェクト $IOにおいて $IO->getline() を用いて１行を読み出し、この１行をパースして配列リファレンスに納める。この配列リファレンスが返されるか、失敗した場合には undef が返される。
134	134
135	135	繰り返しになるが、 I<$csv-E<gt>string()>, I<$csv-E<gt>fields()>, そして I<$csv-E<gt>status()> メソッドはこのメソッドの後では意味をなさない。
136	136
137	137	=item types
138	138
139	139	$csv->types(\@tref);
140	140
141	141	このメソッドは、縦行を指定された形式へ強制的に変換するのに用いる。たとえば、整数値で表現された１カラム、倍精度数形式の２カラム、文字列の１カラムがあった場合は、次を実行することになるだろう
142	142
143	143	$csv->types([Text::CSV_XS::IV(),
144	144	Text::CSV_XS::NV(),
145	145	Text::CSV_XS::NV(),
146	146	Text::CSV_XS::PV()]);
147	147
148	148	カラム形式をデコードするときのみ、言い換えると I<parse()> と I<getline()> メソッドを使うときにのみ、このカラム形式が用いられる。
149	149
150	150
151	151	カラムタイプを解除するのは次のようにする
152	152
153	153	$csv->types(undef);
154	154
155	155	あるいはまた、現在の形式を得るには次の方法を採る
156	156
157	157	$types = $csv->types();
158	158
159	159	=item fields
160	160
161	161	@columns = $csv->fields();
162	162
163	163	このオブジェクト関数は、 C<combine()> への入力値か C<parse()> から得られる切り分けられたフィールド群か、それが何であれ直前のものを返す。
164	164
165	165	=item status
166	166
167	167	$status = $csv->status();
168	168
169	169	This object function returns success (or failure) of C<combine()> or
170	170	C<parse()>, whichever was called more recently.
171	171	このオブジェクト関数は、 C<combine()> か C<parse()> かそれが何であれ直前のメソッドが成功（もしくは失敗）したかどうかを返す。
172	172
173	173	=item error_input
174	174
175	175	$bad_argument = $csv->error_input();
176	176
177	177	このオブジェクト関数は、C<combine()> か C<parse()> か、それが何であれ直前のメソッドがエラーとなった引数（もしあれば）を返す。
178	178
179	179	=back
180	180
181	181	=head1 例
182	182
183	183	require Text::CSV_XS;
184	184
185	185	my $csv = Text::CSV_XS->new;
186	186
187	187	my $column = '';
188	188	my $sample_input_string = '"I said, ""Hi!""",Yes,"",2.34,,"1.09"';
189	189	if ($csv->parse($sample_input_string)) {
190	190	my @field = $csv->fields;
191	191	my $count = 0;
192	192	for $column (@field) {
193	193	print ++$count, " => ", $column, "\n";
194	194	}
195	195	print "\n";
196	196	} else {
197	197	my $err = $csv->error_input;
198	198	print "parse() failed on argument: ", $err, "\n";
199	199	}
200	200
201	201	my @sample_input_fields = ('You said, "Hello!"',
202	202	5.67,
203	203	'Surely',
204	204	'',
205	205	'3.14159');
206	206	if ($csv->combine(@sample_input_fields)) {
207	207	my $string = $csv->string;
208	208	print $string, "\n";
209	209	} else {
210	210	my $err = $csv->error_input;
211	211	print "combine() failed on argument: ", $err, "\n";
212	212	}
213	213
214	214	=head1 注意
215	215
216		このモジュールは策定中の CSV フォーマットを元にしているが、そのフォーマットが最も一般的なものとは言い難いかもしれない。
	216	このモジュールは策定中の CVS フォーマットを元にしているが、そのフォーマットが最も一般的なものとは言い難いかもしれない。
217	217
218	218	=over 4
219	219
220	220	=item 1
221	221
222		CSV フィールドの中に納めることができる文字には、 0x09 (tab) と of 0x20 (space) から 0x7E (tilde)の包括的な範囲とを含む。バイナリモードではクオートされたフィールドの中において全ての文字を受け付ける。
	222	CVS フィールドの中に納めることができる文字には、 0x09 (tab) と of 0x20 (space) から 0x7E (tilde)の包括的な範囲とを含む。バイナリモードではクオートされたフィールドの中において全ての文字を受け付ける。
223	223
224	224	=item 2
225	225
226	226	CSV のフィールドは、二重引用符（quote char）で挟まれるべきである。
227	227
228	228	=item 3
229	229
230		CSV のフィールドの中にコンマ(separator char)がある場合は、二重引用符で挟まれなければならない。
	230	CVS のフィールドの中にコンマ(separator char)がある場合は、二重引用符で挟まれなければならない。
231	231
232	232	=item 4
233	233
234		CSV フィールドの中に二重引用符を埋め込む場合は、一対となった二重引用符の間に挟まれなければならない。バイナリモードでは特に、 NUL バイトを示す C<"0> を用いるべきである。
	234	CVS フィールドの中に二重引用符を埋め込む場合は、一対となった二重引用符の間に挟まれなければならない。バイナリモードでは特に、 NUL バイトを示す C<"0> を用いるべきである。
235	235
236	236	=item 5
237	237
238	238	CSV 文字列は、 0x0A (ラインフィード) もしくは 0x0D + 0x0A(キャリッジリターン + ラインフィード)で終わるべきである。
239	239
240	240	=back
241	241
242	242	=head1 AUTHOR
243	243
244	244	Alan Citterman F<E<lt>alan@mfgrtl.comE<gt>> が、この Perl モジュールを最初に書いた。Alan へ Text::CSV_XS に関するメールをどうか送らないで欲しい。なぜなら、今ではこのモジュールの主要部分を占める C コード部分について、彼は関与していないからである。
245	245
246	246	Jochen Wiedmann F<E<lt>joe@ispsoft.deE<gt>> が、エンコードとデコードのルーチンを有限状態マシンを実装する C コードで書き直し、クオート、エスケープ、そしてセパレーター文字変数、バイナリモード、そして print と getline メソッドを加えた。
247	247
248	248	=head1 SEE ALSO
249	249
250	250	L<perl(1)>, L<IO::File(3)>, L<IO::Wrap(3)>
251	251
252	252	=head1 Translator into Japanese (翻訳者)
253	253
254	254	anahori (at users.sourceforge.jp)
255	255
256	256	Japanized Perl Resources Project (L<http://sourceforge.jp/projects/perldocjp/>)
257	257
258	258	=cut

Powered by Amon2, 翻訳, サイト. Operated by Japan Perl Association