From 275bd883e4759fae90439ddb1a11bbdc8794b720 Mon Sep 17 00:00:00 2001 From: gsinclair Date: Thu, 12 Feb 2004 12:26:44 +0000 Subject: * lib/base64.rb: backported from HEAD (modularised and documented) git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@5682 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- lib/base64.rb | 190 +++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 121 insertions(+), 69 deletions(-) (limited to 'lib/base64.rb') diff --git a/lib/base64.rb b/lib/base64.rb index 0e14dde9f7..b551032d90 100644 --- a/lib/base64.rb +++ b/lib/base64.rb @@ -1,84 +1,136 @@ -require "kconv" - -# Perform encoding and decoding of binary data using a Base64 -# representation. This library rather unfortunately loads its four -# methods directly into the top level namespace. -# -# require "base64" # -# enc = encode64('Send reinforcements') -# puts enc -# plain = decode64(enc) -# puts plain +# = base64.rb: methods for base64-encoding and -decoding stings +# +# Author:: Yukihiro Matsumoto +# Documentation:: Dave Thomas and Gavin Sinclair +# +# Until Ruby 1.8.1, these methods were defined at the top-level. Now +# they are in the Base64 module but included in the top-level, where +# their usage is deprecated. +# +# See Base64 for documentation. +# +require "kconv" -# Returns the Base64-decoded version of \obj{str}. +# The Base64 module provides for the encoding (#encode64) and decoding +# (#decode64) of binary data using a Base64 representation. +# +# The following particular features are also provided: +# - encode into lines of a given length (#b64encode) +# - decode the special format specified in RFC2047 for the +# representation of email headers (decode_b) +# +# == Example # -# require 'base64' -# str = 'VGhpcyBpcyBsaW5lIG9uZQpUaGlzIG' + -# 'lzIGxpbmUgdHdvClRoaXMgaXMgbGlu' + -# 'ZSB0aHJlZQpBbmQgc28gb24uLi4K' -# puts decode64(str) +# A simple encoding and decoding. +# +# require "base64" # -# Generates: +# enc = Base64.encode64('Send reinforcements') +# # -> "U2VuZCByZWluZm9yY2VtZW50cw==\n" +# plain = Base64.decode64(enc) +# # -> "Send reinforcements" # -# This is line one -# This is line two -# This is line three -# And so on... +# The purpose of using base64 to encode data is that it translates any +# binary data into purely printable characters. It is specified in +# RFC 2045 (http://www.faqs.org/rfcs/rfc2045.html). -def decode64(str) - str.unpack("m")[0] -end +module Base64 + module_function + # Returns the Base64-decoded version of +str+. + # + # require 'base64' + # str = 'VGhpcyBpcyBsaW5lIG9uZQpUaGlzIG' + + # 'lzIGxpbmUgdHdvClRoaXMgaXMgbGlu' + + # 'ZSB0aHJlZQpBbmQgc28gb24uLi4K' + # puts Base64.decode64(str) + # + # Generates: + # + # This is line one + # This is line two + # This is line three + # And so on... -# Decodes text formatted using a subset of RFC2047 (the one used for -# mime-encoding mail headers). Only supports an encoding type of 'b' -# (base 64), and only supports the character sets ISO-2022-JP and -# SHIFT_JIS (so the only two encoded word sequences recognized are -# =?ISO-2022-JP?B?...= and -# =?SHIFT_JIS?B?...=). Recognition of these sequences is case -# insensitive. - -def decode_b(str) - str.gsub!(/=\?ISO-2022-JP\?B\?([!->@-~]+)\?=/i) { - decode64($1) - } - str = Kconv::toeuc(str) - str.gsub!(/=\?SHIFT_JIS\?B\?([!->@-~]+)\?=/i) { - decode64($1) - } - str = Kconv::toeuc(str) - str.gsub!(/\n/, ' ') - str.gsub!(/\0/, '') - str -end + def decode64(str) + str.unpack("m")[0] + end -# Returns the Base64-encoded version of \obj{str}. -# -# require 'base64' -# str = "Once\nupon\na\ntime." #!sh! -# enc = encode64(str) -# decode64(enc) -def encode64(bin) - [bin].pack("m") -end + # Decodes text formatted using a subset of RFC2047 (the one used for + # mime-encoding mail headers). + # + # Only supports an encoding type of 'b' (base 64), and only supports + # the character sets ISO-2022-JP and SHIFT_JIS (so the only two + # encoded word sequences recognized are =?ISO-2022-JP?B?...= and + # =?SHIFT_JIS?B?...=). Recognition of these sequences is case + # insensitive. + + def decode_b(str) + str.gsub!(/=\?ISO-2022-JP\?B\?([!->@-~]+)\?=/i) { + decode64($1) + } + str = Kconv::toeuc(str) + str.gsub!(/=\?SHIFT_JIS\?B\?([!->@-~]+)\?=/i) { + decode64($1) + } + str = Kconv::toeuc(str) + str.gsub!(/\n/, ' ') + str.gsub!(/\0/, '') + str + end + + # Returns the Base64-encoded version of +str+. + # + # require 'base64' + # Base64.b64encode("Now is the time for all good coders\nto learn Ruby") + # + # Generates: + # + # Tm93IGlzIHRoZSB0aW1lIGZvciBhbGwgZ29vZCBjb2RlcnMKdG8gbGVhcm4g + # UnVieQ== + + def encode64(bin) + [bin].pack("m") + end + + # _Prints_ the Base64 encoded version of +bin+ (a +String+) in lines of + # +len+ (default 60) characters. + # + # require 'base64' + # data = "Now is the time for all good coders\nto learn Ruby" + # puts Base64.b64encode(data) + # + # Generates: + # + # Tm93IGlzIHRoZSB0aW1lIGZvciBhbGwgZ29vZCBjb2RlcnMKdG8gbGVhcm4g + # UnVieQ== + + def b64encode(bin, len = 60) + encode64(bin).scan(/.{1,#{len}}/o) do + print $&, "\n" + end + end -# Prints the Base64 encoded version of _bin_ (a +String+) in lines of -# _len_ (default 60) characters. -# -# require 'base64' -# b64encode("Now is the time for all good coders\nto learn Ruby") -# -# Generates -# -# Tm93IGlzIHRoZSB0aW1lIGZvciBhbGwgZ29vZCBjb2RlcnMKdG8gbGVhcm4g -# UnVieQ== -def b64encode(bin, len = 60) - encode64(bin).scan(/.{1,#{len}}/o) do - print $&, "\n" + module Deprecated # :nodoc: + include Base64 + + def _deprecated_base64(*args) + m0, m1 = caller(0) + m = m0[/\`(.*?)\'\z/, 1] + warn("#{m1}: #{m} is deprecated; use Base64.#{m} instead") + super + end + dep = instance_method(:_deprecated_base64) + remove_method(:_deprecated_base64) + for m in Base64.private_instance_methods(false) + define_method(m, dep) + end end -end +end + +include Base64::Deprecated -- cgit v1.2.3