/ 
MIME-EncWords-1.014.2
River stage one • 3 direct dependents • 3 total dependents
/ lib/POD2/JA/MIME/EncWords.pod

NAME

MIME::EncWords~[ja] - RFC 2047 encoded-word 関連 (改良版)

SYNOPSIS

MIME::EncWords は、RFC 2047 (旧 RFC 1522) の仕様により適合することをめざした MIME::Words の別実装です。 加えて、いくらかの改良がなされています。 以下の梗概と説明は、もとの MIME::Words から採ったものに、 改良点の説明 (**) および変更点の説明と明確化 (*) を加えたものです。

読み進める前に、MIME::Tools を見るべきだ。そうして、 あなたの成し遂げようとしていることのどこでこのモジュールを使うのかを、 理解してほしい。 いますぐ。待ってるから。

いいかな。はじめるよ...

use MIME::EncWords qw(:all);

### 文字列を、キャラクタセットは無視してデコードした文字列にする:
$decoded = decode_mimewords(
      'To: =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>',
      );

### 文字列を、デコードされた [DATA,CHARSET] の対の配列にする:
@decoded = decode_mimewords(
      'To: =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>',
      );

### 単一の「安全でない語」をエンコードする:
$encoded = encode_mimeword("\xABFran\xE7ois\xBB");

### 文字列を、「安全でない語」を探しながらエンコードする:
$encoded = encode_mimewords("Me and \xABFran\xE7ois\xBB in town");

DESCRIPTION

合衆国の諸君。このモジュールでいったい何をやらかそうというのか、 わからないかもしれないね。欧州、ロシア等の諸君なら、わかるだろう。(:-)。

たとえば、これは有効な MIME ヘッダだ:

From: =?US-ASCII?Q?Keith_Moore?= <moore@cs.utk.edu>
To: =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>
CC: =?ISO-8859-1?Q?Andr=E9_?= Pirard <PIRARD@vm1.ulg.ac.be>
Subject: =?ISO-8859-1?B?SWYgeW91IGNhbiByZWFkIHRoaXMgeW8=?=
 =?ISO-8859-2?B?dSB1bmRlcnN0YW5kIHRoZSBleGFtcGxlLg==?=
 =?US-ASCII?Q?.._cool!?=

これらのフィールドは、だいたいつぎのようにデコードできる:

From: Keith Moore <moore@cs.utk.edu>
To: Keld Jørn Simonsen <keld@dkuug.dk>
CC: André  Pirard <PIRARD@vm1.ulg.ac.be>
Subject: If you can read this you understand the example... cool!

追補: 合衆国、欧州の諸君。 このモジュールでいったいなにをやらかそうというのか、 わからないかもしれないね。東アジア等の諸君なら、わかるだろう。 (^_^).

たとえば、これは有効な MIME ヘッダだ:

Subject: =?EUC-KR?B?sNTAuLinKGxhemluZXNzKSwgwvzB9ri7seIoaW1w?=
 =?EUC-KR?B?YXRpZW5jZSksILGzuLgoaHVicmlzKQ==?=

これらのフィールドは、だいたいつぎのようにデコードできる:

Subject: 게으름(laziness), 참지말기(impatience), 교만(hubris)

PUBLIC INTERFACE

decode_mimewords ENCODED, [OPTS...]

関数。 文字列から RFC 2047 スタイルの "Q" エンコーディング (quoted-printable の一種) や "B" エンコーディング (base64) を探し、それをデコードする。

配列コンテクストでは、文字列 ENCODED をデコードした [DATA, CHARSET] の対に分割し、そのリストを返す。 エンコードされていなかったデータは 1 要素の配列 [DATA] で返す (CHARSET は実質的に undef)。

$enc = '=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>';
foreach (decode_mimewords($enc)) {
    print "", ($_[1] || 'US-ASCII'), ": ", $_[0], "\n";
}

** ただし、隣り合う「encoded-word」を、キャラクタセットがおなじなら連結する。 これは、マルチバイト列を安全に扱えるようにするためである。

** RFC2231 第 5 節で定義している言語情報があれば、第 3 の要素として追加する。

* エンコードされていなかったデータの両端の空白文字は取り去らない。 これは、MIME::Words との互換性を保つためである。

スカラコンテクストでは、上記のリストの DATA 要素をすべて連結し、 それを返す。注意: 情報の損失があるので、 望んだ結果が得られないかもしれない。 だが、文字列 ENCODED のすべての文字のキャラクタセットが同一だとわかっているのなら、 これは役に立つこともある。 (これを使う前に、"unmime" in MIME::WordDecoder を見てほしい。 これが望みのものかもしれない。) ** 下記の "Charset" も参照。

構文エラーが発生すると、$@ にエラーの説明をセットするが、 解析はできるかぎり (ヘッダのデコードで得られたなにかを返すために) 続行する。 エラーが見つからなければ、$@ は偽となる。

* 「encoded-word」が壊れているときは、エンコードしたままのものを返す。 この場合、$@ をセットする。

ENCODED に引き続く引数は、ハッシュによるオプションの定義とみなす。 ** Unicode/マルチバイト文字対応が有効になっていないとき ("USE_ENCODE" in MIME::Charset 参照) は、 以下のオプションはなんの効果も持たない。

Charset **

スカラコンテクストで、DATA 要素をこの名前のキャラクタセットで変換する。 このオプションに特殊値 "_UNICODE_" を指定すると、 返す値は Unicode 文字列となる。

Note: この仕様は、"_UNICODE_" を指定したとき以外は、 やはり情報の損失がある。

Detect7bit **

エンコードされていなかった部分の 7 ビットキャラクタセットを判別しようとする。 初期値は "YES"。

Mapping **

スカラコンテクストで、 キャラクタセットの名前に対して実際に使うマッピングを指定する。 "EXTENDED" は拡張マッピングを使う。 "STANDARD" は標準化されている厳密なマッピングを使う。 初期値は "EXTENDED"。

encode_mimeword RAW, [ENCODING], [CHARSET]

関数。 「安全でない」文字のある単一の「語」RAW をエンコードする。 「語」全体がエンコードされる。

### "«François»" をエンコードする:
$encoded = encode_mimeword("\xABFran\xE7ois\xBB");

エンコーディング ENCODING を指定できる ("Q" または "B")。 初期値は "Q"。 ** さらに、「特殊」な値も指定できる。 "S" は "Q" と "B" のうち短くなるほうを選ぶ。

キャラクタセット CHARSET を指定できる。初期値は iso-8859-1。

* "Q" エンコーディングでは、空白を ``_'' でエスケープする。

encode_mimewords RAW, [OPTS]

関数。 文字列 RAW から、「安全でない」文字の列を見つけてエンコードしようとする。

### 「安全でない語」のある文字列をエンコードする:
$encoded = encode_mimewords("Me and \xABFran\xE7ois\xBB");

エンコードした文字列を返す。

** RAW は Unicode でもよい。ただし Unicode/マルチバイト対応が有効な場合 ("USE_ENCODE" in MIME::Charset 参照)。 さらに RAW は、"decode_mimewords" が配列コンテクストで返すものへの参照でもよい。 後の場合は、"Charset" オプション (下記参照) が適宜上書きされる (下の注も参照)。

Note: * RAW が配列への参照であるときは、 隣り合う「encoded-word」 (つまり、ASCII 以外のキャラクタセット要素のある要素) を連結する。その上で、マルチバイト文字の文字境界を考慮しながら (ただしこれは Unicode/マルチバイト対応が有効なときだけ)、分割する。 エンコードしないデータ部分は両端に空白文字が必要。 そうしなければ隣り合う「encoded-word」に併合されてしまう。

RAW に引き続く引数は、ハッシュによるオプションの定義とみなす:

Charset

「安全でない」ものはこのキャラクタセットでエンコードする。 初期値は 'ISO-8859-1' (別名 "Latin-1")。

Detect7bit **

"Encoding" オプション (下記参照) が "a" に指定してあって "Charset" オプションが不明なら、 RAW 文字列の 7 ビットキャラクタセットを判別しようとする。 初期値は "YES"。 Unicode/マルチバイト文字対応が有効になっていないとき ("USE_ENCODE" in MIME::Charset 参照) は、 このオプションはなんの効果も持たない。

Encoding

使用するエンコーディング。"q" または "b"。 ** 「特殊」な値も指定できる。"a" は推奨されるエンコーディングを自動選択する (キャラクタセットに別のものが推奨されるときはキャラクタセット変換も行う。 MIME::Charset~[ja] 参照)。 "s" は "q" と "b" のうち短くなるほうを選ぶ。 Note: * リリース 1.005 で、初期値が "q" (MIME::Words での初期値) から "a" に変わった。

Field

この文字列を使うメールフィールドの名前。 ** ヘッダをエンコードする際には、最初の行でメールフィールド名の長さを考慮する。

Folding **

エンコードする行を「行折り」する文字の列。初期値は "\n"。 空文字列 "" を指定すると、行長 (下記 "MaxLineLen" 参照) を超える「encoded-word」を SPACE で分割するだけ。

Note: * RFC 5322 (旧 RFC 2822) には、インターネットのメッセージでは行を CRLF ("\r\n") で区切ると明記してあるが、 このモジュールでは後方互換性を保つために LF ("\n") を初期値としてきた。 初期値を使っている場合、 エンコードしたヘッダをセッションへと放つ前に、 改行文字の変換が必要になることもある。

Mapping **

キャラクタセットの名前に対して実際に使うマッピングを指定する。 "EXTENDED" は拡張マッピングを使う。 "STANDARD" は標準化されている厳密なマッピングを使う。 初期値は "EXTENDED"。 Unicode/マルチバイト文字対応が有効になっていないとき ("USE_ENCODE" in MIME::Charset 参照) は、 このオプションはなんの効果も持たない。

MaxLineLen **

行の最大長 (改行を除く)。 初期値は 76。 負の値は行長無制限を意味する (リリース 1.012.3 以降)。

Minimal **

エンコードするテキストの中の自然な語分離子 (要するに空白文字) に注意を払う。 "NO" を指定すると、 このモジュールは空白文字を考慮せずにテキスト全体をエンコード (エンコードが必要なら) し、行長を超える「encoded-word」は単にその長さによって分割される。 初期値は "YES" で、最小限の部分だけエンコードする。 "DISPNAME" を指定すると、RFC5322 (旧 RFC2822、RFC822) のアドレス仕様 (3.4節) で述べている特殊文字を含む部分もエンコードする。 これはアドレスフィールド中の display-name をエンコードする際に有用である。

Note: リリース 0.040 で、初期値が "YES" に変わった。 MIME::Words との互換性を保つためである。 それ以前のリリースでは、このオプションは "NO" 固定であった。

Note: "DISPNAME" はリリース 1.012 で導入された。

Replacement **

"エラー処理" in MIME::Charset~[ja] 参照。

設定ファイル **

"decode_mimewords" ('Charset' オプションを除く) および "encode_mimewords" のオプション引数の組み込み初期値は、 設定ファイルで上書きできる。 MIME/Charset/Defaults.pm と MIME/EncWords/Defaults.pm。 詳細は MIME/EncWords/Defaults.pm.sample を読んでほしい。

VERSION

$VERSION 変数を参照してほしい。

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

SEE ALSO

MIME::Charset~[ja], MIME::Tools

AUTHORS

decode_mimewords() 関数の元の版は MIME::Words モジュールから引き継いだもので、著者は以下のとおり: Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com). David F. Skoll (dfs@roaringpenguin.com) http://www.roaringpenguin.com

そのほかの部分は、次の者が書き直しあるいは加えた: Hatuka*nezumi - IKEDA Soji <hatuka(at)nezumi.nu>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.