class Class - RDoc Documentation

# class Class

Extends any `Class` to include json_creatable? method.

Classes in Ruby are first-class objects—each is an instance of class `Class`.

Typically, you create a new class by using:

    class Name
     # some code describing the class behavior
    end

When a new class is created, an object of type `Class` is initialized and assigned to a global constant (Name in this case).

When `Name.new` is called to create a new object, the `new` method in `Class` is run by default. This can be demonstrated by overriding `new` in Class:

    class Class
      alias old_new new
      def new(*args)
        print "Creating a new ", self.name, "\n"
        old_new(*args)
      end
    end

    class Name
    end

    n = Name.new

produces:

    Creating a new Name

Classes, modules, and objects are interrelated. In the diagram that follows, the vertical arrows represent inheritance, and the parentheses metaclasses. All metaclasses are instances of the class `Class'.

                             +---------+             +-...
                             |         |             |
             BasicObject-----|-->(BasicObject)-------|-...
                 ^           |         ^             |
                 |           |         |             |
              Object---------|----->(Object)---------|-...
                 ^           |         ^             |
                 |           |         |             |
                 +-------+   |         +--------+    |
                 |       |   |         |        |    |
                 |    Module-|---------|--->(Module)-|-...
                 |       ^   |         |        ^    |
                 |       |   |         |        |    |
                 |     Class-|---------|---->(Class)-|-...
                 |       ^   |         |        ^    |
                 |       +---+         |        +----+
                 |                     |
    obj--->OtherClass---------->(OtherClass)-----------...

### Public Class Methods

new(super_class=Object) → a_class click to toggle source
new(super_class=Object) { |mod| ... } → a_class

Creates a new anonymous (unnamed) class with the given superclass (or `Object` if no parameter is given). You can give a class a name by assigning the class object to a constant.

If a block is given, it is passed the class object, and the block is evaluated in the context of this class like `class_eval`.

    fred = Class.new do
      def meth1
        "hello"
      end
      def meth2
        "bye"
      end
    end

    a = fred.new     #=> #<#<Class:0x100381890>:0x100376b98>
    a.meth1          #=> "hello"
    a.meth2          #=> "bye"

Assign the class to a constant (name starting uppercase) if you want to treat it like a regular class.

    static VALUE
    rb_class_initialize(int argc, VALUE *argv, VALUE klass)
    {
        VALUE super;

        if (RCLASS_SUPER(klass) != 0 || klass == rb_cBasicObject) {
            rb_raise(rb_eTypeError, "already initialized class");
        }
        if (rb_check_arity(argc, 0, 1) == 0) {
            super = rb_cObject;
        }
        else {
            super = argv[0];
            rb_check_inheritable(super);
            if (super != rb_cBasicObject && !RCLASS_SUPER(super)) {
                rb_raise(rb_eTypeError, "can't inherit uninitialized class");
            }
        }
        RCLASS_SET_SUPER(klass, super);
        rb_make_metaclass(klass, RBASIC(super)->klass);
        rb_class_inherited(super, klass);
        rb_mod_initialize(klass);

        return klass;
    }

### Public Instance Methods

allocate() → obj click to toggle source

Allocates space for a new object of class's class and does not call initialize on the new instance. The returned object must be an instance of class.

    klass = Class.new do
      def initialize(*args)
        @initialized = true
      end

      def initialized?
        @initialized || false
      end
    end

    klass.allocate.initialized? #=> false

    static VALUE
    rb_class_alloc_m(VALUE klass)
    {
        rb_alloc_func_t allocator = class_get_alloc_func(klass);
        if (!rb_obj_respond_to(klass, rb_intern("allocate"), 1)) {
            rb_raise(rb_eTypeError, "calling %"PRIsVALUE".allocate is prohibited",
                     klass);
        }
        return class_call_alloc_func(allocator, klass);
    }

json_creatable?() click to toggle source

Returns true if this class can be used to create an instance from a serialised `JSON` string. The class has to implement a class method json_create that expects a hash as first parameter. The hash should include the required data.

    # File ext/json/lib/json/common.rb, line 700
    def json_creatable?
      respond_to?(:json_create)
    end

new(args, ...) → obj click to toggle source

Calls `allocate` to create a new object of class's class, then invokes that object's initialize method, passing it args. This is the method that ends up getting called whenever an object is constructed using `.new`.

    VALUE
    rb_class_new_instance_pass_kw(int argc, const VALUE *argv, VALUE klass)
    {
        VALUE obj;

        obj = rb_class_alloc(klass);
        rb_obj_call_init_kw(obj, argc, argv, RB_PASS_CALLED_KEYWORDS);

        return obj;
    }

superclass → a_super_class or nil click to toggle source

Returns the superclass of class, or `nil`.

    File.superclass          #=> IO
    IO.superclass            #=> Object
    Object.superclass        #=> BasicObject
    class Foo; end
    class Bar < Foo; end
    Bar.superclass           #=> Foo

Returns nil when the given class does not have a parent class:

    BasicObject.superclass   #=> nil

    VALUE
    rb_class_superclass(VALUE klass)
    {
        VALUE super = RCLASS_SUPER(klass);

        if (!super) {
            if (klass == rb_cBasicObject) return Qnil;
            rb_raise(rb_eTypeError, "uninitialized class");
        }
        while (RB_TYPE_P(super, T_ICLASS)) {
            super = RCLASS_SUPER(super);
        }
        if (!super) {
            return Qnil;
        }
        return super;
    }

### Private Instance Methods

inherited(subclass) click to toggle source

Callback invoked whenever a subclass of the current class is created.

Example:

    class Foo
      def self.inherited(subclass)
        puts "New subclass: #{subclass}"
      end
    end

    class Bar < Foo
    end

    class Baz < Bar
    end

produces:

    New subclass: Bar
    New subclass: Baz

    static VALUE
    rb_obj_dummy1(VALUE _x, VALUE _y)
    {
        return rb_obj_dummy();
    }