ext/MIME/Base64/Base64.pm

   1 package MIME::Base64;
   2
   3 # $Id: Base64.pm,v 3.5 2004/09/20 09:23:23 gisle Exp $
   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
  13 $VERSION = '3.05';
  14
  15 MIME::Base64->bootstrap($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 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
 128 Decoding does not need slurp mode if every line contains a multiple
 129 of four base64 chars:
 130
 131    perl -MMIME::Base64 -ne 'print decode_base64($_)' <file
 132
 133 =head1 COPYRIGHT
 134
 135 Copyright 1995-1999, 2001-2004 Gisle Aas.
 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
 145 The XS implementation uses code from metamail.  Copyright 1991 Bell
 146 Communications Research, Inc. (Bellcore)
 147
 148 =head1 SEE ALSO
 149
 150 L<MIME::QuotedPrint>
 151
 152 =cut