123456789_123456789_123456789_123456789_123456789_

Class: Class

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, ::Module
Instance Chain:
self, ::Module
Inherits: Module
Defined in: object.c,
class.c

Overview

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)-----------...

Class Method Summary

::Module - Inherited

.constants

In the first form, returns an array of the names of all constants accessible from the point of call.

.nesting

Returns the list of Modules nested at the point of call.

.new

Creates a new anonymous module.

.used_modules

Returns an array of all modules used in the current scope.

.used_refinements

Returns an array of all modules used in the current scope.

Instance Attribute Summary

::Module - Inherited

#singleton_class?

Returns true if mod is a singleton class or false if it is an ordinary class or module.

Instance Method Summary

::Module - Inherited

#<

Returns true if mod is a subclass of other.

#<=

Returns true if mod is a subclass of other or is the same as other.

#<=>

Comparison—Returns -1, 0, +1 or nil depending on whether module includes other_module, they are the same, or if module is included by other_module.

#==

Alias for Object#eql?.

#===

Case Equality—Returns true if obj is an instance of mod or an instance of one of mod’s descendants.

#>

Returns true if mod is an ancestor of other.

#>=

Returns true if mod is an ancestor of other, or the two modules are the same.

#alias_method

Makes new_name a new copy of the method old_name.

#ancestors

Returns a list of modules included/prepended in mod (including mod itself).

#attr

The first form is equivalent to #attr_reader.

#attr_accessor

Defines a named attribute for this module, where the name is symbol.id2name, creating an instance variable (@name) and a corresponding access method to read it.

#attr_reader

Creates instance variables and corresponding methods that return the value of each instance variable.

#attr_writer

Creates an accessor method to allow assignment to the attribute symbol.id2name.

#autoload

Registers filename to be loaded (using Kernel.require) the first time that const (which may be a ::String or a symbol) is accessed in the namespace of mod.

#autoload?

Returns filename to be loaded if name is registered as autoload in the namespace of mod or one of its ancestors.

#class_eval

Evaluates the string or block in the context of mod, except that when a block is given, constant/class variable lookup is not affected.

#class_exec

Evaluates the given block in the context of the class/module.

#class_variable_defined?

Returns true if the given class variable is defined in obj.

#class_variable_get

Returns the value of the given class variable (or throws a ::NameError exception).

#class_variable_set

Sets the class variable named by symbol to the given object.

#class_variables

Returns an array of the names of class variables in mod.

#const_defined?

Says whether mod or its ancestors have a constant with the given name:

#const_get

Checks for a constant with the given name in mod.

#const_missing

Invoked when a reference is made to an undefined constant in mod.

#const_set

Sets the named constant to the given object, returning that object.

#const_source_location

Returns the Ruby source filename and line number containing the definition of the constant specified.

#constants

Returns an array of the names of the constants accessible in mod.

#define_method

Defines an instance method in the receiver.

#deprecate_constant

Makes a list of existing constants deprecated.

#freeze

Prevents further modifications to mod.

#include

Invokes Module#append_features on each parameter in reverse order.

#include?

Returns true if module is included or prepended in mod or one of mod’s ancestors.

#included_modules

Returns the list of modules included or prepended in mod or one of mod’s ancestors.

#inspect

Alias for Module#to_s.

#instance_method

Returns an ::UnboundMethod representing the given instance method in mod.

#instance_methods

Returns an array containing the names of the public and protected instance methods in the receiver.

#method_defined?

Returns true if the named method is defined by mod.

#module_eval
#module_exec
#name

Returns the name of the module mod.

#prepend

Invokes Module#prepend_features on each parameter in reverse order.

#private_class_method

Makes existing class methods private.

#private_constant

Makes a list of existing constants private.

#private_instance_methods

Returns a list of the private instance methods defined in mod.

#private_method_defined?

Returns true if the named private method is defined by mod.

#protected_instance_methods

Returns a list of the protected instance methods defined in mod.

#protected_method_defined?

Returns true if the named protected method is defined mod.

#public_class_method

Makes a list of existing class methods public.

#public_constant

Makes a list of existing constants public.

#public_instance_method

Similar to instance_method, searches public method only.

#public_instance_methods

Returns a list of the public instance methods defined in mod.

#public_method_defined?

Returns true if the named public method is defined by mod.

#refinements

Returns an array of ::Refinement defined within the receiver.

#remove_class_variable

Removes the named class variable from the receiver, returning that variable’s value.

#remove_method

Removes the method identified by symbol from the current class.

#set_temporary_name

Sets the temporary name of the module.

#to_s

Returns a string representing this module or class.

#undef_method

Prevents the current class from responding to calls to the named method.

#undefined_instance_methods

Returns a list of the undefined instance methods defined in mod.

#append_features

When this module is included in another, Ruby calls #append_features in this module, passing it the receiving module in mod.

#const_added

Invoked as a callback whenever a constant is assigned on the receiver.

#extend_object

Extends the specified object by adding this module’s constants and methods (which are added as singleton methods).

#extended

The equivalent of included, but for extended modules.

#included

Callback invoked whenever the receiver is included in another module or class.

#method_added

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

#method_removed

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

#method_undefined

Invoked as a callback whenever an instance method is undefined from the receiver.

#module_function

Creates module functions for the named methods.

#prepend_features

When this module is prepended in another, Ruby calls #prepend_features in this module, passing it the receiving module in mod.

#prepended

The equivalent of included, but for prepended modules.

#private

With no arguments, sets the default visibility for subsequently defined methods to private.

#protected

With no arguments, sets the default visibility for subsequently defined methods to protected.

#public

With no arguments, sets the default visibility for subsequently defined methods to public.

#refine

Refine mod in the receiver.

#remove_const

Removes the definition of the given constant, returning that constant’s previous value.

#ruby2_keywords

For the given method names, marks the method as passing keywords through a normal argument splat.

#using

Import class refinements from module into the current class or module definition.

#initialize_clone, #initialize_copy

Constructor Details

.new(super_class = Object) ⇒ Class .new(super_class = Object) {|mod| ... } ⇒ 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.

[ GitHub ]

  
# File 'object.c', line 2039

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;
}

Instance Method Details

#allocateObject

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
[ GitHub ]

  
# File 'object.c', line 2098

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_objectObject

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
[ GitHub ]

  
# File 'class.c', line 1716

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

    return RCLASS_ATTACHED_OBJECT(klass);
}

#inherited(subclass) (private)

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
[ GitHub ]

#new(args, ...) ⇒ Object

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.

[ GitHub ]

  
# File 'object.c', line 2167

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;
}

#subclassesArray

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
[ GitHub ]

  
# File 'class.c', line 1693

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

#superclassClass?

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
[ GitHub ]

  
# File 'object.c', line 2223

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;
    }
}