定義¶

キャラクタセット とは、MIME での ``character set'' のことで、 オクテットの列を文字の列に変換する方法を指す。 これは、ISO/IEC における ``符号化文字集合'' (CCS) と ``文字符号化法'' (CES) の両方の概念を包含する。

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

コンストラクタ¶

$charset = MIME::Charset->new([CHARSET [, OPTS]])

キャラクタセットオブジェクトを作成して返す。

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

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

$charset->body_encoding

body_encoding CHARSET

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

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

$charset->as_string

canonical_charset CHARSET

キャラクタセットの正規の名前を取得する。

$charset->decoder

キャラクタセットを Unicode に復号するのに使う "Encode::Encoding" オブジェクトを返す。 キャラクタセットが指定されていなかったか、当モジュールの知らないキャラクタセットであった場合は、undef 値を返す。

$charset->dup

キャラクタセットオブジェクトを複写する。

$charset->encoder([CHARSET])

インターネット上の MIME メッセージで使うことを推奨される互換キャラクタセットで符号化するのに使う "Encode::Encoding" オブジェクトを返す。

CHARSET 引数を指定した場合、$charset オブジェクトの符号化器 (および出力キャラクタセット名) を、CHARSET のそれに置き換える。 つまり、$charset オブジェクトは元のキャラクタセットから新たな CHARSET への変換器となる。

$charset->header_encoding

header_encoding CHARSET

CHARSET のメッセージヘッダで推奨されるエンコーディング法を取得する。

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

$charset->output_charset

output_charset CHARSET

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

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

テキストデータの変換¶

$charset->body_encode(STRING [, OPTS])

body_encode STRING, CHARSET [, OPTS]

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

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

$charset->decode(STRING [,CHECK])

STRING を Unicode 文字列に復号する。

NOTE: Unicode/マルチバイト対応が有効になっていないとき ("USE_ENCODE" 参照) は、 この機能を実行すると死ぬ。

detect_7bit_charset STRING

文字列 STRING を符号化している7 ビットキャラクタセットを推測する。 STRING が8ビットのバイトを含むときは "undef" を返す。 そうでないとき、キャラクタセットが不明なら初期キャラクタセットを返す。

$charset->encode(STRING [, CHECK])

STRING (Unicode 文字列または普通の文字列) を、 元のキャラクタセットと互換でインターネット上の MIME メッセージで使うことを推奨されるキャラクタセットを (当モジュールが知っていれば) 使って、符号化する。 元のキャラクタセットと互換キャラクタセットが同じでも、 文字列を Unicode に復号してから符号化することに注意。

NOTE: Unicode/マルチバイト対応が有効になっていないとき ("USE_ENCODE" 参照) は、 この機能を実行すると死ぬ。

$charset->encoded_header_len(STRING [, ENCODING])

encoded_header_len STRING, ENCODING, CHARSET

STRING をメッセージヘッダとしてエンコードしたときの長さ (行折りはしないとして) を取得する。

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

$charset->header_encode(STRING [, OPTS])

header_encode STRING, CHARSET [, OPTS]

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

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

$charset->undecode(STRING [,CHECK])

Unicode 文字列 string を、 $charset の入力キャラクタセットを使って文字列に変換する。 これは "$charset->decoder->encode()" と同等である。

NOTE: Unicode/マルチバイト対応が有効になっていないとき ("USE_ENCODE" 参照) は、 この機能を実行すると死ぬ。

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

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"、"S" (どちらか短くなるほう)、"undef" (伝送エンコードしなくてよい) を指定できる。

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

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

定数¶

USE_ENCODE

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

エラー処理¶

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

"DEFAULT"

不正な文字を置き換え文字で置き換える。 UCM に基づく符号化器を持つキャラクタセットでは <subchar> を使うことがある。

"FALLBACK"

予備キャラクタセット を使って "DEFAULT" 方式をやってみる ("fallback" 参照)。 予備キャラクタセットが未定で変換がエラーを起こしたときは、 コードはエラーメッセージを出力して死ぬ。

"CROAK"

コードはエラーメッセージを出力してすぐ死ぬ。 したがって、本当にエラーで死なせたくなければ eval{} で致命的エラーを受け止めなければいけない。 "STRICT" でも同じ。

"PERLQQ"

"HTMLCREF"

"XMLCREF"

Encode モジュールで定義している "FB_PERLQQ"、"FB_HTMLCREF"、"FB_XMLCREF" の方式を使う。

数値

数値を指定することもできる。 詳細は "Handling Malformed Data" in Encode を見てほしい。

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

設定ファイル¶

オプションのパラメタの組み込み既定値は、設定ファイル MIME/Charset/Defaults.pm で変更することができる。 詳しくは MIME/Charset/Defaults.pm.sample を読んでほしい。

非互換な変更¶

1.001

1.005

1.008.2