facets 2.1.3 → 2.2.0

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

@@ -1,21 +1,17 @@
-# TITLE:
+# = TITLE:
 #
 #   Object Methods
 #
-# FILE:
-#
-#   kernel/object
-#
-# DESCRIPTION:
+# = DESCRIPTION:
 #
 #   Kernel extension using object_ prefix which is beneficial
 #   to separation of metaprogramming from general programming.
 #   object_ methods, in contrast to the instance_ methods,
 #   do not access internal state.
 #
-# AUTHORS:
+# = AUTHORS:
 #
-#   CREDIT Thomas Sawyer
+#   - Thomas Sawyer
 
 module Kernel
 
@@ -38,6 +34,16 @@ module Kernel
   end
 
   # Send only to public methods.
+  #
+  #   class X
+  #     private
+  #     def foo; end
+  #   end
+  #
+  #   X.new.object_send(:foo)
+  #   => NoMethodError: private method `foo' called for #<X:0xb7ac6ba8>
+  #
+  #   CREDIT: Trans
   #--
   # Which implementation is faster?
   #++
@@ -60,34 +66,3 @@ module Kernel
   alias :__class__ :class
 
 end
-
-
-
-#  _____         _
-# |_   _|__  ___| |_
-#   | |/ _ \/ __| __|
-#   | |  __/\__ \ |_
-#   |_|\___||___/\__|
-#
-=begin test
-
-  require 'test/unit'
-
-  class TCKernel < Test::Unit::TestCase
-
-    def test_object_class
-      assert_equal( self.class, self.object_class )
-    end
-
-    def test_object_hexid
-      o = Object.new
-      assert( o.inspect.index( o.object_hexid ) )
-    end
-
-    def test__class__
-      assert_equal( self.class, self.__class__ )
-    end
-
-  end
-
-=end

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

@@ -1,7 +1,7 @@
-# TODO Is there any good way to avoid 'unless const_defined?'.
-
 module Kernel
 
+  # TODO: Is there any good way to avoid 'unless const_defined?'.
+
   unless const_defined?("OPERATORS")
     OPERATORS = %w{ +@ -@ + - ** * / % ~ <=> << >> < > === == =~ <= >= | & ^ []= [] }
     OPERATORS_REGEXP = Regexp.new( '(' << OPERATORS.collect{ |k| Regexp.escape(k) }.join('|') << ')' )
@@ -33,8 +33,30 @@ module Kernel
     }
   end
 
+  # Applies operator escape's according to OPERATORS_ESCAPE_TABLE.
+  #
+  #   op_esc('-') #=> "op_minus"
+  #
+  #   CREDIT: Trans
+
   def op_esc( str )
     str.gsub(OPERATORS_REGEXP){ OPERATORS_ESC_TABLE[$1] }
   end
 
+  # NOTE: op_esc used to support the method require_esc.
+  #
+  #   # Require a file with puncuation marks escaped.
+  #   #
+  #   #   require_esc '[].rb'
+  #   #
+  #   # in actuality requires the file 'op_fetch.rb'.
+  #
+  #   def require_esc( fpath )
+  #     fdir, fname = File.split(fpath)
+  #     ename = op_esc( fname )
+  #     case ename[-1,1] ; when '!','=','?' then ename = ename[0...-1] ; end
+  #     epath = File.join( fdir, ename )
+  #     require( epath )
+  #   end
+
 end

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

@@ -1,23 +1,19 @@
-# TITLE:
+# = TITLE:
 #
 #   Populate
 #
-# FILE:
-#
-#   kernel/populate.rb
-#
-# DESCRIPTION:
+# = DESCRIPTION:
 #
 #   Kernel extensions for setting object state or
 #   assigning variables.
 #
-# AUTHORS:
+# = AUTHORS:
 #
-#   CREDIT Thomas Sawyer
+#   - Thomas Sawyer
 #
-# NOTES:
+# = TODO:
 #
-#   TODO Change these to fit with object_ and instance_ conventions.
+#   - Change these to fit with object_ and instance_ conventions (?)
 
 #
 module Kernel
@@ -138,62 +134,3 @@ module Kernel
   end
 
 end
-
-
-
-
-#  _____         _
-# |_   _|__  ___| |_
-#   | |/ _ \/ __| __|
-#   | |  __/\__ \ |_
-#   |_|\___||___/\__|
-#
-=begin test
-
-  require 'test/unit'
-
-  class TestKernelPopulate < Test::Unit::TestCase
-
-#     def test_assign_from
-#       o = Object.new
-#       o.instance_eval{ @z=0; @a=1; @b=2 } #; @@a=3 }
-#       assign_from( o, "z", "@a", "@b" ) #, "@@a" )
-#       assert_equal( 1, @a )
-#       assert_equal( 2, @b )
-#       #assert_equal( 3, @@a )
-#     end
-
-    Customer = Struct.new( "Customer", :name, :address, :zip )
-
-    def test_set_from
-      bob = Customer.new("Bob Sawyer", "123 Maple, Anytown NC", 12345)
-      joe = Customer.new("Joe Pitare")
-      joe.set_from(bob, :address, :zip)
-      assert_equal("Joe Pitare", joe.name)
-      assert_equal("123 Maple, Anytown NC", joe.address)
-      assert_equal(12345, joe.zip)
-    end
-
-    Customer = Struct.new( "Customer", :name, :address, :zip )
-
-    def test_hash
-      bob = Customer.new()
-      x = { :name => "Bob Sawyer", :address => "123 Maple, Anytown NC", :zip => 12345 }
-      bob.set_with(x)
-      assert_equal(x[:name], bob.name)
-      assert_equal(x[:address], bob.address)
-      assert_equal(x[:zip], bob.zip)
-    end
-
-    def test_block
-      bob = Customer.new()
-      x = lambda {|s| s.name = "Bob Sawyer"; s.address = "123 Maple, Anytown NC"; s.zip = 12345 }
-      bob.set_with(&x)
-      assert_equal("Bob Sawyer", bob.name)
-      assert_equal("123 Maple, Anytown NC", bob.address)
-      assert_equal(12345, bob.zip)
-    end
-
-  end
-
-=end

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

@@ -1,36 +1,29 @@
-# TITLE:
-#
-#   Reporting Extensions
-#
-# DESCRIPTION:
-#
-#   Kernel extensions for debugging, warning and demoing.
-#
-# AUTHORS:
-#
-#   - TransDelabug
-
 module Kernel
+
   module_function
 
-  # Alternate to standard #p method that outputs
-  # Kernel#inspect to stdout, but also passes through
-  # the orginal argument(s).
-  #
-  #   x = 1
-  #   r = 4 + q(1)
-  #   p r
-  #
-  # produces
-  #
-  #   1
-  #   5
-  #
-  # DEPRECATE AS OF 1.9, _if_ #p will then do this too.
+  unless (RUBY_VERSION[0,3] == '1.9')
+
+    # Alternate to standard #p method that outputs
+    # Kernel#inspect to stdout, but also passes through
+    # the orginal argument(s).
+    #
+    #   x = 1
+    #   r = 4 + q(1)
+    #   p r
+    #
+    # produces
+    #
+    #   1
+    #   5
+    #
+    # DEPRECATE AS OF 1.9, _if_ #p will then do this too.
+
+    def p(*x)
+      x.each{ |e| puts e.inspect } #p(*x)
+      x.size > 1 ? x : x.last #x.last
+    end
 
-  def p(*x)
-    x.each{ |e| puts e.inspect } #p(*x)
-    x.size > 1 ? x : x.last #x.last
   end
 
   # Like #p but gives file and line number.
@@ -56,6 +49,10 @@ module Kernel
   #
   # Output:
   # The pretty printed string.
+  #
+  #   TODO: Deprecate in favor of Exception#detail.
+  #
+  #   CREDIT: George Moschovitis
 
   def pp_exception(ex)
     return %{#{ex.message}\n  #{ex.backtrace.join("\n  ")}\n  LOGGED FROM: #{caller[0]}}
@@ -74,10 +71,8 @@ module Kernel
   #   a.slice(1,2)            #=>  [2, 3]
   #   a.map { |x| x**3 }      #=>  [1, 8, 27]
   #
-  #--
-  # Is there a way to do this without the eval string in block?
-  # Preferably just a block and no string.
-  #++
+  #   TODO: Is there a way to do this without the eval string in block?
+  #         Preferably just a block and no string.
 
   def demo(out=$stdout,&block)
     out << sprintf("%-25s#=>  %s\n", expr = block.call, eval(expr, block.binding).inspect)

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

@@ -1,18 +1,14 @@
-# TITLE:
+# = TITLE:
 #
 #   Require / Load Extensions
 #
-# FILE:
-#
-#   requires.rb
-#
-# DESCRIPTION:
+# = DESCRIPTION:
 #
 #   Require/Load extensions.
 #
-# AUTHORS:
+# = AUTHORS:
 #
-#   CREDIT Thomas Sawyer
+#   - Thomas Sawyer
 
 #
 module Kernel
@@ -23,7 +19,7 @@ module Kernel
   #
   #   load_local 'templib'
   #
-  def load_local( fname, safe=nil )
+  def load_local(fname, safe=nil)
     #fdir = File.expand_path( File.dirname( caller[0] ) )
     fdir = File.dirname( caller[0] )
     load( File.join( fdir, fname ), safe )
@@ -33,7 +29,7 @@ module Kernel
   #
   #   require_local 'templib'
   #
-  def require_local( fname )
+  def require_local(fname)
     #fdir = File.expand_path( File.dirname( caller[0] ) )
     fdir = File.dirname( caller[0] )
     require( File.join( fdir, fname ) )
@@ -44,7 +40,7 @@ module Kernel
   #
   #   require_all 'facets/time/*'
   #
-  def require_all( pat )
+  def require_all(pat)
     $LOAD_PATH.each do |path|
       fs = Dir[File.join(path,pat)]
       unless fs.empty?
@@ -57,13 +53,3 @@ module Kernel
   end
 
 end
-
-
-#  _____         _
-# |_   _|__  ___| |_
-#   | |/ _ \/ __| __|
-#   | |  __/\__ \ |_
-#   |_|\___||___/\__|
-#
-# NO RESONABLE WAY TO DO
-# (THAT I CAN THINK OF)

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

@@ -3,11 +3,21 @@ module Kernel
   # Like #respond_to? but returns the result of the call
   # if it does indeed respond.
   #
-  # (This is used to be called #respond_with_value.)
+  #   class X
+  #     def f; "f"; end
+  #   end
   #
+  #   x = X.new
+  #   x.respond(:f)  #=> "f"
+  #   x.respond(:g)  #=> nil
+  #
+  #   CREDIT: Trans
+
   def respond(sym, *args)
     return nil if not respond_to?(sym, *args)
     send(sym, *args)
   end
 
+  alias_method :respond_with_value, :respond
+
 end

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

@@ -0,0 +1,50 @@
+module Kernel
+
+  # A Ruby-ized realization of the K combinator.
+  #
+  #   returning Book.new do |book|
+  #     book.title = "Imperium"
+  #     book.author = "Ulick Varange"
+  #   end
+  #
+  # Also aliased as #with.
+  #
+  #   def foo
+  #     with values = [] do
+  #       values << 'bar'
+  #       values << 'baz'
+  #     end
+  #   end
+  #
+  #   foo # => ['bar', 'baz']
+  #
+  # 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
+  # #returning from #with, however it also would require
+  # implementation in Ruby itself.
+  #
+  #   CREDIT: Mikael Brockman
+
+  def returning(obj=self)
+    yield obj
+    obj
+  end
+
+  alias_method :with, :returning
+
+  # Repeat loop until it yeilds false or nil.
+  #
+  #   a = [3, 2, 1]
+  #   complete do
+  #     b << a.pop
+  #   end
+  #   b  #=> [3, 2, 1, nil]
+  #
+  #  CREDIT: Trans
+
+  def complete
+    loop { break unless yield }
+  end
+
+end

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

@@ -1,15 +1,15 @@
-# TITLE:
+# = TITLE:
 #   Verbosity Reporting Extensions
 #
-# DESCRIPTION:
+# = DESCRIPTION:
 #   Kernel extensions dealing with verbosity of warnings
 #   and error messages.
 #
-# AUTHORS:
+# = AUTHORS:
 #   - David Heinemeier Hansson
 #   - TransSilentNight
 #
-# LOG:
+# = LOG:
 #   - trans 07.09.01 Deprecated #silently as alias of slience_warnings.
 
 module Kernel
@@ -22,6 +22,9 @@ module Kernel
   #   end
   #
   #   puts 'But this will'
+  #
+  #   CREDIT: David Heinemeier Hansson
+
   def silence_stream(stream)
     old_stream = stream.dup
     stream.reopen(RUBY_PLATFORM =~ /mswin/ ? 'NUL:' : '/dev/null')
@@ -32,7 +35,7 @@ module Kernel
   end
   #alias_method :silently, :silence_stream
 
-  # For compatibility
+  # For compatibility.
   def silence_stderr #:nodoc:
     silence_stream(STDERR) { yield }
   end
@@ -44,7 +47,8 @@ module Kernel
   #     value = noisy_call # no warning voiced
   #   end
   #
-  #   noisy_call # warning voiced
+  #   noisy_call  # no warning is voiced
+
   def silence_warnings
     old_verbose, $VERBOSE = $VERBOSE, nil
     yield
@@ -62,6 +66,8 @@ module Kernel
   end
 
   # Supress errors while executing a block, with execptions.
+  #
+  #   CREDIT: David Heinemeier Hansson
 
   def suppress(*exception_classes)
     begin yield
@@ -71,21 +77,3 @@ module Kernel
   end
 
 end
-
-
-
-=begin test
-
-  require 'test/unit'
-
-  class TestKernelError < Test::Unit::TestCase
-
-    def test_silently
-      silently do
-        assert( ! $VERBOSE )
-      end
-    end
-
-  end
-
-=end