ext/MIME/Base64/Base64.pm

   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_01';
  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