facets 2.8.4 → 2.9.0.pre.1

data/lib/more/facets/pathname.rb

@@ -37,10 +37,9 @@ class Pathname
     new(path)
   end
 
-  # Active path separator.
+  # Start a path. Another alias for #new.
   #
-  #   p1 = Pathname.new('/')
-  #   p2 = p1 / 'usr' / 'share'   #=> Pathname:/usr/share
+  #   Pathname / 'usr'
   #
   def self./(path)
     new(path)
@@ -65,13 +64,9 @@ class Pathname
     Pathname.new('.')
   end
 
-  # Try to get this into standard Pathname class.
-  alias_method :/, :+
-
-  # CREDIT Daniel Burger
-
   # Platform dependent null device.
   #
+  # CREDIT Daniel Burger
   def self.null
     case RUBY_PLATFORM
     when /mswin/i
@@ -85,6 +80,9 @@ class Pathname
     end
   end
 
+  # Try to get this into standard Pathname class.
+  alias_method :/, :+
+
   #
   def rootname
     self.class.new(File.rootname(to_s))
@@ -162,19 +160,21 @@ class Pathname
   #
   # Example use case:
   #
-  #   # get rid of any file but *.haml within app/**/*
+  #   # Locate any file but *.haml within app/**/*
   #   Pathname.new("app").visit do |f|
-  #     FileUtils.rm_f(f) unless f.to_s =~ /\.haml$/
-  #     puts "!!! deleting #{f}"
+  #     next unless f.to_s =~ /\.haml$/
+  #     f
   #   end 
   #
+  # TODO: Use #map instead of #each ?
+  # 
   # CREDIT: Jean-Denis Vauguet
   def visit(options = {:all => false, :hidden => false})
     if self.directory?
       children.each do |entry|
         next if entry.basename.to_s[0] == "." && !options[:hidden]
         yield(entry) unless entry.directory? && !options[:all]
-        #entry.visit(:all => options[:all]) { |sub_entry| yield sub_entry } if entry.directory?
+        ##entry.visit(:all => options[:all]) { |sub_entry| yield sub_entry } if entry.directory?
         entry.visit(:all => options[:all], :hidden => options[:hidden]) do |sub_entry|
           yield(sub_entry)
         end if entry.directory?
@@ -184,37 +184,47 @@ class Pathname
     end
   end
 
-#   # Already included in 1.8.4+ version of Ruby (except for inclusion flag)
-#   if not instance_methods.include?(:ascend)
-#
-#     # Calls the _block_ for every successive parent directory of the
-#     # directory path until the root (absolute path) or +.+ (relative path)
-#     # is reached.
-#     def ascend(inclusive=false,&block) # :yield:
-#       cur_dir = self
-#       yield( cur_dir.cleanpath ) if inclusive
-#       until cur_dir.root? or cur_dir == Pathname.new(".")
-#         cur_dir = cur_dir.parent
-#         yield cur_dir
-#       end
-#     end
-#
-#   end
-#
-#   # Already included in 1.8.4+ version of Ruby
-#   if ! instance_methods.include?(:descend)
-#
-#     # Calls the _block_ for every successive subdirectory of the
-#     # directory path from the root (absolute path) until +.+
-#     # (relative path) is reached.
-#     def descend()
-#       @path.scan(%r{[^/]*/?})[0...-1].inject('') do |path, dir|
-#         yield Pathname.new(path << dir)
-#       path
-#       end
-#     end
-#
-#   end
+##   # Already included in 1.8.4+ version of Ruby (except for inclusion flag)
+##   if not instance_methods.include?(:ascend)
+##
+##     # Calls the _block_ for every successive parent directory of the
+##     # directory path until the root (absolute path) or +.+ (relative path)
+##     # is reached.
+##     def ascend(inclusive=false,&block) # :yield:
+##       cur_dir = self
+##       yield( cur_dir.cleanpath ) if inclusive
+##       until cur_dir.root? or cur_dir == Pathname.new(".")
+##         cur_dir = cur_dir.parent
+##         yield cur_dir
+##       end
+##     end
+##
+##   end
+##
+##   # Already included in 1.8.4+ version of Ruby
+##   if ! instance_methods.include?(:descend)
+##
+##     # Calls the _block_ for every successive subdirectory of the
+##     # directory path from the root (absolute path) until +.+
+##     # (relative path) is reached.
+##     def descend()
+##       @path.scan(%r{[^/]*/?})[0...-1].inject('') do |path, dir|
+##         yield Pathname.new(path << dir)
+##       path
+##       end
+##     end
+##
+##   end
+
+  # Does a directory contain a matching entry?
+  # Or if the pathname is a file, same as #fnmatch.
+  def include?(pattern,*opts)
+    if directory?
+      glob_first(pattern,*opts)
+    else
+      fnmatch(pattern,*opts)
+    end
+  end
 
 end
 

data/lib/more/facets/platform.rb

@@ -1,30 +1,41 @@
-# Copyright (c) 2007 Eric Hodel
-#
-# Available list of platforms.
+# Original version from RubyGems, Copyright (c) 2007 Eric Hodel
 
 require 'rbconfig'
 
+# Platform class
+#
 class Platform
 
+  # A pure-ruby gem that may use Gem::Specification#extensions to build
+  # binary files.
+  RUBY = 'ruby'
+
+  # A platform-specific gem that is built for the packaging ruby's platform.
+  # This will be replaced with Gem::Platform::local.
+  CURRENT = 'current'
+
   @local      = nil
   @supported  = nil
 
+  #
   attr_accessor :cpu
 
+  #
   attr_accessor :os
 
+  #
   attr_accessor :version
 
-  RbConfig = Config unless defined? ::RbConfig
+  ##RbConfig = Config unless defined? ::RbConfig
 
-  DEPRECATED_CONSTS = [
-    :DARWIN,
-    :LINUX_586,
-    :MSWIN32,
-    :PPC_DARWIN,
-    :WIN32,
-    :X86_LINUX
-  ]
+  ##DEPRECATED_CONSTS = [
+  ##  :DARWIN,
+  ##  :LINUX_586,
+  ##  :MSWIN32,
+  ##  :PPC_DARWIN,
+  ##  :WIN32,
+  ##  :X86_LINUX
+  ##]
 
   # Array of supported platforms (ie. pure-Ruby and local platform).
 
@@ -32,20 +43,22 @@ class Platform
     @suported ||= [Platform::RUBY, Platform.local]
   end
 
-  def self.const_missing(name) # TODO remove six months from 2007/12
-    if DEPRECATED_CONSTS.include? name then
-      raise NameError, "#{name} has been removed, use CURRENT instead"
-    else
-      super
-    end
-  end
+  ##def self.const_missing(name) # TODO remove six months from 2007/12
+  ##  if DEPRECATED_CONSTS.include? name then
+  ##    raise NameError, "#{name} has been removed, use CURRENT instead"
+  ##  else
+  ##    super
+  ##  end
+  ##end
 
+  #
   def self.local
-    arch = RbConfig::CONFIG['arch']
+    arch = Config::CONFIG['arch']
     arch = "#{arch}_60" if arch =~ /mswin32$/
     @local ||= new(arch)
   end
 
+  #
   def self.match(platform)
     supported.any? do |local_platform|
       platform.nil? or local_platform == platform or
@@ -53,6 +66,7 @@ class Platform
     end
   end
 
+  #
   def self.new(arch) # :nodoc:
     case arch
     when Platform::CURRENT then
@@ -64,6 +78,7 @@ class Platform
     end
   end
 
+  #
   def initialize(arch)
     case arch
     when Array then
@@ -92,26 +107,26 @@ class Platform
       @cpu, os = nil, cpu if os.nil? # legacy jruby
 
       @os, @version = case os
-                      when /aix(\d+)/ then             [ 'aix',       $1  ]
-                      when /cygwin/ then               [ 'cygwin',    nil ]
-                      when /darwin(\d+)?/ then         [ 'darwin',    $1  ]
-                      when /freebsd(\d+)/ then         [ 'freebsd',   $1  ]
-                      when /hpux(\d+)/ then            [ 'hpux',      $1  ]
-                      when /^java$/, /^jruby$/ then    [ 'java',      nil ]
-                      when /^java([\d.]*)/ then        [ 'java',      $1  ]
-                      when /linux/ then                [ 'linux',     $1  ]
-                      when /mingw32/ then              [ 'mingw32',   nil ]
-                      when /(mswin\d+)(\_(\d+))?/ then
-                        os, version = $1, $3
-                        @cpu = 'x86' if @cpu.nil? and os =~ /32$/
-                        [os, version]
-                      when /netbsdelf/ then            [ 'netbsdelf', nil ]
-                      when /openbsd(\d+\.\d+)/ then    [ 'openbsd',   $1  ]
-                      when /solaris(\d+\.\d+)/ then    [ 'solaris',   $1  ]
-                      # test
-                      when /^(\w+_platform)(\d+)/ then [ $1,          $2  ]
-                      else                             [ 'unknown',   nil ]
-                      end
+        when /aix(\d+)/ then             [ 'aix',       $1  ]
+        when /cygwin/ then               [ 'cygwin',    nil ]
+        when /darwin(\d+)?/ then         [ 'darwin',    $1  ]
+        when /freebsd(\d+)/ then         [ 'freebsd',   $1  ]
+        when /hpux(\d+)/ then            [ 'hpux',      $1  ]
+        when /^java$/, /^jruby$/ then    [ 'java',      nil ]
+        when /^java([\d.]*)/ then        [ 'java',      $1  ]
+        when /linux/ then                [ 'linux',     $1  ]
+        when /mingw32/ then              [ 'mingw32',   nil ]
+        when /(mswin\d+)(\_(\d+))?/ then
+          os, version = $1, $3
+          @cpu = 'x86' if @cpu.nil? and os =~ /32$/
+          [os, version]
+        when /netbsdelf/ then            [ 'netbsdelf', nil ]
+        when /openbsd(\d+\.\d+)/ then    [ 'openbsd',   $1  ]
+        when /solaris(\d+\.\d+)/ then    [ 'solaris',   $1  ]
+        # test
+        when /^(\w+_platform)(\d+)/ then [ $1,          $2  ]
+        else                             [ 'unknown',   nil ]
+      end
     when Platform then
       @cpu = arch.cpu
       @os = arch.os
@@ -121,23 +136,28 @@ class Platform
     end
   end
 
+  #
   def inspect
     "#<%s:0x%x @cpu=%p, @os=%p, @version=%p>" % [self.class, object_id, *to_a]
   end
 
+  #
   def to_a
     [@cpu, @os, @version]
   end
 
+  #
   def to_s
     to_a.compact.join '-'
   end
 
+  #
   def ==(other)
     self.class === other and
       @cpu == other.cpu and @os == other.os and @version == other.version
   end
 
+  #
   def ===(other)
     return nil unless Platform === other
 
@@ -151,22 +171,23 @@ class Platform
     (@version.nil? or other.version.nil? or @version == other.version)
   end
 
+  #
   def =~(other)
     case other
     when Platform then # nop
     when String then
       # This data is from http://gems.rubyforge.org/gems/yaml on 19 Aug 2007
       other = case other
-              when /^i686-darwin(\d)/ then     ['x86',       'darwin',  $1]
-              when /^i\d86-linux/ then         ['x86',       'linux',   nil]
-              when 'java', 'jruby' then        [nil,         'java',    nil]
-              when /mswin32(\_(\d+))?/ then    ['x86',       'mswin32', $2]
-              when 'powerpc-darwin' then       ['powerpc',   'darwin',  nil]
-              when /powerpc-darwin(\d)/ then   ['powerpc',   'darwin',  $1]
-              when /sparc-solaris2.8/ then     ['sparc',     'solaris', '2.8']
-              when /universal-darwin(\d)/ then ['universal', 'darwin',  $1]
-              else                             other
-              end
+        when /^i686-darwin(\d)/ then     ['x86',       'darwin',  $1]
+        when /^i\d86-linux/ then         ['x86',       'linux',   nil]
+        when 'java', 'jruby' then        [nil,         'java',    nil]
+        when /mswin32(\_(\d+))?/ then    ['x86',       'mswin32', $2]
+        when 'powerpc-darwin' then       ['powerpc',   'darwin',  nil]
+        when /powerpc-darwin(\d)/ then   ['powerpc',   'darwin',  $1]
+        when /sparc-solaris2.8/ then     ['sparc',     'solaris', '2.8']
+        when /universal-darwin(\d)/ then ['universal', 'darwin',  $1]
+        else                             other
+      end
 
       other = Platform.new other
     else
@@ -176,63 +197,29 @@ class Platform
     self === other
   end
 
-  ##
-  # A pure-ruby gem that may use Gem::Specification#extensions to build
-  # binary files.
-
-  RUBY = 'ruby'
-
-  ##
-  # A platform-specific gem that is built for the packaging ruby's platform.
-  # This will be replaced with Gem::Platform::local.
-
-  CURRENT = 'current'
-
-  # Determine byte order of underlying machine.
+  # Byte order of CPU.
+  #
+  # TODO: This doesn't work well apearently. We need to use a chart for possible
+  # cpus instead, maybe.
   def byte_order
-    ByteOrder.byte_order
+    if [0x12345678].pack("L") == "\x12\x34\x56\x78"
+      BigEndian
+    else
+      LittleEndian
+    end
   end
 
+  #
+  alias_method :byteorder, :byte_order
+
+  #
   def little_endian?
-    ByteOrder.little_endian?
+    byte_order == :little
   end
 
+  #
   def big_endian?
-    ByteOrder.big_endian?
-  end
-
-  # Copyright (c) 2003 Michael Neumann
-  module ByteOrder
-    Native    = :Native
-    BigEndian = Big = Network = :BigEndian
-    LittleEndian = Little = :LittleEndian
-
-    # examines the byte order of the underlying machine
-    def byte_order
-      if [0x12345678].pack("L") == "\x12\x34\x56\x78"
-        BigEndian
-      else
-        LittleEndian
-      end
-    end
-
-    alias_method :byteorder, :byte_order
-
-    def little_endian?
-      byte_order == LittleEndian
-    end
-
-    def big_endian?
-      byte_order == BigEndian
-    end
-
-    alias_method :little?, :little_endian?
-    alias_method :big?, :big_endian?
-    alias_method :network?, :big_endian?
-
-    module_function :byte_order, :byteorder
-    module_function :little_endian?, :little?
-    module_function :big_endian?, :big?, :network?
+    byte_order == :big
   end
 
 end

data/lib/more/facets/random.rb

@@ -1,142 +1,129 @@
-# = Random
-#
-# Randomization core extension methods.
+require 'facets/hash/zipnew'
+require 'facets/string/shatter'
+require 'facets/kernel/maybe'
+
+# = Randomization Extensions
 #
-# This library extends Object, Array, String, Hash, and Range with randomization
-# methods. Most of the methods are of one of two kinds. Either they "pick"
-# a random element from the reciever or they randomly "shuffle" the receiver.
+# This library extends Array, String, Hash and other classes with randomization
+# methods. Most of the methods are of one of two kinds. Either they "pick" a
+# random element from the reciever or they randomly "shuffle" the reciever.
 #
 # The most common example is Array#shuffle, which simply randmomizes the
 # order of an array's elements.
 #
-#   [1,2,3].shuffle  #=> [2,3,1]
+#   [1,2,3].shuffle  #~> [2,3,1]
 #
 # The other methods do similar things for their respective classes.
 #
-# == Authors
-#
-# * Ilmari Heikkinen <mailto:kig@misfiring.net>
-# * Christian Neukirchen <mailto:chneukirchen@gmail.com>
-# * Thomas Sawyer
-#
-# == Copying
+# The classes are all extended via mixins which have been created within
+# Ruby's Random class.
 #
-# Copyright (c) 2005 Ilmari Heikkinen, Christian Neukirchen, Thomas Sawyer
+# Credit for this work is due to:
 #
-# Ruby License
-#
-# This module is free software. You may use, modify, and/or redistribute this
-# software under the same terms as Ruby.
+# * Ilmari Heikkinen
+# * Christian Neukirchen
+# * Thomas Sawyer
 #
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-# FOR A PARTICULAR PURPOSE.
+# NOTE: Inline QED tests are almost pointless here b/c... yea, it's random.
+# So indtead of the usual `#=>` we use `#~>` which means approx. equal and
+# prevens QED from making a hard assertion.
 
-require 'facets/hash/zipnew'
-require 'facets/string/shatter'
-
-# = Random
-#
-# Randomization core extension methods.
-#
-# This library extends Array, String and Hash with randomization methods.
-# Most of the methods are of one of two kinds. Either they "pick" a random
-# element from the reciever or they randomly "shuffle" the reciever.
-#
-# The most common example is Array#shuffle, which simply randmomizes the
-# order of an array's elements.
-#
-#   [1,2,3].shuffle  #=> [2,3,1]
-#
-# The other methods do similar things for their respective classes.
-#
-module Random
+class Random
 
   class << self
     # Alias for Kernel#rand.
     alias_method :number, :rand
+
     public :number
   end
 
-  #def self.number(*args)
-  #  ::Kernel.rand(*args)
-  #end
+  ##def self.number(*args)
+  ##  ::Kernel.rand(*args)
+  ##end
 
+  # Module method to generate a random letter.
   #
-  def self.append_features(mod)
-    if mod == ::Object
-      mod.send(:include, Random::Object)
-    elsif mod == ::Range
-      mod.send(:include, Random::Range)
-    elsif mod == ::Array
-      mod.send(:include, Random::Array)
-    elsif mod == ::Hash
-      mod.send(:include, Random::Hash)
-    elsif mod == ::String
-      mod.send(:include, Random::String)
-    else
-      raise TypeError
-    end
-  end
-
+  #   Random.letter  #~> "q"
+  #   Random.letter  #~> "r"
+  #   Random.letter  #~> "a"
   #
-
-  module Object
-
-    # Random generator that returns true or false.
-    # Can also take a block that has a 50/50 chance to being executed.
-    #
-    #   maybe  #=> true
-    #   maybe  #=> false
-    #
-    def maybe(chance = 0.5, &block)
-      if block then
-        yield if rand < chance
-      else
-        rand < chance
-      end
-    end
-
+  def self.letter
+    (Random.number(26) + (Random.number(2) == 0 ? 65 : 97) ).chr
   end
 
   #
-
-  module Range
-
+  module RangeExtensions
     # Return a random element from the range.
     #
-    #   (1..4).at_rand           #=> 2
-    #   (1..4).at_rand           #=> 4
+    #   (1..4).at_rand           #~> 2
+    #   (1..4).at_rand           #~> 4
     #
-    #   (1.5..2.5).at_rand       #=> 2.06309842754533
-    #   (1.5..2.5).at_rand       #=> 1.74976944931541
+    #   (1.5..2.5).at_rand       #~> 2.06309842754533
+    #   (1.5..2.5).at_rand       #~> 1.74976944931541
     #
-    #   ('a'..'z').at_rand       #=> 'q'
-    #   ('a'..'z').at_rand       #=> 'f'
+    #   ('a'..'z').at_rand       #~> 'q'
+    #   ('a'..'z').at_rand       #~> 'f'
     #
-    # CREDIT: Lavir the Whiolet
-
+    # CREDIT: Lavir the Whiolet, Thomas Sawyer
     def at_rand
-      if first.respond_to?(:succ)
-        to_a.at_rand
-      elsif Numeric===first && Numeric===last
-        number = (last - first) * Random.number + first
-        (number == last && exclude_end?) ? first : number
+      first, last = first(), last()
+      if first.respond_to?(:random_delta)  # TODO: work on this!!!
+        begin
+          first.random_delta(last, exclude_end?)
+        rescue
+          to_a.at_rand
+        end
       else
-        nil
+        to_a.at_rand
       end
+      ##elsif first.respond_to?(:succ)
+      ##  # optimized algorithm
+      ##  if (Fixnum === first || Bignum === first) &&
+      ##     (Fixnum === last  || Bignum === last)
+      ##    last -= 1 if exclude_end?
+      ##    return nil if last < first
+      ##    return Random.number(last - first + 1) + first
+      ##  end
+      ##  # standard algorithm
+      ##  return to_a.at_rand
+      ##elsif Numeric === first && Numeric === last
+      ##  return nil if last < first
+      ##  return nil if exclude_end? && last == first
+      ##  return (last - first) * Random.number + first
+      ##else
+      ##  return nil
+      ##end
     end
-
   end
 
   #
+  module IntegerExtensions
+    #
+    def random_delta(last, exclude_end)
+      first = self
+      last -= 1 if exclude_end
+      return nil if last < first
+      return Random.number(last - first + 1) + first
+    end
+  end
 
-  module Array
+  #
+  module NumericExtensions
+    #
+    def random_delta(last, exclude_end)
+      first = self
+      return nil if last < first
+      return nil if exclude_end && last == first
+      return (last - first) * Random.number + first
+    end
+  end
 
+  #
+  module ArrayExtensions
     # Return a random element from the array.
     #
-    #   [1, 2, 3, 4].at_rand           #=> 2
-    #   [1, 2, 3, 4].at_rand           #=> 4
+    #   [1, 2, 3, 4].at_rand           #~> 2
+    #   [1, 2, 3, 4].at_rand           #~> 4
     #
     def at_rand
       at(Random.number(size))
@@ -146,8 +133,8 @@ module Random
     # random element from the array.
     #
     #   a = [1,2,3,4]
-    #   a.at_rand!       #=> 2
-    #   a                #=> [1,3,4]
+    #   a.at_rand!       #~> 2
+    #   a                #~> [1,3,4]
     #
     def at_rand!
       return delete_at( Random.number( size ) )
@@ -201,10 +188,10 @@ module Random
     # _number_ given is greater than the size of the array,
     # then all values are returned.
     #
-    #   [1, 2, 3, 4].rand_subset(1)        #=> [2]
-    #   [1, 2, 3, 4].rand_subset(4)        #=> [2, 1, 3, 4]
-    #   [1, 2, 3, 4].rand_subset           #=> [1, 3, 4]
-    #   [1, 2, 3, 4].rand_subset           #=> [2, 3]
+    #   [1, 2, 3, 4].rand_subset(1)        #~> [2]
+    #   [1, 2, 3, 4].rand_subset(4)        #~> [2, 1, 3, 4]
+    #   [1, 2, 3, 4].rand_subset           #~> [1, 3, 4]
+    #   [1, 2, 3, 4].rand_subset           #~> [2, 3]
     #
     def rand_subset( number=nil, exclusive=true )
       number = Random.number(size) unless number
@@ -217,7 +204,7 @@ module Random
 
     # Randomize the order of an array.
     #
-    #   [1,2,3,4].shuffle  #=> [2,4,1,3]
+    #   [1,2,3,4].shuffle  #~> [2,4,1,3]
     #
     def shuffle
       dup.shuffle!
@@ -229,10 +216,10 @@ module Random
     #
     #   a = [1,2,3,4]
     #   a.shuffle!
-    #   a  #=> [2,4,1,3]
+    #
+    #   a  #~> [2,4,1,3]
     #
     # CREDIT Niel Spring
-
     def shuffle!
       s = size
       each_index do |j|
@@ -248,12 +235,10 @@ module Random
   end
 
   #
-
-  module Hash
-
+  module HashExtensions
     # Returns a random key.
     #
-    #   {:one => 1, :two => 2, :three => 3}.pick_key  #=> :three
+    #   {:one => 1, :two => 2, :three => 3}.pick_key  #~> :three
     #
     def rand_key
       keys.at(Random.number(keys.size))
@@ -262,8 +247,8 @@ module Random
     # Delete a random key-value pair, returning the key.
     #
     #   a = {:one => 1, :two => 2, :three => 3}
-    #   a.pick_key!  #=> :two
-    #   a            #=> {:one => 1, :three => 3}
+    #   a.rand_key!  #~> :two
+    #   a            #~> {:one => 1, :three => 3}
     #
     def rand_key!
       k,v = rand_pair
@@ -275,7 +260,7 @@ module Random
 
     # Returns a random key-value pair.
     #
-    #   {:one => 1, :two => 2, :three => 3}.pick  #=> [:one, 1]
+    #   {:one => 1, :two => 2, :three => 3}.pick  #~> [:one, 1]
     #
     def rand_pair
       k = rand_key
@@ -285,8 +270,8 @@ module Random
     # Deletes a random key-value pair and returns that pair.
     #
     #   a = {:one => 1, :two => 2, :three => 3}
-    #   a.rand_pair!  #=> [:two, 2]
-    #   a             #=> {:one => 1, :three => 3}
+    #   a.rand_pair!  #~> [:two, 2]
+    #   a             #~> {:one => 1, :three => 3}
     #
     def rand_pair!
       k,v = rand_pair
@@ -298,8 +283,8 @@ module Random
 
     # Returns a random hash value.
     #
-    #   {:one => 1, :two => 2, :three => 3}.rand_value  #=> 2
-    #   {:one => 1, :two => 2, :three => 3}.rand_value  #=> 1
+    #   {:one => 1, :two => 2, :three => 3}.rand_value  #~> 2
+    #   {:one => 1, :two => 2, :three => 3}.rand_value  #~> 1
     #
     def rand_value
       fetch(rand_key)
@@ -308,8 +293,8 @@ module Random
     # Deletes a random key-value pair and returns the value.
     #
     #   a = {:one => 1, :two => 2, :three => 3}
-    #   a.at_rand!  #=> 2
-    #   a           #=> {:one => 1, :three => 3}
+    #   a.at_rand!  #~> 2
+    #   a           #~> {:one => 1, :three => 3}
     #
     def rand_value!
       k,v = rand_pair
@@ -326,7 +311,7 @@ module Random
     # in new random order.
     #
     #   h = {:a=>1, :b=>2, :c=>3}
-    #   h.shuffle_hash  #=> {:b=>2, :c=>1, :a>3}
+    #   h.shuffle  #~> {:b=>2, :c=>1, :a>3}
     #
     def shuffle
       ::Hash.zipnew( keys.sort_by{Random.number}, values.sort_by{Random.number} )
@@ -336,8 +321,8 @@ module Random
     # a new random order.
     #
     #   h = {:a => 1, :b => 2, :c => 3}
-    #   h.shuffle_hash!
-    #   h  #=> {:b=>2, :c=>1, :a=>3}
+    #   h.shuffle!
+    #   h  #~> {:b=>2, :c=>1, :a=>3}
     #
     def shuffle!
       self.replace(shuffle)
@@ -346,31 +331,26 @@ module Random
   end
 
   #
+  module StringExtensions
 
-  module String
-
+    #
     def self.included(base)
       base.extend(Self)
     end
 
     # Class-level methods.
-
     module Self
-
       # Returns a randomly generated string. One possible use is
       # password initialization. Takes a max legnth of characters
       # (default 8) and an optional valid char Regexp (default /\w\d/).
       #
-      #--
-      # CREDIT George Moschovitis
+      #   String.random    #~> 'dd4qed4r'
       #
-      # NOTE This is not very efficient. Better way?
+      # CREDIT George Moschovitis
+      #--
+      # TODO: This is not very efficient. Better way?
       #++
-
       def random(max_length = 8, char_re = /[\w\d]/)
-        # gmosx: this is a nice example of input parameter checking.
-        # this is NOT a real time called method so we can add this
-        # check. Congrats to the author.
         raise ArgumentError.new('char_re must be a regular expression!') unless char_re.is_a?(Regexp)
         string = ""
         while string.length < max_length
@@ -379,23 +359,12 @@ module Random
         end
         return string
       end
-
-      # Module method to generate a random letter.
-      #
-      #   String::Random.rand_letter  #=> "q"
-      #   String::Random.rand_letter  #=> "r"
-      #   String::Random.rand_letter  #=> "a"
-      #
-      def rand_letter
-        (Random.number(26) + (Random.number(2) == 0 ? 65 : 97) ).chr
-      end
-
     end
 
     # Return a random separation of the string.
     # Default separation is by charaacter.
     #
-    #   "Ruby rules".at_rand(' ')  #=> ["Ruby"]
+    #   "Ruby rules".at_rand(' ')  #~> ["Ruby"]
     #
     def at_rand( separator=// )
       #separator = self.class.patterns( separator )
@@ -406,8 +375,8 @@ module Random
     # from the string. Default separation is by character.
     #
     #   s = "Ruby rules"
-    #   s = at_rand!(' ')  #=> "Ruby"
-    #   s                  #=> "rules"
+    #   s.at_rand!(' ')    #~> "Ruby"
+    #   s                  #~> "rules"
     #
     def at_rand!( separator=// )
       #separator = self.class.patterns( separator )
@@ -421,7 +390,7 @@ module Random
 
     # Return a random byte of _self_.
     #
-    #   "Ruby rules".rand_byte  #=> 121
+    #   "Ruby rules".rand_byte  #~> 121
     #
     def rand_byte
       self[Random.number(size)]
@@ -430,8 +399,8 @@ module Random
     # Destructive rand_byte. Delete a random byte of _self_ and return it.
     #
     #   s = "Ruby rules"
-    #   s.rand_byte!      #=> 121
-    #   s                 #=> "Rub rules"
+    #   s.rand_byte!      #~> 121
+    #   s                 #~> "Rub rules"
     #
     def rand_byte!
       i = Random.number(size)
@@ -442,7 +411,7 @@ module Random
 
     # Return a random string index.
     #
-    #   "Ruby rules".rand_index  #=> 3
+    #   "Ruby rules".rand_index  #~> 3
     #
     def rand_index
       Random.number(size)
@@ -451,7 +420,7 @@ module Random
     # Return the string with seperated sections arranged
     # in a random order. The default seperation is by character.
     #
-    #   "Ruby rules".shuffle  #=> "e lybRsuur"
+    #   "Ruby rules".shuffle  #~> "e lybRsuur"
     #
     def shuffle(separator=//)
       split(separator).shuffle.join('')
@@ -467,23 +436,11 @@ module Random
 
 end
 
-class Object
-  include Random
-end
-
-class Range
-  include Random
-end
-
-class Array
-  include Random
-end
-
-class Hash
-  include Random
-end
-
-class String
-  include Random
-end
+class Range   ; include Random::RangeExtensions   ; end
+class Array   ; include Random::ArrayExtensions   ; end
+class Hash    ; include Random::HashExtensions    ; end
+class String  ; include Random::StringExtensions  ; end
+class Integer ; include Random::IntegerExtensions ; end
+class Numeric ; include Random::NumericExtensions ; end
 
+# Copyright (c) 2005 Ilmari Heikkinen, Christian Neukirchen, Thomas Sawyer