"Fossies" - the Fresh Open Source Software Archive

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


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 3.15_vs_3.16.

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