Debian Codegraph @

upstream/mageia-cauldron/man3pm/Encode::MIME::Header.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Encode::MIME::Header 3pm"
61 .TH Encode::MIME::Header 3pm 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Encode::MIME::Header \-\- MIME encoding for an unstructured email header
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use Encode qw(encode decode);
72 \&
73 \& my $mime_str = encode("MIME\-Header", "Sample:Text \eN{U+263A}");
74 \& # $mime_str is "=?UTF\-8?B?U2FtcGxlOlRleHQg4pi6?="
75 \&
76 \& my $mime_q_str = encode("MIME\-Q", "Sample:Text \eN{U+263A}");
77 \& # $mime_q_str is "=?UTF\-8?Q?Sample=3AText_=E2=98=BA?="
78 \&
79 \& my $str = decode("MIME\-Header",
80 \& "=?ISO\-8859\-1?B?SWYgeW91IGNhbiByZWFkIHRoaXMgeW8=?=\er\en " .
81 \& "=?ISO\-8859\-2?B?dSB1bmRlcnN0YW5kIHRoZSBleGFtcGxlLg==?="
82 \& );
83 \& # $str is "If you can read this you understand the example."
84 \&
85 \& use Encode qw(decode :fallbacks);
86 \& use Encode::MIME::Header;
87 \& local $Encode::MIME::Header::STRICT_DECODE = 1;
88 \& my $strict_string = decode("MIME\-Header", $mime_string, FB_CROAK);
89 \& # use strict decoding and croak on errors
90 .Ve
91 .SH ABSTRACT
92 .IX Header "ABSTRACT"
93 This module implements RFC 2047 <https://tools.ietf.org/html/rfc2047> MIME
94 encoding for an unstructured field body of the email header. It can also be
95 used for RFC 822 <https://tools.ietf.org/html/rfc822> \*(Aqtext\*(Aq token. However,
96 it cannot be used directly for the whole header with the field name or for the
97 structured header fields like From, To, Cc, Message\-Id, etc... There are 3
98 encoding names supported by this module: \f(CW\*(C`MIME\-Header\*(C'\fR, \f(CW\*(C`MIME\-B\*(C'\fR and
99 \&\f(CW\*(C`MIME\-Q\*(C'\fR.
100 .SH DESCRIPTION
101 .IX Header "DESCRIPTION"
102 Decode method takes an unstructured field body of the email header (or
103 RFC 822 <https://tools.ietf.org/html/rfc822> \*(Aqtext\*(Aq token) as its input and
104 decodes each MIME encoded\-word from input string to a sequence of bytes
105 according to RFC 2047 <https://tools.ietf.org/html/rfc2047> and
106 RFC 2231 <https://tools.ietf.org/html/rfc2231>. Subsequently, each sequence
107 of bytes with the corresponding MIME charset is decoded with
108 the Encode module and finally, one output string is returned. Text
109 parts of the input string which do not contain MIME encoded\-word stay
110 unmodified in the output string. Folded newlines between two consecutive MIME
111 encoded\-words are discarded, others are preserved in the output string.
112 \&\f(CW\*(C`MIME\-B\*(C'\fR can decode Base64 variant, \f(CW\*(C`MIME\-Q\*(C'\fR can decode Quoted\-Printable
113 variant and \f(CW\*(C`MIME\-Header\*(C'\fR can decode both of them. If Encode module
114 does not support particular MIME charset or chosen variant then an action based
115 on CHECK flags is performed (by default, the
116 MIME encoded\-word is not decoded).
117 .PP
118 Encode method takes a scalar string as its input and uses
119 strict UTF\-8 encoder for encoding it to UTF\-8
120 bytes. Then a sequence of UTF\-8 bytes is encoded into MIME encoded\-words
121 (\f(CW\*(C`MIME\-Header\*(C'\fR and \f(CW\*(C`MIME\-B\*(C'\fR use a Base64 variant while \f(CW\*(C`MIME\-Q\*(C'\fR uses a
122 Quoted\-Printable variant) where each MIME encoded\-word is limited to 75
123 characters. MIME encoded\-words are separated by \f(CW\*(C`CRLF SPACE\*(C'\fR and joined to
124 one output string. Output string is suitable for unstructured field body of
125 the email header.
126 .PP
127 Both encode and decode methods propagate
128 CHECK flags when encoding and decoding the
129 MIME charset.
130 .SH BUGS
131 .IX Header "BUGS"
132 Versions prior to 2.22 (part of Encode 2.83) have a malfunctioning decoder
133 and encoder. The MIME encoder infamously inserted additional spaces or
134 discarded white spaces between consecutive MIME encoded\-words, which led to
135 invalid MIME headers produced by this module. The MIME decoder had a tendency
136 to discard white spaces, incorrectly interpret data or attempt to decode Base64
137 MIME encoded\-words as Quoted\-Printable. These problems were fixed in version
138 2.22. It is highly recommended not to use any version prior 2.22!
139 .PP
140 Versions prior to 2.24 (part of Encode 2.87) ignored
141 CHECK flags. The MIME encoder used
142 not strict utf8 encoder for input Unicode
143 strings which could lead to invalid UTF\-8 sequences. MIME decoder used also
144 not strict utf8 decoder and additionally
145 called the decode method with a \f(CW\*(C`Encode::FB_PERLQQ\*(C'\fR flag (thus user\-specified
146 CHECK flags were ignored). Moreover, it
147 automatically croaked when a MIME encoded\-word contained unknown encoding.
148 Since version 2.24, this module uses
149 strict UTF\-8 encoder and decoder. And
150 CHECK flags are correctly propagated.
151 .PP
152 Since version 2.22 (part of Encode 2.83), the MIME encoder should be fully
153 compliant to RFC 2047 <https://tools.ietf.org/html/rfc2047> and
154 RFC 2231 <https://tools.ietf.org/html/rfc2231>. Due to the aforementioned
155 bugs in previous versions of the MIME encoder, there is a \fIless strict\fR
156 compatible mode for the MIME decoder which is used by default. It should be
157 able to decode MIME encoded\-words encoded by pre 2.22 versions of this module.
158 However, note that this is not correct according to
159 RFC 2047 <https://tools.ietf.org/html/rfc2047>.
160 .PP
161 In default \fInot strict\fR mode the MIME decoder attempts to decode every substring
162 which looks like a MIME encoded\-word. Therefore, the MIME encoded\-words do not
163 need to be separated by white space. To enforce a correct \fIstrict\fR mode, set
164 variable \f(CW$Encode::MIME::Header::STRICT_DECODE\fR to 1 e.g. by localizing:
165 .PP
166 .Vb 2
167 \& use Encode::MIME::Header;
168 \& local $Encode::MIME::Header::STRICT_DECODE = 1;
169 .Ve
170 .SH AUTHORS
171 .IX Header "AUTHORS"
172 Pali <[email protected]>
173 .SH "SEE ALSO"
174 .IX Header "SEE ALSO"
175 Encode,
176 RFC 822 <https://tools.ietf.org/html/rfc822>,
177 RFC 2047 <https://tools.ietf.org/html/rfc2047>,
178 RFC 2231 <https://tools.ietf.org/html/rfc2231>