diff options
author | matz <matz@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2005-09-26 13:59:47 +0000 |
---|---|---|
committer | matz <matz@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2005-09-26 13:59:47 +0000 |
commit | 81b728c2436bfd94abe33b152493bc5b7a3a1728 (patch) | |
tree | 2145042614c2bc1daad13f7c3def31dd31d09bff /lib/forwardable.rb | |
parent | 54ca4e2269ffd818dcd2bd36ea474c03e1ad64af (diff) |
* eval.c (set_trace_func): add rb_secure(4) to prevent adding
tracing function.
* lib/delegate.rb: document update from James Edward Gray II
<james@grayproductions.net>. [ruby-core:05942]
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@9317 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/forwardable.rb')
-rw-r--r-- | lib/forwardable.rb | 174 |
1 files changed, 149 insertions, 25 deletions
diff --git a/lib/forwardable.rb b/lib/forwardable.rb index b845f76ec4..79004ccd20 100644 --- a/lib/forwardable.rb +++ b/lib/forwardable.rb @@ -1,45 +1,145 @@ +# = forwardable - Support for the Delegation Pattern # -# forwardable.rb - -# $Release Version: 1.1$ -# $Revision$ -# $Date$ -# by Keiju ISHITSUKA(keiju@ishitsuka.com) -# original definition by delegator.rb -# -- -# Usage: +# $Release Version: 1.1$ +# $Revision$ +# $Date$ +# by Keiju ISHITSUKA(keiju@ishitsuka.com) # -# class Foo -# extend Forwardable +# Documentation by James Edward Gray II and Gavin Sinclair +# +# == Introduction +# +# 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. +# +# == Notes +# +# Be advised, RDoc will not detect delegated methods. +# +# <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> +# +# == Examples +# +# === Forwardable # -# def_delegators("@out", "printf", "print") -# def_delegators(:@in, :gets) -# def_delegator(:@contents, :[], "content_at") +# 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. +# +# class Queue +# extend Forwardable +# +# def initialize +# @q = [ ] # prepare delegate object +# end +# +# # setup prefered 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 -# f = Foo.new -# f.printf ... -# f.gets -# f.content_at(1) +# +# 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 +# +# <i>Prints:</i> # -# g = Goo.new -# g.extend SingleForwardable -# g.def_delegator("@out", :puts) -# g.puts ... +# 2 +# 3 +# 4 +# 5 +# 6 +# 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 +# extends 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: +# +# class RecordCollection +# # extends Forwardable, but we did that above +# def_delegators :@records, :size, :<<, :map +# end +# +# Also see the example at forwardable.rb. +# module Forwardable @debug = nil class<<self + # force Forwardable to show up in stack backtraces of delegated methods attr_accessor :debug 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 + # + # See the examples at Forwardable and forwardable.rb. + # def def_instance_delegators(accessor, *methods) for method in methods def_instance_delegator(accessor, method) end end + # + # 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. + # + # See the examples at Forwardable and forwardable.rb. + # def def_instance_delegator(accessor, method, ali = method) accessor = accessor.id2name if accessor.kind_of?(Integer) method = method.id2name if method.kind_of?(Integer) @@ -61,13 +161,41 @@ module Forwardable alias def_delegator def_instance_delegator end +# +# 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. +# +# Also see the example at forwardable.rb. +# module SingleForwardable + # + # 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 + # + # See the example at forwardable.rb. + # def def_singleton_delegators(accessor, *methods) for method in methods def_singleton_delegator(accessor, method) end end + # + # 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. + # + # 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) @@ -88,7 +216,3 @@ module SingleForwardable alias def_delegators def_singleton_delegators alias def_delegator def_singleton_delegator end - - - - |