# = 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 which is also in
# the standard library. It may suit your needs better.)
# SimpleDelegator's implementation serves as a nice example if the use of
# class SimpleDelegator < Delegator
# super # pass obj to Delegator constructor, required
# @delegate_sd_obj = obj # store obj for future use
# @delegate_sd_obj # return object we are delegating to, required
# @delegate_sd_obj = obj # change delegation object,
# # a feature we're providing
# Be advised, RDoc will not detect delegated methods.
class Delegator < BasicObject
[:to_s,:inspect,:=~,:!~,:===,:<=>,:eql?,:hash].each do |m|
private_instance_methods.each do |m|
if /\Ablock_given\?\z|iterator\?\z|\A__.*__\z/ =~ m
def self.const_missing(n)
# Use __raise__ if your Delegator does not have a object to delegate the
# Pass in the _obj_ to delegate method calls to. All methods supported by
# _obj_ will be delegated to.
# Handles the magic of delegation through \_\_getobj\_\_.
def method_missing(m, *args, &block)
target = self.__getobj__ {r = false}
if r && target.respond_to?(m)
target.__send__(m, *args, &block)
elsif ::Kernel.respond_to?(m, true)
::Kernel.instance_method(m).bind(self).(*args, &block)
$@.delete_if {|t| %r"\A#{Regexp.quote(__FILE__)}:(?:#{[__LINE__-7, __LINE__-5, __LINE__-3].join('|')}):"o =~ t} if $@
# Checks for a method provided by this the delegate object by forwarding the
# call through \_\_getobj\_\_.
def respond_to_missing?(m, include_private)
target = self.__getobj__ {r = false}
r &&= target.respond_to?(m, include_private)
if r && include_private && !target.respond_to?(m, false)
warn "#{caller(3)[0]}: delegator does not forward private method \##{m}"
# Returns the methods available to this delegate object as the union
# of this object's and \_\_getobj\_\_ methods.
__getobj__.methods(all) | super
# Returns the methods available to this delegate object as the union
# of this object's and \_\_getobj\_\_ public methods.
def public_methods(all=true)
__getobj__.public_methods(all) | super
# Returns the methods available to this delegate object as the union
# of this object's and \_\_getobj\_\_ protected methods.
def protected_methods(all=true)
__getobj__.protected_methods(all) | super
# Note: no need to specialize private_methods, since they are not forwarded
# Returns true if two objects are considered of equal value.
return true if obj.equal?(self)
# Returns true if two objects are not considered of equal value.
return false if obj.equal?(self)
# Delegates ! to the \_\_getobj\_\_
# This method must be overridden by subclasses and should return the object
# method calls are being delegated to.
__raise__ ::NotImplementedError, "need to define `__getobj__'"
# This method must be overridden by subclasses and change the object delegate
__raise__ ::NotImplementedError, "need to define `__setobj__'"
# Serialization support for the object returned by \_\_getobj\_\_.
ivars = instance_variables.reject {|var| /\A@delegate_/ =~ var}
ivars, ivars.map{|var| instance_variable_get(var)},
# Reinitializes delegation from a serialized object.
version, vars, values, obj = data
vars.each_with_index{|var, i| instance_variable_set(var, values[i])}
def initialize_clone(obj) # :nodoc:
self.__setobj__(obj.__getobj__.clone)
def initialize_dup(obj) # :nodoc:
self.__setobj__(obj.__getobj__.dup)
private :initialize_clone, :initialize_dup
# Trust both the object returned by \_\_getobj\_\_ and self.
# Untrust both the object returned by \_\_getobj\_\_ and self.
# Taint both the object returned by \_\_getobj\_\_ and self.
# Untaint both the object returned by \_\_getobj\_\_ and self.
# Freeze both the object returned by \_\_getobj\_\_ and self.
[:trust, :untrust, :taint, :untaint, :freeze].each do |method|
@delegator_api = self.public_instance_methods
def self.public_api # :nodoc:
# 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 UserDecorator < SimpleDelegator
# decorated_user = UserDecorator.new(User.new)
# decorated_user.birth_year #=> 1989
# decorated_user.__getobj__ #=> #<User: ...>
# A SimpleDelegator instance can take advantage of the fact that SimpleDelegator
# is a subclass of +Delegator+ to call <tt>super</tt> to have methods called on
# the object being delegated to.
# class SuperArray < SimpleDelegator
# SuperArray.new([1])[0] #=> 2
# 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])
class SimpleDelegator<Delegator
# Returns the current object method calls are being delegated to.
unless defined?(@delegate_sd_obj)
return yield if block_given?
__raise__ ::ArgumentError, "not delegated"
# 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)
def Delegator.delegating_block(mid) # :nodoc:
lambda do |*args, &block|
target.__send__(mid, *args, &block)
$@.delete_if {|t| /\A#{Regexp.quote(__FILE__)}:#{__LINE__-2}:/o =~ t} if $@
# The primary interface to this library. Use to setup delegation when defining
# class MyClass < DelegateClass(ClassToDelegateTo) # Step 1
# super(obj_of_ClassToDelegateTo) # Step 2
# Here's a sample of use from Tempfile which is really a File object with a
# few special rules about storage location and when the File should be
# deleted. That makes for an almost textbook perfect example of how to use
# 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...
def DelegateClass(superclass)
klass = Class.new(Delegator)
methods = superclass.instance_methods
methods -= ::Delegator.public_api
methods -= [:to_s,:inspect,:=~,:!~,:===]
unless defined?(@delegate_dc_obj)
return yield if block_given?
__raise__ ::ArgumentError, "not delegated"
def __setobj__(obj) # :nodoc:
__raise__ ::ArgumentError, "cannot delegate to self" if self.equal?(obj)
define_method(method, Delegator.delegating_block(method))
klass.define_singleton_method :public_instance_methods do |all=true|
super(all) - superclass.protected_instance_methods
klass.define_singleton_method :protected_instance_methods do |all=true|
super(all) | superclass.protected_instance_methods
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
