facets 2.9.3 → 3.0.0

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

@@ -3,6 +3,8 @@ module Kernel
   # Similar to __FILE__, __DIR__ provides the directory
   # path to the current executing script.
   #
+  # DEPRECATED: As of Ruby 2.0, which will have #__dir__ method.
+  #
   # CREDIT: Trans
 
   def __DIR__(*paths)

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

@@ -108,8 +108,9 @@ class As #:nodoc:
   end
 
   private
+
   def method_missing(sym, *args, &blk)
     @ancestor.instance_method(sym).bind(@subject).call(*args,&blk)
   end
-end
 
+end

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

@@ -1,56 +1 @@
-module Kernel
-
-  alias_method :pp_callstack, :caller
-  alias_method :pp_call_stack, :caller
-
-  # Parse a caller string and break it into its components,
-  # returning an array composed of:
-  #
-  # * file (String)
-  # * lineno (Integer)
-  # * method (Symbol)
-  #
-  # For example, from irb
-  #
-  #   call_stack(1)
-  #
-  # _produces_ ...
-  #
-  #   [["(irb)", 2, :irb_binding],
-  #    ["/usr/lib/ruby/1.8/irb/workspace.rb", 52, :irb_binding],
-  #    ["/usr/lib/ruby/1.8/irb/workspace.rb", 52, nil]]
-  #
-  # Note: If the user decides to redefine caller() to output data
-  # in a different format, _prior_ to requiring this, then the
-  # results will be indeterminate.
-  #
-  # CREDIT: Trans
-
-  def call_stack(level = 1)
-    call_str_array = pp_call_stack(level)
-    stack = []
-    call_str_array.each{ |call_str|
-      file, lineno, method = call_str.split(':')
-      if method =~ /in `(.*)'/ then
-        method = $1.intern()
-      end
-      stack << [file, lineno.to_i, method]
-    }
-    stack
-  end
-
-  alias_method :callstack, :call_stack
-
-end
-
-
-class Binding
-
-  # Returns the call stack, in array format.
-  def call_stack(level=1)
-    eval( "callstack( #{level} )" )
-  end
-
-  alias_method :callstack, :call_stack
-end
-
+require 'facets/kernel/callstack'

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

@@ -1 +1,56 @@
-require 'facets/kernel/call_stack'
+module Kernel
+
+  alias_method :pp_callstack, :caller
+  alias_method :pp_call_stack, :caller
+
+  # Parse a caller string and break it into its components,
+  # returning an array composed of:
+  #
+  # * file (String)
+  # * lineno (Integer)
+  # * method (Symbol)
+  #
+  # For example, from irb
+  #
+  #     callstack(1)
+  #
+  # _produces_ ...
+  #
+  #     [["(irb)", 2, :irb_binding],
+  #       ["/usr/lib/ruby/1.8/irb/workspace.rb", 52, :irb_binding],
+  #       ["/usr/lib/ruby/1.8/irb/workspace.rb", 52, nil]]
+  #
+  # Note: If the user decides to redefine caller() to output data
+  # in a different format, _prior_ to requiring this, then the
+  # results will be indeterminate.
+  #
+  # CREDIT: Trans
+
+  def callstack(level = 1)
+    call_str_array = pp_callstack(level)
+    stack = []
+    call_str_array.each{ |call_str|
+      file, lineno, method = call_str.split(':')
+      if method =~ /in `(.*)'/ then
+        method = $1.intern()
+      end
+      stack << [file, lineno.to_i, method]
+    }
+    stack
+  end
+
+  alias_method :call_stack, :callstack
+
+end
+
+
+class Binding
+
+  # Returns the call stack, in array format.
+  def callstack(level=1)
+    eval( "callstack( #{level} )" )
+  end
+
+  alias_method :call_stack, :callstack
+end
+

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

@@ -9,6 +9,8 @@ module Kernel
   #   constant("Process::Sys")            # => Process::Sys
   #   constant("Regexp::MULTILINE")       # => 4
   #
+  # TODO: As of Ruby 2.0, #constant can be deprecated, or aliased to #get_const.
+  #
   # CREDIT: Trans
 
   def constant(const)

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

@@ -1 +1,27 @@
-require 'facets/kernel/deep_copy'
+module Kernel
+
+  # Deep clone an object by deep cloning every instance
+  # variable as well.
+  #
+  # Returns [Object]
+
+  def deep_clone(cache={})
+    return cache[self] if cache.key?(self)
+
+    copy = clone()
+    cache[self] = copy
+
+    copy.instance_variables.each do |var|
+      val = instance_variable_get(var)
+      begin
+        val = val.deep_clone(cache)
+      rescue TypeError
+        next
+      end
+      copy.instance_variable_set(var, val)
+    end
+
+    return copy
+  end
+
+end

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

@@ -10,29 +10,5 @@ module Kernel
     Marshal::load(Marshal::dump(self))
   end
 
-  #
-  def deep_clone(cache={})
-    return cache[self] if cache.key?(self) #@deep_cloning_obj if @deep_cloning
-    copy = clone
-    cache[self] = copy #@deep_cloning_obj = clone
-    copy.instance_variables.each do |var|
-      val = instance_variable_get(var)
-      begin
-        #@deep_cloning = true
-        val = val.deep_clone(cache)
-      rescue TypeError
-        next
-      ensure
-        #@deep_cloning = false
-      end
-      copy.instance_variable_set(var, val)
-      #@deep_cloning_obj.instance_variable_set(var, val)
-    end
-    #deep_cloning_obj = @deep_cloning_obj
-    #@deep_cloning_obj = nil
-    #deep_cloning_obj
-    copy
-  end
-
 end
 

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

@@ -1,33 +1,2 @@
-require 'facets/functor'
-
-module Kernel
-
-  # Call methods on the eigenclass (i.e. the singleton_class).
-  #
-  #   name = "Tom"
-  #   name.eigen.define_method(:turkey){ self + " Turkey" }
-  #   name.turkey #=> "Tom Turkey"
-  #
-  # One the nice things you can do with #eigen, is define class attributes
-  # without having to open a `class << self` block.
-  #
-  #   c = Class.new do
-  #     eigen.attr_accessor :a
-  #   end
-  #   c.a = 1
-  #   c.a #=> 1
-  #
-  # NOTE: This was once called `#meta`, but meta is such a generic
-  # and overly used term that 'eigen' was decided upon as a better
-  # choice. You can thank or blame _why for the term, if you like.
-  #
-  def eigen
-    Functor.new do |op,*a,&b|
-      (class << self; self; end).class_eval do
-        __send__(op,*a,&b)
-      end
-    end
-  end
-
-end
-
+# Deprecated!
+require 'facets/kernel/meta'

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

@@ -9,7 +9,7 @@ module Kernel
   # I know what my Hallowe’en pumpkin is going to say.
   #
   # NOTE: This method is not a common core extension and is not
-  # loaded automatically when using <code>require 'facets'</code>.
+  # loaded automatically when using `require 'facets'`.
   #
   # CREDIT: WhyTheLuckyStiff
   #

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

@@ -11,7 +11,7 @@ module Kernel
   #   nil.ergo{ |o| o.foobar } #=> nil
   #
   # This is like #tap, but #tap yields self and returns self,
-  # where as #ergo yields self buit return the result.
+  # where as #ergo yields self but returns the result.
   #
   # CREDIT: Daniel DeLorme
 

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

@@ -1,8 +1,6 @@
 module Kernel
 
-  alias_method :_extend, :extend
-
-  private :_extend
+  extend_method = instance_method(:extend)
 
   # Extend an object with a module.
   #
@@ -21,9 +19,9 @@ module Kernel
   #
   # @author Trans
   # @author Marco Otte-Witte (bug fix)
-  def extend(*mod, &blk)
-    _extend(*mod) unless mod.empty?
-    _extend Module.new(&blk) if blk
+  define_method :extend do |*mod, &blk|
+    extend_method.bind(self).call(*mod) unless mod.empty?
+    extend_method.bind(self).call(Module.new(&blk)) if blk
     self
   end
 

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

@@ -2,18 +2,20 @@ module Kernel
 
   # Set instance variables using a hash.
   #
-  #   instance_assign('@a'=>1, '@b'=>2)
-  #   @a   #=> 1
-  #   @b   #=> 2
+  #     instance_assign('@a'=>1, '@b'=>2)
+  #     @a   #=> 1
+  #     @b   #=> 2
+  #
+  # NOTE: Conceptually a better alternative to this method is `instance.update`
+  #       from the `instance` gem. However, practically this method is probably 
+  #       the better choice until such time that Ruby supports anonymous delegators.
   #
-  # DEPRECATE: Use instance.update instead of #instance_assign.
-
   def instance_assign(hash)
     hash.each do |k,v|
       k = "@#{k}" if k !~ /^@/
       instance_variable_set(k, v)
     end
-    return self
+    self
   end
 
 end

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

@@ -0,0 +1,22 @@
+module Kernel
+
+  # Like `instance_assign`, but only assigns an instance variable if
+  # it does not already exist.
+  #
+  #     @a = 9
+  #     instance_extract('@a'=>1, '@b'=>2)
+  #     @a   #=> 9
+  #     @b   #=> 2
+  #
+  # CREDIT: T. Yamada
+
+  def instance_extract(hash)
+    hash.each do |k,v|
+      k = "@#{k}" if k !~ /^@/
+      instance_variable_set(k, v) unless instance_variable_defined?(k)
+    end
+    self
+  end
+
+end
+

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

@@ -0,0 +1,40 @@
+module Kernel
+
+  # Replace state of object with the state of another object of the
+  # same class (or superclass).
+  #
+  #     class ReplaceExample
+  #       attr_reader :a, :b
+  #       def initialize(a,b)
+  #         @a, @b = a, b
+  #       end
+  #     end
+  #
+  #     obj1 = ReplaceExample.new(1,2)
+  #     obj1.a  #=> 1
+  #     obj1.b  #=> 2
+  #
+  #     obj2 = ReplaceExample.new(3,4)
+  #     obj2.a  #=> 3
+  #     obj2.b  #=> 4
+  #
+  #     obj1.instance_replace(obj2)
+  #     obj1.a  #=> 3
+  #     obj1.b  #=> 4
+  #
+  # This is very similar to `instance.assign`, but it is limited
+  # by the class of object, in the same manner as Array#replace.
+  #
+  # NOTE: Conceptually a better alternative is `instance.replace` provided
+  #       by the `instance` gem. However, practically this method is probably 
+  #       the better choice until such time that Ruby support anonymous delegators.
+  #
+  def instance_replace(source)
+    raise ArgumentError, "not a #{self.class} -- #{source}" unless source.is_a?(self.class)
+    instance_variables.each do |iv|
+      instance_variable_set(iv, source.instance_variable_get(iv))
+    end
+  end
+
+end
+

data/lib/core/facets/kernel/{equate.rb → like.rb}

@@ -4,13 +4,16 @@ module Kernel
   # way equal to the reciever, starting with the identity
   # #equal?, then #eql?, then #==, and ending with #===.
   #
-  #   1.equate?(1.0)               #=> true
-  #   "string".equate?("string")   #=> true
-  #   String.equate?("string")     #=> true
+  #   1.like?(1.0)               #=> true
+  #   "string".likee?("string")   #=> true
+  #   String.like?("string")     #=> true
   #
-  def equate?(x)
+  def like?(x)
     equal?(x) || eql?(x) || self == x || self === x
   end
 
+  # @deprecated
+  alias :equate? :like?
+
 end
 

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

@@ -1 +1,25 @@
-require 'facets/kernel/require_relative'
+module Kernel
+
+  unless private_method_defined?(:load_relative)  # Will Ruby ever support out-of-the-box?
+
+    # Load file from same dir as calling script.
+    #
+    #   load_relative 'myscript'
+    #
+    # CREDIT: Paul Brannan, Pragmatic Programmers
+    #
+    def load_relative(relative_feature, safe=nil)
+      c = caller.first
+      fail "Can't parse #{c}" unless c.rindex(/:\d+(:in `.*')?$/)
+      file = $` # File.dirname(c)
+      if /\A\((.*)\)/ =~ file # eval, etc.
+        raise LoadError, "require_relative is called in #{$1}"
+      end
+      absolute = File.expand_path(relative_feature, File.dirname(file))
+      load absolute, safe
+    end
+
+  end
+
+end
+

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

@@ -0,0 +1,35 @@
+require 'facets/functor'
+
+module Kernel
+
+  # TODO: Should Kernel#eigen be moved to a functor gem?
+
+  # Call methods on the eigenclass (i.e. the singleton_class).
+  #
+  #     name = "Tom"
+  #     name.eigen.define_method(:turkey){ self + " Turkey" }
+  #     name.turkey #=> "Tom Turkey"
+  #
+  # One of the nice things you can do with #eigen is define class attributes
+  # without having to open a `class << self` block.
+  #
+  #     c = Class.new do
+  #       meta.attr_accessor :a
+  #     end
+  #     c.a = 1
+  #     c.a #=> 1
+  #
+  def meta
+    Functor.new do |op,*a,&b|
+      (class << self; self; end).class_eval do
+        __send__(op,*a,&b)
+      end
+    end
+  end
+
+  def eigen
+    warn "The `eigen' method is deprecated. Please use `meta' instead."
+    meta
+  end
+
+end