Commit | Line | Data |
---|---|---|
920dae64 AT |
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 | <m.koster@nexor.co.uk> and Joerg Reichelt <j.reichelt@nexor.co.uk> and | |
167 | code posted to comp.lang.perl <3pd2lp$6gf@wsinti07.win.tue.nl> by Hans | |
168 | Mulder <hansm@wsinti07.win.tue.nl> | |
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 |