facets 2.8.4 → 2.9.0.pre.1

data/lib/more/facets/memoizable.rb

@@ -0,0 +1,141 @@
+# Memoization is an optimization technique used primarily to speed up 
+# programs by having function calls avoid repeating the calculation
+# of results for previously-processed inputs.
+#
+# When you "memoize" a method/function using Memoizable its results are cached
+# so that later calls return results from the cache instead of recalculating
+# them.
+#
+#   class T
+#     include Memoizable
+#
+#     def initialize(a)
+#       @a = a
+#     end
+#
+#     def a
+#       "#{@a ^ 3 + 4}"
+#     end
+#
+#     memoize :a
+#   end
+#
+#   t = T.new(10)
+#   (t.a.__id__ == t.a.__id__)  #=> true
+#
+# This method can also be used at the instance level to cache singleton
+# (qua class) methods by including it in the singleton class.
+#
+#--
+# TODO: It would be very cool if Memoizable could set-up default parameters
+# via #[] method, e.g. `include Memoizable[:freeze=>true]`.
+#++
+
+module Memoizable
+
+  @cache = Hash.new{|h,k|h[k]=Hash.new{|h,k|h[k]={}}}
+
+  #
+  def self.cache
+    @cache
+  end
+
+  #
+  def self.append_features(base)
+    Module == base ? super(base) : base.extend(self)
+  end
+
+  # Directive for making your functions faster by trading space for time.
+  # When you "memoize" a method/function using #memoize its results are
+  # cached so that later calls with the same arguments return results from
+  # the cache instead of recalculating them.
+  #
+  # The #memoize method also handles a few options to alter
+  # behavior of the memoization:
+  #
+  #   :class     => true      cache per-class not per-object
+  #   :freeze    => true      freeze the memoized return values
+  #   :arguments => false     do not index cache by arguments
+  #
+  def memoize(*method_names)
+    options = Hash === method_names.last ? method_names.pop : {}
+
+    options[:arguments] = true if options[:arguments].nil?  # default to true
+
+    ref = options[:class]     ? 'self.class.name'       : 'self'
+    frz = options[:freeze]    ? '.freeze'               : ''
+    arg = options[:arguments] ? '[__a__, block_given?]' : 'nil'
+
+    code = ""
+    method_names.each do |m|
+      code << <<-code
+        alias_method '#{ m }:memo', '#{ m }'
+        private '#{ m }:memo'
+        def #{ m }(*__a__,&__b__)
+          c = Memoizable.cache[#{ref}][:'#{ m }']
+          k = #{arg}
+          if c.has_key?(k)
+            c[k]
+          else
+            c[k] = __send__('#{ m }:memo',*__a__,&__b__)#{frz}
+          end
+        end
+      code
+    end
+    module_eval(code)
+  end
+
+  # Remove the memoized value from the memoization cache.
+  # The next time a memoized methos is called if will be
+  # remomoized.
+  def rememoize(*method_names)
+    if Memoizable.cache[self]
+      if method_names.empty?
+        Memoizable.cache.delete(self)
+      else
+        method_names.each do |m|
+          Memoizable.cache[self].delete(m.to_sym)
+        end
+      end
+    end
+    if Memoizable.cache[self.class.name]
+      if method_names.empty?
+        Memoizable.cache.delete(self.class.name)
+      else
+        method_names.each do |m|
+          Memoizable.cache[self.class.name].delete(m.to_sym)
+        end
+      end
+    end
+  end
+
+  #
+  def unmemoize(*method_names)
+    rememoize(*method_names)
+    method_names.each do |m|
+      alias_method name, "#{ m }:memo"
+    end
+  end
+
+  # Include Memoizable alone with an #initialize_copy method that
+  # will copy the memoization cache when #dup or #clone is used.
+  #
+  # TODO: Is this best approach? Perhaps a method to easily create
+  # the #initialize_copy method would suffice?
+  module Copy
+
+    #
+    def self.included(base)
+      base.extend(Memoizable)
+    end 
+
+    #
+    def initialize_copy(original)
+      if Memoizable.cache.key?(original)
+        Memoizable.cache[self] = Memoizable.cache[original].dup
+      end
+    end
+
+  end
+
+end

data/lib/{core → more}/facets/metaid.rb

@@ -2,6 +2,6 @@ require 'facets/kernel/meta_alias'
 require 'facets/kernel/meta_class'
 require 'facets/kernel/meta_def'
 require 'facets/kernel/meta_eval'
-require 'facets/kernel/eigenclass'
-require 'facets/module/class_def'
 
+ # in remberence of _why
+require 'facets/kernel/eigenclass'

data/lib/more/facets/multipliers.rb

@@ -1,41 +1,6 @@
-# = Multipliers
-#
-# == Synopsis
-#
-# Adds methods to Numeric to make working with magnitudes
-# (kilo, mega, giga, milli, micro, etc.)
-#
-# == History
-#
-#   Thanks to Rich Kilmer and bytes.rb which inspired this library.
-#
-# == Notes
-#
-# * This library is not compatible with STICK's units.rb (an spin-off
-#   of Facets old units.rb library). Do not attempt to use both at
-#   the same time.
-#
-# == Authors
-#
-# * Thomas Sawyer
-#
-# == Copying
-#
-# Copyright (c) 2005 Thomas Sawyer
-#
-# Ruby License
-#
-# This module is free software. You may use, modify, and/or redistribute this
-# software under the same terms as Ruby.
-#
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-# FOR A PARTICULAR PURPOSE.
-
-#
 class Numeric
 
-  # = Multipliers
+  # = Numeric::Multipliers
   #
   # Adds methods to Numeric to make working with
   # magnitudes (kilo, mega, giga, milli, micro, etc.)
@@ -48,9 +13,11 @@ class Numeric
   # perform the inverse operation by placing the
   # multiplier called on unit (1) in the denominator.
   #
-  #   1000 / 1.kilo        #=> 1
-  #   1024 / 1.kibi        #=> 1
+  #   (1000 / 1.kilo)        #=> 1
+  #   (1024 / 1.kibi)        #=> 1
   #
+  # Thanks to Rich Kilmer and bytes.rb which inspired this library.
+
   module Multipliers
 
     # SI Multipliers
@@ -95,3 +62,4 @@ class Numeric
   include Multipliers
 end
 
+# Copyright (c) 2005 Thomas Sawyer

data/lib/more/facets/multiton.rb

@@ -60,7 +60,7 @@
 # the uniqueness of an object. To workaround this, define the _class_
 # method ::multiton_id.
 #
-#   def Klass.multiton_id(*args, &block)
+#   def SomeMultitonClass.multiton_id(*args, &block)
 #     # ...
 #   end
 #
@@ -121,7 +121,7 @@ require 'thread'
 # the uniqueness of an object. To workaround this, define the _class_
 # method ::multiton_id.
 #
-#   def Klass.multiton_id(*args, &block)
+#   def SomeMultitonClass.multiton_id(*args, &block)
 #     # ...
 #   end
 #
@@ -130,19 +130,19 @@ require 'thread'
 
 module Multiton
 
-  #  disable build-in copying methods
+  # Disable build-in copying methods.
 
   def clone
     raise TypeError, "can't clone Multiton #{self}"
-    #self
+    ##self
   end
 
   def dup
     raise TypeError, "can't dup Multiton #{self}"
-    #self
+    ##self
   end
 
-  # default marshalling strategy
+  # Default marshalling strategy.
 
   protected
 
@@ -170,13 +170,13 @@ module Multiton
     end
   end
 
-  # Multiton can be included in another module, in which case that module effectively becomes
-  # a multiton behavior distributor too. This is why we propogate #included to the base module.
-  # by putting it in another module.
+  # Multiton can be included in another module, in which case that module
+  # effectively becomes a multiton behavior distributor too. This is why we
+  # propogate #included to the base module by putting it in another module.
   #
   #--
   #    def append_features(mod)
-  #      #  help out people counting on transitive mixins
+  #      # help out people counting on transitive mixins
   #      unless mod.instance_of?(Class)
   #        raise TypeError, "Inclusion of Multiton in module #{mod}"
   #      end
@@ -188,8 +188,8 @@ module Multiton
     private
     def included(base)
       class << base
-        #alias_method(:new!, :new) unless method_defined?(:new!)
-        # gracefully handle multiple inclusions of Multiton
+        ##alias_method(:new!, :new) unless method_defined?(:new!)
+        ## gracefully handle multiple inclusions of Multiton
         unless include?(Multiton::MetaMethods)
           alias_method :new!, :new
           private :allocate #, :new
@@ -275,7 +275,7 @@ end
 
 
 =begin
-# TODO Convert this into a real test and/or benchmark.
+# TODO: Convert this into a real test and/or benchmark.
 
 if $0 == __FILE__
 
@@ -384,3 +384,4 @@ if $0 == __FILE__
 
 end
 =end
+

data/lib/more/facets/nullclass.rb

@@ -1,27 +1,3 @@
-# = NullClass
-#
-# NullClass is essentially NilClass but it differs in one
-# important way. When a method is called against it that it
-# deoesn't have, it will simply return null value rather then
-# raise an error.s
-#
-# == Authors
-#
-# * Thomas Sawyer
-#
-# = Copying
-#
-# Copyright (c) 2005 Thomas Sawyer
-#
-# Ruby License
-#
-# This module is free software. You may use, modify, and/or redistribute this
-# software under the same terms as Ruby.
-#
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-# FOR A PARTICULAR PURPOSE.
-
 # = Nullclass
 #
 # NullClass is essentially NilClass but it differs in one
@@ -29,8 +5,8 @@
 # deoesn't have, it will simply return null value rather then
 # raise an error.
 #
-# TODO: Perhaps NullClass and NackClass should be one and the same?
-#
+# TODO: Perhaps NullClass should be called NackClass?
+
 class NullClass #< NilClass
   class << self
     def new
@@ -59,16 +35,4 @@ class Object
   end
 end
 
-
-
-#  _____         _
-# |_   _|__  ___| |_
-#   | |/ _ \/ __| __|
-#   | |  __/\__ \ |_
-#   |_|\___||___/\__|
-#
-
-# TODO
-
-=begin #testing
-=end
+# Copyright (c) 2005 Thomas Sawyer

data/lib/more/facets/opesc.rb

@@ -1,25 +1,40 @@
 # = OpEsc
 #
+# NOTE: As of v3.0 of Facets these have been renamed:
+#
+#    op_plus_self   -> op_plus
+#    op_minus_self  -> op_minus
+#    op_plus        -> op_add
+#    op_minus       -> op_sub
+#    op_case_eq     -> op_case
+#
+# TODO: In the future we might also rename:
+#
+#    op_lshift      -> op_push
+#    op_rshift      -> op_pull
+#    op_store       -> op_index
+#    op_fetch       -> op_index  (b/c [] and []= in same file)
+
 module OpEsc
 
   OPERATORS = %w{ +@ -@ + - ** * / % ~ <=> << >> < > === == =~ <= >= | & ^ []= [] }
   OPERATORS_REGEXP = Regexp.new( '(' << OPERATORS.collect{ |k| Regexp.escape(k) }.join('|') << ')' )
   OPERATORS_ESC_TABLE = {
-      "+@"   => "op_plus_self",
-      "-@"   => "op_minus_self",
-      "+"    => "op_plus",
-      "-"    => "op_minus",
+      "+@"   => "op_plus",
+      "-@"   => "op_minus",
+      "+"    => "op_add",
+      "-"    => "op_sub",
       "**"   => "op_pow",
       "*"    => "op_mul",
       "/"    => "op_div",
       "%"    => "op_mod",
       "~"    => "op_tilde",
       "<=>"  => "op_cmp",
-      "<<"   => "op_lshift",
-      ">>"   => "op_rshift",
+      "<<"   => "op_lshift",  #push?
+      ">>"   => "op_rshift",  #pull?
       "<"    => "op_lt",
       ">"    => "op_gt",
-      "==="  => "op_case_eq",
+      "==="  => "op_case",
       "=="   => "op_equal",
       "=~"   => "op_apply",
       "<="   => "op_lt_eq",
@@ -33,28 +48,32 @@ module OpEsc
 
   # Applies operator escape's according to OPERATORS_ESCAPE_TABLE.
   #
-  #   op_esc('-') #=> "op_minus"
+  #   OpEsc.escape('-') #=> "op_sub"
   #
   # CREDIT: Trans
 
   def self.escape(str)
-    str.gsub(OPERATORS_REGEXP){ OPERATORS_ESC_TABLE[$1] }
+    str.to_s.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
+  def self.method_to_filename(name)
+    fname = escape(name)
+    fname = fname[0...-1] if fname =~ /[\!\=\?]$/
+    fname
+  end
+
+  ## 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)
+  ##     fname = method_to_filename(fname)
+  ##     path = File.join(fdir, fname)
+  ##     require(path)
+  ##   end
 
 end

data/lib/more/facets/ostruct.rb

@@ -1,29 +1,3 @@
-# = OpenStruct
-#
-# Ruby's standard OpenStruct with a few extensions added-in.
-#
-# == Auhtors
-#
-# * Thomas Sawyer
-#
-# == Copying
-#
-# Copyright (c) 2005 Thomas Sawyer, George Moschovitis
-#
-# Ruby License
-#
-# This module is free software. You may use, modify, and/or redistribute this
-# software under the same terms as Ruby.
-#
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-# FOR A PARTICULAR PURPOSE.
-#
-# == History
-#
-# * 2006-11-04 trans  Deprecate #instance in favor of #instance_delegate.
-# * 2007-04-15 trans  Filled out with actual methods, used "ostruct_" for some accessors.
-
 require 'ostruct'
 
 class OpenStruct
@@ -54,7 +28,6 @@ class OpenStruct
   # the block. You can not provide both at the same time.
   #
   # CREDIT: Noah Gibbs, Gavin Sinclair
-  #
   def initialize(hash=nil, &block)
     if block && block.arity==2
       @table = Hash.new(&block)
@@ -106,37 +79,30 @@ class OpenStruct
     @table[key]=val
   end
 
-  # CREDIT: Robert J. Berger <rberger AT ibd.com>
-  # Thanks for reporting issues that this method resolved.
-
   # Provides access to an OpenStruct's inner table.
   #
   #   o = OpenStruct.new
   #   o.a = 1
   #   o.b = 2
-  #   o.instance_delegate.each { |k, v| puts "#{k} #{v}" }
-  #
-  # produces
-  #
-  #   a 1
-  #   b 2
-  #
+  #   o.instance_delegate.map { |k, v| "#{k} #{v}" }
+  #   #=> ["a 1", "b 2"]
   #
   def instance_delegate
     @table
   end
 
+  #
   alias ostruct_delegate instance_delegate
 
   # Insert/update hash data on the fly.
   #
   #   o = OpenStruct.new
-  #   o.ostruct_update { :a => 2 }
+  #   o.ostruct_update(:a => 2)
   #   o.a  #=> 2
   #
   def ostruct_update(other)
     raise TypeError, "can't modify frozen #{self.class}", caller(1) if self.frozen?
-    #other = other.to_hash  #to_h ?
+    ##other = other.to_hash  #to_h ?
     for k,v in other
       @table[k.to_sym] = v
     end
@@ -146,8 +112,8 @@ class OpenStruct
   # Merge hash data creating a new OpenStruct object.
   #
   #   o = OpenStruct.new
-  #   o.ostruct_merge { :a => 2 }
-  #   o.a  #=> 2
+  #   x = o.ostruct_merge(:a => 2)
+  #   x.a  #=> 2
   #
   def ostruct_merge(other)
     o = dup
@@ -155,21 +121,21 @@ class OpenStruct
     o
   end
 
-  ##
+  #--
   # TO BE DEPRECATED
   # Must consider that accessing instance_delegate instead can be dangerous.
   # Might we us a Functor to ensure the table keys are always symbols?
-  ##
+  #++
 
   # Insert/update hash data on the fly.
   #
   #   o = OpenStruct.new
-  #   o.ostruct_update { :a => 2 }
+  #   o.ostruct_update(:a => 2)
   #   o.a  #=> 2
   #
   def __update__(other)
     raise TypeError, "can't modify frozen #{self.class}", caller(1) if self.frozen?
-    #other = other.to_hash #to_h?
+    ##other = other.to_hash #to_h?
     for k,v in other
       @table[k.to_sym] = v
     end
@@ -179,14 +145,20 @@ class OpenStruct
   # Merge hash data creating a new OpenStruct object.
   #
   #   o = OpenStruct.new
-  #   o.ostruct_merge { :a => 2 }
-  #   o.a  #=> 2
+  #   x = o.ostruct_merge(:a => 2)
+  #   x.a  #=> 2
   #
   def __merge__(other)
     o = dup
     o.__update__(other)
     o
   end
+
+  #
+  def to_ostruct
+    self
+  end
+
 end
 
 
@@ -194,7 +166,7 @@ class Hash
 
   # Turns a hash into a generic object using an OpenStruct.
   #
-  #   o = { 'a' => 1 }.to_ostruct
+  #   o = {'a' => 1}.to_ostruct
   #   o.a  #=> 1
   #
   def to_ostruct
@@ -203,8 +175,8 @@ class Hash
 
   # Like to_ostruct but recusively objectifies all hash elements as well.
   #
-  #     o = { 'a' => { 'b' => 1 } }.to_ostruct_recurse
-  #     o.a.b  #=> 1
+  #   o = {'a' => { 'b' => 1 }}.to_ostruct_recurse
+  #   o.a.b  #=> 1
   #
   # The +exclude+ parameter is used internally to prevent infinite
   # recursion and is not intended to be utilized by the end-user.
@@ -212,12 +184,11 @@ class Hash
   # would like to prevent from being converted to an OpoenStruct
   # then include it in the +exclude+ hash referencing itself. Eg.
   #
-  #     h = { 'a' => { 'b' => 1 } }
-  #     o = h.to_ostruct_recurse( { h['a'] => h['a'] } )
-  #     o.a['b']  #=> 1
+  #   h = { 'a' => { 'b' => 1 } }
+  #   o = h.to_ostruct_recurse( { h['a'] => h['a'] } )
+  #   o.a['b']  #=> 1
   #
   # CREDIT: Alison Rowland, Jamie Macey, Mat Schaffer
-
   def to_ostruct_recurse(exclude={})
     return exclude[self] if exclude.key?( self )
     o = exclude[self] = OpenStruct.new
@@ -227,11 +198,13 @@ class Hash
     end
     o.__update__(h)
   end
+end
 
-  #--
-  # Special thanks to Alison Rowland, Jamie Macey and Mat Schaffer
-  # for inspiring recursive improvements.
-  #++
-
+class NilClass
+  # Create an empty OpenStruct object.
+  def to_ostruct
+    OpenStruct.new
+  end
 end
 
+# Copyright (c) 2005 Thomas Sawyer (Ruby License)