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
|
---|