1POD2::JA::MIME::CharsetU(s3e)r Contributed Perl DocumentaPtOiDo2n::JA::MIME::Charset(3)
2
3
4

NAME

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

SYNOPSIS

9           use MIME::Charset:
10
11           $charset = MIME::Charset->new("euc-jp");
12
13       キャラクタセット情報の取得:
14
15           $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
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                  Charset => 'euc-jp');
27           # ...例えば (<変換ずみ文字列>, "ISO-2022-JP", "B") を返す。
28
29           ($text, $charset, $encoding) =
30               $charset->body_encode(
31                   "Collectioneur path\xe9tiquement ",
32                   Charset => 'latin1');
33           # ...例えば (<元の文字列>, "ISO-8859-1", "QUOTED-PRINTABLE") を返す。
34
35           $len = $charset->encoded_header_len(
36               "Perl\xe8\xa8\x80\xe8\xaa\x9e",
37               Charset => "utf-8",
38               Encoding => "b");
39           # ...例えば 28 を返す。
40
41       モジュール既定値の操作:
42
43           MIME::Charset::alias("csEUCKR", "euc-kr");
44           MIME::Charset::default("iso-8859-1");
45           MIME::Charset::fallback("us-ascii");
46
47       非OO関数 (近い将来に廃止):
48
49           use MIME::Charset qw(:info);
50
51           $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
56           use MIME::Charset qw(:trans);
57
58           ($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
65           ($text, $charset, $encoding) =
66               body_encode(
67                   "Collectioneur path\xe9tiquement ".
68                   "\xe9clectique de d\xe9chets",
69                   "latin1");
70           # ...(<元のテキスト>, "ISO-8859-1", "QUOTED-PRINTABLE") を返す。
71
72           $len = encoded_header_len(
73               "Perl\xe8\xa8\x80\xe8\xaa\x9e", "b", "utf-8"); # 28
74

DESCRIPTION

76       MIME::Charset は、インターネット上での MIME
77       メッセージに用いるキャラクタセットの情報を提供する。
78
79   定義
80       キャラクタセット とは、MIME での ``character set'' のことで、
81       オクテットの列を文字の列に変換する方法を指す。 これは、ISO/IEC における
82       ``符号化文字集合'' (CCS) と ``文字符号化法'' (CES)
83       の両方の概念を包含する。
84
85       エンコーディング とは、MIME でのそれのことで、
86       メッセージ本体やメッセージヘッダ本体を印字可能な US-ASCII
87       文字の列として表現する方法を指す。
88
89   コンストラクタ
90       $charset = MIME::Charset->new([CHARSET [, OPTS]])
91           キャラクタセットオブジェクトを作成して返す。
92
93           OPTS には次の対を指定できる。 NOTE:
94           Unicode/マルチバイト対応が有効になっていないとき ("USE_ENCODE"
95           参照) は、 変換を行わないので、次のオプションは効果を持たない。
96
97           Mapping => MAPTYPE
98               キャラクタセット名に対して実際に使うマッピングの拡張をするかどうか。
99               "EXTENDED" は拡張マッピングを使う。 "STANDARD"
100               は標準化されている厳密なマッピングを使う。 既定は "EXTENDED"。
101
102   キャラクタセット情報の取得
103       $charset->body_encoding
104       body_encoding CHARSET
105           CHARSET
106           のメッセージ本体で推奨される伝送エンコーディングを取得する。
107
108           返値は "B" (BASE64)、"Q" (QUOTED-PRINTABLE)、"S"
109           (どちらか短いほう)、 "undef" (伝送エンコードしなくてよい --- 7BIT
110           か 8BIT)
111           のいずれか。これはメッセージヘッダのエンコーディングとは違うこともある。
112
113       $charset->as_string
114       canonical_charset CHARSET
115           キャラクタセットの正規の名前を取得する。
116
117       $charset->decoder
118           キャラクタセットを Unicode に復号するのに使う "Encode::Encoding"
119           オブジェクトを返す。
120           キャラクタセットが指定されていなかったか、当モジュールの知らないキャラクタセットであった場合は、undef
121           値を返す。
122
123       $charset->dup
124           キャラクタセットオブジェクトを複写する。
125
126       $charset->encoder([CHARSET])
127           インターネット上の MIME
128           メッセージで使うことを推奨される互換キャラクタセットで符号化するのに使う
129           "Encode::Encoding" オブジェクトを返す。
130
131           CHARSET 引数を指定した場合、$charset オブジェクトの符号化器
132           (および出力キャラクタセット名) を、CHARSET のそれに置き換える。
133           つまり、$charset オブジェクトは元のキャラクタセットから新たな
134           CHARSET への変換器となる。
135
136       $charset->header_encoding
137       header_encoding CHARSET
138           CHARSET
139           のメッセージヘッダで推奨されるエンコーディング法を取得する。
140
141           返値は "B"、"Q"、"S" (どちらか短くなるほう)、 "undef"
142           (エンコードしなくてよい)
143           のいずれか。これはメッセージ本体のエンコーディングとは違うこともある。
144
145       $charset->output_charset
146       output_charset CHARSET
147           指定した CHARSET と互換で、インターネット上の MIME
148           メッセージで使うことを推奨されるキャラクタセット名を
149           (当モジュールが知っていれば) 取得する。
150
151           Unicode/マルチバイト対応が有効になっていないとき ("USE_ENCODE"
152           参照) は、 この関数は単に "canonical_charset" の結果を返す。
153
154   テキストデータの変換
155       $charset->body_encode(STRING [, OPTS])
156       body_encode STRING, CHARSET [, OPTS]
157           STRING を (必要なら) 変換したデータと、
158           メッセージ本体で推奨される伝送エンコーディングを取得する。 CHARSET
159           は STRING を符号化しているキャラクタセット。
160
161           OPTS には以下の対を指定できる。 NOTE:
162           Unicode/マルチバイト対応が有効になっていないとき ("USE_ENCODE"
163           参照) は、 変換を行わないので、以下のオプションは効果を持たない。
164
165           Detect7bit => YESNO
166               CHARSET
167               がないとき、7ビットのキャラクタセットを自動認識しようとする。
168               既定は "YES"。
169
170           Replacement => REPLACEMENT
171               エラー処理法の指定。"エラー処理" 参照。
172
173           3要素のリスト (変換ずみの文字列, 出力のキャラクタセット,
174           伝送エンコーディング) が返る。 伝送エンコーディング
175           "BASE64"、"QUOTED-PRINTABLE"、 "7BIT"、"8BIT"
176           のいずれか。出力のキャラクタセット が決定できず、 変換ずみの文字列
177           が ASCII以外のバイトを含むときは、 出力のキャラクタセット
178           "undef"、伝送エンコーディング は "BASE64" となる。
179           出力のキャラクタセット が "US-ASCII" となるのは、文字列が
180           ASCII以外のバイトを含まないときに限る。
181
182       $charset->decode(STRING [,CHECK])
183           STRING を Unicode 文字列に復号する。
184
185           NOTE: Unicode/マルチバイト対応が有効になっていないとき
186           ("USE_ENCODE" 参照) は、 この機能を実行すると死ぬ。
187
188       detect_7bit_charset STRING
189           文字列 STRING を符号化している7 ビットキャラクタセットを推測する。
190           STRING が8ビットのバイトを含むときは "undef" を返す。
191           そうでないとき、キャラクタセットが不明なら初期キャラクタセットを返す。
192
193       $charset->encode(STRING [, CHECK])
194           STRING (Unicode 文字列または普通の文字列) を、
195           元のキャラクタセットと互換でインターネット上の MIME
196           メッセージで使うことを推奨されるキャラクタセットを
197           (当モジュールが知っていれば) 使って、符号化する。
198           元のキャラクタセットと互換キャラクタセットが同じでも、 文字列を
199           Unicode に復号してから符号化することに注意。
200
201           NOTE: Unicode/マルチバイト対応が有効になっていないとき
202           ("USE_ENCODE" 参照) は、 この機能を実行すると死ぬ。
203
204       $charset->encoded_header_len(STRING [, ENCODING])
205       encoded_header_len STRING, ENCODING, CHARSET
206           STRING をメッセージヘッダとしてエンコードしたときの長さ
207           (行折りはしないとして) を取得する。
208
209           ENCODING は "B"、"Q"、"S" ("B" と "Q" のうち短くなるほう)
210           のいずれか。
211
212       $charset->header_encode(STRING [, OPTS])
213       header_encode STRING, CHARSET [, OPTS]
214           STRING を (必要なら) 変換したデータと、
215           メッセージヘッダで推奨されるエンコーディング法を取得する。 CHARSET
216           は STRING を符号化しているキャラクタセット。
217
218           OPTS には以下の対を指定できる。 NOTE:
219           Unicode/マルチバイト対応が有効になっていないとき ("USE_ENCODE"
220           参照) は、 変換を行わないので、以下のオプションは効果を持たない。
221
222           Detect7bit => YESNO
223               CHARSET
224               がないとき、7ビットのキャラクタセットを自動認識しようとする。
225               既定は "YES"。
226
227           Replacement => REPLACEMENT
228               エラー処理法の指定。"エラー処理" 参照。
229
230           3要素のリスト (変換ずみの文字列, 出力のキャラクタセット,
231           エンコーディング法) が返る。 エンコーディング法
232           "B"、"Q"、"undef" (エンコードしなくてよい) のいずれか。
233           出力のキャラクタセット が決定できず、変換ずみの文字列
234           ASCII以外のバイトを含むときは、出力のキャラクタセット は "8BIT"
235           (これはキャラクタセットの名前ではなく、符号化が不可能なデータを表す特殊値)
236エンコーディング法 は "undef" (エンコードするべきではない)
237           となる。 出力のキャラクタセット が "US-ASCII" となるのは、文字列が
238           ASCII以外のバイトを含まないときに限る。
239
240       $charset->undecode(STRING [,CHECK])
241           Unicode 文字列 string を、 $charset
242           の入力キャラクタセットを使って文字列に変換する。 これは
243           "$charset->decoder->encode()" と同等である。
244
245           NOTE: Unicode/マルチバイト対応が有効になっていないとき
246           ("USE_ENCODE" 参照) は、 この機能を実行すると死ぬ。
247
248   モジュール既定値の操作
249       alias ALIAS [, CHARSET]
250           "canonical_charset"
251           で正規名を決定するためのキャラクタセットの別名を取得/設定する。
252
253           CHARSET があって偽でないとき、ALIAS が CHARSET の別名に登録される。
254           さもなければ、別名に変更はない。いずれの場合でも、 現在 ALIAS
255           が登録されているキャラクタセットを返す。
256
257       default [CHARSET]
258           既定キャラクタセットを取得/設定する。
259
260           既定キャラクタセットとは、
261           当モジュールで、処理のためのキャラクタセットが不明なときに用いるキャラクタセット。
262           当モジュールを利用するモジュールでは、
263           処理のためのキャラクタセットが不明なときや暗黙の既定値が必要なとき、
264           このキャラクタセットを使うことを推奨する。 これは既定では
265           "US-ASCII"。
266
267           CHARSET
268           があって偽でなければ、それを既定キャラクタセットに設定する。
269           さもなければ、既定キャラクタセットは変わらない。いずれの場合でも、
270           現在の既定キャラクタセットを返す。
271
272           NOTE: 既定キャラクタセットは変更するべきではない
273
274       fallback [CHARSET]
275           予備キャラクタセットを取得/設定する。
276
277           予備キャラクタセットとは、
278           当モジュールで、指定されたキャラクタセットでの変換が失敗し、
279           エラー処理法に "FALLBACK"
280           が指定されていたときに用いるキャラクタセット。
281           当モジュールを利用するモジュールでは、
282           キャラクタセット変換が失敗するときに最終手段としてこのキャラクタセットを使ってもよい。
283           これは既定では "UTF-8"。
284
285           CHARSET
286           があって偽でなければ、それを予備キャラクタセットに設定する。
287           CHARSET が "NONE" であれば、予備キャラクタセットを未定にする。
288           さもなければ、予備キャラクタセットは変わらない。いずれの場合でも、
289           現在の予備キャラクタセットを返す。
290
291           NOTE: 予備キャラクタセットに "US-ASCII" を指定する価値はある
292           変換の結果は、キャラクタセット情報がないときも可読となる。
293
294       recommended CHARSET [, HEADERENC, BODYENC [, ENCCHARSET]]
295           キャラクタセットの特性を取得/設定する。
296
297           必須でない引数があってそのどれかが偽でなければ、 その引数で CHARSET
298           の特性を設定する。さもなければ、特性は変わらない。
299           いずれの場合でも、CHARSET の現在の特性を 3 要素のリスト (HEADERENC,
300           BODYENC, ENCCHARSET) として返す。
301
302           HEADERENC はメッセージヘッダで推奨されるエンコーディング法。
303           "B"、"Q"、"S" (どちらか短くなるほう)、 "undef"
304           (エンコードしなくてよい) を指定できる。
305
306           BODYENC はメッセージ本体で推奨される伝送エンコーディング。
307           "B"、"Q"、"S" (どちらか短くなるほう)、"undef"
308           (伝送エンコードしなくてよい) を指定できる。
309
310           ENCCHARSET は、指定した CHARSET と互換で、インターネット上の MIME
311           メッセージで使うことを推奨されるキャラクタセット名。 変換が必要ない
312           (または当モジュールが適当なキャラクタセットを知らない) ときは、
313           ENCCHARSET は "undef"。
314
315           NOTE:
316           この関数の今後の版では、ほかにも必須でない引数をとれるようになるかもしれない
317           (たとえば、文字幅、行分割の挙動などについての属性)。
318           そのため、返値の形式も変わるかもしれない。個々の特性を取得するには
319           "header_encoding"、"body_encoding"、"output_charset"
320           を使ってほしい。
321
322   定数
323       USE_ENCODE
324           Unicode/マルチバイト対応フラグ。 Unicode
325           とマルチバイトへの対応が有効になっているときは、空でない文字列が設定されている。
326           現在、このフラグは Perl 5.7.3 以降で空でなく、それより以前の Perl
327           では空の文字列。
328
329   エラー処理
330       "body_encode" と "header_encode" の "Replacement"
331       オプションには以下のものを指定できる:
332
333       "DEFAULT"
334           不正な文字を置き換え文字で置き換える。 UCM
335           に基づく符号化器を持つキャラクタセットでは <subchar>
336           を使うことがある。
337
338       "FALLBACK"
339           予備キャラクタセット を使って "DEFAULT" 方式をやってみる
340           ("fallback" 参照)。
341           予備キャラクタセットが未定で変換がエラーを起こしたときは、
342           コードはエラーメッセージを出力して死ぬ。
343
344       "CROAK"
345           コードはエラーメッセージを出力してすぐ死ぬ。
346           したがって、本当にエラーで死なせたくなければ eval{}
347           で致命的エラーを受け止めなければいけない。 "STRICT" でも同じ。
348
349       "PERLQQ"
350       "HTMLCREF"
351       "XMLCREF"
352           Encode モジュールで定義している
353           "FB_PERLQQ"、"FB_HTMLCREF"、"FB_XMLCREF" の方式を使う。
354
355       数値
356           数値を指定することもできる。 詳細は "Handling Malformed Data" in
357           Encode を見てほしい。
358
359       エラー処理法が指定されないか、上記以外のエラー処理法が指定されたときは、
360       "DEFAULT" とみなす。
361
362   設定ファイル
363       オプションのパラメタの組み込み既定値は、設定ファイル
364       MIME/Charset/Defaults.pm で変更することができる。 詳しくは
365       MIME/Charset/Defaults.pm.sample を読んでほしい。
366

VERSION

368       $VERSION 変数を見てほしい。
369
370       このモジュールの開発版が <http://hatuka.nezumi.nu/repos/MIME-Charset/>
371       にある。
372
373   非互換な変更
374       1.001
375new() メソッドは CHARSET
376               引数を指定しなくてもオブジェクトを返すようになった。
377
378       1.005
379           •   encoded-word に含まれる文字種を RFC 2047 の 5 (3)
380               節のとおりにした。 encoded_header_len()
381               メソッドの返値も変わる。
382
383       1.008.2
384body_encoding() メソッドも "S" を返せるようになった。
385
386body_encode() メソッドの UTF-8
387               に対する返値のエンコーディング要素は、 これまでのリリースでは
388               "BASE64" に固定だったが、"QUOTED-PRINTABLE" になることがある。
389

SEE ALSO

391       Multipurpose Internet Mail Extensions (MIME).
392

AUTHOR

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.
400
401
402
403perl v5.34.0                      2022-01-21        POD2::JA::MIME::Charset(3)
Impressum