Debian Codegraph @

upstream/debian-unstable/man3/MIME::QuotedPrint.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (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 .\"
57 .IX Title "MIME::QuotedPrint 3perl"
58 .TH MIME::QuotedPrint 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 MIME::QuotedPrint \- Encoding and decoding of quoted\-printable strings
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use MIME::QuotedPrint;
69 \&
70 \& $encoded = encode_qp($decoded);
71 \& $decoded = decode_qp($encoded);
72 .Ve
73 .SH DESCRIPTION
74 .IX Header "DESCRIPTION"
75 This module provides functions to encode and decode strings into and from the
76 quoted-printable encoding specified in RFC 2045 \- \fIMIME (Multipurpose
77 Internet Mail Extensions)\fR. The quoted-printable encoding is intended
78 to represent data that largely consists of bytes that correspond to
79 printable characters in the ASCII character set. Each non-printable
80 character (as defined by English Americans) is represented by a
81 triplet consisting of the character "=" followed by two hexadecimal
82 digits.
83 .PP
84 The following functions are provided:
85 .ie n .IP "encode_qp( $str)" 4
86 .el .IP "encode_qp( \f(CW$str\fR)" 4
87 .IX Item "encode_qp( $str)"
88 .PD 0
89 .ie n .IP "encode_qp( $str, $eol)" 4
90 .el .IP "encode_qp( \f(CW$str\fR, \f(CW$eol\fR)" 4
91 .IX Item "encode_qp( $str, $eol)"
92 .ie n .IP "encode_qp( $str, $eol, $binmode )" 4
93 .el .IP "encode_qp( \f(CW$str\fR, \f(CW$eol\fR, \f(CW$binmode\fR )" 4
94 .IX Item "encode_qp( $str, $eol, $binmode )"
95 .PD
96 This function returns an encoded version of the string ($str) given as
97 argument.
98 .Sp
99 The second argument ($eol) is the line-ending sequence to use. It is
100 optional and defaults to "\en". Every occurrence of "\en" is replaced
101 with this string, and it is also used for additional "soft line
102 breaks" to ensure that no line end up longer than 76 characters. Pass
103 it as "\e015\e012" to produce data suitable for external consumption.
104 The string "\er\en" produces the same result on many platforms, but not
105 all.
106 .Sp
107 The third argument ($binmode) will select binary mode if passed as a
108 TRUE value. In binary mode "\en" will be encoded in the same way as
109 any other non-printable character. This ensures that a decoder will
110 end up with exactly the same string whatever line ending sequence it
111 uses. In general it is preferable to use the base64 encoding for
112 binary data; see MIME::Base64.
113 .Sp
114 An \f(CW$eol\fR of "" (the empty string) is special. In this case, no "soft
115 line breaks" are introduced and binary mode is effectively enabled so
116 that any "\en" in the original data is encoded as well.
117 .ie n .IP "decode_qp( $str )" 4
118 .el .IP "decode_qp( \f(CW$str\fR )" 4
119 .IX Item "decode_qp( $str )"
120 This function returns the plain text version of the string given
121 as argument. The lines of the result are "\en" terminated, even if
122 the \f(CW$str\fR argument contains "\er\en" terminated lines.
123 .PP
124 If you prefer not to import these routines into your namespace, you can
125 call them as:
126 .PP
127 .Vb 3
128 \& use MIME::QuotedPrint ();
129 \& $encoded = MIME::QuotedPrint::encode($decoded);
130 \& $decoded = MIME::QuotedPrint::decode($encoded);
131 .Ve
132 .PP
133 Perl v5.8 and better allow extended Unicode characters in strings.
134 Such strings cannot be encoded directly, as the quoted-printable
135 encoding is only defined for single-byte characters. The solution is
136 to use the Encode module to select the byte encoding you want. For
137 example:
138 .PP
139 .Vb 2
140 \& use MIME::QuotedPrint qw(encode_qp);
141 \& use Encode qw(encode);
142 \&
143 \& $encoded = encode_qp(encode("UTF\-8", "\ex{FFFF}\en"));
144 \& print $encoded;
145 .Ve
146 .SH COPYRIGHT
147 .IX Header "COPYRIGHT"
148 Copyright 1995\-1997,2002\-2004 Gisle Aas.
149 .PP
150 This library is free software; you can redistribute it and/or
151 modify it under the same terms as Perl itself.
152 .SH "SEE ALSO"
153 .IX Header "SEE ALSO"
154 MIME::Base64