diff options
Diffstat (limited to 'trunk/lib/delegate.rb')
| -rw-r--r-- | trunk/lib/delegate.rb | 331 |
1 files changed, 331 insertions, 0 deletions
diff --git a/trunk/lib/delegate.rb b/trunk/lib/delegate.rb new file mode 100644 index 0000000000..629753fe3a --- /dev/null +++ b/trunk/lib/delegate.rb @@ -0,0 +1,331 @@ +# = delegate -- Support for the Delegation Pattern +# +# Documentation by James Edward Gray II and Gavin Sinclair +# +# == Introduction +# +# This library provides three different ways to delegate method calls to an +# object. The easiest to use is SimpleDelegator. Pass an object to the +# constructor and all methods supported by the object will be delegated. This +# object can be changed later. +# +# Going a step further, the top level DelegateClass method allows you to easily +# setup delegation through class inheritance. This is considerably more +# flexible and thus probably the most common use for this library. +# +# Finally, if you need full control over the delegation scheme, you can inherit +# from the abstract class Delegator and customize as needed. (If you find +# yourself needing this control, have a look at _forwardable_, also in the +# standard library. It may suit your needs better.) +# +# == Notes +# +# Be advised, RDoc will not detect delegated methods. +# +# <b>delegate.rb provides full-class delegation via the +# DelegateClass() method. For single-method delegation via +# def_delegator(), see forwardable.rb.</b> +# +# == Examples +# +# === SimpleDelegator +# +# Here's a simple example that takes advantage of the fact that +# SimpleDelegator's delegation object can be changed at any time. +# +# class Stats +# def initialize +# @source = SimpleDelegator.new([]) +# end +# +# def stats( records ) +# @source.__setobj__(records) +# +# "Elements: #{@source.size}\n" + +# " Non-Nil: #{@source.compact.size}\n" + +# " Unique: #{@source.uniq.size}\n" +# end +# end +# +# s = Stats.new +# puts s.stats(%w{James Edward Gray II}) +# puts +# puts s.stats([1, 2, 3, nil, 4, 5, 1, 2]) +# +# <i>Prints:</i> +# +# Elements: 4 +# Non-Nil: 4 +# Unique: 4 +# +# Elements: 8 +# Non-Nil: 7 +# Unique: 6 +# +# === DelegateClass() +# +# Here's a sample of use from <i>tempfile.rb</i>. +# +# A _Tempfile_ object is really just a _File_ object with a few special rules +# about storage location and/or when the File should be deleted. That makes for +# an almost textbook perfect example of how to use delegation. +# +# class Tempfile < DelegateClass(File) +# # constant and class member data initialization... +# +# def initialize(basename, tmpdir=Dir::tmpdir) +# # build up file path/name in var tmpname... +# +# @tmpfile = File.open(tmpname, File::RDWR|File::CREAT|File::EXCL, 0600) +# +# # ... +# +# super(@tmpfile) +# +# # below this point, all methods of File are supported... +# end +# +# # ... +# end +# +# === Delegator +# +# SimpleDelegator's implementation serves as a nice example here. +# +# class SimpleDelegator < Delegator +# def initialize(obj) +# super # pass obj to Delegator constructor, required +# @delegate_sd_obj = obj # store obj for future use +# end +# +# def __getobj__ +# @delegate_sd_obj # return object we are delegating to, required +# end +# +# def __setobj__(obj) +# @delegate_sd_obj = obj # change delegation object, a feature we're providing +# end +# +# # ... +# end + +# +# Delegator is an abstract class used to build delegator pattern objects from +# subclasses. Subclasses should redefine \_\_getobj\_\_. For a concrete +# implementation, see SimpleDelegator. +# +class Delegator + preserved = [ + :__id__, :object_id, :__send__, :public_send, :respond_to?, :send, + :instance_eval, :instance_exec, :extend, + ] + instance_methods.each do |m| + next if preserved.include?(m) + undef_method m + end + + module MethodDelegation + # + # Pass in the _obj_ to delegate method calls to. All methods supported by + # _obj_ will be delegated to. + # + def initialize(obj) + __setobj__(obj) + end + + # Handles the magic of delegation through \_\_getobj\_\_. + def method_missing(m, *args, &block) + begin + target = self.__getobj__ + unless target.respond_to?(m) + super(m, *args, &block) + else + target.__send__(m, *args, &block) + end + rescue Exception + $@.delete_if{|s| %r"\A#{__FILE__}:\d+:in `method_missing'\z"o =~ s} + ::Kernel::raise + end + end + + # + # Checks for a method provided by this the delegate object by fowarding the + # call through \_\_getobj\_\_. + # + def respond_to?(m, include_private = false) + return true if super + return self.__getobj__.respond_to?(m, include_private) + end + + # + # Returns true if two objects are considered same. + # + def ==(obj) + return true if obj.equal?(self) + self.__getobj__ == obj + end + + # + # Returns true only if two objects are identical. + # + def equal?(obj) + self.object_id == obj.object_id + end + + # + # This method must be overridden by subclasses and should return the object + # method calls are being delegated to. + # + def __getobj__ + raise NotImplementedError, "need to define `__getobj__'" + end + + # + # This method must be overridden by subclasses and change the object delegate + # to _obj_. + # + def __setobj__(obj) + raise NotImplementedError, "need to define `__setobj__'" + end + + # Serialization support for the object returned by \_\_getobj\_\_. + def marshal_dump + __getobj__ + end + # Reinitializes delegation from a serialized object. + def marshal_load(obj) + __setobj__(obj) + end + + # Clone support for the object returned by \_\_getobj\_\_. + def clone + new = super + new.__setobj__(__getobj__.clone) + new + end + # Duplication support for the object returned by \_\_getobj\_\_. + def dup + new = super + new.__setobj__(__getobj__.dup) + new + end + end + include MethodDelegation +end + +# +# A concrete implementation of Delegator, this class provides the means to +# delegate all supported method calls to the object passed into the constructor +# and even to change the object being delegated to at a later time with +# \_\_setobj\_\_ . +# +class SimpleDelegator<Delegator + # Returns the current object method calls are being delegated to. + def __getobj__ + @delegate_sd_obj + end + + # + # Changes the delegate object to _obj_. + # + # It's important to note that this does *not* cause SimpleDelegator's methods + # to change. Because of this, you probably only want to change delegation + # to objects of the same type as the original delegate. + # + # Here's an example of changing the delegation object. + # + # names = SimpleDelegator.new(%w{James Edward Gray II}) + # puts names[1] # => Edward + # names.__setobj__(%w{Gavin Sinclair}) + # puts names[1] # => Sinclair + # + def __setobj__(obj) + raise ArgumentError, "cannot delegate to self" if self.equal?(obj) + @delegate_sd_obj = obj + end +end + +# :stopdoc: +def Delegator.delegating_block(mid) + lambda do |*args, &block| + begin + @delegate_dc_obj.__send__(mid, *args, &block) + rescue + re = /\A#{Regexp.quote(__FILE__)}:#{__LINE__-2}:/o + $!.backtrace.delete_if {|t| re =~ t} + raise + end + end +end +# :startdoc: + +# +# The primary interface to this library. Use to setup delegation when defining +# your class. +# +# class MyClass < DelegateClass( ClassToDelegateTo ) # Step 1 +# def initialize +# super(obj_of_ClassToDelegateTo) # Step 2 +# end +# end +# +def DelegateClass(superclass) + klass = Class.new + methods = superclass.public_instance_methods(true) + methods -= [ + :__id__, :object_id, :__send__, :public_send, :respond_to?, :send, + :==, :equal?, :initialize, :method_missing, :__getobj__, :__setobj__, + :clone, :dup, :marshal_dump, :marshal_load, :instance_eval, :instance_exec, + :extend, + ] + klass.module_eval { + include Delegator::MethodDelegation + def __getobj__ # :nodoc: + @delegate_dc_obj + end + def __setobj__(obj) # :nodoc: + raise ArgumentError, "cannot delegate to self" if self.equal?(obj) + @delegate_dc_obj = obj + end + } + klass.module_eval do + methods.each do |method| + define_method(method, Delegator.delegating_block(method)) + end + end + return klass +end + +# :enddoc: + +if __FILE__ == $0 + class ExtArray<DelegateClass(Array) + def initialize() + super([]) + end + end + + ary = ExtArray.new + p ary.class + ary.push 25 + p ary + ary.push 42 + ary.each {|x| p x} + + foo = Object.new + def foo.test + 25 + end + def foo.iter + yield self + end + def foo.error + raise 'this is OK' + end + foo2 = SimpleDelegator.new(foo) + p foo2 + foo2.instance_eval{print "foo\n"} + p foo.test == foo2.test # => true + p foo2.iter{[55,true]} # => true + foo2.error # raise error! +end |