1POD2::JA::MIME::CharsetU(s3e)r Contributed Perl DocumentaPtOiDo2n::JA::MIME::Charset(3)
2
6 MIME::Charset~[ja] - MIME のためのキャラクタセット情報
7
9 use MIME::Charset:
10 $charset = MIME::Charset->new("euc-jp");
12 キャラクタセット情報の取得:
14 $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 テキストデータの変換:
21 ($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 ($text, $charset, $encoding) =
30 $charset->body_encode(
31 "Collectioneur path\xe9tiquement ",
32 Charset => 'latin1');
33 # ...例えば (<元の文字列>, "ISO-8859-1", "QUOTED-PRINTABLE") を返す。
34 $len = $charset->encoded_header_len(
36 "Perl\xe8\xa8\x80\xe8\xaa\x9e",
37 Charset => "utf-8",
38 Encoding => "b");
39 # ...例えば 28 を返す。
40 モジュール既定値の操作:
42 MIME::Charset::alias("csEUCKR", "euc-kr");
44 MIME::Charset::default("iso-8859-1");
45 MIME::Charset::fallback("us-ascii");
46 非OO関数 (近い将来に廃止):
48 use MIME::Charset qw(:info);
50 $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 use MIME::Charset qw(:trans);
57 ($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 ($text, $charset, $encoding) =
66 body_encode(
67 "Collectioneur path\xe9tiquement ".
68 "\xe9clectique de d\xe9chets",
69 "latin1");
70 # ...(<元のテキスト>, "ISO-8859-1", "QUOTED-PRINTABLE") を返す。
71 $len = encoded_header_len(
73 "Perl\xe8\xa8\x80\xe8\xaa\x9e", "b", "utf-8"); # 28
74
76 MIME::Charset は、インターネット上での MIME
77 メッセージに用いるキャラクタセットの情報を提供する。
78 定義
80 キャラクタセット とは、MIME での ``character set'' のことで、
81 オクテットの列を文字の列に変換する方法を指す。 これは、ISO/IEC における
82 ``符号化文字集合'' (CCS) と ``文字符号化法'' (CES)
83 の両方の概念を包含する。
84 エンコーディング とは、MIME でのそれのことで、
86 メッセージ本体やメッセージヘッダ本体を印字可能な US-ASCII
87 文字の列として表現する方法を指す。
88 コンストラクタ
90 $charset = MIME::Charset->new([CHARSET [, OPTS]])
91 キャラクタセットオブジェクトを作成して返す。
92 OPTS には次の対を指定できる。 NOTE:
94 Unicode/マルチバイト対応が有効になっていないとき ("USE_ENCODE"
95 参照) は、 変換を行わないので、次のオプションは効果を持たない。
96 Mapping => MAPTYPE
98 キャラクタセット名に対して実際に使うマッピングの拡張をするかどうか。
99 "EXTENDED" は拡張マッピングを使う。 "STANDARD"
100 は標準化されている厳密なマッピングを使う。 既定は "EXTENDED"。
101 キャラクタセット情報の取得
103 $charset->body_encoding
104 body_encoding CHARSET
105 CHARSET
106 のメッセージ本体で推奨される伝送エンコーディングを取得する。
107 返値は "B" (BASE64)、"Q" (QUOTED-PRINTABLE)、"S"
109 (どちらか短いほう)、 "undef" (伝送エンコードしなくてよい --- 7BIT
110 か 8BIT)
111 のいずれか。これはメッセージヘッダのエンコーディングとは違うこともある。
112 $charset->as_string
114 canonical_charset CHARSET
115 キャラクタセットの正規の名前を取得する。
116 $charset->decoder
118 キャラクタセットを Unicode に復号するのに使う "Encode::Encoding"
119 オブジェクトを返す。
120 キャラクタセットが指定されていなかったか、当モジュールの知らないキャラクタセットであった場合は、undef
121 値を返す。
122 $charset->dup
124 キャラクタセットオブジェクトを複写する。
125 $charset->encoder([CHARSET])
127 インターネット上の MIME
128 メッセージで使うことを推奨される互換キャラクタセットで符号化するのに使う
129 "Encode::Encoding" オブジェクトを返す。
130 CHARSET 引数を指定した場合、$charset オブジェクトの符号化器
132 (および出力キャラクタセット名) を、CHARSET のそれに置き換える。
133 つまり、$charset オブジェクトは元のキャラクタセットから新たな
134 CHARSET への変換器となる。
135 $charset->header_encoding
137 header_encoding CHARSET
138 CHARSET
139 のメッセージヘッダで推奨されるエンコーディング法を取得する。
140 返値は "B"、"Q"、"S" (どちらか短くなるほう)、 "undef"
142 (エンコードしなくてよい)
143 のいずれか。これはメッセージ本体のエンコーディングとは違うこともある。
144 $charset->output_charset
146 output_charset CHARSET
147 指定した CHARSET と互換で、インターネット上の MIME
148 メッセージで使うことを推奨されるキャラクタセット名を
149 (当モジュールが知っていれば) 取得する。
150 Unicode/マルチバイト対応が有効になっていないとき ("USE_ENCODE"
152 参照) は、 この関数は単に "canonical_charset" の結果を返す。
153 テキストデータの変換
155 $charset->body_encode(STRING [, OPTS])
156 body_encode STRING, CHARSET [, OPTS]
157 STRING を (必要なら) 変換したデータと、
158 メッセージ本体で推奨される伝送エンコーディングを取得する。 CHARSET
159 は STRING を符号化しているキャラクタセット。
160 OPTS には以下の対を指定できる。 NOTE:
162 Unicode/マルチバイト対応が有効になっていないとき ("USE_ENCODE"
163 参照) は、 変換を行わないので、以下のオプションは効果を持たない。
164 Detect7bit => YESNO
166 CHARSET
167 がないとき、7ビットのキャラクタセットを自動認識しようとする。
168 既定は "YES"。
169 Replacement => REPLACEMENT
171 エラー処理法の指定。"エラー処理" 参照。
172 3要素のリスト (変換ずみの文字列, 出力のキャラクタセット,
174 伝送エンコーディング) が返る。 伝送エンコーディング は
175 "BASE64"、"QUOTED-PRINTABLE"、 "7BIT"、"8BIT"
176 のいずれか。出力のキャラクタセット が決定できず、 変換ずみの文字列
177 が ASCII以外のバイトを含むときは、 出力のキャラクタセット は
178 "undef"、伝送エンコーディング は "BASE64" となる。
179 出力のキャラクタセット が "US-ASCII" となるのは、文字列が
180 ASCII以外のバイトを含まないときに限る。
181 $charset->decode(STRING [,CHECK])
183 STRING を Unicode 文字列に復号する。
184 NOTE: Unicode/マルチバイト対応が有効になっていないとき
186 ("USE_ENCODE" 参照) は、 この機能を実行すると死ぬ。
187 detect_7bit_charset STRING
189 文字列 STRING を符号化している7 ビットキャラクタセットを推測する。
190 STRING が8ビットのバイトを含むときは "undef" を返す。
191 そうでないとき、キャラクタセットが不明なら初期キャラクタセットを返す。
192 $charset->encode(STRING [, CHECK])
194 STRING (Unicode 文字列または普通の文字列) を、
195 元のキャラクタセットと互換でインターネット上の MIME
196 メッセージで使うことを推奨されるキャラクタセットを
197 (当モジュールが知っていれば) 使って、符号化する。
198 元のキャラクタセットと互換キャラクタセットが同じでも、 文字列を
199 Unicode に復号してから符号化することに注意。
200 NOTE: Unicode/マルチバイト対応が有効になっていないとき
202 ("USE_ENCODE" 参照) は、 この機能を実行すると死ぬ。
203 $charset->encoded_header_len(STRING [, ENCODING])
205 encoded_header_len STRING, ENCODING, CHARSET
206 STRING をメッセージヘッダとしてエンコードしたときの長さ
207 (行折りはしないとして) を取得する。
208 ENCODING は "B"、"Q"、"S" ("B" と "Q" のうち短くなるほう)
210 のいずれか。
211 $charset->header_encode(STRING [, OPTS])
213 header_encode STRING, CHARSET [, OPTS]
214 STRING を (必要なら) 変換したデータと、
215 メッセージヘッダで推奨されるエンコーディング法を取得する。 CHARSET
216 は STRING を符号化しているキャラクタセット。
217 OPTS には以下の対を指定できる。 NOTE:
219 Unicode/マルチバイト対応が有効になっていないとき ("USE_ENCODE"
220 参照) は、 変換を行わないので、以下のオプションは効果を持たない。
221 Detect7bit => YESNO
223 CHARSET
224 がないとき、7ビットのキャラクタセットを自動認識しようとする。
225 既定は "YES"。
226 Replacement => REPLACEMENT
228 エラー処理法の指定。"エラー処理" 参照。
229 3要素のリスト (変換ずみの文字列, 出力のキャラクタセット,
231 エンコーディング法) が返る。 エンコーディング法 は
232 "B"、"Q"、"undef" (エンコードしなくてよい) のいずれか。
233 出力のキャラクタセット が決定できず、変換ずみの文字列 が
234 ASCII以外のバイトを含むときは、出力のキャラクタセット は "8BIT"
235 (これはキャラクタセットの名前ではなく、符号化が不可能なデータを表す特殊値)
236 で エンコーディング法 は "undef" (エンコードするべきではない)
237 となる。 出力のキャラクタセット が "US-ASCII" となるのは、文字列が
238 ASCII以外のバイトを含まないときに限る。
239 $charset->undecode(STRING [,CHECK])
241 Unicode 文字列 string を、 $charset
242 の入力キャラクタセットを使って文字列に変換する。 これは
243 "$charset->decoder->encode()" と同等である。
244 NOTE: Unicode/マルチバイト対応が有効になっていないとき
246 ("USE_ENCODE" 参照) は、 この機能を実行すると死ぬ。
247 モジュール既定値の操作
249 alias ALIAS [, CHARSET]
250 "canonical_charset"
251 で正規名を決定するためのキャラクタセットの別名を取得/設定する。
252 CHARSET があって偽でないとき、ALIAS が CHARSET の別名に登録される。
254 さもなければ、別名に変更はない。いずれの場合でも、 現在 ALIAS
255 が登録されているキャラクタセットを返す。
256 default [CHARSET]
258 既定キャラクタセットを取得/設定する。
259 既定キャラクタセットとは、
261 当モジュールで、処理のためのキャラクタセットが不明なときに用いるキャラクタセット。
262 当モジュールを利用するモジュールでは、
263 処理のためのキャラクタセットが不明なときや暗黙の既定値が必要なとき、
264 このキャラクタセットを使うことを推奨する。 これは既定では
265 "US-ASCII"。
266 CHARSET
268 があって偽でなければ、それを既定キャラクタセットに設定する。
269 さもなければ、既定キャラクタセットは変わらない。いずれの場合でも、
270 現在の既定キャラクタセットを返す。
271 NOTE: 既定キャラクタセットは変更するべきではない。
273 fallback [CHARSET]
275 予備キャラクタセットを取得/設定する。
276 予備キャラクタセットとは、
278 当モジュールで、指定されたキャラクタセットでの変換が失敗し、
279 エラー処理法に "FALLBACK"
280 が指定されていたときに用いるキャラクタセット。
281 当モジュールを利用するモジュールでは、
282 キャラクタセット変換が失敗するときに最終手段としてこのキャラクタセットを使ってもよい。
283 これは既定では "UTF-8"。
284 CHARSET
286 があって偽でなければ、それを予備キャラクタセットに設定する。
287 CHARSET が "NONE" であれば、予備キャラクタセットを未定にする。
288 さもなければ、予備キャラクタセットは変わらない。いずれの場合でも、
289 現在の予備キャラクタセットを返す。
290 NOTE: 予備キャラクタセットに "US-ASCII" を指定する価値はある。
292 変換の結果は、キャラクタセット情報がないときも可読となる。
293 recommended CHARSET [, HEADERENC, BODYENC [, ENCCHARSET]]
295 キャラクタセットの特性を取得/設定する。
296 必須でない引数があってそのどれかが偽でなければ、 その引数で CHARSET
298 の特性を設定する。さもなければ、特性は変わらない。
299 いずれの場合でも、CHARSET の現在の特性を 3 要素のリスト (HEADERENC,
300 BODYENC, ENCCHARSET) として返す。
301 HEADERENC はメッセージヘッダで推奨されるエンコーディング法。
303 "B"、"Q"、"S" (どちらか短くなるほう)、 "undef"
304 (エンコードしなくてよい) を指定できる。
305 BODYENC はメッセージ本体で推奨される伝送エンコーディング。
307 "B"、"Q"、"S" (どちらか短くなるほう)、"undef"
308 (伝送エンコードしなくてよい) を指定できる。
309 ENCCHARSET は、指定した CHARSET と互換で、インターネット上の MIME
311 メッセージで使うことを推奨されるキャラクタセット名。 変換が必要ない
312 (または当モジュールが適当なキャラクタセットを知らない) ときは、
313 ENCCHARSET は "undef"。
314 NOTE:
316 この関数の今後の版では、ほかにも必須でない引数をとれるようになるかもしれない
317 (たとえば、文字幅、行分割の挙動などについての属性)。
318 そのため、返値の形式も変わるかもしれない。個々の特性を取得するには
319 "header_encoding"、"body_encoding"、"output_charset"
320 を使ってほしい。
321 定数
323 USE_ENCODE
324 Unicode/マルチバイト対応フラグ。 Unicode
325 とマルチバイトへの対応が有効になっているときは、空でない文字列が設定されている。
326 現在、このフラグは Perl 5.7.3 以降で空でなく、それより以前の Perl
327 では空の文字列。
328 エラー処理
330 "body_encode" と "header_encode" の "Replacement"
331 オプションには以下のものを指定できる:
332 "DEFAULT"
334 不正な文字を置き換え文字で置き換える。 UCM
335 に基づく符号化器を持つキャラクタセットでは <subchar>
336 を使うことがある。
337 "FALLBACK"
339 予備キャラクタセット を使って "DEFAULT" 方式をやってみる
340 ("fallback" 参照)。
341 予備キャラクタセットが未定で変換がエラーを起こしたときは、
342 コードはエラーメッセージを出力して死ぬ。
343 "CROAK"
345 コードはエラーメッセージを出力してすぐ死ぬ。
346 したがって、本当にエラーで死なせたくなければ eval{}
347 で致命的エラーを受け止めなければいけない。 "STRICT" でも同じ。
348 "PERLQQ"
350 "HTMLCREF"
351 "XMLCREF"
352 Encode モジュールで定義している
353 "FB_PERLQQ"、"FB_HTMLCREF"、"FB_XMLCREF" の方式を使う。
354 数値
356 数値を指定することもできる。 詳細は "Handling Malformed Data" in
357 Encode を見てほしい。
358 エラー処理法が指定されないか、上記以外のエラー処理法が指定されたときは、
360 "DEFAULT" とみなす。
361 設定ファイル
363 オプションのパラメタの組み込み既定値は、設定ファイル
364 MIME/Charset/Defaults.pm で変更することができる。 詳しくは
365 MIME/Charset/Defaults.pm.sample を読んでほしい。
366
368 $VERSION 変数を見てほしい。
369 このモジュールの開発版が <http://hatuka.nezumi.nu/repos/MIME-Charset/>
371 にある。
372 非互換な変更
374 1.001
375 • new() メソッドは CHARSET
376 引数を指定しなくてもオブジェクトを返すようになった。
377 1.005
379 • encoded-word に含まれる文字種を RFC 2047 の 5 (3)
380 節のとおりにした。 encoded_header_len()
381 メソッドの返値も変わる。
382 1.008.2
384 • body_encoding() メソッドも "S" を返せるようになった。
385 • body_encode() メソッドの UTF-8
387 に対する返値のエンコーディング要素は、 これまでのリリースでは
388 "BASE64" に固定だったが、"QUOTED-PRINTABLE" になることがある。
389
391 Multipurpose Internet Mail Extensions (MIME).
392
394 Hatuka*nezumi - IKEDA Soji <hatuka(at)nezumi.nu>
395
397 Copyright (C) 2006-2017 Hatuka*nezumi - IKEDA Soji. This program is
398 free software; you can redistribute it and/or modify it under the same
399 terms as Perl itself.
400perl v5.32.1 2021-01-27 POD2::JA::MIME::Charset(3)