C API/Classes and Modules

These are functions that create and manipulate classes and modules.

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

Creating classes
creates a new anonymous class with  as its superclass. This should be  if the class will not inherit another class.

The return value is a handle to the new class.

creates a new class named  and inheriting from.

The return value is a handle to the new class.

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

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

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

The return value is a handle to the new class.

creates a new class that inherits, but does not check whether   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.

creates a singleton class for  and attaches   to it.

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

Creating modules
creates a new anonymous module.

The return value is a handle to the module.

defines a module whose name is the string.

defines a module whose name is the symbol.

The return value is a handle to the module.

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

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

The return value is a handle to the module.

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

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

Class inheritance functions
checks whether  can be inherited by another class. If not, it raises an appropriate exception.

calls the  method on the class , passing   as the single argument.

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

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

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

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

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

If  is -1, the method is called as   where   is the number of arguments provided,   is a C array of   arguments, and   is the receiver.

If  is -2, the method is called as   where   is the receiver and   is a Ruby array containing the arguments.

Removing a method
removes the method  from the class.

Creating an alias of a method
creates an alias of the method ; the alias is called.

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

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  have the type. In the following description, "C arguments" are the ones passed to, 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  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.
 * 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  if no block is passed.

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

Enumerating methods
returns an array listing the public and protected instance methods of the class or module. returns the public instance methods only;  and   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. 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); }

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

Though this function is visible to extensions, the parameter sequence is inconvenient because it is made to implement the  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 module
Includes the module  within the class or module.

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

implements the  method;   implements. Both are also visible to extensions.

indicates whether the module  is included in the class or module. This function implements the  method, but is also visible to extensions.

The return value is  or. Extensions calling this code should use  to convert this value to a C boolean.

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

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.

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

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