Commit | Line | Data |
6fba102d |
1 | package MIME::QuotedPrint; |
2 | |
2a909b05 |
3 | # $Id: QuotedPrint.pm,v 3.4 2004/08/25 09:33:45 gisle Exp $ |
0a362e9d |
4 | |
5 | use strict; |
6 | use vars qw(@ISA @EXPORT $VERSION); |
7 | |
8 | require Exporter; |
9 | @ISA = qw(Exporter); |
10 | @EXPORT = qw(encode_qp decode_qp); |
11 | |
2a909b05 |
12 | $VERSION = "3.03"; |
0a362e9d |
13 | |
14 | use MIME::Base64; # will load XS version of {en,de}code_qp() |
15 | |
16 | *encode = \&encode_qp; |
17 | *decode = \&decode_qp; |
18 | |
19 | 1; |
20 | |
21 | __END__ |
22 | |
6fba102d |
23 | =head1 NAME |
24 | |
25 | MIME::QuotedPrint - Encoding and decoding of quoted-printable strings |
26 | |
27 | =head1 SYNOPSIS |
28 | |
29 | use MIME::QuotedPrint; |
30 | |
31 | $encoded = encode_qp($decoded); |
32 | $decoded = decode_qp($encoded); |
33 | |
34 | =head1 DESCRIPTION |
35 | |
691d66bd |
36 | This module provides functions to encode and decode strings into and from the |
37 | quoted-printable encoding specified in RFC 2045 - I<MIME (Multipurpose |
38 | Internet Mail Extensions)>. The quoted-printable encoding is intended |
6fba102d |
39 | to represent data that largely consists of bytes that correspond to |
691d66bd |
40 | printable characters in the ASCII character set. Each non-printable |
41 | character (as defined by English Americans) is represented by a |
6fba102d |
42 | triplet consisting of the character "=" followed by two hexadecimal |
43 | digits. |
44 | |
45 | The following functions are provided: |
46 | |
47 | =over 4 |
48 | |
49 | =item encode_qp($str) |
50 | |
6a63fb82 |
51 | =item encode_qp($str, $eol) |
6fba102d |
52 | |
9e87bee3 |
53 | =item encode_qp($str, $eol, $binmode) |
8be5f608 |
54 | |
9e87bee3 |
55 | This function returns an encoded version of the string ($str) given as |
56 | argument. |
8be5f608 |
57 | |
9e87bee3 |
58 | The second argument ($eol) is the line-ending sequence to use. It is |
59 | optional and defaults to "\n". Every occurrence of "\n" is replaced |
60 | with this string, and it is also used for additional "soft line |
61 | breaks" to ensure that no line end up longer than 76 characters. Pass |
62 | it as "\015\012" to produce data suitable for external consumption. |
63 | The string "\r\n" produces the same result on many platforms, but not |
64 | all. |
65 | |
66 | The third argument ($binmode) will select binary mode if passed as a |
67 | TRUE value. In binary mode "\n" will be encoded in the same way as |
68 | any other non-printable character. This ensures that a decoder will |
69 | end up with exactly the same string whatever line ending sequence it |
70 | uses. In general it is preferable to use the base64 encoding for |
71 | binary data; see L<MIME::Base64>. |
72 | |
73 | An $eol of "" (the empty string) is special. In this case, no "soft |
74 | line breaks" are introduced and binary mode is effectively enabled so |
75 | that any "\n" in the original data is encoded as well. |
6fba102d |
76 | |
77 | =item decode_qp($str); |
78 | |
691d66bd |
79 | This function returns the plain text version of the string given |
80 | as argument. The lines of the result are "\n" terminated, even if |
8be5f608 |
81 | the $str argument contains "\r\n" terminated lines. |
6fba102d |
82 | |
83 | =back |
84 | |
85 | |
691d66bd |
86 | If you prefer not to import these routines into your namespace, you can |
6fba102d |
87 | call them as: |
88 | |
89 | use MIME::QuotedPrint (); |
90 | $encoded = MIME::QuotedPrint::encode($decoded); |
91 | $decoded = MIME::QuotedPrint::decode($encoded); |
92 | |
8be5f608 |
93 | Perl v5.6 and better allow extended Unicode characters in strings. |
691d66bd |
94 | Such strings cannot be encoded directly, as the quoted-printable |
95 | encoding is only defined for single-byte characters. The solution is to use the Encode |
8be5f608 |
96 | module to select the byte encoding you want. For example: |
97 | |
98 | use MIME::QuotedPrint qw(encode_qp); |
99 | use Encode qw(encode); |
100 | |
101 | $encoded = encode_qp(encode("UTF-8", "\x{FFFF}\n")); |
102 | print $encoded; |
103 | |
6fba102d |
104 | =head1 COPYRIGHT |
105 | |
691d66bd |
106 | Copyright 1995-1997,2002-2004 Gisle Aas. |
6fba102d |
107 | |
108 | This library is free software; you can redistribute it and/or |
109 | modify it under the same terms as Perl itself. |
110 | |
8be5f608 |
111 | =head1 SEE ALSO |
112 | |
113 | L<MIME::Base64> |
114 | |
6fba102d |
115 | =cut |