home *** CD-ROM | disk | FTP | other *** search
/ PC World 2005 December (Special) / PCWorld_2005-12_Special_cd.bin / Bezpecnost / lsti / lsti.exe / framework-2.5.exe / Base64.pm < prev    next >
Text File  |  2005-01-27  |  4KB  |  153 lines
  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
  153.