diff options
author | gsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2004-02-12 12:26:44 +0000 |
---|---|---|
committer | gsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2004-02-12 12:26:44 +0000 |
commit | 275bd883e4759fae90439ddb1a11bbdc8794b720 (patch) | |
tree | fdd2aa262baa40d0b517198546f5033bbbdf4bdf /lib/base64.rb | |
parent | 995dd862a47dc3e83c03d39bba4d908e34fab9e6 (diff) |
* 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
Diffstat (limited to 'lib/base64.rb')
-rw-r--r-- | lib/base64.rb | 190 |
1 files changed, 121 insertions, 69 deletions
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" # -# <i>Generates:</i> +# 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) + # + # <i>Generates:</i> + # + # 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 -# <tt>=?ISO-2022-JP?B?...=</tt> and -# <tt>=?SHIFT_JIS?B?...=</tt>). 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 <tt>=?ISO-2022-JP?B?...=</tt> and + # <tt>=?SHIFT_JIS?B?...=</tt>). 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") + # + # <i>Generates:</i> + # + # 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) + # + # <i>Generates:</i> + # + # 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 |