facets 1.1.0 → 1.2.0

data/lib/facets/more/multiton.rb

@@ -0,0 +1,359 @@
+#--
+# Multiton
+#
+# Copyright (c) 2005 Florian Frank, 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.
+#
+#
+# ==========================================================================
+# Revision History ::
+# --------------------------------------------------------------------------
+#  2005-11-27   trans    * Simplifed variations to one.
+#  2005-08-01   trans    * Minor modifications to documentation.
+#  2005-02-01   trans    * Added New and Semi variations.
+# ==========================================================================
+#++
+
+#:title: Multiton
+#
+# Multiton module that ensures only one object to be allocated for a given
+# argument list.
+#
+# The 'multiton' pattern is similar to a singleton, but instead of only one
+# instance, there are several similar instances.  It is useful when you want to
+# avoid constructing objects many times because of some huge expense (connecting
+# to a database for example), require a set of similar but not identical
+# objects, and cannot easily control how many times a contructor may be called.
+#
+# == Synopsis
+#
+#   class SomeMultitonClass
+#     include Multiton
+#     attr :arg
+#     def initialize(arg)
+#       @arg = arg
+#     end
+#   end
+#
+#   a = SomeMultitonClass.new(4)
+#   b = SomeMultitonClass.new(4)	 # a and b are same object
+#   c = SomeMultitonClass.new(2)   # c is a different object
+#
+# == Previous Behavior
+#
+# In previous versions of Multion the #new method was made 
+# private and #instance was used in its stay --just like Singleton.
+# But this has proved less desirable for Multiton b/c a Multion can
+# have multiple instances not just one. So instead we define #create
+# as a private alias of the original #new method (should it be needed)
+# and then #new is overridden with #instance as an alias for it.
+# So if you must have exact old behavior all you need do is re-alias
+# #new to #create and privatize it.
+#
+#   class SomeMultitonClass
+#     include Multiton
+#     alias_method :new, :create
+#     private :new
+#     ...
+#   end
+#
+# == How It Works
+#
+# A pool of objects is searched for a previously cached object,
+# if one is not found we construct one and cache it in the pool
+# based on class and the args given to the contructor.
+#
+# A limitation of this approach is that it is impossible to
+# detect if different blocks were given to a contructor (if it takes a
+# block).  So it is the constructor arguments _only_ which determine
+# the uniqueness of an object. A workaround is for the class to define
+# the _class_ method ::multiton_id.
+#
+#   def Klass.multiton_id(*args, &block)
+#     # ...
+#   end
+#
+# Which should return a hash key used to identify the object being
+# constructed as (not) unique.
+#
+# == Author(s)
+#
+# * Florian Frank
+# * Thomas Sawyer
+#
+
+module Multiton
+
+  # pools of objects cached on class type
+  POOLS = {}
+
+  # method which can be defined by a class to determine object uniqueness
+  MULTITON_ID_HOOK = :multiton_id
+
+  # method which can be defined by a class to create multiton objects 
+  MULTITON_NEW_HOOK = :multiton_new
+
+  def self.append_features( klass )
+
+    class << klass
+
+      alias_method :create, :new
+      private :create
+
+      def new(*args, &block)
+        # if the class defined 'multiton_id' we use this as the key
+        # otherwise we simply use the argument list.
+        k = (respond_to?(MULTITON_ID_HOOK) ? send(MULTITON_ID_HOOK, *args, &block) : args)
+        unless (obj = (POOLS[self] ||= {})[k])
+          begin
+            critical = Thread.critical
+            Thread.critical = true
+            if self.respond_to?(MULTITON_NEW_HOOK)
+              obj = (POOLS[self][k] = self.send(MULTITON_NEW_HOOK, *args, &block))
+            else
+              obj = (POOLS[self][k] = super)
+            end
+          ensure
+            Thread.critical = critical # restore state
+          end
+        end
+        return obj
+      end
+
+      alias_method :instance, :new
+
+    end
+
+  end
+
+end
+
+# Deprecated use, now use #private_multiton method after including Multiton
+#
+#  module MultitonInstance
+#
+#   def self.append_features(klass)
+#     klass.private_class_method(:new)
+#     def klass.instance(*args, &block)
+#       # if the class has #multiton_id we use this as the key
+#       # otherwise we simply use the argument list.
+#       k = (respond_to?(MULTITON_ID_HOOK) ? send(MULTITON_ID_HOOK, *args, &block) : args)
+#       unless (obj = (POOLS[self] ||= {})[k])
+#         begin
+#           critical = Thread.critical
+#           Thread.critical = true
+#           meth = self.respond_to?(MULTITON_NEW_HOOK) ? MULTITON_NEW_HOOK : :new
+#           obj = (POOLS[self][k] = self.send(meth, *args, &block))
+#         ensure
+#           Thread.critical = critical # restore state
+#         end
+#       end
+#       return obj
+#     end
+#   end
+# 
+# end
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+
+=begin test
+
+  require 'test/unit'
+
+  #
+  # EXAMPLE A - STANDARD USAGE
+  #
+  class TC_Multiton_A < Test::Unit::TestCase
+
+    class SomeMultitonClass
+      include Multiton
+      attr :arg
+      def initialize(arg)
+        @arg = arg
+      end
+    end
+
+    def test_standard
+
+      a = SomeMultitonClass.instance(4)
+      b = SomeMultitonClass.instance(4)     # a and b are same object
+      c = SomeMultitonClass.instance(2)     # c is a different object
+
+      assert_equal( a, b )
+      assert_equal( 42, [a.arg,b.arg].max * 10 + c.arg )
+
+    end
+
+  end
+
+
+  #
+  # EXAMPLE B - MODIFY AN EXISTING CLASS, SHARED FILEHANDLES
+  #
+  class TC_Multiton_B < Test::Unit::TestCase
+
+    class ::File
+      include Multiton
+    end
+
+    def test_modify_existing
+
+      lineno = __LINE__
+      # HERE1
+      # HERE2
+
+      a = File.instance(__FILE__)
+      b = File.instance(__FILE__)
+
+      assert_equal( a, b )
+
+      lineno.times{ a.gets }
+
+      assert_equal( "# HERE1", a.gets.strip )
+      assert_equal( "# HERE2", b.gets.strip )
+
+    end
+
+  end
+
+  #
+  # EXAMPLE C - INHERITENCE
+  #
+  class TC_Multiton_C < Test::Unit::TestCase
+
+    class A < String
+      include Multiton
+    end
+
+    # B is also a multiton - with it's OWN object cache
+    class B < A; end
+
+    def test_inheritence
+
+      # w is the same object as x, y is the same object as z
+      w,x,y,z = A.instance('A'), A.instance('A'), B.instance('B'), B.instance('B')
+
+      assert_equal( w.object_id, x.object_id ) # -> true
+      assert_equal( y.object_id, z.object_id ) # -> true
+
+      a = B.instance('A')
+      b = B.instance('A')
+
+      assert_not_equal( a.object_id, w.object_id ) # -> false (each class has it's own pool)
+      assert_equal( a.object_id, b.object_id )     # -> true
+
+    end
+
+  end
+
+
+  #
+  # EXAMPLE D - MULTIPLE MODULE INCLUSION (does nothing)
+  #
+  class TC_Multiton_D < Test::Unit::TestCase
+
+    class A < String
+      include Multiton
+    end
+
+    # B is also a multiton - with it's OWN object cache
+    class B < A; end
+
+    def test_multiple
+
+      # w is the same object as x, y is the same object as z
+      w,x,y,z = A.instance('A'), A.instance('A'), B.instance('B'), B.instance('B')
+
+      yz_id = y.object_id || z.object_id
+
+      B.class_eval {
+        include Multiton
+      }
+
+      # y is not only the same object as z, but they are both the same object(s)
+      # as from EXAMPLE C
+
+      y,z = B.instance('B'), B.instance('B')
+
+      assert_equal( y.object_id, yz_id )   # -> true
+      assert_equal( z.object_id, yz_id ) # -> true
+
+    end
+
+  end
+
+  #
+  # EXAMPLE E - SO YOU WANNA USE NEW INSTEAD OF INSTANCE...
+  #
+  class TC_Multiton_E < Test::Unit::TestCase
+
+    module K
+      # use an inner class which is itself a multiton
+      class K < String; include Multiton; end
+
+      # define a new which returns a mutltion using #instance... 
+      class << self
+        def new(*args, &block)
+          K.instance *args, &block
+        end
+      end
+    end
+
+    def test_new
+
+      the = K.new '4'
+      answer = K.new '2'
+
+      assert_equal( "42", sprintf( "%s%s", the, answer ) )  #-> 42
+      assert_equal( K::K, the.class )  #-> K::K
+
+    end
+
+  end
+
+  #
+  # EXAMPLE F - using Klass.multiton_id 
+  #
+  class TC_Multiton_F < Test::Unit::TestCase
+
+    class Klass
+      include Multiton
+
+      def initialize( important, not_important )
+        @important, @not_important = important, not_important
+      end
+
+      def Klass.multiton_id(*args, &block)
+        # we consider only the first arg
+        important, not_important = *args
+        important
+      end
+    end
+
+    def test_using_id
+      a = Klass.instance( :a, :b )
+      b = Klass.instance( :a, :c )
+      c = Klass.instance( :b, :b )
+
+      assert_equal( a, b )
+      assert_not_equal( a, c )
+      assert_not_equal( b, c )
+    end
+
+  end
+
+=end

data/lib/facets/more/nackclass.rb

@@ -0,0 +1,162 @@
+#--
+# NackClass
+#
+# 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.
+#
+#
+# ==========================================================================
+# Revision History ::
+# --------------------------------------------------------------------------
+#  04.09.10  Trans   * Making progress. Just usable to some degree now.
+# ==========================================================================
+#
+# TODO I beleive this class has even more potential yet.
+#      It would be interesting to see if a catch/try correction
+#      facility could be built into it too.
+#
+#++
+
+#:title: NackClass
+#
+# The NackClass is is like the NilClass except one step down.
+# Nack is never used to to mean nothingness or emptiness.
+# The Nack class is only used to report something is "a miss" w/o
+# the system raising an Exception. It's a mechanism for
+# lazy error evaluation.
+#
+# == Usage
+#
+#   def scalar( x )
+#     if x.kind_of?(Enumerable)
+#       return nack(ArgumentError, "Value must not be enumerable")
+#     end
+#     x
+#   end
+#
+#   a = scaler( 1 )            #=> 1
+#   b = scaler( [1,2] )        #=> nack
+#   b.first                    #=> ArgumentError (previous)
+#
+#   a = nail scaler( 1 )       #=> 1
+#   b = nail scaler( [1,2] )   #=> ArgumentError
+#
+# == Author(s)
+#
+# * Thomas Sawyer
+#
+
+class InvalidNackError < ArgumentError
+end
+
+#
+#
+#
+class NackClass
+
+  attr_reader :error, :data
+
+  def initialize(error=nil, *data, &ctrl)
+    if Class === error and error <= Exception
+      @error = error.new(*data)
+    elsif error.kind_of?( Exception )
+      @error = error
+    elsif error.kind_of?( String )
+      @error = StandardError.new(error)
+    elsif error == nil
+      @error = StandardError.new
+    else
+      raise InvalidNackError
+    end
+    @data = data
+    @ctrl = ctrl
+  end
+
+  def call(*args)
+    @ctrl.call(*args)
+  end
+
+  def call_with_data
+    @ctrl.call(*@data)
+  end
+
+  def raise_error
+    raise @error
+  end
+
+  def to_s; "n/a"; end
+
+  def ==(x)
+    x.is_a?(NackClass)
+  end
+
+  def method_missing(meth, *args)
+    raise_error
+  end
+
+end
+
+module Kernel
+  def nack(err=nil, *data, &ctrl)
+    NackClass.new(err, *data, &ctrl)
+  end
+end
+
+# A private Object method which will raise a NackClass' error.
+def nail( arg )
+  if NackClass === arg
+    arg.raise_error
+  else
+    return arg
+  end
+end
+
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+
+=begin testing
+
+  require 'test/unit'
+
+  class TC_Nack < Test::Unit::TestCase
+
+    def scalar( x )
+      if x.kind_of?(Enumerable)
+        return nack(ArgumentError, "Value cannot not be enumerable")
+      end
+      x
+    end
+
+    def test000
+      assert_equal( 1, scalar(1) )
+    end
+
+    def test001
+      assert_equal( nack, scalar([1,2]) )
+    end
+
+    def test002
+      assert_equal( 1, nail(scalar(1)) )
+    end
+
+    def test003
+      assert_raises(ArgumentError) { nail(scalar([1,2])) }
+    end
+
+  end
+
+=end