ruby-core

On Sep 23, 2005, at 10:54 AM, Yukihiro Matsumoto wrote:

> I will apply if you re-send the patch in unified format (-u).

How is this?

James Edward Gray II

Attachments (1)

for_n_del_unified.diff (15.2 KB, text/x-diff)

Index: lib/.document
===================================================================
RCS file: /src/ruby/lib/.document,v
retrieving revision 1.8
diff -u -r1.8 .document
--- lib/.document	24 Aug 2005 05:07:58 -0000	1.8
+++ lib/.document	23 Sep 2005 16:10:16 -0000
@@ -14,8 +14,11 @@
 cgi.rb
 complex.rb
 date.rb
+delegate.rb
+erb.rb
 fileutils.rb
 find.rb
+forwardable.rb
 generator.rb
 logger.rb
 matrix.rb
Index: lib/delegate.rb
===================================================================
RCS file: /src/ruby/lib/delegate.rb,v
retrieving revision 1.28
diff -u -r1.28 delegate.rb
--- lib/delegate.rb	12 Aug 2005 07:17:36 -0000	1.28
+++ lib/delegate.rb	23 Sep 2005 16:10:16 -0000
@@ -1,21 +1,119 @@
-#  Delegation class that delegates even methods defined in super class,
-# which can not be covered with normal method_missing hack.
-#  
-#  Delegator is the abstract delegation class. Need to redefine
-# `__getobj__' method in the subclass.  SimpleDelegator is the 
-# concrete subclass for simple delegation.
-#
-# Usage:
-#   foo = Object.new
-#   foo2 = SimpleDelegator.new(foo)
-#   foo.hash == foo2.hash # => false
-#
-#   Foo = DelegateClass(Array)
-#
-#  class ExtArray<DelegateClass(Array)
-#    ...
-#  end
+# = delegate -- Support for the Delegation Pattern
+#
+# Documentation by James Edward Gray II and Gavin Sinclair
+#
+# == Introduction
+#
+# This library provides three different ways to delegate method calls to an
+# object.  The easiest to use is SimpleDelegator.  Pass an object to the
+# constructor and all methods supported by the object will be delegated.  This
+# object can be changed later.
+#
+# Going a step further, the top level DelegateClass method allows you to easily
+# setup delegation through class inheritance.  This is considerably more
+# flexible and thus probably the most common use for this library.
+#
+# Finally, if you need full control over the delegation scheme, you can inherit
+# from the abstract class Delegator and customize as needed.  (If you find
+# yourself needing this control, have a look at _forwardable_, also in the
+# standard library.  It may suit your needs better.)
+#
+# == Notes
+#
+# Be advised, RDoc will not detect delegated methods.
+#
+# <b>delegate.rb provides full-class delegation via the
+# DelegateClass() method.  For single-method delegation via
+# def_delegator(), see forwardable.rb.</b>
+#
+# == Examples
+#
+# === SimpleDelegator
+#
+# Here's a simple example that takes advantage of the fact that
+# SimpleDelegator's delegation object can be changed at any time.
+#
+#   class Stats
+#     def initialize
+#       @source = SimpleDelegator.new([])
+#     end
+#     
+#     def stats( records )
+#       @source.__setobj__(records)
+#       	
+#       "Elements:  #{@source.size}\n" +
+#       " Non-Nil:  #{@source.compact.size}\n" +
+#       "  Unique:  #{@source.uniq.size}\n"
+#     end
+#   end
+#   
+#   s = Stats.new
+#   puts s.stats(%w{James Edward Gray II})
+#   puts
+#   puts s.stats([1, 2, 3, nil, 4, 5, 1, 2])
+#
+# <i>Prints:</i>
+#
+#   Elements:  4
+#    Non-Nil:  4
+#     Unique:  4
+# 
+#   Elements:  8
+#    Non-Nil:  7
+#     Unique:  6
+#
+# === DelegateClass()
+#
+# Here's a sample of use from <i>tempfile.rb</i>.
+#
+# A _Tempfile_ object is really just a _File_ object with a few special rules
+# about storage location and/or when the File should be deleted.  That makes for
+# an almost textbook perfect example of how to use delegation.
+#
+#   class Tempfile < DelegateClass(File)
+#     # constant and class member data initialization...
+#   
+#     def initialize(basename, tmpdir=Dir::tmpdir)
+#       # build up file path/name in var tmpname...
+#     
+#       @tmpfile = File.open(tmpname, File::RDWR|File::CREAT|File::EXCL, 0600)
+#     
+#       # ...
+#     
+#       super(@tmpfile)
+#     
+#       # below this point, all methods of File are supported...
+#     end
+#   
+#     # ...
+#   end
+#
+# === Delegator
+#
+# SimpleDelegator's implementation serves as a nice example here.
+#
+#    class SimpleDelegator < Delegator
+#      def initialize(obj)
+#        super             # pass obj to Delegator constructor, required
+#        @_sd_obj = obj    # store obj for future use
+#      end
+# 
+#      def __getobj__
+#        @_sd_obj          # return object we are delegating to, required
+#      end
+# 
+#      def __setobj__(obj)
+#        @_sd_obj = obj    # change delegation object, a feature we're providing
+#      end
+# 
+#      # ...
+#    end
 
+#
+# Delegator is an abstract class used to build delegator pattern objects from
+# subclasses.  Subclasses should redefine \_\_getobj\_\_.  For a concrete
+# implementation, see SimpleDelegator.
+#
 class Delegator
   preserved = ["__id__", "object_id", "__send__", "respond_to?"]
   instance_methods.each do |m|
@@ -23,10 +121,15 @@
     undef_method m
   end
 
+  #
+  # Pass in the _obj_ to delegate method calls to.  All methods supported by
+  # _obj_ will be delegated to.
+  #
   def initialize(obj)
     __setobj__(obj)
   end
 
+  # Handles the magic of delegation through \_\_getobj\_\_.
   def method_missing(m, *args)
     begin
       target = self.__getobj__
@@ -40,42 +143,79 @@
     end
   end
 
+  # 
+  # Checks for a method provided by this the delegate object by fowarding the 
+  # call through \_\_getobj\_\_.
+  # 
   def respond_to?(m)
     return true if super
     return self.__getobj__.respond_to?(m)
   end
 
+  #
+  # This method must be overridden by subclasses and should return the object
+  # method calls are being delegated to.
+  #
   def __getobj__
     raise NotImplementedError, "need to define `__getobj__'"
   end
 
+  #
+  # This method must be overridden by subclasses and change the object delegate
+  # to _obj_.
+  #
   def __setobj__(obj)
     raise NotImplementedError, "need to define `__setobj__'"
   end
 
+  # Serialization support for the object returned by \_\_getobj\_\_.
   def marshal_dump
     __getobj__
   end
+  # Reinitializes delegation from a serialized object.
   def marshal_load(obj)
     __setobj__(obj)
   end
 end
 
+#
+# A concrete implementation of Delegator, this class provides the means to
+# delegate all supported method calls to the object passed into the constructor
+# and even to change the object being delegated to at a later time with
+# \_\_setobj\_\_ .
+#
 class SimpleDelegator<Delegator
+  # Returns the current object method calls are being delegated to.
   def __getobj__
     @_sd_obj
   end
 
+  #
+  # Changes the delegate object to _obj_.
+  #
+  # It's important to note that this does *not* cause SimpleDelegator's methods
+  # to change.  Because of this, you probably only want to change delegation
+  # to objects of the same type as the original delegate.
+  #
+  # Here's an example of changing the delegation object.
+  #
+  #   names = SimpleDelegator.new(%w{James Edward Gray II})
+  #   puts names[1]    # => Edward
+  #   names.__setobj__(%w{Gavin Sinclair})
+  #   puts names[1]    # => Sinclair
+  #
   def __setobj__(obj)
     raise ArgumentError, "cannot delegate to self" if self.equal?(obj)
     @_sd_obj = obj
   end
 
+  # Clone support for the object returned by \_\_getobj\_\_.
   def clone
     copy = super
     copy.__setobj__(__getobj__.clone)
     copy
   end
+  # Duplication support for the object returned by \_\_getobj\_\_.
   def dup
     copy = super
     copy.__setobj__(__getobj__.dup)
@@ -83,11 +223,22 @@
   end
 end
 
+# :stopdoc:
 # backward compatibility ^_^;;;
 Delegater = Delegator
 SimpleDelegater = SimpleDelegator
+# :startdoc:
 
 #
+# The primary interface to this library.  Use to setup delegation when defining
+# your class.
+#
+#   class MyClass < DelegateClass( ClassToDelegateTo )    # Step 1
+#     def initiaize
+#       super(obj_of_ClassToDelegateTo)                   # Step 2
+#     end
+#   end
+#
 def DelegateClass(superclass)
   klass = Class.new
   methods = superclass.public_instance_methods(true)
@@ -97,31 +248,31 @@
     "clone", "dup", "marshal_dump", "marshal_load",
   ]
   klass.module_eval {
-    def initialize(obj)
+    def initialize(obj)  # :nodoc:
       @_dc_obj = obj
     end
-    def method_missing(m, *args)
+    def method_missing(m, *args)  # :nodoc:
       unless @_dc_obj.respond_to?(m)
         super(m, *args)
       end
       @_dc_obj.__send__(m, *args)
     end
-    def respond_to?(m)
+    def respond_to?(m)  # :nodoc:
       return true if super
       return @_dc_obj.respond_to?(m)
     end
-    def __getobj__
+    def __getobj__  # :nodoc:
       @_dc_obj
     end
-    def __setobj__(obj)
+    def __setobj__(obj)  # :nodoc:
       raise ArgumentError, "cannot delegate to self" if self.equal?(obj)
       @_dc_obj = obj
     end
-    def clone
+    def clone  # :nodoc:
       super
       __setobj__(__getobj__.clone)
     end
-    def dup
+    def dup  # :nodoc:
       super
       __setobj__(__getobj__.dup)
     end
@@ -145,6 +296,8 @@
   return klass
 end
 
+# :enddoc:
+
 if __FILE__ == $0
   class ExtArray<DelegateClass(Array)
     def initialize()
Index: lib/forwardable.rb
===================================================================
RCS file: /src/ruby/lib/forwardable.rb,v
retrieving revision 1.2
diff -u -r1.2 forwardable.rb
--- lib/forwardable.rb	3 Nov 2001 13:41:57 -0000	1.2
+++ lib/forwardable.rb	23 Sep 2005 16:10:16 -0000
@@ -1,45 +1,145 @@
+# = forwardable - Support for the Delegation Pattern
 #
-#   forwardable.rb - 
-#   	$Release Version: 1.1$
-#   	$Revision: 1.2 $
-#   	$Date: 2001/11/03 13:41:57 $
-#   	by Keiju ISHITSUKA(keiju@ishitsuka.com)
-#	original definition by delegator.rb
-# --
-# Usage:
+#    $Release Version: 1.1$
+#    $Revision: 1.2 $
+#    $Date: 2001/11/03 13:41:57 $
+#    by Keiju ISHITSUKA(keiju@ishitsuka.com)
 #
-#   class Foo
+#    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
+#
+# 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
+# 
+#   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>
+#
+#   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:
 #
-#     def_delegators("@out", "printf", "print")
-#     def_delegators(:@in, :gets)
-#     def_delegator(:@contents, :[], "content_at")
+#   class RecordCollection
+#     # extends Forwardable, but we did that above
+#     def_delegators :@records, :size, :<<, :map
 #   end
-#   f = Foo.new
-#   f.printf ...
-#   f.gets
-#   f.content_at(1)
-#
-#   g = Goo.new
-#   g.extend SingleForwardable
-#   g.def_delegator("@out", :puts)
-#   g.puts ...
 #
+# 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 @@
   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)

Thread

Prev Next

In This Thread

Prev Next

[#5711] Lexic confusion: method/local variable distinction works strange — noreply@...

[#5721] uninitialized constant REXML::Parsers::SAX2Parser::Text — noreply@...

[#5724] SystemExit & abort_on_exception in latest "ruby_1_8" — Johan Holmberg <holmberg@...>

[#5727] executing linux shell commands with ruby?? — Pranith Kumar Karampuri <praneeth147@...>

[#5729] Valgrind support — Tilman Sauerbeck <tilman@...>

[#5731] Ruby development issue tracking will go to basecamp — Yukihiro Matsumoto <matz@...>

[#5732] Re: Ruby development issue tracking will go to basecamp — ville.mattila@...

[#5737] returning strings from methods/instance_methods — TRANS <transfire@...>

[#5747] YAML.load hang-up — Kazuhiro NISHIYAMA <zn@...>

[#5750] File.split edge cases — "Berger, Daniel" <Daniel.Berger@...>

[#5752] assert_raises — Eric Hodel <drbrain@...7.net>

[#5753] Wilderness: AutoLoad Feature (variable.c)- Need General Description — "Charles E. Thornton" <ruby-core@...>

[#5766] Re: File.split edge cases — "Berger, Daniel" <Daniel.Berger@...>

[#5768] Wilderness: AutoLoad Feature (variable.c)- Need General Description — "Charles E. Thornton" <ruby-core@...>

[#5774] YAML broken — Kazuhiro NISHIYAMA <zn@...>

[#5779] Strange 'ambiguous arguments' warning — Nathaniel Talbott <ntalbott@...>

[#5781] array sharing — Eric Mahurin <eric_mahurin@...>

[#5784] Documentation for 1.8.3 — Eric Hodel <drbrain@...7.net>

[#5786] Difference between class declarations — Peter Vanbroekhoven <calamitas@...>

[#5787] Wilderness: How does __autoload__ work?? — "Charles E. Thornton" <ruby-core@...>

[#5793] syck.so compile error — URABE Shyouhei <s-urabe@...>

[#5796] proposed attr writer patch — Daniel Berger <Daniel.Berger@...>

[#5797] Re: proposed attr writer patch — "Berger, Daniel" <Daniel.Berger@...>

[#5798] Makefile error in OpenSLL extension (on Windows) — noreply@...

[#5804] Wilderness: Is there any way to invoke rb_define_class() from the Ruby Level — "Charles E. Thornton" <ruby-core@...>

[#5806] 5**(-1/2) gives incorrect results under mathn. — C Erler <erlercw@...>

[#5807] Wliderness: Ruby Code to force AUTOLOAD sequence to run — "Charles E. Thornton" <ruby-core@...>

[#5818] Weird SIGCHLD-related problem — Ben Schumacher <benschumacher@...>

[#5820] patch for O(1) performance for Array#unshift and Array#shift — Eric Mahurin <eric_mahurin@...>

[#5826] YAML bug - dump string terminating with ':' — "H.Yamamoto" <ocean@...2.ccsnet.ne.jp>

[#5837] Re: RubyGems in Ruby HEAD — TRANS <transfire@...>

[#5838] Re: RubyGems in Ruby HEAD — David Heinemeier Hansson <david.heinemeier@...>

[#5839] Forward: [ruby-dev:27237] Re: yaml warnig in verbose mode — nobu.nokada@...

[#5840] Re: RubyGems in Ruby HEAD — Aredridel <aredridel@...>

[#5842] Re: RubyGems in Ruby HEAD — Eric Hodel <drbrain@...7.net>

[#5844] Ruby 1.8.3 released — Yukihiro Matsumoto <matz@...>

[#5848] Re: RubyGems in Ruby HEAD — Hugh Sasse <hgs@...>

[#5851] Re: RubyGems in Ruby HEAD — Paul van Tilburg <paul@...>

[#5854] Warnings in YAML — noreply@...

[#5858] FileUtils#cd doesn't allow :noop in options anymore, but still queries it — noreply@...

[#5861] another array patch - performance boosts all over the place — Eric Mahurin <eric_mahurin@...>

[#5863] Re: another array patch - performance boosts all over the place — "Berger, Daniel" <Daniel.Berger@...>

[#5871] Wilderness: What is ID_JUNK Used for? — "Charles E. Thornton" <ruby-core@...>

[#5879] Re: RubyGems TODO — Austin Ziegler <halostatue@...>

[#5882] Re: RubyGems TODO — Austin Ziegler <halostatue@...>

[#5888] Re: RubyGems TODO — Mauricio Fern疣dez <mfp@...>

[#5896] Re: RubyGems TODO — Tom Copeland <tom@...>

[#5898] Delegate and Forwardable Documentation — James Edward Gray II <james@...>

[#5899] Re: Delegate and Forwardable Documentation — "Berger, Daniel" <Daniel.Berger@...>

[#5901] Re: RubyGems TODO — "Jim Weirich" <jim@...>

[#5902] Vulnerability fixed in 1.8.3 — Yukihiro Matsumoto <matz@...>

[#5905] The standard library "openssl" does not get built/installed in ruby 1.8.3. — noreply@...

[#5906] Re: RubyGems TODO — Daigo Moriwaki <techml@...>

[#5910] 1.8.3, pleasant surprise. — Hugh Sasse <hgs@...>

[#5921] Mutually dependent libs double loading. — TRANS <transfire@...>

[#5932] patch for imap.rb -- error handling when waiting for continuation request response — noreply@...

[#5933] — "Andreas Farre" <d00farre@...>

[#5954] FileUtils::Verbose.{compare_file,uptodate?} are private in Ruby 1.8.3 — noreply@...

[#5955] Re: RubyGems TODO (the Second) — TRANS <transfire@...>

[#5966] $SAFE=4 is still dangerous to use as a sandbox — URABE Shyouhei <s-urabe@...>

[#5970] [BUG] unknown node type 0 -- on Linux, AMD Athlon 900, Ruby 1.8.3 — noreply@...

[#5975] segmentation fault on require 'yaml' — Ralph Amissah <ralph.amissah@...>

[#5976] basecamp RSS feed requires username and passwd — sheepman <sheepman@...>

[#5984] Wilderness: How to convert from Klass/Super References to Name — "Charles E. Thornton" <ruby-core@...>

[#5985] Finally an answer to my RubyGems question and some small suggestions — TRANS <transfire@...>

[#5992] New Ruby Mirror Ready — "Scott B." <scott@...>

[#5999] ruby 1.8.3 (2005-06-23) [i486-linux] sisu segfault — Ralph Amissah <ralph.amissah@...>

[#6001] Require Namepaces and RubyGems' effect on LoadPath problem — TRANS <transfire@...>

[#6004] Problem with 1.8.3, extensions — Daniel Berger <Daniel.Berger@...>

[#6009] Re: ruby 1.8.3 (2005-09-21) [i486-linux] sisu segfault — Ralph Amissah <ralph.amissah@...>

[#6021] $\ not escaped in IO#print documentation — noreply@...

[#6031] Undefined method error in net/http.rb — noreply@...

[#6038] make warning from 1.8.3 — Daniel Berger <Daniel.Berger@...>

[#6053] _'s not escaped in Object#send documentation — noreply@...

[#6057] YAML loading of quoted Symbols broken in 1.8.3 — noreply@...

[#6070] Ads by gooooooooogle on Ruby Home Page... — Austin Ziegler <halostatue@...>

[#6076] Question about cgi.rb's read_multipart method and possible fix — "Zev Blut" <rubyzbibd@...>

[#6089] irb segfault — "David A. Black" <dblack@...>

[#6108] Re: [sydney-devel] Threading Performance? — Evan Webb <evanwebb@...>

[#6109] Fix a warning in Syck — Tilman Sauerbeck <tilman@...>

[#5787] Wilderness: How does autoload work?? — "Charles E. Thornton" <ruby-core@...>