Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | package MIME::QuotedPrint; |
2 | ||
3 | # $Id: QuotedPrint.pm,v 3.7 2005/11/29 20:49:46 gisle Exp $ | |
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 | ||
12 | $VERSION = "3.07"; | |
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 | ||
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 | ||
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 | |
39 | to represent data that largely consists of bytes that correspond to | |
40 | printable characters in the ASCII character set. Each non-printable | |
41 | character (as defined by English Americans) is represented by a | |
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 | ||
51 | =item encode_qp($str, $eol) | |
52 | ||
53 | =item encode_qp($str, $eol, $binmode) | |
54 | ||
55 | This function returns an encoded version of the string ($str) given as | |
56 | argument. | |
57 | ||
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. | |
76 | ||
77 | =item decode_qp($str); | |
78 | ||
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 | |
81 | the $str argument contains "\r\n" terminated lines. | |
82 | ||
83 | =back | |
84 | ||
85 | ||
86 | If you prefer not to import these routines into your namespace, you can | |
87 | call them as: | |
88 | ||
89 | use MIME::QuotedPrint (); | |
90 | $encoded = MIME::QuotedPrint::encode($decoded); | |
91 | $decoded = MIME::QuotedPrint::decode($encoded); | |
92 | ||
93 | Perl v5.8 and better allow extended Unicode characters in strings. | |
94 | Such strings cannot be encoded directly, as the quoted-printable | |
95 | encoding is only defined for single-byte characters. The solution is | |
96 | to use the Encode module to select the byte encoding you want. For | |
97 | example: | |
98 | ||
99 | use MIME::QuotedPrint qw(encode_qp); | |
100 | use Encode qw(encode); | |
101 | ||
102 | $encoded = encode_qp(encode("UTF-8", "\x{FFFF}\n")); | |
103 | print $encoded; | |
104 | ||
105 | =head1 COPYRIGHT | |
106 | ||
107 | Copyright 1995-1997,2002-2004 Gisle Aas. | |
108 | ||
109 | This library is free software; you can redistribute it and/or | |
110 | modify it under the same terms as Perl itself. | |
111 | ||
112 | =head1 SEE ALSO | |
113 | ||
114 | L<MIME::Base64> | |
115 | ||
116 | =cut |