MIME::Charset-ja_JP.3pm

Langue: en

Version: 2006-12-08 (mandriva - 22/10/07)

Section: 3 (Bibliothèques de fonctions)

Sommaire

NAME

MIME::Charset - MIME のためのキャラクタセット情報

SYNOPSIS

キャラクタセット情報の取得: 
     use MIME::Charset qw(:info);
 
 

     $benc = body_encoding("iso-8859-2"); # "Q"
     $cset = canonical_charset("ANSI X3.4-1968"); # "US-ASCII"
     $henc = header_encoding("utf-8"); # "S"
     $cset = output_charset("shift_jis"); # "ISO-2022-JP"

テキストデータの変換:

     use MIME::Charset qw(:trans);
 
 

     ($text, $charset, $encoding) =
         header_encode(
            "\xc9\xc2\xc5\xaa\xc0\xde\xc3\xef\xc5\xaa".
            "\xc7\xd1\xca\xaa\xbd\xd0\xce\xcf\xb4\xef",
            "euc-jp");
     # ...(<変換されたテキスト>, "ISO-2022-JP", "B") を返す。
 
 

     ($text, $charset, $encoding) =
         body_encode(
             "Collectioneur path\xe9tiquement ".
             "\xe9clectique de d\xe9chets",
             "latin1");
     # ...(<元のテキスト>, "ISO-8859-1", "QUOTED-PRINTABLE") を返す。
 
 

     $len = encoded_header_len(
         "Perl\xe8\xa8\x80\xe8\xaa\x9e", "b", "utf-8"); # 28

モジュール既定値の操作:

     use MIME::Charset;
 
 

     MIME::Charset::alias("csEUCKR", "euc-kr");
     MIME::Charset::default("iso-8859-1");
     MIME::Charset::fallback("us-ascii");

DESCRIPTION

MIME::Charset は、インターネット上での MIME メッセージに用いるキャラクタセットの情報を提供する。

定義

キャラクタセット とは、MIME での ``character set'' のことで、 オクテットの列を文字の列に変換する方法を指す。 これは、ISO/IEC における ``符号化文字集合'' (CCS) と ``文字符合化法'' (CES) の両方の概念を包含する (この定義は不正確かもしれません。 より正確な定義をご存じの方ご指南ください)。

エンコーディング とは、MIME でのそれのことで、 メッセージ本体やメッセージヘッダ本体を印字可能な US-ASCII 文字の列として表現する方法を指す。

キャラクタセット情報の取得

body_encoding CHARSET
CHARSET のメッセージ本体で推奨される伝送エンコーディングを取得する。

返値は "B" (BASE64)、"Q" (QUOTED-PRINTABLE)、 "undef" (伝送エンコーディングしなくてよい --- 7BIT か 8BIT) のいずれか。これはメッセージヘッダのエンコーディングとは違うこともある。

canonical_charset CHARSET
キャラクタセット CHARSET の正規の名前を取得する。
header_encoding CHARSET
CHARSET のメッセージヘッダで推奨されるエンコーディング法を取得する。

返値は "B"、"Q"、"S" (どちらか短くなるほう)、 "undef" (エンコードしなくてよい) のいずれか。これはメッセージ本体のエンコーディングとは違うこともある。

output_charset CHARSET
指定した CHARSET と互換で、インターネット上の MIME メッセージで使うことを推奨されるキャラクタセット名を (当モジュールが知っていれば) 取得する。

Unicode/マルチバイト対応が有効になっていないとき (``USE_ENCODE'' 参照) は、 この関数は単に ``canonical_charset'' の結果を返す。

テキストデータの変換

body_encode STRING, CHARSET [, OPTS]
STRING を (必要なら) 変換したデータと、 メッセージ本体で推奨される伝送エンコーディングを取得する。 CHARSET は STRING を符号化しているキャラクタセット。

OPTS には以下の対を指定できる。 NOTE: Unicode/マルチバイト対応が有効になっていないとき (``USE_ENCODE'' 参照) は、 変換を行わないので、以下のオプションは効果を持たない。

Replacement => REPLACEMENT
エラー処理法の指定。``エラー処理'' 参照。
Detect7bit => YESNO
CHARSET がないとき、7ビットのキャラクタセットを自動認識しようとする。 既定は "YES"。

3要素のリスト (変換ずみの文字列, 出力のキャラクタセット, 伝送エンコーディング) が返る。 伝送エンコーディング は "BASE64"、"QUOTED-PRINTABLE"、 "7BIT"、"8BIT" のいずれか。出力のキャラクタセット が決定できず、 変換ずみの文字列 が ASCII以外のバイトを含むときは、 出力のキャラクタセット は "undef"、伝送エンコーディング は "BASE64" となる。 出力のキャラクタセット が "US-ASCII" となるのは、文字列が ASCII以外のバイトを含まないときに限る。
encoded_header_len STRING, ENCODING, CHARSET
STRING をメッセージヘッダとしてエンコードしたときの長さ (行折りはしないとして) を取得する。

ENCODING は "B"、"Q"、"S" ("B" と "Q" のうち短くなるほう) のいずれか。

header_encode STRING, CHARSET [, OPTS]
STRING を (必要なら) 変換したデータと、 メッセージヘッダで推奨されるエンコーディング法を取得する。 CHARSET は STRING を符号化しているキャラクタセット。

OPTS には以下の対を指定できる。 NOTE: Unicode/マルチバイト対応が有効になっていないとき (``USE_ENCODE'' 参照) は、 変換を行わないので、以下のオプションは効果を持たない。

Replacement => REPLACEMENT
エラー処理法の指定。``エラー処理'' 参照。
Detect7bit => YESNO
CHARSET がないとき、7ビットのキャラクタセットを自動認識しようとする。 既定は "YES"。

3要素のリスト (変換ずみの文字列, 出力のキャラクタセット, エンコーディング法) が返る。 エンコーディング法 は "B"、"Q"、"undef" (エンコーディングしなくてよい) のいずれか。 出力のキャラクタセット が決定できず、変換ずみの文字列 が ASCII以外のバイトを含むときは、出力のキャラクタセット は "8BIT" (これはキャラクタセットの名前ではなく、エンコーディング不可能なデータを表す特殊値) で エンコーディング法 は "undef" (エンコードするべきではない) となる。 出力のキャラクタセット が "US-ASCII" となるのは、文字列が ASCII以外のバイトを含まないときに限る。

モジュール既定値の操作

alias ALIAS [, CHARSET]
``canonical_charset'' で正規名を決定するためのキャラクタセットの別名を取得/設定する。

CHARSET があって偽でないとき、ALIAS が CHARSET の別名に登録される。 さもなければ、別名に変更はない。いずれの場合でも、 現在 ALIAS が登録されているキャラクタセットを返す。

default [CHARSET]
既定キャラクタセットを取得/設定する。

既定キャラクタセットとは、 当モジュールで、処理のためのキャラクタセットが不明なときに用いるキャラクタセット。 当モジュールを利用するモジュールでは、 処理のためのキャラクタセットが不明なときや暗黙の既定値が必要なとき、 このキャラクタセットを使うことを推奨する。 これは既定では "US-ASCII"。

CHARSET があって偽でなければ、それを既定キャラクタセットに設定する。 さもなければ、既定キャラクタセットは変わらない。いずれの場合でも、 現在の既定キャラクタセットを返す。

NOTE: 既定キャラクタセットは変更するべきではない。

fallback [CHARSET]
予備キャラクタセットを取得/設定する。

予備キャラクタセットとは、 当モジュールで、指定されたキャラクタセットでの変換が失敗し、 エラー処理法に "FALLBACK" が指定されていたときに用いるキャラクタセット。 当モジュールを利用するモジュールでは、 キャラクタセット変換が失敗するときに最終手段としてこのキャラクタセットを使ってもよい。 これは既定では "UTF-8"。

CHARSET があって偽でなければ、それを予備キャラクタセットに設定する。 CHARSET が "NONE" であれば、予備キャラクタセットを未定にする。 さもなければ、予備キャラクタセットは変わらない。いずれの場合でも、 現在の予備キャラクタセットを返す。

NOTE: 予備キャラクタセットに "US-ASCII" を指定する価値はある。 変換の結果は、キャラクタセット情報がないときも可読となる。

recommended CHARSET [, HEADERENC, BODYENC [, ENCCHARSET]]
キャラクタセットの特性を取得/設定する。

必須でない引数があってそのどれかが偽でなければ、 その引数で CHARSET の特性を設定する。さもなければ、特性は変わらない。 いずれの場合でも、CHARSET の現在の特性を 3 要素のリスト (HEADERENC, BODYENC, ENCCHARSET) として返す。

HEADERENC はメッセージヘッダで推奨されるエンコーディング法。 "B"、"Q"、"S" (どちらか短くなるほう)、 "undef" (エンコーディングしなくてよい) を指定できる。

BODYENC はメッセージ本体で推奨される伝送エンコーディング。 "B"、"Q"、"undef" (伝送エンコーディングしなくてよい) を指定できる。

ENCCHARSET は、指定した CHARSET と互換で、インターネット上の MIME メッセージで使うことを推奨されるキャラクタセット名。 変換が必要ない (または当モジュールが適当なキャラクタセットを知らない) ときは、 ENCCHARSET は "undef"。

NOTE: この関数の今後の版では、ほかにも必須でない引数をとれるようになるかもしれない (たとえば、文字幅、行分割の挙動などについての属性)。 そのため、返値の形式も変わるかもしれない。個々の特性を取得するには ``header_encoding''、``body_encoding''、``output_charset'' を使ってほしい。

定数

USE_ENCODE
Unicode/マルチバイト対応フラグ。 Unicode とマルチバイトへの対応が有効になっているときは、空でない文字列が設定されている。 現在、このフラグは Perl 5.8.1 以降で空でなく、それより以前の Perl では空の文字列。

エラー処理

``body_encode'' と ``header_encode'' の "Replacement" オプションには以下のものを指定できる:

"DEFAULT"
不正な文字を置き換え文字で置き換える。 UCM に基づくエンコーディングのキャラクタセットでは <subchar> を使う。
"FALLBACK"
予備キャラクタセット を使って "DEFAULT" 方式をやってみる (``fallback'' 参照)。 予備キャラクタセットが未定で変換がエラーを起こしたときは、 コードはエラーメッセージを出力して死ぬ。
"CROAK"
コードはエラーメッセージを出力してすぐ死ぬ。 したがって、本当にエラーで死なせたくなければ eval{} で致命的エラーを受け止めなければいけない。 "STRICT" でも同じ。
"PERQQ"
"HTMLCREF"
"XMLCREF"
Encode モジュールで定義している "FB_PERLQQ"、"FB_HTMLCREF"、"FB_XMLCREF" の方式を使う。

エラー処理法が指定されないか、上記以外のエラー処理法が指定されたときは、 "DEFAULT" とみなす。

VERSION

$VERSION 変数を見てほしい。

このモジュールの開発版が <http://hatuka.nezumi.nu/repos/MIME-Charset/> にある。

SEE ALSO

Multipurpose Internet Mail Extensions (MIME).

AUTHORS

Copyright (C) 2006 Hatuka*nezumi - IKEDA Soji <hatuka(at)nezumi.nu>.

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.