Skip to content
Browse files

* object.c: Add usage documentation for BasicObject. Based on patch

	  by Thomas Sawyer.  [Ruby 1.9 - Bug #5067]


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32700 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
  • Loading branch information...
1 parent e29d589 commit 3eb7d2b33e3f8555d81db5369eb6fb7100a91e63 @drbrain drbrain committed Jul 27, 2011
Showing with 52 additions and 0 deletions.
  1. +5 −0 ChangeLog
  2. +47 −0 object.c
View
5 ChangeLog
@@ -1,3 +1,8 @@
+Wed Jul 27 15:39:14 2011 Eric Hodel <drbrain@segment7.net>
+
+ * 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@segment7.net>
* lib/rubygems/uninstaller.rb: Add missing require and update
View
47 object.c
@@ -2614,6 +2614,53 @@ rb_f_array(VALUE obj, VALUE arg)
*
* 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

0 comments on commit 3eb7d2b

Please sign in to comment.
Something went wrong with that request. Please try again.