Documentation made easier

POD2::JA::MIME::Charset

NAME

MIME::Charset~[ja] − MIME の た め の キ ャ ラ ク タ セ ッ ト 情 報

SYNOPSIS

use MIME::Charset:
$charset = MIME::Charset−>new("euc−jp");

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

$benc = $charset−>body_encoding; # 例 "Q"
$cset = $charset−>as_string; # 例 "US−ASCII"
$henc = $charset−>header_encoding; # 例 "S"
$cset = $charset−>output_charset; # 例 "ISO−2022−JP"

テ キ ス ト デ ー タ の 変 換 :

($text, $charset, $encoding) =
$charset−>header_encode(
"\xc9\xc2\xc5\xaa\xc0\xde\xc3\xef\xc5\xaa".
"\xc7\xd1\xca\xaa\xbd\xd0\xce\xcf\xb4\xef",
Charset => 'euc−jp');
# ...例 え ば (<変 換 ず み 文 字 列 >, "ISO−2022−JP", "B") を 返 す 。
($text, $charset, $encoding) =
$charset−>body_encode(
"Collectioneur path\xe9tiquement ",
Charset => 'latin1');
# ...例 え ば (<元 の 文 字 列 >, "ISO−8859−1", "QUOTED−PRINTABLE") を 返 す 。
$len = $charset−>encoded_header_len(
"Perl\xe8\xa8\x80\xe8\xaa\x9e",
Charset => "utf−8",
Encoding => "b");
# ...例 え ば 28 を 返 す 。

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

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

非 OO関 数 (近 い 将 来 に 廃 止 ):

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

DESCRIPTION

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

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

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

コ ン ス ト ラ ク タ
$charset = MIME::Charset−>new([ CHARSET [, OPTS ]])

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

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

キ ャ ラ ク タ セ ッ ト 名 に 対 し て 実 際 に 使 う マ ッ ピ ン グ の 拡 張 を す る か ど う か 。 "EXTENDED" は 拡 張 マ ッ ピ ン グ を 使 う 。 "STANDARD" は 標 準 化 さ れ て い る 厳 密 な マ ッ ピ ン グ を 使 う 。 既 定 は "EXTENDED"。

キ ャ ラ ク タ セ ッ ト 情 報 の 取 得
$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" 参 照 ) は 、 変 換 を 行 わ な い の で 、 以 下 の オ プ シ ョ ン は 効 果 を 持 た な い 。
Detect7bit => YESNO

CHARSET が な い と き 、 7ビ ッ ト の キ ャ ラ ク タ セ ッ ト を 自 動 認 識 し よ う と す る 。 既 定 は "YES"。

Replacement => REPLACEMENT

エ ラ ー 処 理 法 の 指 定 。 "エ ラ ー 処 理 " 参 照 。

3要 素 の リ ス ト (変 換 ず み の 文 字 列 , 出 力 の キ ャ ラ ク タ セ ッ ト , 伝 送 エ ン コ ー デ ィ ン グ ) が 返 る 。 伝 送 エ ン コ ー デ ィ ン グ は "BASE64"、 "QUOTED−PRINTABLE"、 "7BIT"、 "8BIT" の い ず れ か 。 出 力 の キ ャ ラ ク タ セ ッ ト が 決 定 で き ず 、 変 換 ず み の 文 字 列 が ASCII以 外 の バ イ ト を 含 む と き は 、 出 力 の キ ャ ラ ク タ セ ッ ト は "undef"、 伝 送 エ ン コ ー デ ィ ン グ は "BASE64" と な る 。 出 力 の キ ャ ラ ク タ セ ッ ト が "US−ASCII" と な る の は 、 文 字 列 が ASCII以 外 の バ イ ト を 含 ま な い と き に 限 る 。

$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" 参 照 ) は 、 変 換 を 行 わ な い の で 、 以 下 の オ プ シ ョ ン は 効 果 を 持 た な い 。
Detect7bit => YESNO

CHARSET が な い と き 、 7ビ ッ ト の キ ャ ラ ク タ セ ッ ト を 自 動 認 識 し よ う と す る 。 既 定 は "YES"。

Replacement => REPLACEMENT

エ ラ ー 処 理 法 の 指 定 。 "エ ラ ー 処 理 " 参 照 。

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

$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 を 読 ん で ほ し い 。

VERSION

$VERSION 変 数 を 見 て ほ し い 。

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

非 互 換 な 変 更
1.001

1.005

1.008.2

SEE ALSO

Multipurpose Internet Mail Extensions ( MIME ).

AUTHOR

Hatuka*nezumi − IKEDA Soji <hatuka(at)nezumi.nu>

COPYRIGHT

Copyright (C) 2006−2017 Hatuka*nezumi − IKEDA Soji. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.