Ruby: Defining methods

Ruby 3.0.5p211 (2022-11-24 revision ba5cf0f7c52d4d35cc6a173c89eda98ceffa2dcf)

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)
void | rb_define_method (VALUE klass, const char *name, 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_undef_method (VALUE klass, const char *name)
void | rb_undef_methods_from (VALUE klass, VALUE super)
void | rb_define_singleton_method (VALUE obj, const char *name, VALUE(*func)(ANYARGS), int argc)
| Defines a singleton method for obj. More...
void | rb_define_module_function (VALUE module, const char *name, VALUE(*func)(ANYARGS), int argc)
| Defines a module function for module. More...
void | rb_define_global_function (const char *name, VALUE(*func)(ANYARGS), int argc)
| Defines a global function. More...
void | rb_define_alias (VALUE klass, const char *name1, const char *name2)
| Defines an alias of a method. More...
void | rb_define_attr (VALUE klass, const char *name, int read, int write)
| Defines (a) public accessor method(s) for an attribute. More...
VALUE | rb_keyword_error_new (const char *error, VALUE keys)
VALUE | rb_extract_keywords (VALUE *orighash)
int | rb_get_kwargs (VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values)
int | rb_scan_args (int argc, const VALUE *argv, const char *fmt,...)
int | rb_scan_args_kw (int kw_flag, int argc, const VALUE *argv, const char *fmt,...)
int | rb_class_has_methods (VALUE c)
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...
ID | rb_frame_this_func (void)
| The original name of the current method. More...
ID | rb_frame_callee (void)
| The name of the current method. 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);
    VALUE
    unsigned long VALUE
    Definition: value.h:38
  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);
    argc
    int argc
    Definition: ruby.c:240
    argv
    char ** argv
    Definition: ruby.c:241
  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:
  zero or positive number
    This means the method body function takes a fixed number of parameters
  -1
    This means the method body function is "argc and argv" style.
  -2
    This means the method body function is "self and args" style.

## Function Documentation

## ◆ rb_block_given_p()

int rb_block_given_p | ( | void |  | ) |

Determines if the current method is given a block.

Return values

  zero | if not given
  non-zero | if given

Definition at line 935 of file eval.c.

References FALSE, rb_vm_frame_block_handler(), TRUE, and VM_BLOCK_HANDLER_NONE.

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

## ◆ rb_class_has_methods()

int rb_class_has_methods | ( | VALUE | c | ) |

Definition at line 2321 of file class.c.

References FALSE, rb_id_table_size(), RCLASS_M_TBL, and TRUE.

## ◆ rb_define_alias()

void rb_define_alias | ( | VALUE | klass,
|  | const char * | name1,
|  | const char * | name2
| ) |  |

Defines an alias of a method.

Parameters

  klass | the class which the original method belongs to
  name1 | a new name for the method
  name2 | the original name of the method

Definition at line 1999 of file class.c.

References rb_alias(), and rb_intern().

Referenced by Init_Array(), Init_Cont(), Init_date_core(), Init_generator(), Init_Hash(), Init_IO(), Init_nkf(), Init_Numeric(), Init_ossl_asn1(), Init_ossl_bn(), Init_ossl_dh(), Init_ossl_digest(), Init_ossl_dsa(), Init_ossl_ec(), Init_ossl_hmac(), Init_ossl_ns_spki(), Init_ossl_pkcs7(), Init_ossl_rand(), Init_ossl_rsa(), Init_ossl_ssl(), Init_ossl_x509cert(), Init_ossl_x509crl(), Init_ossl_x509name(), Init_ossl_x509req(), Init_Proc(), Init_Thread(), Init_top_self(), Init_win32ole(), Init_win32ole_method(), Init_win32ole_param(), Init_win32ole_type(), Init_win32ole_typelib(), Init_win32ole_variable(), InitVM_Enumerator(), InitVM_process(), and InitVM_Struct().

## ◆ rb_define_attr()

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

Defines (a) public accessor method(s) for an attribute.

Parameters

  klass | the class which the attribute will belongs to
  name | name of the attribute
  read | a getter method for the attribute will be defined if read is non-zero.
  write | a setter method for the attribute will be defined if write is non-zero.

Definition at line 2012 of file class.c.

References FALSE, name, rb_attr(), rb_intern(), read(), and write().

Referenced by Init_zlib().

## ◆ rb_define_global_function()

void rb_define_global_function | ( | const char * | name,
|  | VALUE(*)(ANYARGS) | func,
|  | int | argc
| ) |  |

Defines a global function.

Parameters

  name | name of the function
  func | the method body
  argc | the number of parameters, or -1 or -2. see Defining methods.

Definition at line 1986 of file class.c.

References argc, name, rb_define_module_function, and rb_mKernel.

## ◆ rb_define_method()

void rb_define_method | ( | VALUE | klass,
|  | const char * | name,
|  | VALUE(*)(ANYARGS) | func,
|  | int | argc
| ) |  |

Definition at line 1753 of file class.c.

References argc, METHOD_VISI_PUBLIC, name, rb_add_method_cfunc(), and rb_intern().

## ◆ rb_define_method_id()

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

Definition at line 1744 of file class.c.

References argc, METHOD_VISI_PUBLIC, and rb_add_method_cfunc().

## ◆ rb_define_module_function()

void rb_define_module_function | ( | VALUE | module,
|  | const char * | name,
|  | VALUE(*)(ANYARGS) | func,
|  | int | argc
| ) |  |

Defines a module function for module.

Parameters

  module | an module or a class.
  name | name of the function
  func | the method body
  argc | the number of parameters, or -1 or -2. see Defining methods.

Definition at line 1970 of file class.c.

References argc, name, rb_define_private_method, and rb_define_singleton_method.

## ◆ rb_define_private_method()

void rb_define_private_method | ( | VALUE | klass,
|  | const char * | name,
|  | VALUE(*)(ANYARGS) | func,
|  | int | argc
| ) |  |

Definition at line 1771 of file class.c.

References argc, METHOD_VISI_PRIVATE, name, rb_add_method_cfunc(), and rb_intern().

## ◆ rb_define_protected_method()

void rb_define_protected_method | ( | VALUE | klass,
|  | const char * | name,
|  | VALUE(*)(ANYARGS) | func,
|  | int | argc
| ) |  |

Definition at line 1762 of file class.c.

References argc, METHOD_VISI_PROTECTED, name, rb_add_method_cfunc(), and rb_intern().

## ◆ rb_define_singleton_method()

void rb_define_singleton_method | ( | VALUE | obj,
|  | const char * | name,
|  | VALUE(*)(ANYARGS) | func,
|  | int | argc
| ) |  |

Defines a singleton method for obj.

Parameters

  obj | an arbitrary object
  name | name of the singleton method
  func | the method body
  argc | the number of parameters, or -1 or -2. see Defining methods.

Definition at line 1954 of file class.c.

References argc, name, and rb_define_method.

## ◆ rb_extract_keywords()

VALUE rb_extract_keywords | ( | VALUE * | orighash | ) |

Definition at line 2067 of file class.c.

References rb_cHash, rb_hash_foreach(), RBASIC_CLASS, and RHASH_EMPTY_P.

## ◆ rb_frame_callee()

ID rb_frame_callee | ( | void |  | ) |

The name of the current method.

The function returns the alias if an alias of the method is called. The function can also return 0 if it is not in a method. This case can happen in a toplevel of a source file, for example.

Returns
  the ID of the name or 0.

See also
  rb_frame_this_func

Definition at line 1233 of file eval.c.

## ◆ rb_frame_this_func()

ID rb_frame_this_func | ( | void |  | ) |

The original name of the current method.

The function returns the original name of the method even if an alias of the method is called. The function can also return 0 if it is not in a method. This case can happen in a toplevel of a source file, for example.

Returns
  the ID of the name or 0

See also
  rb_frame_callee

Definition at line 1216 of file eval.c.

Referenced by rb_notimplement().

## ◆ rb_get_kwargs()

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

Definition at line 2085 of file class.c.

References extract_kwarg, ID2SYM, key, NIL_P, Qnil, Qundef, rb_ary_push(), rb_ary_tmp_new(), and RHASH_SIZE.

Referenced by rb_num_get_rounding_option(), and rb_opts_exception_p().

## ◆ rb_keyword_error_new()

VALUE rb_keyword_error_new | ( | const char * | error,
|  | VALUE | keys
| ) |  |

Definition at line 2018 of file class.c.

References error(), len, RARRAY_AREF, RARRAY_LEN, rb_eArgError, rb_exc_new_str(), rb_inspect(), rb_sprintf(), rb_str_append(), and rb_str_cat_cstr.

## ◆ rb_need_block()

void rb_need_block | ( | void |  | ) |

Declares that the current method needs a block.

Raises a `LocalJumpError` if not given a block.

Definition at line 961 of file eval.c.

References Qnil, rb_block_given_p(), and rb_vm_localjump_error().

## ◆ rb_scan_args()

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

Definition at line 2296 of file class.c.

References argc, argv, and RB_SCAN_ARGS_PASS_CALLED_KEYWORDS.

Referenced by rb_f_eval(), rb_f_trace_var(), rb_f_untrace_var(), rb_math_log(), rsock_bsock_send(), and rsock_s_recvfrom().

## ◆ rb_scan_args_kw()

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

Definition at line 2309 of file class.c.

References argc, argv, and rb_scan_args_t::kw_flag.

## ◆ rb_undef_method()

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

Definition at line 1777 of file class.c.

References METHOD_VISI_UNDEF, name, rb_add_method(), rb_intern(), and VM_METHOD_TYPE_UNDEF.

Referenced by Init_bigdecimal(), Init_Binding(), Init_Complex(), Init_cparse(), Init_date_core(), Init_Encoding(), Init_eval(), Init_ISeq(), Init_Numeric(), Init_ossl_asn1(), Init_ossl_ssl(), Init_ossl_x509store(), Init_pathname(), Init_Proc(), Init_Rational(), Init_Regexp(), Init_String(), Init_VM(), Init_vm_backtrace(), InitVM_console(), InitVM_Enumerator(), InitVM_process(), rsock_init_basicsocket(), rsock_init_ipsocket(), and ruby_Init_Continuation_body().

## ◆ rb_undef_methods_from()

void rb_undef_methods_from | ( | VALUE | klass,
|  | VALUE | super
| ) |  |

Definition at line 1791 of file class.c.

References rb_id_table_foreach(), and RCLASS_M_TBL.

Referenced by Init_Complex().