facets 1.0.3 → 1.1.0

data/packages/more/lib/facet/multiton.rb

@@ -1,359 +0,0 @@
-#--
-# 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/packages/more/lib/facet/nackclass.rb

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