# = forwardable - Support for the Delegation Pattern

[0] Fix | Delete

#

[1] Fix | Delete

# $Release Version: 1.1$

[2] Fix | Delete

# $Revision: 16857 $

[3] Fix | Delete

# $Date: 2008-06-06 17:05:24 +0900 (Fri, 06 Jun 2008) $

[4] Fix | Delete

# by Keiju ISHITSUKA(keiju@ishitsuka.com)

[5] Fix | Delete

#

[6] Fix | Delete

# Documentation by James Edward Gray II and Gavin Sinclair

[7] Fix | Delete

#

[8] Fix | Delete

# == Introduction

[9] Fix | Delete

#

[10] Fix | Delete

# This library allows you delegate method calls to an object, on a method by

[11] Fix | Delete

# method basis. You can use Forwardable to setup this delegation at the class

[12] Fix | Delete

# level, or SingleForwardable to handle it at the object level.

[13] Fix | Delete

#

[14] Fix | Delete

# == Notes

[15] Fix | Delete

#

[16] Fix | Delete

# Be advised, RDoc will not detect delegated methods.

[17] Fix | Delete

#

[18] Fix | Delete

# <b>forwardable.rb provides single-method delegation via the

[19] Fix | Delete

# def_delegator() and def_delegators() methods. For full-class

[20] Fix | Delete

# delegation via DelegateClass(), see delegate.rb.</b>

[21] Fix | Delete

#

[22] Fix | Delete

# == Examples

[23] Fix | Delete

#

[24] Fix | Delete

# === Forwardable

[25] Fix | Delete

#

[26] Fix | Delete

# Forwardable makes building a new class based on existing work, with a proper

[27] Fix | Delete

# interface, almost trivial. We want to rely on what has come before obviously,

[28] Fix | Delete

# but with delegation we can take just the methods we need and even rename them

[29] Fix | Delete

# as appropriate. In many cases this is preferable to inheritance, which gives

[30] Fix | Delete

# us the entire old interface, even if much of it isn't needed.

[31] Fix | Delete

#

[32] Fix | Delete

# class Queue

[33] Fix | Delete

# extend Forwardable

[34] Fix | Delete

#

[35] Fix | Delete

# def initialize

[36] Fix | Delete

# @q = [ ] # prepare delegate object

[37] Fix | Delete

# end

[38] Fix | Delete

#

[39] Fix | Delete

# # setup preferred interface, enq() and deq()...

[40] Fix | Delete

# def_delegator :@q, :push, :enq

[41] Fix | Delete

# def_delegator :@q, :shift, :deq

[42] Fix | Delete

#

[43] Fix | Delete

# # support some general Array methods that fit Queues well

[44] Fix | Delete

# def_delegators :@q, :clear, :first, :push, :shift, :size

[45] Fix | Delete

# end

[46] Fix | Delete

#

[47] Fix | Delete

# q = Queue.new

[48] Fix | Delete

# q.enq 1, 2, 3, 4, 5

[49] Fix | Delete

# q.push 6

[50] Fix | Delete

#

[51] Fix | Delete

# q.shift # => 1

[52] Fix | Delete

# while q.size > 0

[53] Fix | Delete

# puts q.deq

[54] Fix | Delete

# end

[55] Fix | Delete

#

[56] Fix | Delete

# q.enq "Ruby", "Perl", "Python"

[57] Fix | Delete

# puts q.first

[58] Fix | Delete

# q.clear

[59] Fix | Delete

# puts q.first

[60] Fix | Delete

#

[61] Fix | Delete

# <i>Prints:</i>

[62] Fix | Delete

#

[63] Fix | Delete

# 2

[64] Fix | Delete

# 3

[65] Fix | Delete

# 4

[66] Fix | Delete

# 5

[67] Fix | Delete

# 6

[68] Fix | Delete

# Ruby

[69] Fix | Delete

# nil

[70] Fix | Delete

#

[71] Fix | Delete

# === SingleForwardable

[72] Fix | Delete

#

[73] Fix | Delete

# printer = String.new

[74] Fix | Delete

# printer.extend SingleForwardable # prepare object for delegation

[75] Fix | Delete

# printer.def_delegator "STDOUT", "puts" # add delegation for STDOUT.puts()

[76] Fix | Delete

# printer.puts "Howdy!"

[77] Fix | Delete

#

[78] Fix | Delete

# <i>Prints:</i>

[79] Fix | Delete

#

[80] Fix | Delete

# Howdy!

[81] Fix | Delete

[82] Fix | Delete

#

[83] Fix | Delete

# The Forwardable module provides delegation of specified

[84] Fix | Delete

# methods to a designated object, using the methods #def_delegator

[85] Fix | Delete

# and #def_delegators.

[86] Fix | Delete

#

[87] Fix | Delete

# For example, say you have a class RecordCollection which

[88] Fix | Delete

# contains an array <tt>@records</tt>. You could provide the lookup method

[89] Fix | Delete

# #record_number(), which simply calls #[] on the <tt>@records</tt>

[90] Fix | Delete

# array, like this:

[91] Fix | Delete

#

[92] Fix | Delete

# class RecordCollection

[93] Fix | Delete

# extend Forwardable

[94] Fix | Delete

# def_delegator :@records, :[], :record_number

[95] Fix | Delete

# end

[96] Fix | Delete

#

[97] Fix | Delete

# Further, if you wish to provide the methods #size, #<<, and #map,

[98] Fix | Delete

# all of which delegate to @records, this is how you can do it:

[99] Fix | Delete

#

[100] Fix | Delete

# class RecordCollection

[101] Fix | Delete

# # extend Forwardable, but we did that above

[102] Fix | Delete

# def_delegators :@records, :size, :<<, :map

[103] Fix | Delete

# end

[104] Fix | Delete

#

[105] Fix | Delete

# Also see the example at forwardable.rb.

[106] Fix | Delete

#

[107] Fix | Delete

module Forwardable

[108] Fix | Delete

[109] Fix | Delete

@debug = nil

[110] Fix | Delete

class<<self

[111] Fix | Delete

# force Forwardable to show up in stack backtraces of delegated methods

[112] Fix | Delete

attr_accessor :debug

[113] Fix | Delete

end

[114] Fix | Delete

[115] Fix | Delete

#

[116] Fix | Delete

# Shortcut for defining multiple delegator methods, but with no

[117] Fix | Delete

# provision for using a different name. The following two code

[118] Fix | Delete

# samples have the same effect:

[119] Fix | Delete

#

[120] Fix | Delete

# def_delegators :@records, :size, :<<, :map

[121] Fix | Delete

#

[122] Fix | Delete

# def_delegator :@records, :size

[123] Fix | Delete

# def_delegator :@records, :<<

[124] Fix | Delete

# def_delegator :@records, :map

[125] Fix | Delete

#

[126] Fix | Delete

# See the examples at Forwardable and forwardable.rb.

[127] Fix | Delete

#

[128] Fix | Delete

def def_instance_delegators(accessor, *methods)

[129] Fix | Delete

for method in methods

[130] Fix | Delete

def_instance_delegator(accessor, method)

[131] Fix | Delete

end

[132] Fix | Delete

end

[133] Fix | Delete

[134] Fix | Delete

#

[135] Fix | Delete

# Defines a method _method_ which delegates to _obj_ (i.e. it calls

[136] Fix | Delete

# the method of the same name in _obj_). If _new_name_ is

[137] Fix | Delete

# provided, it is used as the name for the delegate method.

[138] Fix | Delete

#

[139] Fix | Delete

# See the examples at Forwardable and forwardable.rb.

[140] Fix | Delete

#

[141] Fix | Delete

def def_instance_delegator(accessor, method, ali = method)

[142] Fix | Delete

accessor = accessor.id2name if accessor.kind_of?(Integer)

[143] Fix | Delete

method = method.id2name if method.kind_of?(Integer)

[144] Fix | Delete

ali = ali.id2name if ali.kind_of?(Integer)

[145] Fix | Delete

[146] Fix | Delete

module_eval(<<-EOS, "(__FORWARDABLE__)", 1)

[147] Fix | Delete

def #{ali}(*args, &block)

[148] Fix | Delete

begin

[149] Fix | Delete

#{accessor}.__send__(:#{method}, *args, &block)

[150] Fix | Delete

rescue Exception

[151] Fix | Delete

$@.delete_if{|s| /^\\(__FORWARDABLE__\\):/ =~ s} unless Forwardable::debug

[152] Fix | Delete

Kernel::raise

[153] Fix | Delete

end

[154] Fix | Delete

end

[155] Fix | Delete

EOS

[156] Fix | Delete

end

[157] Fix | Delete

[158] Fix | Delete

alias def_delegators def_instance_delegators

[159] Fix | Delete

alias def_delegator def_instance_delegator

[160] Fix | Delete

end

[161] Fix | Delete

[162] Fix | Delete

#

[163] Fix | Delete

# The SingleForwardable module provides delegation of specified

[164] Fix | Delete

# methods to a designated object, using the methods #def_delegator

[165] Fix | Delete

# and #def_delegators. This module is similar to Forwardable, but it works on

[166] Fix | Delete

# objects themselves, instead of their defining classes.

[167] Fix | Delete

#

[168] Fix | Delete

# Also see the example at forwardable.rb.

[169] Fix | Delete

#

[170] Fix | Delete

module SingleForwardable

[171] Fix | Delete

#

[172] Fix | Delete

# Shortcut for defining multiple delegator methods, but with no

[173] Fix | Delete

# provision for using a different name. The following two code

[174] Fix | Delete

# samples have the same effect:

[175] Fix | Delete

#

[176] Fix | Delete

# single_forwardable.def_delegators :@records, :size, :<<, :map

[177] Fix | Delete

#

[178] Fix | Delete

# single_forwardable.def_delegator :@records, :size

[179] Fix | Delete

# single_forwardable.def_delegator :@records, :<<

[180] Fix | Delete

# single_forwardable.def_delegator :@records, :map

[181] Fix | Delete

#

[182] Fix | Delete

# See the example at forwardable.rb.

[183] Fix | Delete

#

[184] Fix | Delete

def def_singleton_delegators(accessor, *methods)

[185] Fix | Delete

for method in methods

[186] Fix | Delete

def_singleton_delegator(accessor, method)

[187] Fix | Delete

end

[188] Fix | Delete

end

[189] Fix | Delete

[190] Fix | Delete

#

[191] Fix | Delete

# Defines a method _method_ which delegates to _obj_ (i.e. it calls

[192] Fix | Delete

# the method of the same name in _obj_). If _new_name_ is

[193] Fix | Delete

# provided, it is used as the name for the delegate method.

[194] Fix | Delete

#

[195] Fix | Delete

# See the example at forwardable.rb.

[196] Fix | Delete

#

[197] Fix | Delete

def def_singleton_delegator(accessor, method, ali = method)

[198] Fix | Delete

accessor = accessor.id2name if accessor.kind_of?(Integer)

[199] Fix | Delete

method = method.id2name if method.kind_of?(Integer)

[200] Fix | Delete

ali = ali.id2name if ali.kind_of?(Integer)

[201] Fix | Delete

[202] Fix | Delete

instance_eval(<<-EOS, "(__FORWARDABLE__)", 1)

[203] Fix | Delete

def #{ali}(*args, &block)

[204] Fix | Delete

begin

[205] Fix | Delete

#{accessor}.__send__(:#{method}, *args,&block)

[206] Fix | Delete

rescue Exception

[207] Fix | Delete

$@.delete_if{|s| /^\\(__FORWARDABLE__\\):/ =~ s} unless Forwardable::debug

[208] Fix | Delete

Kernel::raise

[209] Fix | Delete

end

[210] Fix | Delete

end

[211] Fix | Delete

EOS

[212] Fix | Delete

end

[213] Fix | Delete

[214] Fix | Delete

alias def_delegators def_singleton_delegators

[215] Fix | Delete

alias def_delegator def_singleton_delegator

[216] Fix | Delete

end

[217] Fix | Delete

[218] Fix | Delete