* 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

1 files changed, 170 insertions, 21 deletions

diff --git a/lib/delegate.rb b/lib/delegate.rb
index ca1f028268..2a0119d082 100644
--- a/lib/delegate.rb
+++ b/lib/delegate.rb
@@ -1,23 +1,125 @@
-#  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.
+# = delegate -- Support for the Delegation Pattern
 #
-# Usage:
-#   foo = Object.new
-#   foo2 = SimpleDelegator.new(foo)
-#   foo.hash == foo2.hash # => false
+# Documentation by James Edward Gray II and Gavin Sinclair
 #
-#   Foo = DelegateClass(Array)
+# == Introduction
 #
-#  class ExtArray<DelegateClass(Array)
-#    ...
-#  end
+# 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
 
+  #
+  # Pass in the _obj_ to delegate method calls to.  All methods supported by
+  # _obj_ will be delegated to.
+  #
   def initialize(obj)
     preserved = ::Kernel.public_instance_methods(false)
     preserved -= ["to_s","to_a","inspect","==","=~","==="]
@@ -49,6 +151,7 @@ class Delegator
   end
   alias initialize_methods initialize
 
+  # Handles the magic of delegation through \_\_getobj\_\_.
   def method_missing(m, *args)
     target = self.__getobj__
     unless target.respond_to?(m)
@@ -57,23 +160,39 @@ class Delegator
     target.__send__(m, *args)
   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
 
+  # Serialization support for the object returned by \_\_getobj\_\_.
   def marshal_dump
     __getobj__
   end
+  # Reinitializes delegation from a serialized object.
   def marshal_load(obj)
     initialize_methods(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
 
   def initialize(obj)
@@ -81,61 +200,89 @@ class SimpleDelegator<Delegator
     @_sd_obj = obj
   end
 
+  # 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
     super
     __setobj__(__getobj__.clone)
   end
+  # Duplication support for the object returned by \_\_getobj\_\_.
   def dup(obj)
     super
     __setobj__(__getobj__.dup)
   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)
   methods -= ::Kernel.public_instance_methods(false)
   methods |= ["to_s","to_a","inspect","==","=~","==="]
   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
@@ -159,6 +306,8 @@ def DelegateClass(superclass)
   return klass
 end
 
+# :enddoc:
+
 if __FILE__ == $0
   class ExtArray<DelegateClass(Array)
     def initialize()