"Fossies" - the Fresh Open Source Software Archive

Member "MIME-Base64-3.16/lib/MIME/Base64.pm" (27 Sep 2020, 5433 Bytes) of package /linux/privat/MIME-Base64-3.16.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "Base64.pm" see the Fossies "Dox" file reference documentation.

    1 package MIME::Base64;
    2 
    3 use strict;
    4 use warnings;
    5 
    6 require Exporter;
    7 our @ISA = qw(Exporter);
    8 our @EXPORT = qw(encode_base64 decode_base64);
    9 our @EXPORT_OK = qw(encode_base64url decode_base64url encoded_base64_length decoded_base64_length);
   10 
   11 our $VERSION = '3.16';
   12 
   13 require XSLoader;
   14 XSLoader::load('MIME::Base64', $VERSION);
   15 
   16 *encode = \&encode_base64;
   17 *decode = \&decode_base64;
   18 
   19 sub encode_base64url {
   20     my $e = encode_base64(shift, "");
   21     $e =~ s/=+\z//;
   22     $e =~ tr[+/][-_];
   23     return $e;
   24 }
   25 
   26 sub decode_base64url {
   27     my $s = shift;
   28     $s =~ tr[-_][+/];
   29     $s .= '=' while length($s) % 4;
   30     return decode_base64($s);
   31 }
   32 
   33 1;
   34 
   35 __END__
   36 
   37 =head1 NAME
   38 
   39 MIME::Base64 - Encoding and decoding of base64 strings
   40 
   41 =head1 SYNOPSIS
   42 
   43  use MIME::Base64;
   44 
   45  $encoded = encode_base64('Aladdin:open sesame');
   46  $decoded = decode_base64($encoded);
   47 
   48 =head1 DESCRIPTION
   49 
   50 This module provides functions to encode and decode strings into and from the
   51 base64 encoding specified in RFC 2045 - I<MIME (Multipurpose Internet
   52 Mail Extensions)>. The base64 encoding is designed to represent
   53 arbitrary sequences of octets in a form that need not be humanly
   54 readable. A 65-character subset ([A-Za-z0-9+/=]) of US-ASCII is used,
   55 enabling 6 bits to be represented per printable character.
   56 
   57 The following primary functions are provided:
   58 
   59 =over 4
   60 
   61 =item encode_base64( $bytes )
   62 
   63 =item encode_base64( $bytes, $eol );
   64 
   65 Encode data by calling the encode_base64() function.  The first
   66 argument is the byte string to encode.  The second argument is the
   67 line-ending sequence to use.  It is optional and defaults to "\n".  The
   68 returned encoded string is broken into lines of no more than 76
   69 characters each and it will end with $eol unless it is empty.  Pass an
   70 empty string as second argument if you do not want the encoded string
   71 to be broken into lines.
   72 
   73 The function will croak with "Wide character in subroutine entry" if $bytes
   74 contains characters with code above 255.  The base64 encoding is only defined
   75 for single-byte characters.  Use the Encode module to select the byte encoding
   76 you want.
   77 
   78 =item decode_base64( $str )
   79 
   80 Decode a base64 string by calling the decode_base64() function.  This
   81 function takes a single argument which is the string to decode and
   82 returns the decoded data.
   83 
   84 Any character not part of the 65-character base64 subset is
   85 silently ignored.  Characters occurring after a '=' padding character
   86 are never decoded.
   87 
   88 =back
   89 
   90 If you prefer not to import these routines into your namespace, you can
   91 call them as:
   92 
   93     use MIME::Base64 ();
   94     $encoded = MIME::Base64::encode($decoded);
   95     $decoded = MIME::Base64::decode($encoded);
   96 
   97 Additional functions not exported by default:
   98 
   99 =over 4
  100 
  101 =item encode_base64url( $bytes )
  102 
  103 =item decode_base64url( $str )
  104 
  105 Encode and decode according to the base64 scheme for "URL applications" [1].
  106 This is a variant of the base64 encoding which does not use padding, does not
  107 break the string into multiple lines and use the characters "-" and "_" instead
  108 of "+" and "/" to avoid using reserved URL characters.
  109 
  110 =item encoded_base64_length( $bytes )
  111 
  112 =item encoded_base64_length( $bytes, $eol )
  113 
  114 Returns the length that the encoded string would have without actually
  115 encoding it.  This will return the same value as C<< length(encode_base64($bytes)) >>,
  116 but should be more efficient.
  117 
  118 =item decoded_base64_length( $str )
  119 
  120 Returns the length that the decoded string would have without actually
  121 decoding it.  This will return the same value as C<< length(decode_base64($str)) >>,
  122 but should be more efficient.
  123 
  124 =back
  125 
  126 =head1 EXAMPLES
  127 
  128 If you want to encode a large file, you should encode it in chunks
  129 that are a multiple of 57 bytes.  This ensures that the base64 lines
  130 line up and that you do not end up with padding in the middle. 57
  131 bytes of data fills one complete base64 line (76 == 57*4/3):
  132 
  133    use MIME::Base64 qw(encode_base64);
  134 
  135    open(FILE, "/var/log/wtmp") or die "$!";
  136    while (read(FILE, $buf, 60*57)) {
  137        print encode_base64($buf);
  138    }
  139 
  140 or if you know you have enough memory
  141 
  142    use MIME::Base64 qw(encode_base64);
  143    local($/) = undef;  # slurp
  144    print encode_base64(<STDIN>);
  145 
  146 The same approach as a command line:
  147 
  148    perl -MMIME::Base64 -0777 -ne 'print encode_base64($_)' <file
  149 
  150 Decoding does not need slurp mode if every line contains a multiple
  151 of four base64 chars:
  152 
  153    perl -MMIME::Base64 -ne 'print decode_base64($_)' <file
  154 
  155 Perl v5.8 and better allow extended Unicode characters in strings.
  156 Such strings cannot be encoded directly, as the base64
  157 encoding is only defined for single-byte characters.  The solution is
  158 to use the Encode module to select the byte encoding you want.  For
  159 example:
  160 
  161     use MIME::Base64 qw(encode_base64);
  162     use Encode qw(encode);
  163 
  164     $encoded = encode_base64(encode("UTF-8", "\x{FFFF}\n"));
  165     print $encoded;
  166 
  167 =head1 COPYRIGHT
  168 
  169 Copyright 1995-1999, 2001-2004, 2010 Gisle Aas.
  170 
  171 This library is free software; you can redistribute it and/or
  172 modify it under the same terms as Perl itself.
  173 
  174 Distantly based on LWP::Base64 written by Martijn Koster
  175 <m.koster@nexor.co.uk> and Joerg Reichelt <j.reichelt@nexor.co.uk> and
  176 code posted to comp.lang.perl <3pd2lp$6gf@wsinti07.win.tue.nl> by Hans
  177 Mulder <hansm@wsinti07.win.tue.nl>
  178 
  179 The XS implementation uses code from metamail.  Copyright 1991 Bell
  180 Communications Research, Inc. (Bellcore)
  181 
  182 =head1 SEE ALSO
  183 
  184 L<MIME::QuotedPrint>
  185 
  186 [1] L<http://en.wikipedia.org/wiki/Base64#URL_applications>
  187 
  188 =cut