1POD2::JA::MIME::EncWordUss(e3r)Contributed Perl DocumentPaOtDi2o:n:JA::MIME::EncWords(3)
2
6 MIME::EncWords~[ja] - RFC 2047 encoded-word 関連 (改良版)
7
9 MIME::EncWords は、RFC 2047 (旧 RFC 1522)
10 の仕様により適合することをめざした MIME::Words の別実装です。
11 加えて、いくらかの改良がなされています。 以下の梗概と説明は、もとの
12 MIME::Words から採ったものに、 改良点の説明 (**)
13 および変更点の説明と明確化 (*) を加えたものです。
14 読み進める前に、MIME::Tools を見るべきだ。そうして、
16 あなたの成し遂げようとしていることのどこでこのモジュールを使うのかを、
17 理解してほしい。 いますぐ。待ってるから。
18 いいかな。はじめるよ...
20 use MIME::EncWords qw(:all);
22 ### 文字列を、キャラクタセットは無視してデコードした文字列にする:
24 $decoded = decode_mimewords(
25 'To: =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>',
26 );
27 ### 文字列を、デコードされた [DATA,CHARSET] の対の配列にする:
29 @decoded = decode_mimewords(
30 'To: =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>',
31 );
32 ### 単一の「安全でない語」をエンコードする:
34 $encoded = encode_mimeword("\xABFran\xE7ois\xBB");
35 ### 文字列を、「安全でない語」を探しながらエンコードする:
37 $encoded = encode_mimewords("Me and \xABFran\xE7ois\xBB in town");
38
40 合衆国の諸君。このモジュールでいったい何をやらかそうというのか、
41 わからないかもしれないね。欧州、ロシア等の諸君なら、わかるだろう。"(:-)"。
42 たとえば、これは有効な MIME ヘッダだ:
44 From: =?US-ASCII?Q?Keith_Moore?= <moore@cs.utk.edu>
46 To: =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>
47 CC: =?ISO-8859-1?Q?Andr=E9_?= Pirard <PIRARD@vm1.ulg.ac.be>
48 Subject: =?ISO-8859-1?B?SWYgeW91IGNhbiByZWFkIHRoaXMgeW8=?=
49 =?ISO-8859-2?B?dSB1bmRlcnN0YW5kIHRoZSBleGFtcGxlLg==?=
50 =?US-ASCII?Q?.._cool!?=
51 これらのフィールドは、だいたいつぎのようにデコードできる:
53 From: Keith Moore <moore@cs.utk.edu>
55 To: Keld Jørn Simonsen <keld@dkuug.dk>
56 CC: André Pirard <PIRARD@vm1.ulg.ac.be>
57 Subject: If you can read this you understand the example... cool!
58 追補: 合衆国、欧州の諸君。
60 このモジュールでいったいなにをやらかそうというのか、
61 わからないかもしれないね。東アジア等の諸君なら、わかるだろう。 "(^_^)".
62 たとえば、これは有効な MIME ヘッダだ:
64 Subject: =?EUC-KR?B?sNTAuLinKGxhemluZXNzKSwgwvzB9ri7seIoaW1w?=
66 =?EUC-KR?B?YXRpZW5jZSksILGzuLgoaHVicmlzKQ==?=
67 これらのフィールドは、だいたいつぎのようにデコードできる:
69 Subject: 게으름(laziness), 참지말기(impatience), 교만(hubris)
71
73 decode_mimewords ENCODED, [OPTS...]
74 関数。 文字列から RFC 2047 スタイルの "Q" エンコーディング (quoted-
75 printable の一種) や "B" エンコーディング (base64)
76 を探し、それをデコードする。
77 配列コンテクストでは、文字列 ENCODED をデコードした "[DATA,
79 CHARSET]" の対に分割し、そのリストを返す。
80 エンコードされていなかったデータは 1 要素の配列 "[DATA]" で返す
81 (CHARSET は実質的に "undef")。
82 $enc = '=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>';
84 foreach (decode_mimewords($enc)) {
85 print "", ($_[1] || 'US-ASCII'), ": ", $_[0], "\n";
86 }
87 **
89 ただし、隣り合う「encoded-word」を、キャラクタセットがおなじなら連結する。
90 これは、マルチバイト列を安全に扱えるようにするためである。
91 ** RFC2231 第 5 節で定義している言語情報があれば、第 3
93 の要素として追加する。
94 * エンコードされていなかったデータの両端の空白文字は取り去らない。
96 これは、MIME::Words との互換性を保つためである。
97 スカラコンテクストでは、上記のリストの DATA 要素をすべて連結し、
99 それを返す。注意: 情報の損失があるので、
100 望んだ結果が得られないかもしれない。 だが、文字列 ENCODED
101 のすべての文字のキャラクタセットが同一だとわかっているのなら、
102 これは役に立つこともある。 (これを使う前に、"unmime" in
103 MIME::WordDecoder を見てほしい。 これが望みのものかもしれない。) **
104 下記の "Charset" も参照。
105 構文エラーが発生すると、$@ にエラーの説明をセットするが、
107 解析はできるかぎり (ヘッダのデコードで得られたなにかを返すために)
108 続行する。 エラーが見つからなければ、$@ は偽となる。
109 *
111 「encoded-word」が壊れているときは、エンコードしたままのものを返す。
112 この場合、$@ をセットする。
113 ENCODED に引き続く引数は、ハッシュによるオプションの定義とみなす。
115 ** Unicode/マルチバイト文字対応が有効になっていないとき
116 ("USE_ENCODE" in MIME::Charset 参照) は、
117 以下のオプションはなんの効果も持たない。
118 Charset **
120 スカラコンテクストで、DATA
121 要素をこの名前のキャラクタセットで変換する。
122 このオプションに特殊値 "_UNICODE_" を指定すると、 返す値は
123 Unicode 文字列となる。
124 Note: この仕様は、"_UNICODE_" を指定したとき以外は、
126 やはり情報の損失がある。
127 Detect7bit **
129 エンコードされていなかった部分の 7
130 ビットキャラクタセットを判別しようとする。 初期値は "YES"。
131 Mapping **
133 スカラコンテクストで、
134 キャラクタセットの名前に対して実際に使うマッピングを指定する。
135 "EXTENDED" は拡張マッピングを使う。 "STANDARD"
136 は標準化されている厳密なマッピングを使う。 初期値は
137 "EXTENDED"。
138 encode_mimeword RAW, [ENCODING], [CHARSET]
140 関数。 「安全でない」文字のある単一の「語」RAW をエンコードする。
141 「語」全体がエンコードされる。
142 ### "«François»" をエンコードする:
144 $encoded = encode_mimeword("\xABFran\xE7ois\xBB");
145 エンコーディング ENCODING を指定できる ("Q" または "B")。 初期値は
147 "Q"。 ** さらに、「特殊」な値も指定できる。 "S" は "Q" と "B"
148 のうち短くなるほうを選ぶ。
149 キャラクタセット CHARSET を指定できる。初期値は "iso-8859-1"。
151 * "Q" エンコーディングでは、空白を ``_'' でエスケープする。
153 encode_mimewords RAW, [OPTS]
155 関数。 文字列 RAW
156 から、「安全でない」文字の列を見つけてエンコードしようとする。
157 ### 「安全でない語」のある文字列をエンコードする:
159 $encoded = encode_mimewords("Me and \xABFran\xE7ois\xBB");
160 エンコードした文字列を返す。
162 ** RAW は Unicode でもよい。ただし
164 Unicode/マルチバイト対応が有効な場合 ("USE_ENCODE" in MIME::Charset
165 参照)。 さらに RAW は、"decode_mimewords"
166 が配列コンテクストで返すものへの参照でもよい。
167 後の場合は、"Charset" オプション (下記参照) が適宜上書きされる
168 (下の注も参照)。
169 Note: * RAW が配列への参照であるときは、 隣り合う「encoded-word」
171 (つまり、ASCII 以外のキャラクタセット要素のある要素)
172 を連結する。その上で、マルチバイト文字の文字境界を考慮しながら
173 (ただしこれは Unicode/マルチバイト対応が有効なときだけ)、分割する。
174 エンコードしないデータ部分は両端に空白文字が必要。
175 そうしなければ隣り合う「encoded-word」に併合されてしまう。
176 RAW に引き続く引数は、ハッシュによるオプションの定義とみなす:
178 Charset
180 「安全でない」ものはこのキャラクタセットでエンコードする。
181 初期値は 'ISO-8859-1' (別名 "Latin-1")。
182 Detect7bit **
184 "Encoding" オプション (下記参照) が "a" に指定してあって
185 "Charset" オプションが不明なら、 RAW 文字列の 7
186 ビットキャラクタセットを判別しようとする。 初期値は "YES"。
187 Unicode/マルチバイト文字対応が有効になっていないとき
188 ("USE_ENCODE" in MIME::Charset 参照) は、
189 このオプションはなんの効果も持たない。
190 Encoding
192 使用するエンコーディング。"q" または "b"。 **
193 「特殊」な値も指定できる。"a"
194 は推奨されるエンコーディングを自動選択する
195 (キャラクタセットに別のものが推奨されるときはキャラクタセット変換も行う。
196 MIME::Charset~[ja] 参照)。 "s" は "q" と "b"
197 のうち短くなるほうを選ぶ。 Note: * リリース 1.005 で、初期値が
198 "q" (MIME::Words での初期値) から "a" に変わった。
199 Field
201 この文字列を使うメールフィールドの名前。 **
202 ヘッダをエンコードする際には、最初の行でメールフィールド名の長さを考慮する。
203 Folding **
205 エンコードする行を「行折り」する文字の列。初期値は "\n"。
206 空文字列 "" を指定すると、行長 (下記 "MaxLineLen" 参照)
207 を超える「encoded-word」を SPACE で分割するだけ。
208 Note: * RFC 5322 (旧 RFC 2822)
210 には、インターネットのメッセージでは行を CRLF ("\r\n")
211 で区切ると明記してあるが、
212 このモジュールでは後方互換性を保つために LF ("\n")
213 を初期値としてきた。 初期値を使っている場合、
214 エンコードしたヘッダをセッションへと放つ前に、
215 改行文字の変換が必要になることもある。
216 Mapping **
218 キャラクタセットの名前に対して実際に使うマッピングを指定する。
219 "EXTENDED" は拡張マッピングを使う。 "STANDARD"
220 は標準化されている厳密なマッピングを使う。 初期値は
221 "EXTENDED"。
222 Unicode/マルチバイト文字対応が有効になっていないとき
223 ("USE_ENCODE" in MIME::Charset 参照) は、
224 このオプションはなんの効果も持たない。
225 MaxLineLen **
227 行の最大長 (改行を除く)。 初期値は 76。
228 負の値は行長無制限を意味する (リリース 1.012.3 以降)。
229 Minimal **
231 エンコードするテキストの中の自然な語分離子 (要するに空白文字)
232 に注意を払う。 "NO" を指定すると、
233 このモジュールは空白文字を考慮せずにテキスト全体をエンコード
234 (エンコードが必要なら)
235 し、行長を超える「encoded-word」は単にその長さによって分割される。
236 初期値は "YES" で、最小限の部分だけエンコードする。 "DISPNAME"
237 を指定すると、RFC5322 (旧 RFC2822、RFC822) のアドレス仕様
238 (3.4節) で述べている特殊文字を含む部分もエンコードする。
239 これはアドレスフィールド中の display-name
240 をエンコードする際に有用である。
241 Note: リリース 0.040 で、初期値が "YES" に変わった。
243 MIME::Words との互換性を保つためである。
244 それ以前のリリースでは、このオプションは "NO" 固定であった。
245 Note: "DISPNAME" はリリース 1.012 で導入された。
247 Replacement **
249 "エラー処理" in MIME::Charset~[ja] 参照。
250 設定ファイル **
252 "decode_mimewords" ('Charset' オプションを除く) および
253 "encode_mimewords" のオプション引数の組み込み初期値は、
254 設定ファイルで上書きできる。 MIME/Charset/Defaults.pm と
255 MIME/EncWords/Defaults.pm。 詳細は MIME/EncWords/Defaults.pm.sample
256 を読んでほしい。
257
259 $VERSION 変数を参照してほしい。
260 このモジュールの開発版が <http://hatuka.nezumi.nu/repos/MIME-EncWords/>
262 にある。
263
265 MIME::Charset~[ja], MIME::Tools
266
268 decode_mimewords() 関数の元の版は MIME::Words
269 モジュールから引き継いだもので、著者は以下のとおり:
270 Eryq (eryq@zeegee.com), ZeeGee Software Inc
271 (http://www.zeegee.com).
272 David F. Skoll (dfs@roaringpenguin.com)
273 http://www.roaringpenguin.com
274 そのほかの部分は、次の者が書き直しあるいは加えた:
276 Hatuka*nezumi - IKEDA Soji <hatuka(at)nezumi.nu>.
277 This program is free software; you can redistribute it and/or modify it
279 under the same terms as Perl itself.
280perl v5.38.0 2023-07-20 POD2::JA::MIME::EncWords(3)