Debian Codegraph @

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