diff options
| -rw-r--r-- | doc/forwardable.rd | 83 | ||||
| -rw-r--r-- | lib/forwardable.rb | 137 |
2 files changed, 62 insertions, 158 deletions
diff --git a/doc/forwardable.rd b/doc/forwardable.rd deleted file mode 100644 index 0eca25b90a..0000000000 --- a/doc/forwardable.rd +++ /dev/null @@ -1,83 +0,0 @@ - -- forwardable.rb - - $Release Version: 1.1 $ - $Revision$ - Original version by Tosh - -=begin - -= Forwardable - -A Module to define delegations for selected methods to a class. - -== Usage - -Using through extending the class. - - class Foo - extend Forwardable - - def_delegators("@out", "printf", "print") - def_delegators(:@in, :gets) - def_delegator(:@contents, :[], "content_at") - end - f = Foo.new - f.printf ... - f.gets - f.content_at(1) - -== Methods - ---- Forwardable#def_instance_delegators(accessor, *methods) - - adding the delegations for each method of ((|methods|)) to - ((|accessor|)). - ---- Forwardable#def_instance_delegator(accessor, method, ali = method) - - adding the delegation for ((|method|)) to ((|accessor|)). When - you give optional argument ((|ali|)), ((|ali|)) is used as the - name of the delegation method, instead of ((|method|)). - ---- Forwardable#def_delegators(accessor, *methods) - - the alias of ((|Forwardable#def_instance_delegators|)). - ---- Forwardable#def_delegator(accessor, method, ali = method) - - the alias of ((|Forwardable#def_instance_delegator|)). - -= SingleForwardable - -a Module to define delegations for selected methods to an object. - -== Usage - -Using through extending the object. - - g = Goo.new - g.extend SingleForwardable - g.def_delegator("@out", :puts) - g.puts ... - -== Methods - ---- SingleForwardable#def_singleton_delegators(accessor, *methods) - - adding the delegations for each method of ((|methods|)) to - ((|accessor|)). - ---- SingleForwardable#def_singleton_delegator(accessor, method, ali = method) - - adding the delegation for ((|method|)) to ((|accessor|)). When - you give optional argument ((|ali|)), ((|ali|)) is used as the - name of the delegation method, instead of ((|method|)). - ---- SingleForwardable#def_delegators(accessor, *methods) - - the alias of ((|SingleForwardable#def_instance_delegators|)). - ---- SingleForwardable#def_delegator(accessor, method, ali = method) - - the alias of ((|SingleForwardable#def_instance_delegator|)). -=end diff --git a/lib/forwardable.rb b/lib/forwardable.rb index 7a42e914bc..ac3d569d45 100644 --- a/lib/forwardable.rb +++ b/lib/forwardable.rb @@ -7,29 +7,49 @@ # 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. # -# == 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. +# class RecordCollection +# extend Forwardable +# def_delegator :@records, :[], :record_number +# end # -# == Notes +# Further, if you wish to provide the methods #size, #<<, and #map, +# all of which delegate to @records, this is how you can do it: # -# Be advised, RDoc will not detect delegated methods. +# class RecordCollection +# # extend Forwardable, but we did that above +# def_delegators :@records, :size, :<<, :map +# end +# f = Foo.new +# f.printf ... +# f.gets +# f.content_at(1) # -# <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> +# If the object isn't a Module and Class, You can too extend Forwardable +# module. # -# == Examples +# printer = String.new +# printer.extend Forwardable # prepare object for delegation +# printer.def_delegator "STDOUT", "puts" # add delegation for STDOUT.puts() +# printer.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. +# 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. # # class Queue # extend Forwardable @@ -60,7 +80,7 @@ # q.clear # puts q.first # -# <i>Prints:</i> +# This should output: # # 2 # 3 @@ -70,72 +90,22 @@ # Ruby # nil # -# 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 use to Class or Module. -# -# module Facade -# extend SingleForwardable -# def_delegator :Implementation, :service -# -# class Implementation -# def service... -# end -# end -# -# If you want to use both Forwardable and SingleForwardable, you can -# use methods def_instance_delegator and def_single_delegator, etc. -# -# If the object isn't a Module and Class, You can too extend -# Forwardable module. -# printer = String.new -# printer.extend Forwardable # 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: +# == Notes # -# class RecordCollection -# extend Forwardable -# def_delegator :@records, :[], :record_number -# end +# Be advised, RDoc will not detect delegated methods. # -# Further, if you wish to provide the methods #size, #<<, and #map, -# all of which delegate to @records, this is how you can do it: +# +forwardable.rb+ provides single-method delegation via the def_delegator and +# def_delegators methods. For full-class delegation via DelegateClass, see +# +delegate.rb+. # -# class RecordCollection -# # extend Forwardable, but we did that above -# def_delegators :@records, :size, :<<, :map -# end -# f = Foo.new -# f.printf ... -# f.gets -# f.content_at(1) -# -# Also see the example at forwardable.rb. - module Forwardable + # Version of +forwardable.rb+ FORWARDABLE_VERSION = "1.1.0" @debug = nil class << self + # If true, <tt>__FILE__</tt> will remain in the backtrace in the event an + # Exception is raised. attr_accessor :debug end @@ -219,9 +189,26 @@ module Forwardable alias def_delegator def_instance_delegator 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!" # -# Usage of The SingleForwardable is like Fowadable module. +# Also, SingleForwardable can be use to Class or Module. +# +# module Facade +# extend SingleForwardable +# def_delegator :Implementation, :service +# +# class Implementation +# def service... +# end +# end # +# 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 |