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