diff options
Diffstat (limited to 'lib/forwardable.rb')
| -rw-r--r-- | lib/forwardable.rb | 328 |
1 files changed, 212 insertions, 116 deletions
diff --git a/lib/forwardable.rb b/lib/forwardable.rb index b9a135bf4b..175d6d9c6b 100644 --- a/lib/forwardable.rb +++ b/lib/forwardable.rb @@ -1,35 +1,65 @@ -# = forwardable - Support for the Delegation Pattern +# frozen_string_literal: false # -# $Release Version: 1.1$ -# $Revision$ -# $Date$ -# by Keiju ISHITSUKA(keiju@ishitsuka.com) +# forwardable.rb - +# $Release Version: 1.1$ +# $Revision$ +# by Keiju ISHITSUKA(keiju@ishitsuka.com) +# original definition by delegator.rb +# Revised by Daniel J. Berger with suggestions from Florian Gross. # -# Documentation by James Edward Gray II and Gavin Sinclair +# Documentation by James Edward Gray II and Gavin Sinclair + + + +# The Forwardable module provides delegation of specified +# methods to a designated object, using the methods #def_delegator +# and #def_delegators. # -# == Introduction +# For example, say you have a class RecordCollection which +# contains an array <tt>@records</tt>. You could provide the lookup method +# #record_number(), which simply calls #[] on the <tt>@records</tt> +# array, like this: # -# This library allows you delegate method calls to an object, on a method by -# method basis. You can use Forwardable to setup this delegation at the class -# level, or SingleForwardable to handle it at the object level. +# require 'forwardable' # -# == Notes +# class RecordCollection +# attr_accessor :records +# extend Forwardable +# def_delegator :@records, :[], :record_number +# end # -# Be advised, RDoc will not detect delegated methods. +# We can use the lookup method like so: +# +# r = RecordCollection.new +# r.records = [4,5,6] +# r.record_number(0) # => 4 +# +# Further, if you wish to provide the methods #size, #<<, and #map, +# all of which delegate to @records, this is how you can do it: +# +# class RecordCollection # re-open RecordCollection class +# def_delegators :@records, :size, :<<, :map +# end +# +# r = RecordCollection.new +# r.records = [1,2,3] +# r.record_number(0) # => 1 +# r.size # => 3 +# r << 4 # => [1, 2, 3, 4] +# r.map { |x| x * 2 } # => [2, 4, 6, 8] # -# <b>forwardable.rb provides single-method delegation via the -# def_delegator() and def_delegators() methods. For full-class -# delegation via DelegateClass(), see delegate.rb.</b> +# You can even extend regular objects with Forwardable. # -# == Examples +# my_hash = Hash.new +# my_hash.extend Forwardable # prepare object for delegation +# my_hash.def_delegator "STDOUT", "puts" # add delegation for STDOUT.puts() +# my_hash.puts "Howdy!" # -# === Forwardable +# == Another example # -# Forwardable makes building a new class based on existing work, with a proper -# interface, almost trivial. We want to rely on what has come before obviously, -# but with delegation we can take just the methods we need and even rename them -# as appropriate. In many cases this is preferable to inheritance, which gives -# us the entire old interface, even if much of it isn't needed. +# You could use Forwardable as an alternative to inheritance, when you don't want +# to inherit all methods from the superclass. For instance, here is how you might +# add a range of +Array+ instance methods to a new class +Queue+: # # class Queue # extend Forwardable @@ -46,7 +76,7 @@ # def_delegators :@q, :clear, :first, :push, :shift, :size # end # -# q = Queue.new +# q = Thread::Queue.new # q.enq 1, 2, 3, 4, 5 # q.push 6 # @@ -60,7 +90,7 @@ # q.clear # puts q.first # -# <i>Prints:</i> +# This should output: # # 2 # 3 @@ -70,50 +100,48 @@ # Ruby # nil # -# === SingleForwardable -# -# printer = String.new -# printer.extend SingleForwardable # prepare object for delegation -# printer.def_delegator "STDOUT", "puts" # add delegation for STDOUT.puts() -# printer.puts "Howdy!" -# -# <i>Prints:</i> -# -# Howdy! - -# -# The Forwardable module provides delegation of specified -# methods to a designated object, using the methods #def_delegator -# and #def_delegators. -# -# For example, say you have a class RecordCollection which -# contains an array <tt>@records</tt>. You could provide the lookup method -# #record_number(), which simply calls #[] on the <tt>@records</tt> -# array, like this: -# -# class RecordCollection -# extend Forwardable -# def_delegator :@records, :[], :record_number -# end -# -# Further, if you wish to provide the methods #size, #<<, and #map, -# all of which delegate to @records, this is how you can do it: +# == Notes # -# class RecordCollection -# # extend Forwardable, but we did that above -# def_delegators :@records, :size, :<<, :map -# end +# Be advised, RDoc will not detect delegated methods. # -# Also see the example at forwardable.rb. +# +forwardable.rb+ provides single-method delegation via the def_delegator and +# def_delegators methods. For full-class delegation via DelegateClass, see +# +delegate.rb+. # module Forwardable + # Version of +forwardable.rb+ + VERSION = "1.4.0" + VERSION.freeze + + # Version for backward compatibility + FORWARDABLE_VERSION = VERSION + FORWARDABLE_VERSION.freeze @debug = nil - class<<self - # force Forwardable to show up in stack backtraces of delegated methods + class << self + # ignored attr_accessor :debug end + # Takes a hash as its argument. The key is a symbol or an array of + # symbols. These symbols correspond to method names, instance variable + # names, or constant names (see def_delegator). The value is + # the accessor to which the methods will be delegated. + # + # :call-seq: + # delegate method => accessor + # delegate [method, method, ...] => accessor + # + def instance_delegate(hash) + hash.each do |methods, accessor| + unless defined?(methods.each) + def_instance_delegator(accessor, methods) + else + methods.each {|method| def_instance_delegator(accessor, method)} + end + end + end + # # Shortcut for defining multiple delegator methods, but with no # provision for using a different name. The following two code @@ -125,94 +153,162 @@ module Forwardable # def_delegator :@records, :<< # def_delegator :@records, :map # - # See the examples at Forwardable and forwardable.rb. - # def def_instance_delegators(accessor, *methods) - for method in methods + methods.each do |method| + next if /\A__(?:send|id)__\z/ =~ method def_instance_delegator(accessor, method) end end + # Define +method+ as delegator instance method with an optional + # alias name +ali+. Method calls to +ali+ will be delegated to + # +accessor.method+. +accessor+ should be a method name, instance + # variable name, or constant name. Use the full path to the + # constant if providing the constant name. + # Returns the name of the method defined. # - # Defines a method _method_ which delegates to _obj_ (i.e. it calls - # the method of the same name in _obj_). If _new_name_ is - # provided, it is used as the name for the delegate method. + # class MyQueue + # CONST = 1 + # extend Forwardable + # attr_reader :queue + # def initialize + # @queue = [] + # end + # + # def_delegator :@queue, :push, :mypush + # def_delegator 'MyQueue::CONST', :to_i + # end # - # See the examples at Forwardable and forwardable.rb. + # q = MyQueue.new + # q.mypush 42 + # q.queue #=> [42] + # q.push 23 #=> NoMethodError + # q.to_i #=> 1 # def def_instance_delegator(accessor, method, ali = method) - accessor = accessor.id2name if accessor.kind_of?(Integer) - method = method.id2name if method.kind_of?(Integer) - ali = ali.id2name if ali.kind_of?(Integer) - - module_eval(<<-EOS, "(__FORWARDABLE__)", 1) - def #{ali}(*args, &block) - begin - #{accessor}.__send__(:#{method}, *args, &block) - rescue Exception - $@.delete_if{|s| /^\\(__FORWARDABLE__\\):/ =~ s} unless Forwardable::debug - Kernel::raise - end - end - EOS + gen = Forwardable._delegator_method(self, accessor, method, ali) + + # If it's not a class or module, it's an instance + mod = Module === self ? self : singleton_class + mod.module_eval(&gen) end + alias delegate instance_delegate alias def_delegators def_instance_delegators alias def_delegator def_instance_delegator + + # :nodoc: + def self._delegator_method(obj, accessor, method, ali) + accessor = accessor.to_s unless Symbol === accessor + + if Module === obj ? + obj.method_defined?(accessor) || obj.private_method_defined?(accessor) : + obj.respond_to?(accessor, true) + accessor = "(#{accessor}())" + end + + args = RUBY_VERSION >= '2.7' ? '...' : '*args, &block' + method_call = ".__send__(:#{method}, #{args})" + if method.match?(/\A[_a-zA-Z]\w*[?!]?\z/) + loc, = caller_locations(2,1) + pre = "_ =" + mesg = "#{Module === obj ? obj : obj.class}\##{ali} at #{loc.path}:#{loc.lineno} forwarding to private method " + method_call = <<~RUBY.chomp + if defined?(_.#{method}) + _.#{method}(#{args}) + else + ::Kernel.warn #{mesg.dump}"\#{_.class}"'##{method}', uplevel: 1 + _#{method_call} + end + RUBY + end + + eval(<<~RUBY, nil, __FILE__, __LINE__ + 1) + proc do + def #{ali}(#{args}) + #{pre}#{accessor} + #{method_call} + end + end + RUBY + end end +# SingleForwardable can be used to setup delegation at the object level as well. # -# The SingleForwardable module provides delegation of specified -# methods to a designated object, using the methods #def_delegator -# and #def_delegators. This module is similar to Forwardable, but it works on -# objects themselves, instead of their defining classes. +# printer = String.new +# printer.extend SingleForwardable # prepare object for delegation +# printer.def_delegator "STDOUT", "puts" # add delegation for STDOUT.puts() +# printer.puts "Howdy!" +# +# Also, SingleForwardable can be used to set up delegation for a Class or Module. # -# Also see the example at forwardable.rb. +# class Implementation +# def self.service +# puts "serviced!" +# end +# end +# +# module Facade +# extend SingleForwardable +# def_delegator :Implementation, :service +# end +# +# Facade.service #=> serviced! # +# If you want to use both Forwardable and SingleForwardable, you can +# use methods def_instance_delegator and def_single_delegator, etc. module SingleForwardable + # Takes a hash as its argument. The key is a symbol or an array of + # symbols. These symbols correspond to method names. The value is + # the accessor to which the methods will be delegated. + # + # :call-seq: + # delegate method => accessor + # delegate [method, method, ...] => accessor + # + def single_delegate(hash) + hash.each do |methods, accessor| + unless defined?(methods.each) + def_single_delegator(accessor, methods) + else + methods.each {|method| def_single_delegator(accessor, method)} + end + end + end + # # Shortcut for defining multiple delegator methods, but with no # provision for using a different name. The following two code # samples have the same effect: # - # single_forwardable.def_delegators :@records, :size, :<<, :map - # - # single_forwardable.def_delegator :@records, :size - # single_forwardable.def_delegator :@records, :<< - # single_forwardable.def_delegator :@records, :map + # def_delegators :@records, :size, :<<, :map # - # See the example at forwardable.rb. + # def_delegator :@records, :size + # def_delegator :@records, :<< + # def_delegator :@records, :map # - def def_singleton_delegators(accessor, *methods) - for method in methods - def_singleton_delegator(accessor, method) + def def_single_delegators(accessor, *methods) + methods.each do |method| + next if /\A__(?:send|id)__\z/ =~ method + def_single_delegator(accessor, method) end end + # :call-seq: + # def_single_delegator(accessor, method, new_name=method) # - # Defines a method _method_ which delegates to _obj_ (i.e. it calls - # the method of the same name in _obj_). If _new_name_ is + # Defines a method _method_ which delegates to _accessor_ (i.e. it calls + # the method of the same name in _accessor_). If _new_name_ is # provided, it is used as the name for the delegate method. - # - # See the example at forwardable.rb. - # - def def_singleton_delegator(accessor, method, ali = method) - accessor = accessor.id2name if accessor.kind_of?(Integer) - method = method.id2name if method.kind_of?(Integer) - ali = ali.id2name if ali.kind_of?(Integer) - - instance_eval(<<-EOS, "(__FORWARDABLE__)", 1) - def #{ali}(*args, &block) - begin - #{accessor}.__send__(:#{method}, *args,&block) - rescue Exception - $@.delete_if{|s| /^\\(__FORWARDABLE__\\):/ =~ s} unless Forwardable::debug - Kernel::raise - end - end - EOS + # Returns the name of the method defined. + def def_single_delegator(accessor, method, ali = method) + gen = Forwardable._delegator_method(self, accessor, method, ali) + + instance_eval(&gen) end - alias def_delegators def_singleton_delegators - alias def_delegator def_singleton_delegator + alias delegate single_delegate + alias def_delegators def_single_delegators + alias def_delegator def_single_delegator end |