POD2::J...ncWords(3)

📦
version 1.15.0 · 8 versions
, in opensuse-leap 16.0

POD2::J...ncWords(3) — yeah that's genuinely the name of the page, the truncation is part of the aesthetic, we don't question it 💅 this is the Japanese-flavoured manual for MIME::EncWords, and it's part 1 of 2 so don't go anywhere.

✨ NAME ✨

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

(translation bestie: everything to do with RFC 2047 encoded-words — but make it the improved version 😌)

🎀 SYNOPSIS 🎀

Okay so MIME::EncWords is a whole separate implementation of MIME::Words, and the entire goal is to be more conformant to the spec in RFC 2047 (which used to be called RFC 1522, iykyk 🫶). On top of that it's got a bunch of improvements added in.

Everything you're about to read — the synopsis and the descriptions — is lifted from the original MIME::Words, with two extra flavours mixed in:

  • notes about the improvements are marked (**)
  • notes about the changes and the clarifications are marked (*)

Keep an eye out for them, they're like little easter eggs except they're about correctness 🥚✨

Before you go any further, seriously: go look at MIME::Tools first. Like actually. And get clear in your head where, inside the thing you're trying to accomplish, this module fits. Right now. I'm waiting. ⏳

Okay good. Let's go...

   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 🌈

Hey to everyone in the US 👋 you might not have the faintest clue what this module is out here doing. Europe, Russia, all y'all — you're gonna get it immediately. "(:-)".

For real though, check it: this right here is a valid MIME header 🔥

     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!?=

And those fields decode, roughly, into this absolute slay of a header 💖

     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!

(and yes, André and Pirard are separated by two spaces in there — that's not me being sloppy, that's the source, don't come for me 🙈)

Now the addendum, because we're nothing if not inclusive 🫶 US and Europe, you still might not fully clock what this module is up to. East Asia, though? You already know. "(^_^)".

For example, tHis is a valid MIME header too:

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

And those fields decode, roughly, into:

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

okay that's the setup, the vibe check is passed ✅ — the actual function-by-function stuff is still coming, so keep scrolling bestie, part 2 is literally right there 🌸

💅 PUBLIC INTERFACE 💅

✨ decode_mimewords ENCODED, [OPTS...] ✨

Okay so this is a function. It digs through a string looking for RFC 2047-style Q encoding (a kind of quoted-printable) and B encoding (base64), then decodes it.

In array context, it splits the decoded string ENCODED into [DATA, CHARSET] pairs and returns that list. Data that wasn’t encoded comes back as a one-element array [DATA] (CHARSET is effectively undef).

$enc = '=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>';
foreach (decode_mimewords($enc)) {
    print "", ($_[1] || 'US-ASCII'), ": ", $_[0], "\n";
}
Heads up bestie: adjacent encoded-words get concatenated if their character sets are the same. Why? So multibyte sequences can be handled safely. No cap.
Also: if there’s language information defined in RFC2231 section 5, it gets added as a third element.
Tiny detail: whitespace at both ends of data that wasn’t encoded is not removed. That’s for compatibility with MIME::Words.

In scalar context, it concatenates all the DATA elements from the list above and returns that. Note: there is information loss, so you might not get the result you wanted. But if you know every character in ENCODED has the same charset, this can be useful. (Before you use this, go look at unmime in MIME::WordDecoder — that might be exactly what you want.) Also see Charset below.

If a syntax error happens, it sets the error description in $@, but keeps parsing as much as it can (so it can return something from decoding the header). If no error is found, $@ is false.

Broken encoded-word? It returns the thing still encoded, and sets $@ in that case.

Arguments after ENCODED are treated as hash-style option definitions.

Important: when Unicode/multibyte support is not enabled (see USE_ENCODE in MIME::Charset), the following options have no effect at all.
  • Charset — In scalar context, convert DATA elements to the charset with this name. If you pass the special value _UNICODE_, the returned value becomes a Unicode string.

Note: this spec, except when _UNICODE_ is specified, still has information loss.

  • Detect7bit — Try to detect the 7-bit charset of the parts that weren’t encoded. Default is YES.
  • Mapping — In scalar context, specify the mapping actually used for charset names. EXTENDED uses extended mapping. STANDARD uses standardized strict mapping. Default is EXTENDED.

🎀 encode_mimeword RAW, [ENCODING], [CHARSET] 🎀

Function. It encodes a single “word” RAW that has “unsafe” characters. The entire “word” gets encoded.

### Encode "«François»":
$encoded = encode_mimeword("\xABFran\xE7ois\xBB");

You can specify encoding ENCODING (Q or B). Default is Q. Special values also work. S picks whichever is shorter, Q or B.

You can specify charset CHARSET. Default is iso-8859-1.

Note: in Q encoding, whitespace is escaped with _.

🦋 encode_mimewords RAW, [OPTS] 🦋

Function. It tries to find sequences of “unsafe” characters in string RAW and encode them.

### Encode a string with an "unsafe word":
$encoded = encode_mimewords("Me and \xABFran\xE7ois\xBB");

It returns the encoded string.

RAW can be Unicode, but only when Unicode/multibyte support is enabled (see USE_ENCODE in MIME::Charset). Also, RAW can be a reference to whatever decode_mimewords returns in array context. In that case, the Charset option (see below) gets overridden as appropriate (see the note below too).

Note: when RAW is a reference to an array, adjacent encoded-words are concatenated (that is, elements with a non-ASCII charset element), and then split while respecting multibyte character boundaries — but only when Unicode/multibyte support is enabled. Data parts that aren’t encoded need whitespace on both ends. If they don’t have it, they get merged into the adjacent encoded-word.

Arguments after RAW are treated as hash-style options:

  • Charset — “Unsafe” stuff gets encoded in this charset. Default is 'ISO-8859-1' (aka Latin-1).
  • Detect7bit — If the Encoding option (below) is set to a and the Charset option is unknown, try to detect the 7-bit charset of the RAW string. Default is YES. When Unicode/multibyte support is not enabled (see USE_ENCODE in MIME::Charset), this option has no effect.
  • Encoding — The encoding to use. q or b. Special values also work. a auto-selects the recommended encoding (it also does charset conversion when another one is recommended for the charset — see MIME::Charset~[ja]). s picks whichever is shorter, q or b. Note: in release 1.005, the default changed from q (the default in MIME::Words) to a.
  • Field — The name of the mail field where this string is used. Note: when encoding a header, it considers the mail field name length on the first line.
  • Folding — The sequence of characters used to “fold” lines being encoded. Default is "\n". If you specify the empty string "", it just splits an encoded-word that exceeds the line length (see MaxLineLen below) with SPACE.

Note: RFC 5322 (formerly RFC 2822) says lines in internet messages are separated with CRLF ("\r\n"), but this module has defaulted to LF ("\n") for backward compatibility. If you’re using the default, you may need to convert newline characters before sending the encoded header out to a session.

  • Mapping — The mapping actually used for charset names. EXTENDED uses extended mapping. STANDARD uses standardized strict mapping. Default is EXTENDED. When Unicode/multibyte support is not enabled (see USE_ENCODE in MIME::Charset), this option has no effect.
  • MaxLineLen — Maximum line length (not counting the newline). Default is 76. A negative value means unlimited line length (since release 1.012.3).
  • Minimal — Pay attention to natural word separators (basically whitespace) in the text being encoded. If you set it to NO, the module encodes the entire text without considering whitespace (if encoding is needed), and any encoded-word that exceeds line length is simply split by its length. Default is YES, which encodes only the minimal parts. If you set it to DISPNAME, it also encodes parts containing special characters described in the RFC5322 (formerly RFC2822, RFC822) address spec (section 3.4). That’s useful when encoding a display-name in an address field.

Note: in release 0.040, the default changed to YES for compatibility with MIME::Words. In earlier releases, this option was fixed to NO.

Note: DISPNAME was introduced in release 1.012.

  • Replacement — See "エラー処理" in MIME::Charset~[ja] (the error-handling section, iykyk).

🗂️ 設定ファイル (Config File) 🗂️

The built-in default values for the option arguments of decode_mimewords (except the Charset option) and encode_mimewords can be overridden by config files: MIME/Charset/Defaults.pm and MIME/EncWords/Defaults.pm. For details, read MIME/EncWords/Defaults.pm.sample.

🌈 VERSION 🌈

Go look at the $VERSION variable.

The development version of this module lives at <http://hatuka.nezumi.nu/repos/MIME-EncWords/>.

👀 SEE ALSO 👀

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

👑 AUTHORS 👑

The original version of the decode_mimewords() function was inherited from the MIME::Words module, and the authors are:

Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).
David F. Skoll (dfs@roaringpenguin.com)

http://www.roaringpenguin.com

Other parts were rewritten or added by:

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.

Catch you in the group chat 💖 — this one comes from perl v5.42.0, dated 2024-02-13 (the POD2::J...ncWords(3) page).

📦 where this page comes from