# = 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.
#
# delegate.rb provides full-class delegation via the
# DelegateClass() method. For single-method delegation via
# def_delegator(), see forwardable.rb.
#
# == 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])
#
# Prints:
#
# Elements: 4
# Non-Nil: 4
# Unique: 4
#
# Elements: 8
# Non-Nil: 7
# Unique: 6
#
# === DelegateClass()
#
# Here's a sample of use from tempfile.rb.
#
# 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
[:to_s,:inspect,:=~,:!~,:===].each do |m|
undef_method m
end
#
# 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
if i = $@.index{|s| %r"\A#{Regexp.quote(__FILE__)}:\d+:in `method_missing'\z"o =~ s}
$@[0..i] = []
end
::Kernel::raise
end
end
#
# Checks for a method provided by this the delegate object by forwarding the
# call through \_\_getobj\_\_.
#
def respond_to_missing?(m, include_private = false)
if include_private
warn "#{caller(3)[0]}: delegator does not forward private methods"
end
self.__getobj__.respond_to?(m)
end
#
# Returns true if two objects are considered same.
#
def ==(obj)
return true if obj.equal?(self)
self.__getobj__ == obj
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
# Freeze self and target at once.
def freeze
__getobj__.freeze
super
end
@delegator_api = self.public_instance_methods
def self.public_api # :nodoc:
@delegator_api
end
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 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
def initialize(obj) # :nodoc:
(self.public_methods - Delegator.public_api).each do |m|
class << self
self
end.class_eval do
undef_method m
end
end
super
end
end
# :stopdoc:
def Delegator.delegating_block(mid)
lambda do |*args, &block|
begin
__getobj__.__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(Delegator)
methods = superclass.public_instance_methods(true)
methods -= ::Delegator.public_api
methods -= [:to_s,:inspect,:=~,:!~,:===]
klass.module_eval {
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 true
p foo2.iter{[55,true]} # => true
foo2.error # raise error!
end