class Class - Documentation for Ruby 3.3

# 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_exec(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);
    }

attached_object → object click to toggle source

Returns the object for which the receiver is the singleton class.

Raises an `TypeError` if the class is not a singleton class.

    class Foo; end

    Foo.singleton_class.attached_object        #=> Foo
    Foo.attached_object                        #=> TypeError: `Foo' is not a singleton class
    Foo.new.singleton_class.attached_object    #=> #<Foo:0x000000010491a370>
    TrueClass.attached_object                  #=> TypeError: `TrueClass' is not a singleton class
    NilClass.attached_object                   #=> TypeError: `NilClass' is not a singleton class

    VALUE
    rb_class_attached_object(VALUE klass)
    {
        if (!FL_TEST(klass, FL_SINGLETON)) {
            rb_raise(rb_eTypeError, "`%"PRIsVALUE"' is not a singleton class", klass);
        }

        return RCLASS_ATTACHED_OBJECT(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 695
    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;
    }

subclasses → array click to toggle source

Returns an array of classes where the receiver is the direct superclass of the class, excluding singleton classes. The order of the returned array is not defined.

    class A; end
    class B < A; end
    class C < B; end
    class D < A; end

    A.subclasses        #=> [D, B]
    B.subclasses        #=> [C]
    C.subclasses        #=> []

Anonymous subclasses (not associated with a constant) are returned, too:

    c = Class.new(A)
    A.subclasses        # => [#<Class:0x00007f003c77bd78>, D, B]

Note that the parent does not hold references to subclasses and doesn’t prevent them from being garbage collected. This means that the subclass might disappear when all references to it are dropped:

    # drop the reference to subclass, it can be garbage-collected now
    c = nil

    A.subclasses
    # It can be
    #  => [#<Class:0x00007f003c77bd78>, D, B]
    # ...or just
    #  => [D, B]
    # ...depending on whether garbage collector was run

    VALUE
    rb_class_subclasses(VALUE klass)
    {
        return class_descendants(klass, true);
    }

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)
    {
        RUBY_ASSERT(RB_TYPE_P(klass, T_CLASS));

        VALUE super = RCLASS_SUPER(klass);

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

        if (!RCLASS_SUPERCLASS_DEPTH(klass)) {
            return Qnil;
        }
        else {
            super = RCLASS_SUPERCLASSES(klass)[RCLASS_SUPERCLASS_DEPTH(klass) - 1];
            RUBY_ASSERT(RB_TYPE_P(klass, T_CLASS));
            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

    #define rb_obj_class_inherited rb_obj_dummy1