diff options
Diffstat (limited to 'lib/delegate.rb')
| -rw-r--r-- | lib/delegate.rb | 592 |
1 files changed, 357 insertions, 235 deletions
diff --git a/lib/delegate.rb b/lib/delegate.rb index 9a4f76f164..0cc3ddb1b0 100644 --- a/lib/delegate.rb +++ b/lib/delegate.rb @@ -1,9 +1,9 @@ +# frozen_string_literal: true # = 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 @@ -15,157 +15,171 @@ # # 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> +# yourself needing this control, have a look at Forwardable which is also in +# the standard library. It may suit your needs better.) # -# == Examples +# SimpleDelegator's implementation serves as a nice example of the use of +# Delegator: # -# === SimpleDelegator +# require 'delegate' # -# 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([]) +# class SimpleDelegator < Delegator +# def __getobj__ +# @delegate_sd_obj # return object we are delegating to, required # 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... +# def __setobj__(obj) +# @delegate_sd_obj = obj # change delegation object, +# # a feature we're providing # 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 -# @_sd_obj = obj # store obj for future use -# end -# -# def __getobj__ -# @_sd_obj # return object we are delegating to, required -# end +# == Notes # -# def __setobj__(obj) -# @_sd_obj = obj # change delegation object, a feature we're providing -# end +# Be advised, RDoc will not detect delegated methods. # -# # ... -# end +class Delegator < BasicObject + # The version string + VERSION = "0.6.1" -# -# 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 - IgnoreBacktracePat = %r"\A#{Regexp.quote(__FILE__)}:\d+:in `" + kernel = ::Kernel.dup + kernel.class_eval do + alias __raise__ raise + [:to_s, :inspect, :!~, :===, :<=>, :hash].each do |m| + undef_method m + end + private_instance_methods.each do |m| + if /\Ablock_given\?\z|\Aiterator\?\z|\A__.*__\z/ =~ m + next + end + undef_method m + end + end + include kernel + + # :stopdoc: + def self.const_missing(n) + ::Object.const_get(n) + end + # :startdoc: + + ## + # :method: raise + # Use #__raise__ if your Delegator does not have a object to delegate the + # #raise method call. + # # # Pass in the _obj_ to delegate method calls to. All methods supported by # _obj_ will be delegated to. # def initialize(obj) - 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) - break if t == Delegator + __setobj__(obj) + end + + # + # Handles the magic of delegation through +__getobj__+. + # + ruby2_keywords def method_missing(m, *args, &block) + r = true + target = self.__getobj__ {r = false} + + if r && target_respond_to?(target, m, false) + target.__send__(m, *args, &block) + elsif ::Kernel.method_defined?(m) || ::Kernel.private_method_defined?(m) + ::Kernel.instance_method(m).bind_call(self, *args, &block) + else + super(m, *args, &block) end - preserved << "singleton_method_added" - for method in obj.methods - next if preserved.include? method - begin - eval <<-EOS, nil, __FILE__, __LINE__+1 - def self.#{method}(*args, &block) - begin - __getobj__.__send__(:#{method}, *args, &block) - ensure - $@.delete_if{|s|IgnoreBacktracePat=~s} if $@ - end - end - EOS - rescue SyntaxError - raise NameError, "invalid identifier %s" % method, caller(4) - 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) + r = true + target = self.__getobj__ {r = false} + r &&= target_respond_to?(target, m, include_private) + if r && include_private && !target_respond_to?(target, m, false) + warn "delegator does not forward private method \##{m}", uplevel: 3 + return false end + r end - alias initialize_methods initialize - # Handles the magic of delegation through \_\_getobj\_\_. - def method_missing(m, *args, &block) - target = self.__getobj__ - unless target.respond_to?(m) - super(m, *args, &block) + KERNEL_RESPOND_TO = ::Kernel.instance_method(:respond_to?) # :nodoc: + private_constant :KERNEL_RESPOND_TO + + # Handle BasicObject instances + private def target_respond_to?(target, m, include_private) + case target + when Object + target.respond_to?(m, include_private) + else + if KERNEL_RESPOND_TO.bind_call(target, :respond_to?) + target.respond_to?(m, include_private) + else + KERNEL_RESPOND_TO.bind_call(target, m, include_private) + end end - target.__send__(m, *args, &block) end # - # Checks for a method provided by this the delegate object by fowarding the - # call through \_\_getobj\_\_. + # Returns the methods available to this delegate object as the union + # of this object's and +__getobj__+ methods. # - def respond_to?(m, include_private = false) - return true if super - return self.__getobj__.respond_to?(m, include_private) + def methods(all=true) + __getobj__.methods(all) | super + end + + # + # 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 + end + + # + # 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 + end + + # Note: no need to specialize private_methods, since they are not forwarded + + # + # Returns true if two objects are considered of equal value. + # + def ==(obj) + return true if obj.equal?(self) + self.__getobj__ == obj + end + + # + # Returns true if two objects are not considered of equal value. + # + def !=(obj) + return false if obj.equal?(self) + __getobj__ != obj + end + + # + # Returns true if two objects are considered of equal value. + # + def eql?(obj) + return true if obj.equal?(self) + obj.eql?(__getobj__) + end + + # + # Delegates ! to the +__getobj__+ + # + def ! + !__getobj__ end # @@ -173,37 +187,141 @@ class Delegator # method calls are being delegated to. # def __getobj__ - raise NotImplementedError, "need to define `__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\_\_. + # + # Serialization support for the object returned by +__getobj__+. + # def marshal_dump - __getobj__ + ivars = instance_variables.reject {|var| /\A@delegate_/ =~ var} + [ + :__v2__, + ivars, ivars.map {|var| instance_variable_get(var)}, + __getobj__ + ] end + + # # Reinitializes delegation from a serialized object. - def marshal_load(obj) - initialize_methods(obj) - __setobj__(obj) + # + def marshal_load(data) + version, vars, values, obj = data + if version == :__v2__ + vars.each_with_index {|var, i| instance_variable_set(var, values[i])} + __setobj__(obj) + else + __setobj__(data) + end + end + + def initialize_clone(obj, freeze: nil) # :nodoc: + self.__setobj__(obj.__getobj__.clone(freeze: freeze)) + end + def initialize_dup(obj) # :nodoc: + self.__setobj__(obj.__getobj__.dup) + end + private :initialize_clone, :initialize_dup + + ## + # :method: freeze + # Freeze both the object returned by +__getobj__+ and self. + # + 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\_\_ . +# #__setobj__. # -class SimpleDelegator<Delegator - - # Pass in the _obj_ you would like to delegate method calls to. - def initialize(obj) - super - @_sd_obj = obj - end - +# class User +# def born_on +# Date.new(1989, 9, 10) +# end +# end +# +# require 'delegate' +# +# class UserDecorator < SimpleDelegator +# def birth_year +# born_on.year +# end +# end +# +# 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 +# def [](*args) +# super + 1 +# end +# end +# +# 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. +# +# 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 +# +class SimpleDelegator < Delegator # Returns the current object method calls are being delegated to. def __getobj__ - @_sd_obj + unless defined?(@delegate_sd_obj) + return yield if block_given? + __raise__ ::ArgumentError, "not delegated" + end + @delegate_sd_obj end # @@ -221,117 +339,121 @@ class SimpleDelegator<Delegator # puts names[1] # => Sinclair # def __setobj__(obj) - raise ArgumentError, "cannot delegate to self" if self.equal?(obj) - @_sd_obj = 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__.clone) - new + __raise__ ::ArgumentError, "cannot delegate to self" if self.equal?(obj) + @delegate_sd_obj = obj end end -# :stopdoc: -# backward compatibility ^_^;;; -Delegater = Delegator -SimpleDelegater = SimpleDelegator -# :startdoc: +def Delegator.delegating_block(mid) # :nodoc: + lambda do |*args, &block| + target = self.__getobj__ + target.__send__(mid, *args, &block) + end.ruby2_keywords +end # # The primary interface to this library. Use to setup delegation when defining # your class. # -# class MyClass < DelegateClass( ClassToDelegateTo ) # Step 1 +# class MyClass < DelegateClass(ClassToDelegateTo) # Step 1 # def initialize -# super(obj_of_ClassToDelegateTo) # Step 2 +# super(obj_of_ClassToDelegateTo) # Step 2 # end # end # -def DelegateClass(superclass) - klass = Class.new - methods = superclass.public_instance_methods(true) - methods -= ::Kernel.public_instance_methods(false) - methods |= ["to_s","to_a","inspect","==","=~","==="] - klass.module_eval { - def initialize(obj) # :nodoc: - @_dc_obj = obj - end - def method_missing(m, *args, &block) # :nodoc: - unless @_dc_obj.respond_to?(m) - super(m, *args, &block) +# or: +# +# MyClass = DelegateClass(ClassToDelegateTo) do # Step 1 +# def initialize +# super(obj_of_ClassToDelegateTo) # Step 2 +# end +# end +# +# 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 +# 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 +# +def DelegateClass(superclass, &block) + klass = Class.new(Delegator) + ignores = [*::Delegator.public_api, :to_s, :inspect, :=~, :!~, :===] + protected_instance_methods = superclass.protected_instance_methods + protected_instance_methods -= ignores + public_instance_methods = superclass.public_instance_methods + public_instance_methods -= ignores + + normal, special = public_instance_methods.partition { |m| m.match?(/\A[a-zA-Z]\w*[!\?]?\z/) } + + source = normal.map do |method| + "def #{method}(...); __getobj__.#{method}(...); end" + end + + protected_instance_methods.each do |method| + source << "def #{method}(...); __getobj__.__send__(#{method.inspect}, ...); end" + end + + klass.module_eval do + def __getobj__ # :nodoc: + unless defined?(@delegate_dc_obj) + return yield if block_given? + __raise__ ::ArgumentError, "not delegated" end - @_dc_obj.__send__(m, *args, &block) - end - def respond_to?(m, include_private = false) # :nodoc: - return true if super - return @_dc_obj.respond_to?(m, include_private) - end - def __getobj__ # :nodoc: - @_dc_obj + @delegate_dc_obj end + def __setobj__(obj) # :nodoc: - raise ArgumentError, "cannot delegate to self" if self.equal?(obj) - @_dc_obj = obj - end - def clone # :nodoc: - new = super - new.__setobj__(__getobj__.clone) - new - end - def dup # :nodoc: - new = super - new.__setobj__(__getobj__.clone) - new + __raise__ ::ArgumentError, "cannot delegate to self" if self.equal?(obj) + @delegate_dc_obj = obj end - } - for method in methods - begin - klass.module_eval <<-EOS, __FILE__, __LINE__+1 - def #{method}(*args, &block) - begin - @_dc_obj.__send__(:#{method}, *args, &block) - ensure - $@.delete_if{|s| ::Delegator::IgnoreBacktracePat =~ s} if $@ - end - end - EOS - rescue SyntaxError - raise NameError, "invalid identifier %s" % method, caller(3) - end - end - return klass -end -# :enddoc: + class_eval(source.join(";"), __FILE__, __LINE__) -if __FILE__ == $0 - class ExtArray<DelegateClass(Array) - def initialize() - super([]) + special.each do |method| + define_method(method, Delegator.delegating_block(method)) end - end - ary = ExtArray.new - p ary.class - ary.push 25 - p ary + protected(*protected_instance_methods) + end - foo = Object.new - def foo.test - 25 + klass.define_singleton_method :public_instance_methods do |all=true| + super(all) | superclass.public_instance_methods + end + klass.define_singleton_method :protected_instance_methods do |all=true| + super(all) | superclass.protected_instance_methods end - def foo.error - raise 'this is OK' + klass.define_singleton_method :instance_methods do |all=true| + super(all) | superclass.instance_methods end - foo2 = SimpleDelegator.new(foo) - p foo.test == foo2.test # => true - foo2.error # raise error! + klass.define_singleton_method :public_instance_method do |name| + super(name) + rescue NameError + raise unless self.public_instance_methods.include?(name) + superclass.public_instance_method(name) + end + klass.define_singleton_method :instance_method do |name| + super(name) + rescue NameError + raise unless self.instance_methods.include?(name) + superclass.instance_method(name) + end + klass.module_eval(&block) if block + return klass end |