facets-glimmer 3.2.0

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

@@ -0,0 +1,26 @@
+module Kernel
+
+  # Repeat loop until it yeilds false or nil.
+  #
+  #   a = [3, 2, 1]
+  #   b = []
+  #
+  #   complete do
+  #     x = a.pop
+  #     b << x
+  #     x
+  #   end
+  #
+  #   b  #=> [1, 2, 3, nil]
+  #
+  # Be "aware" when using this method, it easy to accidently
+  # induce infinite loops.
+  #
+  # CREDIT: Trans
+
+  def complete
+    loop { break unless yield }
+  end
+
+end
+

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

@@ -0,0 +1,27 @@
+module Kernel
+
+  # Like #p but gives file and line number...
+  #
+  #   d("hi")
+  #
+  # produces ...
+  #
+  #   "hi" (/home/dave/projects/foo.rb, 38)
+  #
+  def d(*x)
+    puts "#{x.inspect} #{caller[0]}"
+    return *x
+  end
+  
+  #--
+  # Old definition ...
+  #
+  #   def d(*x)
+  #     puts "#{__FILE__}, #{__LINE__}"
+  #     x.each{ |e| puts e.inspect } #p(*x)
+  #     x.size > 1 ? x : x.last #x.last
+  #   end
+  #++
+
+end
+

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

@@ -0,0 +1,27 @@
+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

@@ -0,0 +1,14 @@
+module Kernel
+
+  # Anything that can be marshaled can be copied in totality.
+  #
+  #   "ABC".deep_copy  #=> "ABC"
+  #
+  # NOTE: Not sure why we wouldn't just call this #copy, but
+  # the term +deep_copy+ seems to be the common practive.
+  def deep_copy
+    Marshal::load(Marshal::dump(self))
+  end
+
+end
+

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

@@ -0,0 +1,30 @@
+module Kernel
+
+  # TODO: Is there a way to do this without the eval string in block?
+  # Preferably just a block and no string.
+
+  # For debugging and showing examples. Currently this
+  # takes an argument of a string in a block...
+  #
+  #   demo {%{ a = [1,2,3] }}
+  #   demo {%{ a.slice(1,2) }}
+  #   demo {%{ a.map { |x| x**3 } }}
+  #
+  # produces ...
+  #
+  #   a = [1,2,3]             #=>  [1, 2, 3]
+  #   a.slice(1,2)            #=>  [2, 3]
+  #   a.map { |x| x**3 }      #=>  [1, 8, 27]
+  #
+  # NOTE: This method is not a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  #
+  # @uncommon
+  #   require 'facets/kernel/demo'
+  #
+  def demo(out=$stdout,&block)
+    out << sprintf("%-25s#=>  %s\n", expr = block.call, eval(expr, block.binding).inspect)
+  end
+
+end
+

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

@@ -0,0 +1,26 @@
+module Kernel
+
+  #
+  # CREDIT: Trans
+
+  def disable_warnings #:yield:
+    verbose, $VERBOSE = $VERBOSE, nil
+    yield
+  ensure
+    $VERBOSE = verbose
+  end
+
+  # DEPRECATE: Use #disable_warnings instead.
+  alias_method :silence_warnings, :disable_warnings
+
+  #
+  # CREDIT: Trans
+
+  def enable_warnings #:yield:
+    verbose, $VERBOSE = $VERBOSE, true
+    yield
+  ensure
+    $VERBOSE = verbose
+  end
+
+end

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

@@ -0,0 +1,2 @@
+# Deprecated!
+require 'facets/kernel/meta'

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

@@ -0,0 +1,24 @@
+module Kernel
+
+  # During this trying time when no one can get their
+  # techie catchwords to stick to the refrigerator no
+  # matter how hard they slap it with the enchanted
+  # magnetic spatula, it’s good to know that the
+  # contrived phrases really do fly, graceful and
+  # unclasped and bearing north toward chilled shrimp.
+  # 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 `require 'facets'`.
+  #
+  # CREDIT: WhyTheLuckyStiff
+  #
+  # @uncommon
+  #   require 'facets/kernel/eigenclass'
+  #
+  def eigenclass
+    (class << self; self; end)
+  end
+
+end
+

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

@@ -0,0 +1 @@
+require 'facets/kernel/disable_warnings'

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

@@ -0,0 +1,43 @@
+require 'facets/functor'
+
+module Kernel
+
+  # Yield self -or- return self.
+  #
+  #   "a".ergo.upcase #=> "A"
+  #   nil.ergo.foobar #=> nil
+  #
+  #   "a".ergo{ |o| o.upcase } #=> "A"
+  #   nil.ergo{ |o| o.foobar } #=> nil
+  #
+  # This is like #tap, but #tap yields self and returns self,
+  # where as #ergo yields self but returns the result.
+  #
+  # CREDIT: Daniel DeLorme
+
+  def ergo(&b)
+    if block_given?
+      b.arity == 1 ? yield(self) : instance_eval(&b)
+    else
+      self
+    end
+  end
+
+end
+
+class NilClass
+  FUNCTOR = Functor.new{ nil }
+  
+  # Compliments Kernel#ergo.
+  #
+  #   "a".ergo{ |o| o.upcase } #=> "A"
+  #   nil.ergo{ |o| o.bar }    #=> nil
+  #
+  # CREDIT: Daniel DeLorme
+
+  def ergo
+    FUNCTOR unless block_given?
+  end
+
+end
+

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

@@ -0,0 +1,28 @@
+module Kernel
+
+  extend_method = instance_method(:extend)
+
+  # Extend an object with a module.
+  #
+  # If a block is given, it will be evaluated into an anonymous
+  # module and used to extend the object.
+  #
+  #   obj = Object.new
+  #
+  #   obj.extend do
+  #     def foo; "foo"; end
+  #   end
+  #
+  #   obj.foo  #=> "foo"
+  #
+  # NOTE: This is one of the few core overrides in Facets.
+  #
+  # @author Trans
+  # @author Marco Otte-Witte (bug fix)
+  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
+
+end

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

@@ -0,0 +1,12 @@
+module Kernel
+
+  # TODO: Must reduce the number of singleton method methods.
+
+  # Don't say it!
+  #
+  def extension
+    class << self; self; end
+  end
+
+end
+

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

@@ -0,0 +1,2 @@
+require 'facets/kernel/true'
+

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

@@ -0,0 +1,11 @@
+module Kernel
+
+  # A shorthand pronoun for binding().
+  #
+  #   a = 3
+  #   eval("a", here)  #=> 3
+  #
+  alias_method :here, :binding
+
+end
+

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

@@ -0,0 +1,44 @@
+require 'facets/class/hierarchically'
+
+module Kernel
+
+  # Send a message to each ancestor in an object's class hierarchy.
+  # The method will only be called if the method is defined for the
+  # ancestor.
+  # 
+  # This can be very useful for setting up a `preinitialize` system.
+  #
+  #   m = Module.new do
+  #         attr :a
+  #         def preinitialize
+  #           @a = 1
+  #         end
+  #       end
+  #         
+  #   c = Class.new do
+  #         include m
+  #         def initialize
+  #           hierarchical_send(:preinitialize)
+  #         end
+  #       end
+  #
+  #   c.new.a  #=> 1
+  #
+  # @todo Include singleton class?
+  def hierarchical_send(method_name, *args, &block)
+    method_name = method_name.to_s if RUBY_VERSION < '1.9'
+    this = self
+    self.class.hierarchically do |anc|
+      ## is there really no better way to check for the method?
+      if anc.instance_methods(false).include?(method_name) or
+           anc.public_instance_methods(false).include?(method_name) or
+           anc.private_instance_methods(false).include?(method_name) or
+           anc.protected_instance_methods(false).include?(method_name)
+        im = anc.instance_method(method_name)
+        ##im.arity == 0 ? im.bind(this).call(&block) : im.bind(this).call(*args, &block)
+        im.bind(this).call(*args, &block)
+      end
+    end
+  end
+
+end

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

@@ -0,0 +1,4 @@
+module Kernel
+  alias_method :identical?, :equal?
+end
+

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

@@ -0,0 +1,13 @@
+module Kernel
+
+  # Is self included in other?
+  #
+  #   5.in?(0..10)       #=> true
+  #   5.in?([0,1,2,3])   #=> false
+  #
+  def in?(other)
+    other.include?(self)
+  end
+
+end
+

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

@@ -0,0 +1,22 @@
+module Kernel
+
+  # Set instance variables using a hash.
+  #
+  #     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.
+  #
+  def instance_assign(hash)
+    hash.each do |k,v|
+      k = "@#{k}" if k !~ /^@/
+      instance_variable_set(k, v)
+    end
+    self
+  end
+
+end
+

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

@@ -0,0 +1,26 @@
+module Kernel
+
+  # Kernel extension prefixed by instance_ which provide
+  # internal (eg private) access to the object.
+  # Kernel extension using instance_ prefix which is beneficial
+  # to separation of metaprogramming from general programming.
+  # object_ methods, in contrast to the instance_ methods,
+  # do not access internal state.
+
+  # Easy access to an object qua class, otherwise known
+  # as the object's metaclass or singleton class. This
+  # implemnetation alwasy returns the class, even if a
+  # block is provided to eval against it...
+  #
+  #     It is what it is.
+  #     But I think I like this one best.
+  #
+  # CREDIT: Trans
+
+  def instance_class(&block)
+    (class << self; self; end).module_eval(&block) if block
+    (class << self; self; end)
+  end
+
+end
+

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

@@ -0,0 +1,47 @@
+class Object #module Kernel
+
+  unless method_defined?(:instance_exec) # 1.9
+
+    require 'thread'
+
+    module InstanceExecMethods #:nodoc:
+    end
+
+    include InstanceExecMethods
+
+    # Evaluate the block with the given arguments within the context of
+    # this object, so self is set to the method receiver.
+    #
+    # From Mauricio's http://eigenclass.org/hiki/bounded+space+instance_exec
+    #
+    # This version has been borrowed from Rails for compatibility sake.
+    #
+    # NOTE: This is not a common core extension (due to the use of thread.rb)
+    # and is not loaded automatically when using <code>require 'facets'</code>.
+    # However it is a core method in Ruby 1.9, so this only matters for users
+    # of Ruby 1.8.x or below.
+    #
+    # @uncommon
+    #   require 'facets/kernel/instance_exec'
+    #
+    def instance_exec(*args, &block)
+      begin
+        old_critical, Thread.critical = Thread.critical, true
+        n = 0
+        n += 1 while respond_to?(method_name = "__instance_exec#{n}")
+        InstanceExecMethods.module_eval { define_method(method_name, &block) }
+      ensure
+        Thread.critical = old_critical
+      end
+
+      begin
+        __send__(method_name, *args)
+      ensure
+        InstanceExecMethods.module_eval { remove_method(method_name) } rescue nil
+      end
+    end
+
+  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/instance_send.rb

@@ -0,0 +1,7 @@
+module Kernel
+
+  # Private send.
+  alias_method :instance_send, :__send__
+
+end
+

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

@@ -0,0 +1,19 @@
+module Kernel
+
+  # Broad equality. Checks to see if the object +x+ is in any
+  # way equal to the reciever, starting with the identity
+  # #equal?, then #eql?, then #==, and ending with #===.
+  #
+  #   1.like?(1.0)               #=> true
+  #   "string".like?("string")   #=> true
+  #   String.like?("string")     #=> true
+  #
+  def like?(x)
+    equal?(x) || eql?(x) || self == x || self === x
+  end
+
+  # @deprecated
+  alias :equate? :like?
+
+end
+

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

@@ -0,0 +1 @@
+require 'facets/kernel/require_all'

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

@@ -0,0 +1,25 @@
+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/maybe.rb

@@ -0,0 +1,19 @@
+module Kernel
+
+  # 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
+      yield if rand < chance
+    else
+      rand < chance
+    end
+  end
+
+end
+

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

@@ -0,0 +1,44 @@
+require 'facets/binding/eval'
+require 'facets/kernel/__method__'
+
+module Kernel
+
+  # Global memo cache.
+  $MEMO ||= {}
+
+  # Memoize a method.
+  # 
+  #   class MemoExample
+  #     attr_accessor :a
+  #     def m
+  #       memo{ @a }
+  #     end
+  #   end
+  #
+  #   ex = MemoExample.new
+  #
+  #   ex.a = 10
+  #   ex.m  #=> 10
+  #
+  #   ex.a = 20
+  #   ex.m  #=> 10
+  #
+  # NOTE: This method is not a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  #
+  # @uncommon
+  #   require 'facets/kernel/memo'
+  #
+  def memo(*args, &block)
+    if args.empty?
+      args = block.binding.eval('[self, __method__]')
+    end
+    if $MEMO.key?(args)
+      $MEMO[args]
+    else
+      $MEMO[args] = block.call
+    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