Encode::MIME::Header(3pm)

1Encode::MIME::Header(3)User Contributed Perl DocumentatioEnncode::MIME::Header(3)
2
3
4

NAME

6       Encode::MIME::Header -- MIME encoding for an unstructured email header
7

SYNOPSIS

9           use Encode qw(encode decode);
10
11           my $mime_str = encode("MIME-Header", "Sample:Text \N{U+263A}");
12           # $mime_str is "=?UTF-8?B?U2FtcGxlOlRleHQg4pi6?="
13
14           my $mime_q_str = encode("MIME-Q", "Sample:Text \N{U+263A}");
15           # $mime_q_str is "=?UTF-8?Q?Sample=3AText_=E2=98=BA?="
16
17           my $str = decode("MIME-Header",
18               "=?ISO-8859-1?B?SWYgeW91IGNhbiByZWFkIHRoaXMgeW8=?=\r\n " .
19               "=?ISO-8859-2?B?dSB1bmRlcnN0YW5kIHRoZSBleGFtcGxlLg==?="
20           );
21           # $str is "If you can read this you understand the example."
22
23           use Encode qw(decode :fallbacks);
24           use Encode::MIME::Header;
25           local $Encode::MIME::Header::STRICT_DECODE = 1;
26           my $strict_string = decode("MIME-Header", $mime_string, FB_CROAK);
27           # use strict decoding and croak on errors
28

ABSTRACT

30       This module implements RFC 2047 <https://tools.ietf.org/html/rfc2047>
31       MIME encoding for an unstructured field body of the email header.  It
32       can also be used for RFC 822 <https://tools.ietf.org/html/rfc822>
33       'text' token.  However, it cannot be used directly for the whole header
34       with the field name or for the structured header fields like From, To,
35       Cc, Message-Id, etc...  There are 3 encoding names supported by this
36       module: "MIME-Header", "MIME-B" and "MIME-Q".
37

DESCRIPTION

39       Decode method takes an unstructured field body of the email header (or
40       RFC 822 <https://tools.ietf.org/html/rfc822> 'text' token) as its input
41       and decodes each MIME encoded-word from input string to a sequence of
42       bytes according to RFC 2047 <https://tools.ietf.org/html/rfc2047> and
43       RFC 2231 <https://tools.ietf.org/html/rfc2231>.  Subsequently, each
44       sequence of bytes with the corresponding MIME charset is decoded with
45       the Encode module and finally, one output string is returned.  Text
46       parts of the input string which do not contain MIME encoded-word stay
47       unmodified in the output string.  Folded newlines between two
48       consecutive MIME encoded-words are discarded, others are preserved in
49       the output string.  "MIME-B" can decode Base64 variant, "MIME-Q" can
50       decode Quoted-Printable variant and "MIME-Header" can decode both of
51       them.  If Encode module does not support particular MIME charset or
52       chosen variant then an action based on CHECK flags is performed (by
53       default, the MIME encoded-word is not decoded).
54
55       Encode method takes a scalar string as its input and uses strict UTF-8
56       encoder for encoding it to UTF-8 bytes.  Then a sequence of UTF-8 bytes
57       is encoded into MIME encoded-words ("MIME-Header" and "MIME-B" use a
58       Base64 variant while "MIME-Q" uses a Quoted-Printable variant) where
59       each MIME encoded-word is limited to 75 characters.  MIME encoded-words
60       are separated by "CRLF SPACE" and joined to one output string.  Output
61       string is suitable for unstructured field body of the email header.
62
63       Both encode and decode methods propagate CHECK flags when encoding and
64       decoding the MIME charset.
65

BUGS

67       Versions prior to 2.22 (part of Encode 2.83) have a malfunctioning
68       decoder and encoder.  The MIME encoder infamously inserted additional
69       spaces or discarded white spaces between consecutive MIME encoded-
70       words, which led to invalid MIME headers produced by this module.  The
71       MIME decoder had a tendency to discard white spaces, incorrectly
72       interpret data or attempt to decode Base64 MIME encoded-words as
73       Quoted-Printable.  These problems were fixed in version 2.22.  It is
74       highly recommended not to use any version prior 2.22!
75
76       Versions prior to 2.24 (part of Encode 2.87) ignored CHECK flags.  The
77       MIME encoder used not strict utf8 encoder for input Unicode strings
78       which could lead to invalid UTF-8 sequences.  MIME decoder used also
79       not strict utf8 decoder and additionally called the decode method with
80       a "Encode::FB_PERLQQ" flag (thus user-specified CHECK flags were
81       ignored).  Moreover, it automatically croaked when a MIME encoded-word
82       contained unknown encoding.  Since version 2.24, this module uses
83       strict UTF-8 encoder and decoder.  And CHECK flags are correctly
84       propagated.
85
86       Since version 2.22 (part of Encode 2.83), the MIME encoder should be
87       fully compliant to RFC 2047 <https://tools.ietf.org/html/rfc2047> and
88       RFC 2231 <https://tools.ietf.org/html/rfc2231>.  Due to the
89       aforementioned bugs in previous versions of the MIME encoder, there is
90       a less strict compatible mode for the MIME decoder which is used by
91       default.  It should be able to decode MIME encoded-words encoded by pre
92       2.22 versions of this module.  However, note that this is not correct
93       according to RFC 2047 <https://tools.ietf.org/html/rfc2047>.
94
95       In default not strict mode the MIME decoder attempts to decode every
96       substring which looks like a MIME encoded-word.  Therefore, the MIME
97       encoded-words do not need to be separated by white space.  To enforce a
98       correct strict mode, set variable $Encode::MIME::Header::STRICT_DECODE
99       to 1 e.g. by localizing:
100
101         use Encode::MIME::Header;
102         local $Encode::MIME::Header::STRICT_DECODE = 1;
103

AUTHORS

105       Pali <pali@cpan.org>
106

NAME

SYNOPSIS

ABSTRACT

DESCRIPTION

BUGS

AUTHORS

SEE ALSO