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 参照) は、 以下のオプションはなんの効果も持たない。

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 に引き続く引数は、ハッシュによるオプションの定義とみなす:

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.