mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00

This restores compatibility with previous versions. This behavior
was previously undefined, but it makes sense for the name of the
defined method to be returned.
a52ef3451e
316 lines
8.9 KiB
Ruby
316 lines
8.9 KiB
Ruby
# frozen_string_literal: false
|
|
#
|
|
# 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
|
|
|
|
|
|
|
|
# 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:
|
|
#
|
|
# require 'forwardable'
|
|
#
|
|
# class RecordCollection
|
|
# attr_accessor :records
|
|
# extend Forwardable
|
|
# def_delegator :@records, :[], :record_number
|
|
# end
|
|
#
|
|
# 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]
|
|
#
|
|
# You can even extend regular objects with Forwardable.
|
|
#
|
|
# 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!"
|
|
#
|
|
# == Another example
|
|
#
|
|
# 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
|
|
#
|
|
# def initialize
|
|
# @q = [ ] # prepare delegate object
|
|
# end
|
|
#
|
|
# # setup preferred interface, enq() and deq()...
|
|
# def_delegator :@q, :push, :enq
|
|
# def_delegator :@q, :shift, :deq
|
|
#
|
|
# # support some general Array methods that fit Queues well
|
|
# def_delegators :@q, :clear, :first, :push, :shift, :size
|
|
# end
|
|
#
|
|
# q = Queue.new
|
|
# q.enq 1, 2, 3, 4, 5
|
|
# q.push 6
|
|
#
|
|
# q.shift # => 1
|
|
# while q.size > 0
|
|
# puts q.deq
|
|
# end
|
|
#
|
|
# q.enq "Ruby", "Perl", "Python"
|
|
# puts q.first
|
|
# q.clear
|
|
# puts q.first
|
|
#
|
|
# This should output:
|
|
#
|
|
# 2
|
|
# 3
|
|
# 4
|
|
# 5
|
|
# 6
|
|
# Ruby
|
|
# nil
|
|
#
|
|
# == Notes
|
|
#
|
|
# Be advised, RDoc will not detect delegated methods.
|
|
#
|
|
# +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
|
|
require 'forwardable/impl'
|
|
require "forwardable/version"
|
|
|
|
@debug = nil
|
|
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
|
|
# samples have the same effect:
|
|
#
|
|
# def_delegators :@records, :size, :<<, :map
|
|
#
|
|
# def_delegator :@records, :size
|
|
# def_delegator :@records, :<<
|
|
# def_delegator :@records, :map
|
|
#
|
|
def def_instance_delegators(accessor, *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.
|
|
#
|
|
# 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
|
|
#
|
|
# 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)
|
|
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
|
|
ret = mod.module_eval(&gen)
|
|
mod.send(:ruby2_keywords, ali) if RUBY_VERSION >= '2.7'
|
|
ret
|
|
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
|
|
|
|
method_call = ".__send__(:#{method}, *args, &block)"
|
|
if _valid_method?(method)
|
|
loc, = caller_locations(2,1)
|
|
pre = "_ ="
|
|
mesg = "#{Module === obj ? obj : obj.class}\##{ali} at #{loc.path}:#{loc.lineno} forwarding to private method "
|
|
method_call = "#{<<-"begin;"}\n#{<<-"end;".chomp}"
|
|
begin;
|
|
unless defined? _.#{method}
|
|
::Kernel.warn #{mesg.dump}"\#{_.class}"'##{method}', uplevel: 1
|
|
_#{method_call}
|
|
else
|
|
_.#{method}(*args, &block)
|
|
end
|
|
end;
|
|
end
|
|
|
|
_compile_method("#{<<-"begin;"}\n#{<<-"end;"}", __FILE__, __LINE__+1)
|
|
begin;
|
|
proc do
|
|
def #{ali}(*args, &block)
|
|
#{pre}
|
|
begin
|
|
#{accessor}
|
|
end#{method_call}
|
|
end
|
|
end
|
|
end;
|
|
end
|
|
end
|
|
|
|
# SingleForwardable can be used to setup delegation at the object level as well.
|
|
#
|
|
# 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.
|
|
#
|
|
# 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:
|
|
#
|
|
# def_delegators :@records, :size, :<<, :map
|
|
#
|
|
# def_delegator :@records, :size
|
|
# def_delegator :@records, :<<
|
|
# def_delegator :@records, :map
|
|
#
|
|
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 _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.
|
|
# Returns the name of the method defined.
|
|
def def_single_delegator(accessor, method, ali = method)
|
|
gen = Forwardable._delegator_method(self, accessor, method, ali)
|
|
|
|
ret = instance_eval(&gen)
|
|
singleton_class.send(:ruby2_keywords, ali) if RUBY_VERSION >= '2.7'
|
|
ret
|
|
end
|
|
|
|
alias delegate single_delegate
|
|
alias def_delegators def_single_delegators
|
|
alias def_delegator def_single_delegator
|
|
end
|