facets 2.9.0.pre.1 → 2.9.0.pre.2

data/AUTHORS

@@ -9,6 +9,7 @@
 The following developers have recently contributed to the development of Facets.
 They are held in the highest regard for their efforts.
 
+* Alexey Petrushin     Some methods from `ruby-ext` project.
 * Michael Harmer       Documentation Improvements
 * Lavir the Whiolet    Improved Range#at_rand and added File#ext.
 * Jean-Denis Vauguet   Added Pathname#visit.

data/COPYING

@@ -1,8 +1,7 @@
 
  Ruby Facets
 
- Copyright (c) 2005 Thomas Sawyer
- Copyright (c) 2008 TigerOps / Thomas Sawyer
+ Copyright (c) 2005,2010 Thomas Sawyer
 
 
  THE RUBY LICENSE

data/HISTORY.rdoc

@@ -27,6 +27,10 @@ extensions you want, thus avoiding any conflicts. There are actually only a
 dozen or so overlaps and all are intended to compatible, but it doesn't hurt
 to be sure.
 
+Lastly, it is worth mentioning that this release has been more thuroughly
+tested than any version of Facets to date. Thanks to RVM this release runs
+green on Ruby 1.8.6, 1.8.7 and 1.9.2.
+
 Changes:
 
 * New Features
@@ -44,10 +48,13 @@ Changes:
   * Add Module#anonymous?
   * Add Module#copy_inheritor
   * Add Indexable#from and Indexable#upto
-  * Add Array#from and Array#upto
+  * Add Array#from and Array#thru
   * Add NA class via na.rb
   * Add Memoizable in memoizable.rb for a more robust memoization system
   * Add Module#safe_memo in thread.rb for thread safe memoization
+  * Add Kernel#sandbox in thread.rb for threaded $SAFE=4 evaluation
+  * Add Hash#subset
+  * Add numerous Math extensions
 
 * Deprecations
 
@@ -59,9 +66,8 @@ Changes:
   * Deprecate Kernel#populate and #set_from (use #assign and #assign_from)
   * Deprecate Kernel#non_nil? since #not_nil? is enough
   * Deprecate #__HERE__ b/c implementation was unreliable
-  * Deprecate Array#upto and Indexable#upto, use #thru instead
-  * Deprecate Time#since, use #ago instead
-  * Deprecate Time#advance, use #in instead  TODO
+  * Deprecate Time#since, use #less instead
+  * Deprecate Time#advance, use #shift instead
   * Deprecate Kernel#super_as (no good way to get callers method name)
   * Deprecate Integer#clear_bit, use #bit_clear instead
   * Deprecate Kernel#resc, use String#to_re or #to_rx instead
@@ -90,6 +96,8 @@ Changes:
   * Rename String#chars             to String#characters
   * Rename String#outdent           to String#unindent
   * Rename Time#round               to Time#round_to
+  * Rename Time#hence               to Time#shift (but keep aliases)
+  * Rename Hash#zipnew              to Hash#zip
 
 * Moved Libraries
 
@@ -121,15 +129,15 @@ Changes:
 * Improved Features
 
   * New lib/tour division of libraries
-  * Module#class_extend synamically creates append_features method
+  * Module#class_extend dynamically creates append_features method
   * Kernel#require_all is only for relative requires
   * __DIR__ can take subdirectory arguments
   * Hash#join has more sensible default separator (' ')
-  * A few OpEsc escapes have been renamed
+  * Some OpEsc escapes have been renamed
   * Kernel#assign does not accept a block
-  * Kernel#try is like ActiveSupport version
+  * Kernel#try is now like ActiveSupport's
   * Improved #respond (which is like old #try)
-  * Remove all `if defined?(ActiveSupport)`
+  * Remove all `if defined?(ActiveSupport)` conditions
   * Use #random_range to support specialized Range#at_rand functionality
   * Use Comparable.[] instead of Comparable()
   * Array#rotate rotates in opposite direction than before (b/c or Ruby 1.9)

data/lib/core/facets/hash/subset.rb

@@ -0,0 +1,24 @@
+class Hash
+
+  # Take a subset of the hash, based on keys given or a block
+  # that evaluates to true for each hash key.
+  #
+  #   {'a'=>1, 'b'=>2}.subset('a')            #=> {'a'=>1}
+  #   {'a'=>1, 'b'=>2}.subset{|k| k == 'a' }  #=> {'a'=>1}
+  #
+  # CREDIT: Alexey Petrushin
+  def subset(keys=nil, &block)
+    h = {}
+    if keys
+      self.each do |k, v|
+        h[k] = v if keys.include?(k)
+      end
+    else
+      self.each do |k, v|
+        h[k] = v if block.call(k)
+      end
+    end
+    h
+  end
+
+end

data/lib/core/facets/hash/zip.rb

@@ -0,0 +1,18 @@
+class Hash
+
+  # Creates a new hash from two separate arrays, a +keys+ array and
+  # a +values+ array.
+  #
+  #   Hash.zip(["a","b","c"], [1,2,3])
+  #   # => { "a"=>1, "b"=>2, "c"=>3 }
+  #
+  # CREDIT: Trans, Ara T. Howard
+
+  def self.zip(keys,values) # or some better name
+    h = {}
+    keys.size.times{ |i| h[ keys[i] ] = values[i] }
+    h
+  end
+
+end
+

data/lib/core/facets/kernel/try.rb

@@ -18,7 +18,7 @@ module Kernel
   #
   # or:
   #
-  #   @example? @example.name : nil
+  #   @example ? @example.name : nil
   #
   # But with try
   #
@@ -26,9 +26,9 @@ module Kernel
   #
   # or
   #
-  #   @example.try.name  #=> "bob"
+  #   @example.try.name    #=> "bob"
   #
-  # It also accepts arguments and/or a block, for the method it is trying:
+  # It also accepts arguments and a block, for the method it is trying:
   #
   #   @people.try(:collect){ |p| p.name }
   #

data/lib/core/facets/module/home.rb

@@ -0,0 +1,90 @@
+class Module
+
+  # Returns the module or class containing the receiver.
+  #
+  #   module ::HomeExample
+  #     module M
+  #       module N
+  #       end
+  #     end
+  #   end
+  #
+  #   HomeExample::M::N.home  #=> HomeExample::M
+  #
+  # The home of a top-level module/class is Object.
+  #
+  #   HomeExample.home   #=> Object
+  #
+  # This method is called *home* because techinally a module or class
+  # is just a constant reference, and as such can reside with multiple
+  # namespaces, like any variable. For example:
+  #
+  #   module OtherPlace
+  #     M = ::HomeExample::M
+  #   end
+  #
+  # In this example, you might think that +OtherPlace::M+'s home would be
+  # +OtherPlace+, but +OtherPlace::M+ is the same object as +HomeExample::M+,
+  # and it can have only one "home" --the original location of it's definition.
+  def home
+    #homename = /::[^:]+\Z/ =~ name ? $` : nil
+    if homename
+      homename.split(/::/).inject(self) do |mod, cref|
+        if /\:(0x.*?)\>$/ =~ cref   # TODO: does this ever happen?
+          #p $1.to_i(16)
+          ObjectSpace._idref($1.to_i(16))
+        else
+          mod.const_get(cref)
+        end
+      end
+    else
+      Object
+    end
+  end
+
+  # Returns the name of module or class containing the receiver.
+  #
+  #   module ::HomeExample
+  #     module M
+  #       module N
+  #       end
+  #     end
+  #   end
+  #
+  #   HomeExample::M::N.homename  #=> "HomeExample::M"
+  #
+  # See also Module#basename.
+  def homename
+    /::[^:]+\Z/ =~ name ? $` : nil
+  end
+
+  # Original name for #homename.
+  alias_method :modname, :homename
+
+  # Returns all the namespaces of this module according ordered from
+  # nearest and moving outwards. The receiver is not contained within
+  # the result.
+  #
+  #   module ::HouseExample
+  #     module M
+  #       module N
+  #       end
+  #     end
+  #   end
+  #
+  #   HouseExample.housing        #=> [Object]
+  #   HouseExample::M.housing     #=> [HouseExample, Object]
+  #   HouseExample::M::N.housing  #=> [HouseExample::M, HouseExample, Object]
+  #
+  # Compare this to +Module.nesting+.
+  def housing
+    n = []
+    name.split(/::/).inject(self) do |mod, cref|
+      c = mod.const_get(cref) ; n.unshift(c) ; c
+    end
+    n << Object # ?
+    n.shift # we really don't need +self+ too.
+    n
+  end
+
+end

data/lib/core/facets/module/homename.rb

@@ -0,0 +1 @@
+require 'facets/module/home'

data/lib/core/facets/module/housing.rb

@@ -0,0 +1 @@
+require 'facets/module/home'

data/lib/core/facets/module/modname.rb

@@ -1,22 +1 @@
-class Module
-
-  # Returns the name of the module containing this one.
-  #
-  #   module ::NSExample
-  #     module M
-  #       module N
-  #       end
-  #     end
-  #   end
-  #
-  #   NSExample::M::N.modname  #=> "NSExample::M"
-  #
-  # See also Module#basename.
-  def modname
-    unless defined? @_modname
-      @_modname = name =~ /::[^:]+\Z/ ? $`.freeze : nil
-    end
-    @_modname
-  end
-
-end
+require 'facets/module/homename'

data/lib/core/facets/na.rb

@@ -6,10 +6,16 @@
 #
 # NA is also used to represent an argument "slot" for Proc#partial.
 #
-# NA is a subclass of ArgumentError.
+# NA is an instance of ArgumentError.
 
-class NA < ArgumentError
-  class << self
-    def method_missing(*); self; end
-  end
+class << NA = ArgumentError.new
+  def inspect ; 'N/A' ; end
+  def method_missing(*); self; end
 end
+
+# NA is a subclass of ArgumentError.
+#class NA < ArgumentError
+#  class << self
+#    def method_missing(*); self; end
+#  end
+#end

data/lib/core/facets/object/clone.rb

@@ -0,0 +1 @@
+require 'facets/object/dup'

data/lib/core/facets/{kernel/try_dup.rb → object/dup.rb}

@@ -1,73 +1,79 @@
-module Kernel
+class Object
   # Override this in a child class if it cannot be dup'ed.
   #
   #   obj1 = Object.new
-  #   obj2 = obj1.try_dup
+  #   obj2 = obj1.dup!
   #   obj2.equal?(obj1)    #=> false
   #
   # CREDIT: Dan Kubb (extlib)
-  def try_dup
+  def dup!
     dup
   end
 
-  # Alternative name for #try_dup.
-  def dup!
-    try_dup
+  # Alternative name for #dup!
+  def try_dup
+    dup!
   end
+
+  # Can you safely call #dup on this object?
+  #
+  # Returns +false+ for +nil+, +false+, +true+, symbols, and numbers;
+  # +true+ otherwise.
+  def dup?   ; true ; end
+  def clone? ; true ; end
 end
 
-class TrueClass
-  # Since TrueClass is immutable it cannot be duplicated.
+class NilClass
+  # Since NilClass is immutable it cannot be duplicated.
   # For this reason #try_dup returns +self+.
   #
-  #   true.try_dup  #=> true
+  #   nil.dup!  #=> nil
   #
-  def try_dup
-    self
-  end
+  def dup!   ; self  ; end
+  def dup?   ; false ; end
+  def clone? ; false ; end
 end
 
 class FalseClass
   # Since FalseClass is immutable it cannot be duplicated.
   # For this reason #try_dup returns +self+.
   #
-  #   false.try_dup  #=> false
+  #   false.dup!  #=> false
   #
-  def try_dup
-    self
-  end
+  def dup!   ; self  ; end
+  def dup?   ; false ; end
+  def clone? ; false ; end
 end
 
-class NilClass
-  # Since NilClass is immutable it cannot be duplicated.
+class TrueClass
+  # Since TrueClass is immutable it cannot be duplicated.
   # For this reason #try_dup returns +self+.
   #
-  #   nil.try_dup  #=> nil
+  #   true.dup!  #=> true
   #
-  def try_dup
-    self
-  end
+  def dup!   ; self  ; end
+  def dup?   ; false ; end
+  def clone? ; false ; end
 end
 
-class Numeric
-  # Since Numeric is immutable it cannot be duplicated.
+class Symbol
+  # Since Symbol is immutable it cannot be duplicated.
   # For this reason #try_dup returns +self+.
   #
-  #   1.try_dup  #=> 1
+  #   :a.dup!  #=> :a
   #
-  def try_dup
-    self
-  end
+  def dup!   ; self  ; end
+  def dup?   ; false ; end
+  def clone? ; false ; end
 end
 
-class Symbol
-  # Since Symbol is immutable it cannot be duplicated.
+class Numeric
+  # Since Numeric is immutable it cannot be duplicated.
   # For this reason #try_dup returns +self+.
   #
-  #   :a.try_dup  #=> :a
+  #   1.dup!  #=> 1
   #
-  def try_dup
-    self
-  end
+  def dup!   ; self  ; end
+  def dup?   ; false ; end
+  def clone? ; false ; end
 end
-

data/lib/core/facets/{kernel → object}/object_state.rb

@@ -1,5 +1,6 @@
-class Object  # module Kernel ?
-  # Get or set state of object.
+class Object
+  # Get or set state of object. You can think of #object_state as an in-code
+  # form of marshalling.
   #
   #   class StateExample
   #     attr_reader :a, :b
@@ -12,13 +13,18 @@ class Object  # module Kernel ?
   #   obj.a  #=> 1
   #   obj.b  #=> 2
   #
+  #   obj.object_state  #=> {:a=>1, :b=>2}
+  #
   #   obj.object_state(:a=>3, :b=>4)
   #   obj.a  #=> 3
   #   obj.b  #=> 4
   #
-  # TODO: Would #instance_state be a more appropriate name?
-  #
-  # TODO: Consider how this relates to #instance.
+  # For most object's this is essentially the same as <code>instance.to_h</code>.
+  # But for data structures like Array and Hash it returns a snapshot of their
+  # contents, not the state of their instance variables.
+  #--
+  # TODO: Should this be in module Kernel ?
+  #++
   def object_state(data=nil)
     if data
       instance_variables.each do |iv|
@@ -34,35 +40,31 @@ class Object  # module Kernel ?
       data
     end
   end
-
-  # Replace state of object.
-  def replace(data)
-    instance_variables.each do |iv|
-      name = iv.to_s.sub(/^[@]/, '').to_sym
-      instance_variable_set(iv, data[name])
-    end
-  end
 end
 
 class Array
+  #
   def object_state(data=nil)
     data ? replace(data) : dup
   end
 end
 
 class String
+  #
   def object_state(data=nil)
     data ? replace(data) : dup
   end
 end
 
 class Hash
+  #
   def object_state(data=nil)
     data ? replace(data) : dup
   end
 end
 
 class Struct
+  #
   def object_state(data=nil)
     if data
       data.each_pair {|k,v| send(k.to_s + "=", v)}
@@ -72,9 +74,4 @@ class Struct
       data
     end
   end
-
-  def replace(data)
-    data.each_pair {|k,v| send(k.to_s + "=", v)}
-  end
 end
-