1 | package MIME::Base64;
|
---|
2 |
|
---|
3 | # $Id: Base64.pm,v 3.11 2005/11/29 20:59:55 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_base64 decode_base64);
|
---|
11 |
|
---|
12 | $VERSION = '3.07';
|
---|
13 |
|
---|
14 | require XSLoader;
|
---|
15 | XSLoader::load('MIME::Base64', $VERSION);
|
---|
16 |
|
---|
17 | *encode = \&encode_base64;
|
---|
18 | *decode = \&decode_base64;
|
---|
19 |
|
---|
20 | 1;
|
---|
21 |
|
---|
22 | __END__
|
---|
23 |
|
---|
24 | =head1 NAME
|
---|
25 |
|
---|
26 | MIME::Base64 - Encoding and decoding of base64 strings
|
---|
27 |
|
---|
28 | =head1 SYNOPSIS
|
---|
29 |
|
---|
30 | use MIME::Base64;
|
---|
31 |
|
---|
32 | $encoded = encode_base64('Aladdin:open sesame');
|
---|
33 | $decoded = decode_base64($encoded);
|
---|
34 |
|
---|
35 | =head1 DESCRIPTION
|
---|
36 |
|
---|
37 | This module provides functions to encode and decode strings into and from the
|
---|
38 | base64 encoding specified in RFC 2045 - I<MIME (Multipurpose Internet
|
---|
39 | Mail Extensions)>. The base64 encoding is designed to represent
|
---|
40 | arbitrary sequences of octets in a form that need not be humanly
|
---|
41 | readable. A 65-character subset ([A-Za-z0-9+/=]) of US-ASCII is used,
|
---|
42 | enabling 6 bits to be represented per printable character.
|
---|
43 |
|
---|
44 | The following functions are provided:
|
---|
45 |
|
---|
46 | =over 4
|
---|
47 |
|
---|
48 | =item encode_base64($str)
|
---|
49 |
|
---|
50 | =item encode_base64($str, $eol);
|
---|
51 |
|
---|
52 | Encode data by calling the encode_base64() function. The first
|
---|
53 | argument is the string to encode. The second argument is the
|
---|
54 | line-ending sequence to use. It is optional and defaults to "\n". The
|
---|
55 | returned encoded string is broken into lines of no more than 76
|
---|
56 | characters each and it will end with $eol unless it is empty. Pass an
|
---|
57 | empty string as second argument if you do not want the encoded string
|
---|
58 | to be broken into lines.
|
---|
59 |
|
---|
60 | =item decode_base64($str)
|
---|
61 |
|
---|
62 | Decode a base64 string by calling the decode_base64() function. This
|
---|
63 | function takes a single argument which is the string to decode and
|
---|
64 | returns the decoded data.
|
---|
65 |
|
---|
66 | Any character not part of the 65-character base64 subset is
|
---|
67 | silently ignored. Characters occurring after a '=' padding character
|
---|
68 | are never decoded.
|
---|
69 |
|
---|
70 | If the length of the string to decode, after ignoring
|
---|
71 | non-base64 chars, is not a multiple of 4 or if padding occurs too early,
|
---|
72 | then a warning is generated if perl is running under C<-w>.
|
---|
73 |
|
---|
74 | =back
|
---|
75 |
|
---|
76 | If you prefer not to import these routines into your namespace, you can
|
---|
77 | call them as:
|
---|
78 |
|
---|
79 | use MIME::Base64 ();
|
---|
80 | $encoded = MIME::Base64::encode($decoded);
|
---|
81 | $decoded = MIME::Base64::decode($encoded);
|
---|
82 |
|
---|
83 | =head1 DIAGNOSTICS
|
---|
84 |
|
---|
85 | The following warnings can be generated if perl is invoked with the
|
---|
86 | C<-w> switch:
|
---|
87 |
|
---|
88 | =over 4
|
---|
89 |
|
---|
90 | =item Premature end of base64 data
|
---|
91 |
|
---|
92 | The number of characters to decode is not a multiple of 4. Legal
|
---|
93 | base64 data should be padded with one or two "=" characters to make
|
---|
94 | its length a multiple of 4. The decoded result will be the same
|
---|
95 | whether the padding is present or not.
|
---|
96 |
|
---|
97 | =item Premature padding of base64 data
|
---|
98 |
|
---|
99 | The '=' padding character occurs as the first or second character
|
---|
100 | in a base64 quartet.
|
---|
101 |
|
---|
102 | =back
|
---|
103 |
|
---|
104 | The following exception can be raised:
|
---|
105 |
|
---|
106 | =over 4
|
---|
107 |
|
---|
108 | =item Wide character in subroutine entry
|
---|
109 |
|
---|
110 | The string passed to encode_base64() contains characters with code
|
---|
111 | above 255. The base64 encoding is only defined for single-byte
|
---|
112 | characters. Use the Encode module to select the byte encoding you
|
---|
113 | want.
|
---|
114 |
|
---|
115 | =back
|
---|
116 |
|
---|
117 | =head1 EXAMPLES
|
---|
118 |
|
---|
119 | If you want to encode a large file, you should encode it in chunks
|
---|
120 | that are a multiple of 57 bytes. This ensures that the base64 lines
|
---|
121 | line up and that you do not end up with padding in the middle. 57
|
---|
122 | bytes of data fills one complete base64 line (76 == 57*4/3):
|
---|
123 |
|
---|
124 | use MIME::Base64 qw(encode_base64);
|
---|
125 |
|
---|
126 | open(FILE, "/var/log/wtmp") or die "$!";
|
---|
127 | while (read(FILE, $buf, 60*57)) {
|
---|
128 | print encode_base64($buf);
|
---|
129 | }
|
---|
130 |
|
---|
131 | or if you know you have enough memory
|
---|
132 |
|
---|
133 | use MIME::Base64 qw(encode_base64);
|
---|
134 | local($/) = undef; # slurp
|
---|
135 | print encode_base64(<STDIN>);
|
---|
136 |
|
---|
137 | The same approach as a command line:
|
---|
138 |
|
---|
139 | perl -MMIME::Base64 -0777 -ne 'print encode_base64($_)' <file
|
---|
140 |
|
---|
141 | Decoding does not need slurp mode if every line contains a multiple
|
---|
142 | of four base64 chars:
|
---|
143 |
|
---|
144 | perl -MMIME::Base64 -ne 'print decode_base64($_)' <file
|
---|
145 |
|
---|
146 | Perl v5.8 and better allow extended Unicode characters in strings.
|
---|
147 | Such strings cannot be encoded directly, as the base64
|
---|
148 | encoding is only defined for single-byte characters. The solution is
|
---|
149 | to use the Encode module to select the byte encoding you want. For
|
---|
150 | example:
|
---|
151 |
|
---|
152 | use MIME::Base64 qw(encode_base64);
|
---|
153 | use Encode qw(encode);
|
---|
154 |
|
---|
155 | $encoded = encode_base64(encode("UTF-8", "\x{FFFF}\n"));
|
---|
156 | print $encoded;
|
---|
157 |
|
---|
158 | =head1 COPYRIGHT
|
---|
159 |
|
---|
160 | Copyright 1995-1999, 2001-2004 Gisle Aas.
|
---|
161 |
|
---|
162 | This library is free software; you can redistribute it and/or
|
---|
163 | modify it under the same terms as Perl itself.
|
---|
164 |
|
---|
165 | Distantly based on LWP::Base64 written by Martijn Koster
|
---|
166 | <[email protected]> and Joerg Reichelt <[email protected]> and
|
---|
167 | code posted to comp.lang.perl <[email protected]> by Hans
|
---|
168 | Mulder <[email protected]>
|
---|
169 |
|
---|
170 | The XS implementation uses code from metamail. Copyright 1991 Bell
|
---|
171 | Communications Research, Inc. (Bellcore)
|
---|
172 |
|
---|
173 | =head1 SEE ALSO
|
---|
174 |
|
---|
175 | L<MIME::QuotedPrint>
|
---|
176 |
|
---|
177 | =cut
|
---|