TheForwardable module provides delegation of specified methods to a designated object, using the methodsdef_delegator anddef_delegators.

For example, say you have a class RecordCollection which contains an array@records. You could provide the lookup method record_number(), which simply calls [] on the@records array, like this:

require'forwardable'classRecordCollectionattr_accessor:recordsextendForwardabledef_delegator:@records,:[],:record_numberend

We can use the lookup method like so:

r =RecordCollection.newr.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:

classRecordCollection# re-open RecordCollection classdef_delegators:@records,:size,:<<,:mapendr =RecordCollection.newr.records = [1,2,3]r.record_number(0)# => 1r.size# => 3r<<4# => [1, 2, 3, 4]r.map {|x|x*2 }# => [2, 4, 6, 8]

You can even extend regular objects withForwardable.

my_hash =Hash.newmy_hash.extendForwardable# prepare object for delegationmy_hash.def_delegator"STDOUT","puts"# add delegation for STDOUT.puts()my_hash.puts"Howdy!"

Another example

You could useForwardable 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 ofArray instance methods to a new classQueue:

classQueueextendForwardabledefinitialize@q = [ ]# prepare delegate objectend# setup preferred interface, enq() and deq()...def_delegator:@q,:push,:enqdef_delegator:@q,:shift,:deq# support some general Array methods that fit Queues welldef_delegators:@q,:clear,:first,:push,:shift,:sizeendq =Thread::Queue.newq.enq1,2,3,4,5q.push6q.shift# => 1whileq.size>0putsq.deqendq.enq"Ruby","Perl","Python"putsq.firstq.clearputsq.first

This should output:

23456Rubynil

Notes

Be advised, RDoc will not detect delegated methods.

forwardable.rb provides single-method delegation via thedef_delegator anddef_delegators methods. For full-class delegation via DelegateClass, seedelegate.rb.