Ruby  3.4.0dev (2024-11-05 revision ff560644692057f8caa3697d6821d6d2e865f724)
Data Structures | Functions
Defining methods

There are some APIs to define a method from C. More...

Data Structures

struct  rb_scan_args_t
 

Functions

void rb_define_method_id (VALUE klass, ID mid, VALUE(*func)(ANYARGS), int argc)
 Identical to rb_define_method(), except it takes the name of the method in ID instead of C's string. More...
 
void rb_define_method (VALUE klass, const char *mid, VALUE(*func)(ANYARGS), int arity)
 Defines a method. More...
 
void rb_define_protected_method (VALUE klass, const char *name, VALUE(*func)(ANYARGS), int argc)
 Identical to rb_define_method(), except it defines a protected method. More...
 
void rb_define_private_method (VALUE klass, const char *name, VALUE(*func)(ANYARGS), int argc)
 Identical to rb_define_method(), except it defines a private method. More...
 
void rb_undef_method (VALUE klass, const char *name)
 Defines an undef of a method. More...
 
static enum rb_id_table_iterator_result undef_method_i (ID name, VALUE value, void *data)
 
void rb_undef_methods_from (VALUE klass, VALUE super)
 
void rb_define_singleton_method (VALUE obj, const char *name, VALUE(*func)(ANYARGS), int argc)
 Identical to rb_define_method(), except it defines a singleton method. More...
 
void rb_define_module_function (VALUE klass, const char *mid, VALUE(*func)(ANYARGS), int arity)
 Defines a module function for a module. More...
 
void rb_define_global_function (const char *mid, VALUE(*func)(ANYARGS), int arity)
 Defines a global function. More...
 
void rb_define_alias (VALUE klass, const char *dst, const char *src)
 Defines an alias of a method. More...
 
void rb_define_attr (VALUE klass, const char *name, int read, int write)
 Defines public accessor method(s) for an attribute. More...
 
VALUE rb_keyword_error_new (const char *error, VALUE keys)
 
static void rb_keyword_error (const char *error, VALUE keys)
 
static void unknown_keyword_error (VALUE hash, const ID *table, int keywords)
 
static int separate_symbol (st_data_t key, st_data_t value, st_data_t arg)
 
VALUE rb_extract_keywords (VALUE *orighash)
 Splits a hash into two. More...
 
int rb_get_kwargs (VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values)
 Keyword argument deconstructor. More...
 
static void rb_scan_args_parse (int kw_flag, const char *fmt, struct rb_scan_args_t *arg)
 
static int rb_scan_args_assign (const struct rb_scan_args_t *arg, int argc, const VALUE *const argv, va_list vargs)
 
static int rb_scan_args_result (const struct rb_scan_args_t *const arg, int argc)
 
int rb_scan_args (int argc, const VALUE *argv, const char *fmt,...)
 Retrieves argument from argc and argv to given VALUE references according to the format string. More...
 
int rb_scan_args_kw (int kw_flag, int argc, const VALUE *argv, const char *fmt,...)
 Identical to rb_scan_args(), except it also accepts kw_splat. More...
 
int rb_keyword_given_p (void)
 Determines if the current method is given a keyword argument. More...
 
int rb_block_given_p (void)
 Determines if the current method is given a block. More...
 
void rb_need_block (void)
 Declares that the current method needs a block. More...
 

Detailed Description

There are some APIs to define a method from C.

These API takes a C function as a method body.

Method body functions

Method body functions must return a VALUE and can be one of the following form:

Fixed number of parameters

This form is a normal C function, excepting it takes a receiver object as the first argument.

static VALUE my_method(VALUE self, VALUE x, VALUE y);
uintptr_t VALUE
Type that represents a Ruby object.
Definition: value.h:40

argc and argv style

This form takes three parameters: argc, argv and self. self is the receiver. argc is the number of arguments. argv is a pointer to an array of the arguments.

static VALUE my_method(int argc, VALUE *argv, VALUE self);

Ruby array style

This form takes two parameters: self and args. self is the receiver. args is an Array object which contains the arguments.

static VALUE my_method(VALUE self, VALUE args);

Number of parameters

Method defining APIs takes the number of parameters which the method will takes. This number is called argc. argc can be:

Function Documentation

◆ rb_block_given_p()

int rb_block_given_p ( void  )

Determines if the current method is given a block.

Return values
falseNo block is given.
trueA block is given.

Definition at line 916 of file eval.c.

Referenced by rb_ary_delete(), rb_ary_sort_bang(), rb_method_call(), rb_method_call_kw(), and rb_need_block().

◆ rb_define_alias()

void rb_define_alias ( VALUE  klass,
const char *  dst,
const char *  src 
)

Defines an alias of a method.

Parameters
[in,out]klassThe class which the original method belongs to; this is also where the new method will belong to.
[in]dstA new name for the method.
[in]srcThe original name of the method.
Exceptions
rb_eTypeErrorklass is a non-module.
rb_eFrozenErrorklass is frozen.
rb_eNameErrorThere is no such method named as src in klass.

Definition at line 2345 of file class.c.

◆ rb_define_attr()

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

Defines public accessor method(s) for an attribute.

Parameters
[out]klassThe class which the attribute will belong to.
[in]nameName of the attribute.
[in]readWhether to define a getter method.
[in]writeWhether to define a setter method.
Exceptions
rb_eTypeErrorklass is a non-module.
rb_eFrozenErrorklass is frozen.
rb_eNameErrorname invalid as an attr e.g. an operator.

Definition at line 2351 of file class.c.

◆ rb_define_global_function()

void rb_define_global_function ( const char *  mid,
VALUE(*)(ANYARGS func,
int  arity 
)

Defines a global function.

Parameters
[in]midName of the function.
[in]funcThe method body.
[in]arityThe number of parameters. See Defining methods.
Note
There are in fact 18 different prototypes for func.
See also
ruby::backward::cxxanyargs::define_method::rb_define_global_function

Definition at line 2339 of file class.c.

◆ rb_define_method()

void rb_define_method ( VALUE  klass,
const char *  mid,
VALUE(*)(ANYARGS func,
int  arity 
)

Defines a method.

Parameters
[out]klassA module or a class.
[in]midName of the function.
[in]funcThe method body.
[in]arityThe number of parameters. See Defining methods.
Note
There are in fact 18 different prototypes for func.
See also
ruby::backward::cxxanyargs::define_method::rb_define_method

Definition at line 2142 of file class.c.

Referenced by rb_define_singleton_method().

◆ rb_define_method_id()

void rb_define_method_id ( VALUE  klass,
ID  mid,
VALUE(*)(ANYARGS func,
int  arity 
)

Identical to rb_define_method(), except it takes the name of the method in ID instead of C's string.

Parameters
[out]klassA module or a class.
[in]midName of the function.
[in]funcThe method body.
[in]arityThe number of parameters. See Defining methods.
Note
There are in fact 18 different prototypes for func.
See also
ruby::backward::cxxanyargs::define_method::rb_define_method_id

Definition at line 2133 of file class.c.

◆ rb_define_module_function()

void rb_define_module_function ( VALUE  klass,
const char *  mid,
VALUE(*)(ANYARGS func,
int  arity 
)

Defines a module function for a module.

Parameters
[out]klassA module or a class.
[in]midName of the function.
[in]funcThe method body.
[in]arityThe number of parameters. See Defining methods.
Note
There are in fact 18 different prototypes for func.
See also
ruby::backward::cxxanyargs::define_method::rb_define_module_function

Definition at line 2329 of file class.c.

Referenced by rb_define_global_function(), and ruby_prog_init().

◆ rb_define_private_method()

void rb_define_private_method ( VALUE  klass,
const char *  mid,
VALUE(*)(ANYARGS func,
int  arity 
)

Identical to rb_define_method(), except it defines a private method.

Parameters
[out]klassA module or a class.
[in]midName of the function.
[in]funcThe method body.
[in]arityThe number of parameters. See Defining methods.
Note
There are in fact 18 different prototypes for func.
See also
ruby::backward::cxxanyargs::define_method::rb_define_protected_method

Definition at line 2160 of file class.c.

Referenced by rb_define_module_function().

◆ rb_define_protected_method()

void rb_define_protected_method ( VALUE  klass,
const char *  mid,
VALUE(*)(ANYARGS func,
int  arity 
)

Identical to rb_define_method(), except it defines a protected method.

Parameters
[out]klassA module or a class.
[in]midName of the function.
[in]funcThe method body.
[in]arityThe number of parameters. See Defining methods.
Note
There are in fact 18 different prototypes for func.
See also
ruby::backward::cxxanyargs::define_method::rb_define_protected_method

Definition at line 2151 of file class.c.

◆ rb_define_singleton_method()

void rb_define_singleton_method ( VALUE  obj,
const char *  mid,
VALUE(*)(ANYARGS func,
int  arity 
)

Identical to rb_define_method(), except it defines a singleton method.

Parameters
[out]objArbitrary ruby object.
[in]midName of the function.
[in]funcThe method body.
[in]arityThe number of parameters. See Defining methods.
Note
There are in fact 18 different prototypes for func.
See also
ruby::backward::cxxanyargs::define_method::rb_define_singleton_method

Definition at line 2320 of file class.c.

Referenced by rb_define_module_function().

◆ rb_extract_keywords()

VALUE rb_extract_keywords ( VALUE orighash)

Splits a hash into two.

Takes a hash of various keys, and split it into symbol-keyed parts and others. Symbol-keyed part becomes the return value. What remains are returned as a new hash object stored at the argument pointer.

Parameters
[in,out]orighashPointer to a target hash to split.
Returns
An extracted keyword hash.
Postcondition
Upon successful return orighash points to another hash object, whose contents are the remainder of the operation.
Note
The argument hash object is not modified.

Definition at line 2406 of file class.c.

◆ rb_get_kwargs()

int rb_get_kwargs ( VALUE  keyword_hash,
const ID table,
int  required,
int  optional,
VALUE values 
)

Keyword argument deconstructor.

Retrieves argument values bound to keywords, which directed by table into values, deleting retrieved entries from keyword_hash along the way. First required number of IDs referred by table are mandatory, and succeeding optional (-optional-1 if optional is negative) number of IDs are optional. If a mandatory key is not contained in keyword_hash, raises rb_eArgError. If an optional key is not present in keyword_hash, the corresponding element in values is set to RUBY_Qundef. If optional is negative, rest of keyword_hash are ignored, otherwise raises rb_eArgError.

Warning
Handling keyword arguments in the C API is less efficient than handling them in Ruby. Consider using a Ruby wrapper method around a non-keyword C function.
See also
https://bugs.ruby-lang.org/issues/11339
Parameters
[out]keyword_hashTarget hash to deconstruct.
[in]tableList of keywords that you are interested in.
[in]requiredNumber of mandatory keywords.
[in]optionalNumber of optional keywords (can be negative).
[out]valuesBuffer to be filled.
Exceptions
rb_eArgErrorAbsence of a mandatory keyword.
rb_eArgErrorFound an unknown keyword.
Returns
Number of found values that are stored into values.

Definition at line 2424 of file class.c.

◆ rb_keyword_given_p()

int rb_keyword_given_p ( void  )

Determines if the current method is given a keyword argument.

Return values
falseNo keyword argument is given.
trueKeyword argument(s) are given.

Definition at line 929 of file eval.c.

Referenced by rb_enumeratorize_with_size().

◆ rb_need_block()

void rb_need_block ( void  )

Declares that the current method needs a block.

Exceptions
rb_eLocalJumpErrorNo block given.

Definition at line 937 of file eval.c.

◆ rb_scan_args()

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

Retrieves argument from argc and argv to given VALUE references according to the format string.

The format can be described in ABNF as follows:

scan-arg-spec := param-arg-spec [keyword-arg-spec] [block-arg-spec]
param-arg-spec := pre-arg-spec [post-arg-spec] / post-arg-spec /
pre-opt-post-arg-spec
pre-arg-spec := num-of-leading-mandatory-args
[num-of-optional-args]
post-arg-spec := sym-for-variable-length-args
[num-of-trailing-mandatory-args]
pre-opt-post-arg-spec := num-of-leading-mandatory-args num-of-optional-args
num-of-trailing-mandatory-args
keyword-arg-spec := sym-for-keyword-arg
block-arg-spec := sym-for-block-arg
num-of-leading-mandatory-args := DIGIT ; The number of leading mandatory
; arguments
num-of-optional-args := DIGIT ; The number of optional arguments
sym-for-variable-length-args := "*" ; Indicates that variable length
; arguments are captured as a ruby
; array
num-of-trailing-mandatory-args := DIGIT ; The number of trailing mandatory
; arguments
sym-for-keyword-arg := ":" ; Indicates that keyword argument
; captured as a hash.
; If keyword arguments are not
; provided, returns nil.
sym-for-block-arg := "&" ; Indicates that an iterator block
; should be captured if given
The main namespace.
Definition: cxxanyargs.hpp:37

For example, "12" means that the method requires at least one argument, and at most receives three (1+2) arguments. So, the format string must be followed by three variable references, which are to be assigned to captured arguments. For omitted arguments, variables are set to RUBY_Qnil. NULL can be put in place of a variable reference, which means the corresponding captured argument(s) should be just dropped.

The number of given arguments, excluding an option hash or iterator block, is returned.

Parameters
[in]argcLength of argv.
[in]argvPointer to the arguments to parse.
[in]fmtFormat, in the language described above.
[out]...Variables to fill in.
Exceptions
rb_eFatalMalformed fmt.
rb_eArgErrorArity mismatch.
Returns
Actually parsed number of given arguments.
Postcondition
Each values passed to argv is filled into the variadic arguments, according to the format.

Definition at line 2635 of file class.c.

Referenced by rb_f_trace_var(), rb_f_untrace_var(), and rb_obj_init_clone().

◆ rb_scan_args_kw()

int rb_scan_args_kw ( int  kw_splat,
int  argc,
const VALUE argv,
const char *  fmt,
  ... 
)

Identical to rb_scan_args(), except it also accepts kw_splat.

Parameters
[in]kw_splatHow to understand the keyword arguments.
  • RB_SCAN_ARGS_PASS_CALLED_KEYWORDS: Same behaviour as rb_scan_args().
  • RB_SCAN_ARGS_KEYWORDS: The final argument is a kwarg.
  • RB_SCAN_ARGS_LAST_HASH_KEYWORDS: The final argument is a kwarg, iff it is a hash.
[in]argcLength of argv.
[in]argvPointer to the arguments to parse.
[in]fmtFormat, in the language described above.
[out]...Variables to fill in.
Exceptions
rb_eFatalMalformed fmt.
rb_eArgErrorArity mismatch.
Returns
Actually parsed number of given arguments.
Postcondition
Each values passed to argv is filled into the variadic arguments, according to the format.

Definition at line 2648 of file class.c.

◆ rb_undef_method()

void rb_undef_method ( VALUE  klass,
const char *  name 
)

Defines an undef of a method.

– What?

In ruby, there are two separate concepts called "undef" and "remove_method". The thing you imagine when you "un-define" a method is remove_method. This one on the other hand is masking of a previous method definition. Suppose for instance:

class Foo
def foo
end
end
class Bar < Foo
def bar
foo
end
end
class Baz < Foo
undef foo # <--- (*1)
end

This undef foo at (*1) must not eliminate Foo#foo, because that method is also used from Bar#bar. So instead of physically executing the target method, undef inserts a special filtering entry to the class (Baz this case). That entry, when called, acts as if there were no methods at all. But the original can still be accessible, via ways like Bar#bar above.

Parameters
[out]klassThe class to insert an undef.
[in]nameName of the undef.
Exceptions
rb_eTypeErrorklass is a non-module.
rb_eFrozenErrorklass is frozen.
See also
rb_remove_method

Definition at line 2166 of file class.c.