FANDOM


These are functions that create and manipulate classes and modules.

The parameter that accepts a class is usually called klass with a K. This is possibly because class is a reserved word in C++. This will make no difference unless someone were to convert the Ruby interpreter to C++.

Class functionsEdit

Creating classesEdit

VALUE rb_class_new(VALUE super);

rb_class_new creates a new anonymous class with super as its superclass. This should be rb_cObject if the class will not inherit another class.

The return value is a handle to the new class.


VALUE rb_define_class(const char *name, VALUE super);

rb_define_class creates a new class named name and inheriting from super.

The return value is a handle to the new class.


VALUE rb_define_class_id(ID id, VALUE super);

rb_define_class_id creates a new class with super as its superclass. id is ignored, and the class name is not set. It is not clear that this function is meant to be called by extensions.


VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super);
VALUE rb_define_class_id_under(VALUE outer, ID name, VALUE super);

rb_define_class_under creates a new class within the class or module outer, named name and inheriting from super. The full name of the class will be Outer::name where Outer is the name of the class or module outer.

rb_define_class_id_under is similar, except that it accepts an ID type instead of a string constant.

The return value is a handle to the new class.


VALUE rb_class_boot(VALUE super);

rb_class_boot creates a new class that inherits super, but does not check whether super is inheritable or even that it is a class. This function is common to several other functions that create new classes. It is not clear that this function is meant to be called by extensions.

The return value is a handle to the new class.


VALUE rb_singleton_class_clone(VALUE obj);

rb_singleton_class_clone creates a singleton class for obj and attaches obj to it.

The return value is a handle to the new singleton class.

Creating modulesEdit

VALUE rb_module_new(void);

rb_module_new creates a new anonymous module.

The return value is a handle to the module.


VALUE rb_define_module(const char *name);
VALUE rb_define_module_id(ID id);

rb_define_module defines a module whose name is the string name.

rb_define_module_id defines a module whose name is the symbol id.

The return value is a handle to the module.


VALUE rb_define_module_under(VALUE outer, const char *name);
VALUE rb_define_module_id_under(VALUE outer, ID id);

rb_define_module_under defines a module within the class or module outer whose name is the string name.

rb_define_module_id_under defines a module within the class or module outer whose name is the symbol id.

The return value is a handle to the module.

Singleton classesEdit

VALUE rb_singleton_class(VALUE obj);

rb_singleton_class creates a singleton class for obj, if it does not already have one, and returns a handle to that class.

AttributesEdit

void rb_define_attr(VALUE klass, const char *name, int read, int write);

Defines an attribute called name for the class klass. If read is nonzero, the attribute has a reader method; if write is nonzero, the attribute has a writer method. The attribute itself is an instance variable named @name.

Class inheritance functionsEdit

void rb_check_inheritable(VALUE super);

rb_check_inheritable checks whether super can be inherited by another class. If not, it raises an appropriate exception.


VALUE rb_class_inherited(VALUE super, VALUE klass);

rb_class_inherited calls the

  1. inherited method on the class super, passing klass as the single argument.

Method functionsEdit

Creating a methodEdit

void rb_define_method(VALUE klass, const char *name, VALUE (*func)(ANYARGS), int argc);
void rb_define_method_id(VALUE klass, ID mid, VALUE (*func)(ANYARGS), int argc);
void rb_define_protected_method(VALUE klass, const char *name, VALUE (*func)(ANYARGS), int argc);
void rb_define_private_method(VALUE klass, const char *name, VALUE (*func)(ANYARGS), int argc);
void rb_define_singleton_method(VALUE obj, const char *name, VALUE(*func)(ANYARGS), int argc);
void rb_define_module_function(VALUE module, const char *name, VALUE(*func)(ANYARGS), int argc);
void rb_define_global_function(const char *name, VALUE(*func)(ANYARGS), int argc);

rb_define_method and rb_define_method_id define a new instance method in the class or module klass. The method calls func with argc arguments. They differ in how they specify the name: rb_define_method uses the constant string name, while rb_define_method_id uses the symbol mid.

rb_define_protected_method and rb_define_private_method are similar to rb_define_method, except that they define protected and private methods, respectively.

rb_define_singleton_method defines a singleton method on the object obj, creating a singleton class for obj if it does not already have one. If obj is a class or module, the method will be a class method.

rb_define_module_function defines a private class method of the class or module module. rb_define_global_function defines a "global function" (actually a private class method of Kernel).

If argc is at least 0, the method is called with argc+1 arguments, all with type VALUE, of which the first is the receiver and the rest are the method arguments in order. For example, if argc is 2, the method is called as VALUE method(VALUE self, VALUE arg1, VALUE arg2); where self is the receiver and arg1 and arg2 are the two arguments. argc cannot be greater than 15; if more arguments are needed, one of the variable argument options must be used.

If argc is -1, the method is called as VALUE method(int argc, VALUE *argv, VALUE self); where argc is the number of arguments provided, argv is a C array of argc arguments, and self is the receiver.

If argc is -2, the method is called as VALUE method(VALUE self, VALUE args); where self is the receiver and args is a Ruby array containing the arguments.

Removing a methodEdit

void rb_undef_method(VALUE klass, const char *name);

rb_undef_method removes the method name from the class klass.

Creating an alias of a methodEdit

void rb_define_alias(VALUE klass, const char *new_name, const char *old_name);

rb_define_alias creates an alias of the method old_name; the alias is called new_name.

Working with variable argumentsEdit

int rb_scan_args(int argc, const VALUE *argv, const char *fmt, ...);

rb_scan_args scans the argument list of a method that has a variable argument list, with argv as a C array (that is, with the argc parameter of rb_define_method or another method creation function set to -1). argc and argv are the count and array of arguments, respectively; both may be passed directly from the parameters to the method. fmt determines the expected argument types and the number of arguments.

fmt takes a constant string with characters as follows:

  • an optional first digit, giving the number of mandatory arguments at the start;
  • an optional second digit, giving the maximum number of optional arguments after the leading mandatory arguments to pack into a C array;
  • an optional '*' character, meaning build a Ruby array with any arguments not otherwise accounted for;
  • an optional third digit, giving the number of mandatory arguments at the end;
  • an optional '&' character, meaning that a block is expected and will be passed as one more argument.

All further arguments after fmt have the type VALUE *. In the following description, "C arguments" are the ones passed to rb_scan_args, and "method arguments" are those passed to the method by the calling Ruby function. The C arguments are processed as follows:

  • If the first digit is given, that many C arguments are collected and filled, one method argument to each C argument.
  • If the second digit is given, the next C argument points to an array of that many VALUE elements. Anywhere from 0 to the given number of method arguments are placed in the array, and any unfilled elements of the array are set to Qnil.
  • If the '*' character is given, the next C argument receives a Ruby array with all the remaining method arguments, except for those collected by the third digit if it is present.
  • If the third digit is given, that many C arguments are collected and filled, one method argument to each C argument.
  • If the '&' character is given, one more C argument receives a block if one is passed, or Qnil if no block is passed.

The return value is argc. ArgumentError is raised if the number of arguments is incorrect.

Enumerating methodsEdit

VALUE rb_class_instance_methods(int argc, VALUE *argv, VALUE mod);
VALUE rb_class_public_instance_methods(int argc, VALUE *argv, VALUE mod);
VALUE rb_class_protected_instance_methods(int argc, VALUE *argv, VALUE mod);
VALUE rb_class_private_instance_methods(int argc, VALUE *argv, VALUE mod);

rb_class_instance_methods returns an array listing the public and protected instance methods of the class or module. rb_class_public_instance_methods returns the public instance methods only; rb_class_protected_instance_methods and rb_class_private_instance_methods return the protected and private instance methods, respectively.

Though these functions are visible to extensions, the parameter sequence is inconvenient because it is made to implement such methods as Module#instance_methods. The following function provides a more convenient interface:

/* If your compiler does not have bool, use int instead */
VALUE
list_instance_methods(VALUE mod, bool include_superclasses)
{
    VALUE argv = include_superclasses ? Qtrue : Qfalse;
    return rb_class_instance_methods(1, &argv, mod);
}

VALUE rb_obj_singleton_methods(int argc, VALUE *argv, VALUE obj);

rb_obj_singleton_methods returns an array listing the public and protected singleton methods of the object obj.


Though this function is visible to extensions, the parameter sequence is inconvenient because it is made to implement the Module#singleton_methods method. The following function provides a more convenient interface:

/* If your compiler does not have bool, use int instead */
VALUE
list_singleton_methods(VALUE mod, bool include_superclasses)
{
    VALUE argv = include_superclasses ? Qtrue : Qfalse;
    return rb_obj_singleton_methods(1, &argv, mod);
}

Including a moduleEdit

void rb_include_module(VALUE klass, VALUE module);

Includes the module module within the class or module klass.


VALUE rb_mod_included_modules(VALUE mod);
VALUE rb_mod_ancestors(VALUE mod);

rb_mod_included_modules returns an array listing the modules included within the class or module mod. rb_mod_ancestors is similar to rb_mod_included_modules, but the returned array also includes mod itself.

rb_mod_included_modules implements the Module#included_modules method; rb_mod_ancestors implements Module#ancestors. Both are also visible to extensions.


VALUE rb_mod_include_p(VALUE mod, VALUE mod2);

rb_mod_include_p indicates whether the module mod2 is included in the class or module mod. This function implements the Module#include? method, but is also visible to extensions.

The return value is Qtrue or Qfalse. Extensions calling this code should use RTEST(rval) to convert this value to a C boolean.

UncategorizedEdit

VALUE rb_mod_init_copy(VALUE clone, VALUE orig);

rb_mod_init_copy has no comment header in the source code, and its purpose is unclear. It is not clear that this function is meant to be called by extensions.


VALUE rb_class_init_copy(VALUE clone, VALUE orig);

rb_class_init_copy has no comment header in the source code, and its purpose is unclear. It is not clear that this function is meant to be called by extensions.


void rb_singleton_class_attached(VALUE klass, VALUE obj);

rb_singleton_class_attached attaches the object obj to the singleton class klass. It is not clear that this function is meant to be called by extensions.


VALUE rb_make_metaclass(VALUE obj, VALUE unused);

This function is visible to extensions and present in intern.h (which ruby.h includes), but the comment header advises using rb_singleton_class instead instead of this function.

Ad blocker interference detected!


Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.