# = delegate -- Support for the Delegation Pattern
# Documentation by James Edward Gray II and Gavin Sinclair
# 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.)
# 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>
# Here's a simple example that takes advantage of the fact that
# SimpleDelegator's delegation object can be changed at any time.
# @source = SimpleDelegator.new([])
# @source.__setobj__(records)
# "Elements: #{@source.size}\n" +
# " Non-Nil: #{@source.compact.size}\n" +
# " Unique: #{@source.uniq.size}\n"
# puts s.stats(%w{James Edward Gray II})
# puts s.stats([1, 2, 3, nil, 4, 5, 1, 2])
# 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)
# # below this point, all methods of File are supported...
# SimpleDelegator's implementation serves as a nice example here.
# class SimpleDelegator < Delegator
# super # pass obj to Delegator constructor, required
# @_sd_obj = obj # store obj for future use
# @_sd_obj # return object we are delegating to, required
# @_sd_obj = obj # change delegation object, a feature we're providing
# Delegator is an abstract class used to build delegator pattern objects from
# subclasses. Subclasses should redefine \_\_getobj\_\_. For a concrete
# implementation, see SimpleDelegator.
IgnoreBacktracePat = %r"\A#{Regexp.quote(__FILE__)}:\d+:in `"
# Pass in the _obj_ to delegate method calls to. All methods supported by
# _obj_ will be delegated to.
preserved = ::Kernel.public_instance_methods(false)
preserved -= ["to_s","to_a","inspect","==","=~","==="]
for t in self.class.ancestors
preserved |= t.public_instance_methods(false)
preserved |= t.private_instance_methods(false)
preserved |= t.protected_instance_methods(false)
preserved << "singleton_method_added"
for method in obj.methods
next if preserved.include? method
eval <<-EOS, nil, __FILE__, __LINE__+1
def self.#{method}(*args, &block)
__getobj__.__send__(:#{method}, *args, &block)
$@.delete_if{|s|IgnoreBacktracePat=~s} if $@
raise NameError, "invalid identifier %s" % method, caller(4)
alias initialize_methods initialize
# Handles the magic of delegation through \_\_getobj\_\_.
def method_missing(m, *args, &block)
unless target.respond_to?(m)
target.__send__(m, *args, &block)
# Checks for a method provided by this the delegate object by fowarding the
# call through \_\_getobj\_\_.
def respond_to?(m, include_private = false)
return self.__getobj__.respond_to?(m, include_private)
# This method must be overridden by subclasses and should return the object
# method calls are being delegated to.
raise NotImplementedError, "need to define `__getobj__'"
# Serialization support for the object returned by \_\_getobj\_\_.
# Reinitializes delegation from a serialized object.
# 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
class SimpleDelegator<Delegator
# Pass in the _obj_ you would like to delegate method calls to.
# Returns the current object method calls are being delegated to.
# 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
raise ArgumentError, "cannot delegate to self" if self.equal?(obj)
# Clone support for the object returned by \_\_getobj\_\_.
new.__setobj__(__getobj__.clone)
# Duplication support for the object returned by \_\_getobj\_\_.
new.__setobj__(__getobj__.clone)
# backward compatibility ^_^;;;
SimpleDelegater = SimpleDelegator
# The primary interface to this library. Use to setup delegation when defining
# class MyClass < DelegateClass( ClassToDelegateTo ) # Step 1
# super(obj_of_ClassToDelegateTo) # Step 2
def DelegateClass(superclass)
methods = superclass.public_instance_methods(true)
methods -= ::Kernel.public_instance_methods(false)
methods |= ["to_s","to_a","inspect","==","=~","==="]
def initialize(obj) # :nodoc:
def method_missing(m, *args, &block) # :nodoc:
unless @_dc_obj.respond_to?(m)
@_dc_obj.__send__(m, *args, &block)
def respond_to?(m, include_private = false) # :nodoc:
return @_dc_obj.respond_to?(m, include_private)
def __setobj__(obj) # :nodoc:
raise ArgumentError, "cannot delegate to self" if self.equal?(obj)
new.__setobj__(__getobj__.clone)
new.__setobj__(__getobj__.clone)
klass.module_eval <<-EOS, __FILE__, __LINE__+1
def #{method}(*args, &block)
@_dc_obj.__send__(:#{method}, *args, &block)
$@.delete_if{|s| ::Delegator::IgnoreBacktracePat =~ s} if $@
raise NameError, "invalid identifier %s" % method, caller(3)
class ExtArray<DelegateClass(Array)
foo2 = SimpleDelegator.new(foo)
p foo.test == foo2.test # => true
foo2.error # raise error!
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
