class BasicObject - RDoc Documentation

# class BasicObject

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 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 `include Kernel` 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)
        DELEGATE.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 `::File` or `::Enumerator`. 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

### Public Class Methods

new() click to toggle source

Not documented

    static VALUE
    rb_obj_dummy(void)
    {
        return Qnil;
    }

### Public Instance Methods

!obj → true or false click to toggle source

Boolean negate.

    VALUE
    rb_obj_not(VALUE obj)
    {
        return RTEST(obj) ? Qfalse : Qtrue;
    }

obj != other → true or false click to toggle source

Returns true if two objects are not-equal, otherwise false.

    VALUE
    rb_obj_not_equal(VALUE obj1, VALUE obj2)
    {
        VALUE result = rb_funcall(obj1, id_eq, 1, obj2);
        return RTEST(result) ? Qfalse : Qtrue;
    }

obj == other → true or false click to toggle source

Equality — At the `Object` level, `==` returns `true` only if `obj` and `other` are the same object. Typically, this method is overridden in descendant classes to provide class-specific meaning.

Unlike `==`, the `equal?` method should never be overridden by subclasses as it is used to determine object identity (that is, `a.equal?(b)` if and only if `a` is the same object as `b`):

    obj = "a"
    other = obj.dup

    obj == other      #=> true
    obj.equal? other  #=> false
    obj.equal? obj    #=> true

The `eql?` method returns `true` if `obj` and `other` refer to the same hash key. This is used by Hash to test members for equality. For objects of class `Object`, `eql?` is synonymous with `==`. Subclasses normally continue this tradition by aliasing `eql?` to their overridden `==` method, but there are exceptions. `Numeric` types, for example, perform type conversion across `==`, but not across `eql?`, so:

    1 == 1.0     #=> true
    1.eql? 1.0   #=> false

    VALUE
    rb_obj_equal(VALUE obj1, VALUE obj2)
    {
        if (obj1 == obj2) return Qtrue;
        return Qfalse;
    }

__id__ → integer click to toggle source
object_id → integer

Returns an integer identifier for `obj`.

The same number will be returned on all calls to `object_id` for a given object, and no two active objects will share an id.

Note: that some objects of builtin classes are reused for optimization. This is the case for immediate values and frozen string literals.

Immediate values are not passed by reference but are passed by value: `nil`, `true`, `false`, Fixnums, Symbols, and some Floats.

    Object.new.object_id  == Object.new.object_id  # => false
    (21 * 2).object_id    == (21 * 2).object_id    # => true
    "hello".object_id     == "hello".object_id     # => false
    "hi".freeze.object_id == "hi".freeze.object_id # => true

    VALUE
    rb_obj_id(VALUE obj)
    {
        /*
         *                32-bit VALUE space
         *          MSB ------------------------ LSB
         *  false   00000000000000000000000000000000
         *  true    00000000000000000000000000000010
         *  nil     00000000000000000000000000000100
         *  undef   00000000000000000000000000000110
         *  symbol  ssssssssssssssssssssssss00001110
         *  object  oooooooooooooooooooooooooooooo00        = 0 (mod sizeof(RVALUE))
         *  fixnum  fffffffffffffffffffffffffffffff1
         *
         *                    object_id space
         *                                       LSB
         *  false   00000000000000000000000000000000
         *  true    00000000000000000000000000000010
         *  nil     00000000000000000000000000000100
         *  undef   00000000000000000000000000000110
         *  symbol   000SSSSSSSSSSSSSSSSSSSSSSSSSSS0        S...S % A = 4 (S...S = s...s * A + 4)
         *  object   oooooooooooooooooooooooooooooo0        o...o % A = 0
         *  fixnum  fffffffffffffffffffffffffffffff1        bignum if required
         *
         *  where A = sizeof(RVALUE)/4
         *
         *  sizeof(RVALUE) is
         *  20 if 32-bit, double is 4-byte aligned
         *  24 if 32-bit, double is 8-byte aligned
         *  40 if 64-bit
         */
        if (STATIC_SYM_P(obj)) {
            return (SYM2ID(obj) * sizeof(RVALUE) + (4 << 2)) | FIXNUM_FLAG;
        }
        else if (FLONUM_P(obj)) {
    #if SIZEOF_LONG == SIZEOF_VOIDP
            return LONG2NUM((SIGNED_VALUE)obj);
    #else
            return LL2NUM((SIGNED_VALUE)obj);
    #endif
        }
        else if (SPECIAL_CONST_P(obj)) {
            return LONG2NUM((SIGNED_VALUE)obj);
        }
        return nonspecial_obj_id(obj);
    }

send(symbol [, args...]) → obj click to toggle source
__send__(symbol [, args...]) → obj
send(string [, args...]) → obj
__send__(string [, args...]) → obj

Invokes the method identified by symbol, passing it any arguments specified. You can use `__send__` if the name `send` clashes with an existing method in obj. When the method is identified by a string, the string is converted to a symbol.

    class Klass
      def hello(*args)
        "Hello " + args.join(' ')
      end
    end
    k = Klass.new
    k.send :hello, "gentle", "readers"   #=> "Hello gentle readers"

    VALUE
    rb_f_send(int argc, VALUE *argv, VALUE recv)
    {
        return send_internal(argc, argv, recv, CALL_FCALL);
    }

equal?(other) → true or false click to toggle source

Equality — At the `Object` level, `==` returns `true` only if `obj` and `other` are the same object. Typically, this method is overridden in descendant classes to provide class-specific meaning.

Unlike `==`, the `equal?` method should never be overridden by subclasses as it is used to determine object identity (that is, `a.equal?(b)` if and only if `a` is the same object as `b`):

    obj = "a"
    other = obj.dup

    obj == other      #=> true
    obj.equal? other  #=> false
    obj.equal? obj    #=> true

The `eql?` method returns `true` if `obj` and `other` refer to the same hash key. This is used by Hash to test members for equality. For objects of class `Object`, `eql?` is synonymous with `==`. Subclasses normally continue this tradition by aliasing `eql?` to their overridden `==` method, but there are exceptions. `Numeric` types, for example, perform type conversion across `==`, but not across `eql?`, so:

    1 == 1.0     #=> true
    1.eql? 1.0   #=> false

    VALUE
    rb_obj_equal(VALUE obj1, VALUE obj2)
    {
        if (obj1 == obj2) return Qtrue;
        return Qfalse;
    }

instance_eval(string [, filename [, lineno]] ) → obj click to toggle source
instance_eval {|obj| block } → obj

Evaluates a string containing Ruby source code, or the given block, within the context of the receiver (obj). In order to set the context, the variable `self` is set to obj while the code is executing, giving the code access to obj's instance variables and private methods.

When `instance_eval` is given a block, obj is also passed in as the block's only argument.

When `instance_eval` is given a `String`, the optional second and third parameters supply a filename and starting line number that are used when reporting compilation errors.

    class KlassWithSecret
      def initialize
        @secret = 99
      end
      private
      def the_secret
        "Ssssh! The secret is #{@secret}."
      end
    end
    k = KlassWithSecret.new
    k.instance_eval { @secret }          #=> 99
    k.instance_eval { the_secret }       #=> "Ssssh! The secret is 99."
    k.instance_eval {|obj| obj == self } #=> true

    VALUE
    rb_obj_instance_eval(int argc, const VALUE *argv, VALUE self)
    {
        VALUE klass = singleton_class_for_eval(self);
        return specific_eval(argc, argv, klass, self);
    }

instance_exec(arg...) {|var...| block } → obj click to toggle source

Executes the given block within the context of the receiver (obj). In order to set the context, the variable `self` is set to obj while the code is executing, giving the code access to obj's instance variables. Arguments are passed as block parameters.

    class KlassWithSecret
      def initialize
        @secret = 99
      end
    end
    k = KlassWithSecret.new
    k.instance_exec(5) {|x| @secret+x }   #=> 104

    VALUE
    rb_obj_instance_exec(int argc, const VALUE *argv, VALUE self)
    {
        VALUE klass = singleton_class_for_eval(self);
        return yield_under(klass, self, argc, argv);
    }

### Private Instance Methods

method_missing(symbol [, *args] ) → result click to toggle source

Invoked by Ruby when obj is sent a message it cannot handle. symbol is the symbol for the method called, and args are any arguments that were passed to it. By default, the interpreter raises an error when this method is called. However, it is possible to override the method to provide more dynamic behavior. If it is decided that a particular method should not be handled, then super should be called, so that ancestors can pick up the missing method. The example below creates a class `Roman`, which responds to methods with names consisting of roman numerals, returning the corresponding integer values.

    class Roman
      def roman_to_int(str)
        # ...
      end
      def method_missing(methId)
        str = methId.id2name
        roman_to_int(str)
      end
    end

    r = Roman.new
    r.iv      #=> 4
    r.xxiii   #=> 23
    r.mm      #=> 2000

    static VALUE
    rb_method_missing(int argc, const VALUE *argv, VALUE obj)
    {
        rb_execution_context_t *ec = GET_EC();
        raise_method_missing(ec, argc, argv, obj, ec->method_missing_reason);
        UNREACHABLE;
    }

singleton_method_added(symbol) click to toggle source

Invoked as a callback whenever a singleton method is added to the receiver.

    module Chatty
      def Chatty.singleton_method_added(id)
        puts "Adding #{id.id2name}"
      end
      def self.one()     end
      def two()          end
      def Chatty.three() end
    end

produces:

    Adding singleton_method_added
    Adding one
    Adding three

    static VALUE
    rb_obj_dummy(void)
    {
        return Qnil;
    }

singleton_method_removed(symbol) click to toggle source

Invoked as a callback whenever a singleton method is removed from the receiver.

    module Chatty
      def Chatty.singleton_method_removed(id)
        puts "Removing #{id.id2name}"
      end
      def self.one()     end
      def two()          end
      def Chatty.three() end
      class << self
        remove_method :three
        remove_method :one
      end
    end

produces:

    Removing three
    Removing one

    static VALUE
    rb_obj_dummy(void)
    {
        return Qnil;
    }

singleton_method_undefined(symbol) click to toggle source

Invoked as a callback whenever a singleton method is undefined in the receiver.

    module Chatty
      def Chatty.singleton_method_undefined(id)
        puts "Undefining #{id.id2name}"
      end
      def Chatty.one()   end
      class << self
         undef_method(:one)
      end
    end

produces:

    Undefining one

    static VALUE
    rb_obj_dummy(void)
    {
        return Qnil;
    }