Commit | Line | Data |
6fba102d |
1 | package MIME::Base64; |
2 | |
2a909b05 |
3 | # $Id: Base64.pm,v 3.3 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 | require DynaLoader; |
10 | @ISA = qw(Exporter DynaLoader); |
11 | @EXPORT = qw(encode_base64 decode_base64); |
12 | |
2a909b05 |
13 | $VERSION = '3.03'; |
0a362e9d |
14 | |
15 | MIME::Base64->bootstrap($VERSION); |
16 | |
17 | *encode = \&encode_base64; |
18 | *decode = \&decode_base64; |
19 | |
20 | 1; |
21 | |
22 | __END__ |
23 | |
6fba102d |
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 | |
691d66bd |
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 |
6fba102d |
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 | |
6a63fb82 |
48 | =item encode_base64($str) |
49 | |
50 | =item encode_base64($str, $eol); |
6fba102d |
51 | |
52 | Encode data by calling the encode_base64() function. The first |
691d66bd |
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 |
6fba102d |
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 |
691d66bd |
58 | to be broken into lines. |
6fba102d |
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 | |
691d66bd |
66 | Any character not part of the 65-character base64 subset is |
67 | silently ignored. Characters occurring after a '=' padding character |
6fba102d |
68 | are never decoded. |
69 | |
8be5f608 |
70 | If the length of the string to decode, after ignoring |
691d66bd |
71 | non-base64 chars, is not a multiple of 4 or if padding occurs too early, |
6fba102d |
72 | then a warning is generated if perl is running under C<-w>. |
73 | |
74 | =back |
75 | |
691d66bd |
76 | If you prefer not to import these routines into your namespace, you can |
6fba102d |
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 | |
691d66bd |
85 | The following warnings can be generated if perl is invoked with the |
6fba102d |
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 anyway be as if |
95 | the padding was there. |
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 | =head1 EXAMPLES |
105 | |
106 | If you want to encode a large file, you should encode it in chunks |
107 | that are a multiple of 57 bytes. This ensures that the base64 lines |
108 | line up and that you do not end up with padding in the middle. 57 |
109 | bytes of data fills one complete base64 line (76 == 57*4/3): |
110 | |
111 | use MIME::Base64 qw(encode_base64); |
112 | |
113 | open(FILE, "/var/log/wtmp") or die "$!"; |
114 | while (read(FILE, $buf, 60*57)) { |
115 | print encode_base64($buf); |
116 | } |
117 | |
118 | or if you know you have enough memory |
119 | |
120 | use MIME::Base64 qw(encode_base64); |
121 | local($/) = undef; # slurp |
122 | print encode_base64(<STDIN>); |
123 | |
124 | The same approach as a command line: |
125 | |
126 | perl -MMIME::Base64 -0777 -ne 'print encode_base64($_)' <file |
127 | |
691d66bd |
128 | Decoding does not need slurp mode if every line contains a multiple |
129 | of four base64 chars: |
6fba102d |
130 | |
131 | perl -MMIME::Base64 -ne 'print decode_base64($_)' <file |
132 | |
133 | =head1 COPYRIGHT |
134 | |
691d66bd |
135 | Copyright 1995-1999, 2001-2004 Gisle Aas. |
6fba102d |
136 | |
137 | This library is free software; you can redistribute it and/or |
138 | modify it under the same terms as Perl itself. |
139 | |
140 | Distantly based on LWP::Base64 written by Martijn Koster |
141 | <m.koster@nexor.co.uk> and Joerg Reichelt <j.reichelt@nexor.co.uk> and |
142 | code posted to comp.lang.perl <3pd2lp$6gf@wsinti07.win.tue.nl> by Hans |
143 | Mulder <hansm@wsinti07.win.tue.nl> |
144 | |
691d66bd |
145 | The XS implementation uses code from metamail. Copyright 1991 Bell |
6fba102d |
146 | Communications Research, Inc. (Bellcore) |
147 | |
8be5f608 |
148 | =head1 SEE ALSO |
149 | |
150 | L<MIME::QuotedPrint> |
151 | |
6fba102d |
152 | =cut |