facets 2.8.4 → 2.9.0.pre.1

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

@@ -1,12 +1,29 @@
-class Object
+class Object  # module Kernel ?
   # Get or set state of object.
   #
+  #   class StateExample
+  #     attr_reader :a, :b
+  #     def initialize(a,b)
+  #       @a, @b = a, b
+  #     end
+  #   end
+  #
+  #   obj = StateExample.new(1,2)
+  #   obj.a  #=> 1
+  #   obj.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.
   def object_state(data=nil)
     if data
       instance_variables.each do |iv|
         name = iv.to_s.sub(/^[@]/, '').to_sym
-        instance_variable_set(iv, snap[name])
+        instance_variable_set(iv, data[name])
       end
     else
       data = {}
@@ -56,8 +73,8 @@ class Struct
     end
   end
 
-  def replace(snap)
-    snap.each_pair {|k,v| send(k.to_s + "=", v)}
+  def replace(data)
+    data.each_pair {|k,v| send(k.to_s + "=", v)}
   end
 end
 

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

@@ -2,13 +2,13 @@ module Kernel
 
   # Alternate to standard #p method that outputs
   # Kernel#inspect to stdout, but also passes through
-  # the orginal argument(s).
+  # the orginal argument(s) ...
   #
   #   x = 1
-  #   r = 4 + q(1)
+  #   r = 4 + p(1)
   #   p r
   #
-  # produces
+  # produces ...
   #
   #   1
   #   5

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

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

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

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

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

@@ -1,7 +1,17 @@
 module Kernel
 
-  # Easy access to an object qua class, otherwise
-  # known as the object's singleton class.
+  # Easy access to an object qua class, otherwise known as the object's
+  # singleton class. #qua_class can also take a block.
+  #
+  #   string = "Hello World"
+  #
+  #   string.qua_class do
+  #     def important
+  #        self + "!"
+  #     end
+  #   end
+  #
+  #   string.important  #=> "Hello World!"
   #
   # Yes, another one.
   #
@@ -15,5 +25,7 @@ module Kernel
     end
   end
 
-end
+  # The +qua_class+ method can also be written +quaclass+.
+  alias_method :quaclass, :qua_class
 
+end

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

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

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

@@ -1,24 +1,40 @@
 module Kernel
 
-  # Require a pattern of files. This make is easy
-  # to require an entire directory, for instance.
+  # Require a pattern of files relatvie to the current file.
+  # This makes is easy to require an entire directory, for instance:
   #
-  #   require_all 'facets/time/*'
+  #   require_all 'core_ext/*'
   #
-  # You can also you #require_all relative to the
-  # current script simply by using __DIR__.
-  #
-  #   require_all(__DIR__ + '/foo/*')
-  #
-  def require_all(pat)
-    $LOAD_PATH.each do |path|
-      fs = Dir[File.join(path,pat)]
-      unless fs.empty?
-        fs.each { |f|
-          Kernel.require(f) unless File.directory?(f)
-        }
-        break;
-      end
+  # NOTE: This method used to allow glob-based requires from the $LOAD_PATH,
+  # but this was deprecated in favor of relative requiring only, as it is
+  # consider the typical usecase, and globbing from the $LOAD_PATH is a
+  # bit dangerous. Better options exist for globbing the $LOAD_PATH such as
+  # the +plugins+ gem.
+
+  def require_all(pattern)
+    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
+    glob = File.expand_path(pattern, File.dirname(file))
+    Dir.glob(glob).each do |absolute|
+      require absolute
+    end
+  end
+
+  # Same as #require_all, but for #load.
+  def load_all(pattern, 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
+    glob = File.expand_path(pattern, File.dirname(file))
+    Dir.glob(glob).each do |absolute|
+      load absolute, safe
     end
   end
 

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

@@ -1,10 +1,10 @@
 module Kernel
 
-  unless method_defined?(:require_relative) # 1.9
+  unless private_method_defined?(:require_relative) # 1.9
 
-    # Require file from same dir as calling script.
+    # Require file from same dir as calling script...
     #
-    #   require_local 'templib'
+    #   require_local 'myscript'
     #
     # CREDIT: Paul Brannan, Pragmatic Programmers
     #
@@ -21,14 +21,14 @@ module Kernel
 
   end
 
-  # Backward compatability.
-  alias_method :require_local, :require_relative
+  # DEPRECATED
+  # alias_method :require_local, :require_relative
 
-  unless method_defined?(:load_relative) # 1.9
+  unless private_method_defined?(:load_relative) # 1.9
 
-    # Load file from same dir as calling script.
+    # Load file from same dir as calling script...
     #
-    #   load_local 'templib'
+    #   load_local 'myscript'
     #
     # CREDIT: Paul Brannan, Pragmatic Programmers
     #
@@ -45,8 +45,8 @@ module Kernel
 
   end
 
-  # Backward compatability.
-  alias_method :load_local, :load_relative
+  # DEPRECATED
+  # alias_method :load_local, :load_relative
 
 end
 

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

@@ -1,23 +1,42 @@
+require 'facets/functor'
+
 module Kernel
 
   # Like #respond_to? but returns the result of the call
   # if it does indeed respond.
   #
-  #   class X
+  #   class RespondExample
   #     def f; "f"; end
   #   end
   #
-  #   x = X.new
+  #   x = RespondExample.new
   #   x.respond(:f)  #=> "f"
   #   x.respond(:g)  #=> nil
   #
-  # CREDIT: Trans
+  # or
+  #
+  #   x.respond.f   #=> "f"
+  #   x.respond.g   #=> nil
+  #
+  # This method was known as #try until Rails defined #try
+  # to be something more akin to #ergo.
+  #
+  # CREDIT: Trans, Chris Wanstrath
 
-  def respond(sym, *args)
-    return nil if not respond_to?(sym)
-    send(sym, *args)
+  def respond(sym=nil, *args, &blk)
+    if sym
+      return nil if not respond_to?(sym)
+      __send__(sym, *args, &blk)
+    else
+      ## TODO: use after 1.8.6 not supported anymore
+      ##Functor.new do |op, *a, &b|
+      ##  respond(op, *a, &b)
+      ##end
+      Functor.new(&method(:respond).to_proc)
+    end
   end
 
-  alias_method :respond_with_value, :respond
+  # DEPRECATED: #respond is enough.
+  #alias_method :respond_with_value, :respond
 
 end

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

@@ -2,11 +2,15 @@ module Kernel
 
   # A Ruby-ized realization of the K combinator.
   #
-  #   returning Book.new do |book|
+  #   book_class = Struct.new(:title, :author)
+  #
+  #   book = returning book_class.new do |book|
   #     book.title = "Imperium"
   #     book.author = "Ulick Varange"
   #   end
   #
+  #   book.class  #=> book_class
+  #
   # Technically, #returning probably should force the return of
   # the stated object irregardless of any return statements that
   # might appear within it's block. This might differentiate

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

@@ -1,6 +1,42 @@
 module Kernel
 
-  # Silences any stream for the duration of the block.
+  # Silence a stream and/or warnings...
+  #
+  #   silence(:stdout) do
+  #     puts "won't see me"
+  #   end
+  #
+  # Supported +streams+ are +stderr+, +stdout+, +verbose+, +debug+,
+  # and +warnings+, which is the same as +verbose+. You can also
+  # use the actual streams, STDERR and STDOUT.
+  def silence(*streams) #:yield:
+    streams = streams.map do |stream|
+      case stream
+      when :stderr
+        STDERR
+      when :stdout
+        STDOUT
+      else
+        stream
+      end
+    end
+
+    if streams.empty?
+      yield
+    else
+      silence_stream(*streams){ yield }
+    end
+  end
+
+  # Just like silence_stream, but will default to
+  # STDOUT, STDERR if no streams are given.
+
+  def silently(*streams) #:yeild:
+    streams = [STDOUT, STDERR] if streams.empty?
+    silence_stream(*streams){ yield }
+  end
+
+  # Silences any stream for the duration of the block...
   #
   #   silence_stream(STDOUT) do
   #     puts 'This will never be seen'
@@ -23,53 +59,15 @@ module Kernel
     end
   end
 
-  #
+  # Equivalent to `silence_stream(STDERR)`.
   def silence_stderr #:yeild:
     silence_stream(STDERR) { yield }
   end
 
-  #
+  # Equivalent to `silence_stream(STDOUT)`.
   def silence_stdout #:yeild:
     silence_stream(STDOUT) { yield }
   end
 
-  # Just like silence_stream, but will default to
-  # STDOUT, STDERR if no streams are given.
-
-  def silently(*streams) #:yeild:
-    streams = [STDOUT, STDERR] if streams.empty?
-    silence_stream(*streams){ yield }
-  end
-
-  # Sets $VERBOSE to nil for the duration of the block
-  # and back to its original value afterwards.
-  #
-  #   silence_warnings do
-  #     value = noisy_call # no warning voiced
-  #   end
-  #
-  #   noisy_call  # no warning is voiced
-  #
-  # CREDIT: David Heinemeier Hansson
-
-  def silence_warnings
-    old_verbose, $VERBOSE = $VERBOSE, nil
-    yield
-  ensure
-    $VERBOSE = old_verbose
-  end
-
-  # Sets $VERBOSE to true for the duration of the block
-  # and back to its original value afterwards.
-  #
-  # CREDIT: David Heinemeier Hansson
-
-  def enable_warnings
-    old_verbose, $VERBOSE = $VERBOSE, true
-    yield
-  ensure
-    $VERBOSE = old_verbose
-  end
-
 end
 

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

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

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

@@ -1,20 +1,9 @@
 module Kernel
 
   # Easy access to an object's "special" class.
-  #
-  # <b>This is part of Ruby as of 1.9.2+.</b>
-  #
-  # NOTE: This used to support a class eval block,
-  # but to comply with Ruby 1.9.2's definition
-  # it has been removed.
 
   def singleton_class(&block)
-    #if block_given?
-    #  (class << self; self; end).class_eval(&block)
-    #else
-      (class << self; self; end)
-    #end
-  end unless method_defined? :singleton_class
+    (class << self; self; end)
+  end unless method_defined?(:singleton_class)
 
 end
-

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

@@ -0,0 +1,11 @@
+module Kernel
+
+  # Returns method of a parent class bound to self.
+  def super_method(klass, meth)
+    unless self.class.ancestors.include?(klass)
+      raise ArgumentError, "Not an ancestor for super_method-- #{klass}"
+    end
+    klass.instance_method(meth).bind(self)
+  end
+
+end

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

@@ -4,16 +4,24 @@ module Kernel
 
     # The tap K-Combinator. This yields self -and- returns self.
     #
-    # Note, Ruby 1.9+ does not appear to support the zero arity 
-    # instance_eval option.
-    #
-    def tap(&b)
-      if block_given?
-        b.arity == 1 ? yield(self) : instance_eval(&b)
-      end
+    # Note, Ruby 1.9+ does not support the zero arity #instance_eval
+    # variation so it has been deprecated.
+    def tap #:yield:
+      yield(self)
       self
     end
 
+    #--
+    # == Old definition
+    #
+    #
+    #   def tap #:yield:
+    #     if block_given?
+    #       b.arity == 1 ? yield(self) : instance_eval(&b)
+    #     end
+    #     return self
+    #   end
+    #
     # == Future definition?
     #
     # This is a consideration for a future #tap using Functor:
@@ -32,6 +40,7 @@ module Kernel
     # It would allow a single call, before returning the original.
     # However there are not very many useful things you can do with
     # that.
+    #++
 
   end