Debian Codegraph @

lib/POD2/JA/MIME/Charset.pod

raw
1 =encoding utf-8
2
3 =head1 NAME
4
5 MIME::Charset~[ja] - MIME のためのキャラクタセット情報
6
7 =head1 SYNOPSIS
8
9 use MIME::Charset:
10
11 $charset = MIME::Charset->new("euc-jp");
12
13 キャラクタセット情報の取得:
14
15 $benc = $charset->body_encoding; # 例 "Q"
16 $cset = $charset->as_string; # 例 "US-ASCII"
17 $henc = $charset->header_encoding; # 例 "S"
18 $cset = $charset->output_charset; # 例 "ISO-2022-JP"
19
20 テキストデータの変換:
21
22 ($text, $charset, $encoding) =
23 $charset->header_encode(
24 "\xc9\xc2\xc5\xaa\xc0\xde\xc3\xef\xc5\xaa".
25 "\xc7\xd1\xca\xaa\xbd\xd0\xce\xcf\xb4\xef",
26 Charset => 'euc-jp');
27 # ...例えば (<変換ずみ文字列>, "ISO-2022-JP", "B") を返す。
28
29 ($text, $charset, $encoding) =
30 $charset->body_encode(
31 "Collectioneur path\xe9tiquement ",
32 Charset => 'latin1');
33 # ...例えば (<元の文字列>, "ISO-8859-1", "QUOTED-PRINTABLE") を返す。
34
35 $len = $charset->encoded_header_len(
36 "Perl\xe8\xa8\x80\xe8\xaa\x9e",
37 Charset => "utf-8",
38 Encoding => "b");
39 # ...例えば 28 を返す。
40
41 モジュール既定値の操作:
42
43 MIME::Charset::alias("csEUCKR", "euc-kr");
44 MIME::Charset::default("iso-8859-1");
45 MIME::Charset::fallback("us-ascii");
46
47 非OO関数 (近い将来に廃止):
48
49 use MIME::Charset qw(:info);
50
51 $benc = body_encoding("iso-8859-2"); # "Q"
52 $cset = canonical_charset("ANSI X3.4-1968"); # "US-ASCII"
53 $henc = header_encoding("utf-8"); # "S"
54 $cset = output_charset("shift_jis"); # "ISO-2022-JP"
55
56 use MIME::Charset qw(:trans);
57
58 ($text, $charset, $encoding) =
59 header_encode(
60 "\xc9\xc2\xc5\xaa\xc0\xde\xc3\xef\xc5\xaa".
61 "\xc7\xd1\xca\xaa\xbd\xd0\xce\xcf\xb4\xef",
62 "euc-jp");
63 # ...(<変換されたテキスト>, "ISO-2022-JP", "B") を返す。
64
65 ($text, $charset, $encoding) =
66 body_encode(
67 "Collectioneur path\xe9tiquement ".
68 "\xe9clectique de d\xe9chets",
69 "latin1");
70 # ...(<元のテキスト>, "ISO-8859-1", "QUOTED-PRINTABLE") を返す。
71
72 $len = encoded_header_len(
73 "Perl\xe8\xa8\x80\xe8\xaa\x9e", "b", "utf-8"); # 28
74
75 =head1 DESCRIPTION
76
77 MIME::Charset は、インターネット上での MIME
78 メッセージに用いるキャラクタセットの情報を提供する。
79
80 =head2 定義
81
82 B<キャラクタセット> とは、MIME での ``character set'' のことで、
83 オクテットの列を文字の列に変換する方法を指す。
84 これは、ISO/IEC における ``符号化文字集合'' (CCS) と
85 ``文字符号化法'' (CES) の両方の概念を包含する。
86
87 B<エンコーディング> とは、MIME でのそれのことで、
88 メッセージ本体やメッセージヘッダ本体を印字可能な
89 US-ASCII 文字の列として表現する方法を指す。
90
91
92 =cut
93
94 =head2 コンストラクタ
95
96 =over
97
98 =item $charset = MIME::Charset->new([CHARSET [, OPTS]])
99
100 キャラクタセットオブジェクトを作成して返す。
101
102 OPTS には次の対を指定できる。
103 B<NOTE>:
104 Unicode/マルチバイト対応が有効になっていないとき (L<"USE_ENCODE"> 参照) は、
105 変換を行わないので、次のオプションは効果を持たない。
106
107 =over 4
108
109 =item Mapping => MAPTYPE
110
111 キャラクタセット名に対して実際に使うマッピングの拡張をするかどうか。
112 C<"EXTENDED"> は拡張マッピングを使う。
113 C<"STANDARD"> は標準化されている厳密なマッピングを使う。
114 既定は C<"EXTENDED">。
115
116 =back
117
118 =cut
119
120 =back
121
122 =head2 キャラクタセット情報の取得
123
124 =over
125
126 =item $charset->body_encoding
127
128 =item body_encoding CHARSET
129
130 CHARSET のメッセージ本体で推奨される伝送エンコーディングを取得する。
131
132 返値は C<"B"> (BASE64)、C<"Q"> (QUOTED-PRINTABLE)、C<"S"> (どちらか短いほう)、
133 C<undef> (伝送エンコードしなくてよい --- 7BIT か 8BIT)
134 のいずれか。これはメッセージヘッダのエンコーディングとは違うこともある。
135
136 =cut
137
138 =item $charset->as_string
139
140 =item canonical_charset CHARSET
141
142 キャラクタセットの正規の名前を取得する。
143
144 =cut
145
146 =item $charset->decoder
147
148 キャラクタセットを Unicode に復号するのに使う
149 L<"Encode::Encoding"> オブジェクトを返す。
150 キャラクタセットが指定されていなかったか、当モジュールの知らないキャラクタセットであった場合は、undef 値を返す。
151
152 =cut
153
154 =item $charset->dup
155
156 キャラクタセットオブジェクトを複写する。
157
158 =cut
159
160 =item $charset->encoder([CHARSET])
161
162 インターネット上の MIME
163 メッセージで使うことを推奨される互換キャラクタセットで符号化するのに使う
164 L<"Encode::Encoding"> オブジェクトを返す。
165
166 CHARSET 引数を指定した場合、$charset オブジェクトの符号化器
167 (および出力キャラクタセット名) を、CHARSET のそれに置き換える。
168 つまり、$charset オブジェクトは元のキャラクタセットから新たな
169 CHARSET への変換器となる。
170
171 =cut
172
173 =item $charset->header_encoding
174
175 =item header_encoding CHARSET
176
177 CHARSET のメッセージヘッダで推奨されるエンコーディング法を取得する。
178
179 返値は C<"B">、C<"Q">、C<"S"> (どちらか短くなるほう)、
180 C<undef> (エンコードしなくてよい)
181 のいずれか。これはメッセージ本体のエンコーディングとは違うこともある。
182
183
184 =cut
185
186 =item $charset->output_charset
187
188 =item output_charset CHARSET
189
190 指定した CHARSET と互換で、インターネット上の
191 MIME メッセージで使うことを推奨されるキャラクタセット名を
192 (当モジュールが知っていれば) 取得する。
193
194 Unicode/マルチバイト対応が有効になっていないとき (L<"USE_ENCODE"> 参照) は、
195 この関数は単に L<"canonical_charset"> の結果を返す。
196
197
198 =cut
199
200 =back
201
202 =head2 テキストデータの変換
203
204 =over
205
206 =item $charset->body_encode(STRING [, OPTS])
207
208 =item body_encode STRING, CHARSET [, OPTS]
209
210 STRING を (必要なら) 変換したデータと、
211 メッセージ本体で推奨される伝送エンコーディングを取得する。
212 CHARSET は STRING を符号化しているキャラクタセット。
213
214 OPTS には以下の対を指定できる。
215 B<NOTE>:
216 Unicode/マルチバイト対応が有効になっていないとき (L<"USE_ENCODE"> 参照) は、
217 変換を行わないので、以下のオプションは効果を持たない。
218
219 =over 4
220
221 =item Detect7bit => YESNO
222
223 CHARSET がないとき、7ビットのキャラクタセットを自動認識しようとする。
224 既定は C<"YES">。
225
226 =item Replacement => REPLACEMENT
227
228 エラー処理法の指定。L<"エラー処理"> 参照。
229
230 =back
231
232 3要素のリスト (I<変換ずみの文字列>, I<出力のキャラクタセット>,
233 I<伝送エンコーディング>) が返る。
234 I<伝送エンコーディング> は C<"BASE64">、C<"QUOTED-PRINTABLE">、
235 C<"7BIT">、C<"8BIT"> のいずれか。I<出力のキャラクタセット> が決定できず、
236 I<変換ずみの文字列> が ASCII以外のバイトを含むときは、
237 I<出力のキャラクタセット> は C<undef>、I<伝送エンコーディング> は C<"BASE64">
238 となる。
239 I<出力のキャラクタセット> が C<"US-ASCII">
240 となるのは、文字列が ASCII以外のバイトを含まないときに限る。
241
242
243 =cut
244
245 =item $charset->decode(STRING [,CHECK])
246
247 STRING を Unicode 文字列に復号する。
248
249 B<NOTE>:
250 Unicode/マルチバイト対応が有効になっていないとき (L<"USE_ENCODE"> 参照) は、
251 この機能を実行すると死ぬ。
252
253 =cut
254
255 =item detect_7bit_charset STRING
256
257 文字列 STRING を符号化している7 ビットキャラクタセットを推測する。
258 STRING が8ビットのバイトを含むときは C<undef> を返す。
259 そうでないとき、キャラクタセットが不明なら初期キャラクタセットを返す。
260
261 =cut
262
263 =item $charset->encode(STRING [, CHECK])
264
265 STRING (Unicode 文字列または普通の文字列) を、
266 元のキャラクタセットと互換でインターネット上の
267 MIME メッセージで使うことを推奨されるキャラクタセットを
268 (当モジュールが知っていれば) 使って、符号化する。
269 元のキャラクタセットと互換キャラクタセットが同じでも、
270 文字列を Unicode に復号してから符号化することに注意。
271
272 B<NOTE>:
273 Unicode/マルチバイト対応が有効になっていないとき (L<"USE_ENCODE"> 参照) は、
274 この機能を実行すると死ぬ。
275
276 =cut
277
278 =item $charset->encoded_header_len(STRING [, ENCODING])
279
280 =item encoded_header_len STRING, ENCODING, CHARSET
281
282 STRING をメッセージヘッダとしてエンコードしたときの長さ
283 (行折りはしないとして) を取得する。
284
285 ENCODING は C<"B">、C<"Q">、C<"S">
286 (C<"B"> と C<"Q"> のうち短くなるほう) のいずれか。
287
288
289 =cut
290
291 =item $charset->header_encode(STRING [, OPTS])
292
293 =item header_encode STRING, CHARSET [, OPTS]
294
295 STRING を (必要なら) 変換したデータと、
296 メッセージヘッダで推奨されるエンコーディング法を取得する。
297 CHARSET は STRING を符号化しているキャラクタセット。
298
299 OPTS には以下の対を指定できる。
300 B<NOTE>:
301 Unicode/マルチバイト対応が有効になっていないとき (L<"USE_ENCODE"> 参照) は、
302 変換を行わないので、以下のオプションは効果を持たない。
303
304 =over 4
305
306 =item Detect7bit => YESNO
307
308 CHARSET がないとき、7ビットのキャラクタセットを自動認識しようとする。
309 既定は C<"YES">。
310
311 =item Replacement => REPLACEMENT
312
313 エラー処理法の指定。L<"エラー処理"> 参照。
314
315 =back
316
317 3要素のリスト (I<変換ずみの文字列>, I<出力のキャラクタセット>,
318 I<エンコーディング法>) が返る。
319 I<エンコーディング法> は C<"B">、C<"Q">、C<undef> (エンコードしなくてよい)
320 のいずれか。
321 I<出力のキャラクタセット> が決定できず、I<変換ずみの文字列>
322 が ASCII以外のバイトを含むときは、I<出力のキャラクタセット> は C<"8BIT">
323 (これはキャラクタセットの名前ではI<なく>、符号化が不可能なデータを表す特殊値)
324 で I<エンコーディング法> は C<undef> (エンコードするべきではない) となる。
325 I<出力のキャラクタセット> が C<"US-ASCII">
326 となるのは、文字列が ASCII以外のバイトを含まないときに限る。
327
328 =cut
329
330 =item $charset->undecode(STRING [,CHECK])
331
332 Unicode 文字列 string を、
333 $charset の入力キャラクタセットを使って文字列に変換する。
334 これは C<$charset-E<gt>decoder-E<gt>encode()> と同等である。
335
336 B<NOTE>:
337 Unicode/マルチバイト対応が有効になっていないとき (L<"USE_ENCODE"> 参照) は、
338 この機能を実行すると死ぬ。
339
340 =cut
341
342 =back
343
344 =head2 モジュール既定値の操作
345
346 =over
347
348 =item alias ALIAS [, CHARSET]
349
350 L<"canonical_charset"> で正規名を決定するためのキャラクタセットの別名を取得/設定する。
351
352 CHARSET があって偽でないとき、ALIAS が CHARSET の別名に登録される。
353 さもなければ、別名に変更はない。いずれの場合でも、
354 現在 ALIAS が登録されているキャラクタセットを返す。
355
356
357 =cut
358
359 =item default [CHARSET]
360
361 既定キャラクタセットを取得/設定する。
362
363 B<既定キャラクタセット>とは、
364 当モジュールで、処理のためのキャラクタセットが不明なときに用いるキャラクタセット。
365 当モジュールを利用するモジュールでは、
366 処理のためのキャラクタセットが不明なときや暗黙の既定値が必要なとき、
367 このキャラクタセットを使うことを推奨する。
368 これは既定では C<"US-ASCII">。
369
370 CHARSET があって偽でなければ、それを既定キャラクタセットに設定する。
371 さもなければ、既定キャラクタセットは変わらない。いずれの場合でも、
372 現在の既定キャラクタセットを返す。
373
374 B<NOTE>: 既定キャラクタセットは変更するI<べきではない>。
375
376
377 =cut
378
379 =item fallback [CHARSET]
380
381 予備キャラクタセットを取得/設定する。
382
383 B<予備キャラクタセット>とは、
384 当モジュールで、指定されたキャラクタセットでの変換が失敗し、
385 エラー処理法に C<"FALLBACK"> が指定されていたときに用いるキャラクタセット。
386 当モジュールを利用するモジュールでは、
387 キャラクタセット変換が失敗するときに最終手段としてこのキャラクタセットを使ってもよい。
388 これは既定では C<"UTF-8">。
389
390 CHARSET があって偽でなければ、それを予備キャラクタセットに設定する。
391 CHARSET が C<"NONE"> であれば、予備キャラクタセットを未定にする。
392 さもなければ、予備キャラクタセットは変わらない。いずれの場合でも、
393 現在の予備キャラクタセットを返す。
394
395 B<NOTE>: 予備キャラクタセットに C<"US-ASCII"> を指定する価値はI<ある>。
396 変換の結果は、キャラクタセット情報がないときも可読となる。
397
398
399 =cut
400
401 =item recommended CHARSET [, HEADERENC, BODYENC [, ENCCHARSET]]
402
403 キャラクタセットの特性を取得/設定する。
404
405 必須でない引数があってそのどれかが偽でなければ、
406 その引数で CHARSET の特性を設定する。さもなければ、特性は変わらない。
407 いずれの場合でも、CHARSET の現在の特性を 3 要素のリスト
408 (HEADERENC, BODYENC, ENCCHARSET) として返す。
409
410 HEADERENC はメッセージヘッダで推奨されるエンコーディング法。
411 C<"B">、C<"Q">、C<"S"> (どちらか短くなるほう)、
412 C<undef> (エンコードしなくてよい) を指定できる。
413
414 BODYENC はメッセージ本体で推奨される伝送エンコーディング。
415 C<"B">、C<"Q">、C<"S"> (どちらか短くなるほう)、C<undef> (伝送エンコードしなくてよい) を指定できる。
416
417 ENCCHARSET は、指定した CHARSET と互換で、インターネット上の
418 MIME メッセージで使うことを推奨されるキャラクタセット名。
419 変換が必要ない (または当モジュールが適当なキャラクタセットを知らない) ときは、
420 ENCCHARSET は C<undef>。
421
422 B<NOTE>: この関数の今後の版では、ほかにも必須でない引数をとれるようになるかもしれない
423 (たとえば、文字幅、行分割の挙動などについての属性)。
424 そのため、返値の形式も変わるかもしれない。個々の特性を取得するには
425 L<"header_encoding">、L<"body_encoding">、L<"output_charset"> を使ってほしい。
426
427
428 =cut
429
430 =back
431
432 =head2 定数
433
434 =over
435
436 =item USE_ENCODE
437
438 Unicode/マルチバイト対応フラグ。
439 Unicode とマルチバイトへの対応が有効になっているときは、空でない文字列が設定されている。
440 現在、このフラグは Perl 5.7.3 以降で空でなく、それより以前の Perl では空の文字列。
441
442 =back
443
444 =head2 エラー処理
445
446 L<"body_encode"> と L<"header_encode"> の
447 C<Replacement> オプションには以下のものを指定できる:
448
449 =over
450
451 =item C<"DEFAULT">
452
453 不正な文字を置き換え文字で置き換える。
454 UCM に基づく符号化器を持つキャラクタセットでは <subchar> を使うことがある。
455
456 =item C<"FALLBACK">
457
458 I<予備キャラクタセット> を使って C<"DEFAULT"> 方式をやってみる
459 (L<"fallback"> 参照)。
460 予備キャラクタセットが未定で変換がエラーを起こしたときは、
461 コードはエラーメッセージを出力して死ぬ。
462
463 =item C<"CROAK">
464
465 コードはエラーメッセージを出力してすぐ死ぬ。
466 したがって、本当にエラーで死なせたくなければ
467 eval{} で致命的エラーを受け止めなければいけない。
468 C<"STRICT"> でも同じ。
469
470 =item C<"PERLQQ">
471
472 =item C<"HTMLCREF">
473
474 =item C<"XMLCREF">
475
476 L<Encode> モジュールで定義している
477 C<FB_PERLQQ>、C<FB_HTMLCREF>、C<FB_XMLCREF>
478 の方式を使う。
479
480 =item 数値
481
482 数値を指定することもできる。
483 詳細は L<Encode/Handling Malformed Data> を見てほしい。
484
485 =back
486
487 エラー処理法が指定されないか、上記以外のエラー処理法が指定されたときは、
488 C<"DEFAULT"> とみなす。
489
490 =head2 設定ファイル
491
492 オプションのパラメタの組み込み既定値は、設定ファイル
493 F<MIME/Charset/Defaults.pm> で変更することができる。
494 詳しくは F<MIME/Charset/Defaults.pm.sample> を読んでほしい。
495
496 =head1 VERSION
497
498 $VERSION 変数を見てほしい。
499
500 このモジュールの開発版が
501 L<http://hatuka.nezumi.nu/repos/MIME-Charset/> にある。
502
503 =head2 非互換な変更
504
505 =over 4
506
507 =item 1.001
508
509 =over 4
510
511 =item *
512
513 new() メソッドは CHARSET 引数を指定しなくてもオブジェクトを返すようになった。
514
515 =back
516
517 =item 1.005
518
519 =over 4
520
521 =item *
522
523 encoded-word に含まれる文字種を RFC 2047 の 5 (3) 節のとおりにした。
524 encoded_header_len() メソッドの返値も変わる。
525
526 =back
527
528 =item 1.008.2
529
530 =over 4
531
532 =item *
533
534 body_encoding() メソッドも C<"S"> を返せるようになった。
535
536 =item *
537
538 body_encode() メソッドの UTF-8 に対する返値のエンコーディング要素は、
539 これまでのリリースでは C<"BASE64"> に固定だったが、C<"QUOTED-PRINTABLE"> になることがある。
540
541 =back
542
543 =back
544
545 =head1 SEE ALSO
546
547 Multipurpose Internet Mail Extensions (MIME).
548
549 =head1 AUTHOR
550
551 Hatuka*nezumi - IKEDA Soji <hatuka(at)nezumi.nu>
552
553 =head1 COPYRIGHT
554
555 Copyright (C) 2006-2017 Hatuka*nezumi - IKEDA Soji.
556 This program is free software; you can redistribute it and/or modify it
557 under the same terms as Perl itself.
558
559
560 =cut