drbrain	2011-07-27 15:44:39 +0900 (Wed, 27 Jul 2011)

  New Revision: 32700

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=32700

  Log:
    * object.c:  Add usage documentation for BasicObject.  Based on patch
      by Thomas Sawyer.  [Ruby 1.9 - Bug #5067]

  Modified files:
    trunk/ChangeLog
    trunk/object.c

Index: ChangeLog
===================================================================
--- ChangeLog	(revision 32699)
+++ ChangeLog	(revision 32700)
@@ -1,3 +1,8 @@
+Wed Jul 27 15:39:14 2011  Eric Hodel  <drbrain@s...>
+
+	* object.c:  Add usage documentation for BasicObject.  Based on patch
+	  by Thomas Sawyer.  [Ruby 1.9 - Bug #5067]
+
 Wed Jul 27 12:24:17 2011  Eric Hodel  <drbrain@s...>
 
 	* lib/rubygems/uninstaller.rb:  Add missing require and update
Index: object.c
===================================================================
--- object.c	(revision 32699)
+++ object.c	(revision 32700)
@@ -2614,6 +2614,53 @@
  *
  *  BasicObject is the parent class of all classes in Ruby.  It's an explicit
  *  blank class.
+ *
+ *  BasicObject can be used for creating object hierarchies independent of
+ *  Ruby's object hierarchy, proxy objects like the Delegator class, or other
+ *  uses where namespace pollution from Ruby's methods and classes must be
+ *  avoided.
+ *
+ *  To avoid polluting BasicObject for other users an appropriately named
+ *  subclass of BasicObject should be created instead of directly modifying
+ *  BasicObject:
+ *
+ *    class MyObjectSystem < BasicObject
+ *    end
+ *
+ *  BasicObject does not include Kernel (for methods like +puts+) and
+ *  BasicObject is outside of the namespace of the standard library so common
+ *  classes will not be found without a using a full class path.
+ *
+ *  A variety of strategies can be used to provide useful portions of the
+ *  standard library to subclasses of BasicObject.  A subclass could
+ *  <code>include Kernel</code> to obtain +puts+, +exit+, etc.  A custom
+ *  Kernel-like module could be created and included or delegation can be used
+ *  via #method_missing:
+ *
+ *    class MyObjectSystem < BasicObject
+ *      DELEGATE = [:puts, :p]
+ *
+ *      def method_missing(name, *args, &block)
+ *        super unless DELEGATE.include? name
+ *        ::Kernel.send(name, *args, &block)
+ *      end
+ *
+ *      def respond_to_missing?(name, include_private = false)
+ *        DELGATE.include?(name) or super
+ *      end
+ *    end
+ *
+ *  Access to classes and modules from the Ruby standard library can be
+ *  obtained in a BasicObject subclass by referencing the desired constant
+ *  from the root like <code>::File</code> or <code>::Enumerator</code>.
+ *  Like #method_missing, #const_missing can be used to delegate constant
+ *  lookup to +Object+:
+ *
+ *    class MyObjectSystem < BasicObject
+ *      def self.const_missing(name)
+ *        ::Object.const_get(name)
+ *      end
+ *    end
  */
 
 /*  Document-class: Object

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/