Ruby: include/ruby/internal/eval.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Macros | Functions
eval.h File Reference

Declares rb_eval_string(). More...

`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/attr/nonnull.h"`
`#include "ruby/internal/value.h"`

Go to the source code of this file.

## Macros
#define | rb_funcall2 rb_funcallv
#define | rb_funcall3 rb_funcallv_public

## Functions
VALUE | rb_eval_string (const char *str)
| Evaluates the given string.
VALUE | rb_eval_string_protect (const char *str, int *state)
| Identical to rb_eval_string(), except it avoids potential global escapes.
VALUE | rb_eval_string_wrap (const char *str, int *state)
| Identical to rb_eval_string_protect(), except it evaluates the given string under a module binding in an isolated binding.
VALUE | rb_funcall (VALUE recv, ID mid, int n,...)
| Calls a method.
VALUE | rb_funcallv (VALUE recv, ID mid, int argc, const VALUE *argv)
| Identical to rb_funcall(), except it takes the method arguments as a C array.
VALUE | rb_funcallv_kw (VALUE recv, ID mid, int argc, const VALUE *argv, int kw_splat)
| Identical to rb_funcallv(), except you can specify how to handle the last element of the given array.
VALUE | rb_funcallv_public (VALUE recv, ID mid, int argc, const VALUE *argv)
| Identical to rb_funcallv(), except it only takes public methods into account.
VALUE | rb_funcallv_public_kw (VALUE recv, ID mid, int argc, const VALUE *argv, int kw_splat)
| Identical to rb_funcallv_public(), except you can specify how to handle the last element of the given array.
VALUE | rb_funcall_passing_block (VALUE recv, ID mid, int argc, const VALUE *argv)
| Identical to rb_funcallv_public(), except you can pass the passed block.
VALUE | rb_funcall_passing_block_kw (VALUE recv, ID mid, int argc, const VALUE *argv, int kw_splat)
| Identical to rb_funcallv_passing_block(), except you can specify how to handle the last element of the given array.
VALUE | rb_funcall_with_block (VALUE recv, ID mid, int argc, const VALUE *argv, VALUE procval)
| Identical to rb_funcallv_public(), except you can pass a block.
VALUE | rb_funcall_with_block_kw (VALUE recv, ID mid, int argc, const VALUE *argv, VALUE procval, int kw_splat)
| Identical to rb_funcallv_with_block(), except you can specify how to handle the last element of the given array.
VALUE | rb_call_super (int argc, const VALUE *argv)
| This resembles ruby's `super`.
VALUE | rb_call_super_kw (int argc, const VALUE *argv, int kw_splat)
| Identical to rb_call_super(), except you can specify how to handle the last element of the given array.
VALUE | rb_current_receiver (void)
| This resembles ruby's `self`.
int | rb_get_kwargs (VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values)
| Keyword argument deconstructor.
VALUE | rb_extract_keywords (VALUE *orighash)
| Splits a hash into two.

## Detailed Description

Declares rb_eval_string().

Author
  Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Warning
  Symbols prefixed with either `RBIMPL` or `rbimpl` are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.

Note
  To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance `__VA_ARGS__` is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Definition in file eval.h.

## Macro Definition Documentation

## ◆ rb_funcall2

#define rb_funcall2 rb_funcallv

Deprecated
  This is an old name of rb_funcallv(). Provided here for backwards compatibility to 2.x programs (introduced in 2.1). It is not a good name. Please don't use it any longer.

Definition at line 205 of file eval.h.

## ◆ rb_funcall3

#define rb_funcall3 rb_funcallv_public

Deprecated
  This is an old name of rb_funcallv_public(). Provided here for backwards compatibility to 2.x programs (introduced in 2.1). It is not a good name. Please don't use it any longer.

Definition at line 212 of file eval.h.

## Function Documentation

## ◆ rb_call_super()

VALUE rb_call_super | ( | int | argc,
|  | const VALUE * | argv )

This resembles ruby's `super`.

Parameters

  [in] | argc | Number of arguments.
  [in] | argv | Arbitrary number of method arguments.

Exceptions

  rb_eNoMethodError | No super method are there.
  rb_eException | Any exceptions happen inside.

Returns
  What the super method evaluates to.

Definition at line 339 of file vm_eval.c.

## ◆ rb_call_super_kw()

VALUE rb_call_super_kw | ( | int | argc,
|  | const VALUE * | argv,
|  | int | kw_splat )

Identical to rb_call_super(), except you can specify how to handle the last element of the given array.

Parameters

  [in] | argc | Number of arguments.
  [in] | argv | Arbitrary number of method arguments.
  [in] | kw_splat | Handling of keyword parameters: RB_NO_KEYWORDS `argv`'s last is not a keyword argument. RB_PASS_KEYWORDS `argv`'s last is a keyword argument. RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.

Exceptions

  rb_eNoMethodError | No super method are there.
  rb_eException | Any exceptions happen inside.

Returns
  What the super method evaluates to.

Definition at line 331 of file vm_eval.c.

Referenced by rb_call_super().

## ◆ rb_current_receiver()

VALUE rb_current_receiver | ( | void |  | ) |

This resembles ruby's `self`.

Exceptions

  rb_eRuntimeError | Called from outside of method context.

Returns
  Current receiver.

Definition at line 345 of file vm_eval.c.

## ◆ rb_eval_string()

VALUE rb_eval_string | ( | const char * | str | ) |

Evaluates the given string.

In case it is called from within a C-backended method, the evaluation is done under the current binding. However there can be no method. On such situation this function evaluates in an isolated binding, like `require` runs in a separate one.

`__FILE__` will be `"(eval)"`, and `__LINE__` starts from 1 in the evaluation.

Parameters

  [in] | str | Ruby code to evaluate.

Exceptions

  rb_eException | Raises an exception on error.

Returns
  The evaluated result.

Definition at line 1848 of file vm_eval.c.

## ◆ rb_eval_string_protect()

VALUE rb_eval_string_protect | ( | const char * | str,
|  | int * | state )

Identical to rb_eval_string(), except it avoids potential global escapes.

Such global escapes include exceptions, `throw`, `break`, for example.

It first evaluates the given string as rb_eval_string() does. If no global escape occurred during the evaluation, it returns the result and `*state` is zero. Otherwise, it returns some undefined value and sets `*state` to nonzero. If state is `NULL`, it is not set in both cases.

Parameters

  [in] | str | Ruby code to evaluate.
  [out] | state | State of execution.

Returns
  The evaluated result if succeeded, an undefined value if otherwise.

Postcondition
  `*state` is set to zero if succeeded. Nonzero otherwise.

Warning
  You have to clear the error info with `rb_set_errinfo(Qnil)` if you decide to ignore the caught exception.

See also
  rb_eval_string
  rb_protect

Definition at line 1860 of file vm_eval.c.

## ◆ rb_eval_string_wrap()

VALUE rb_eval_string_wrap | ( | const char * | str,
|  | int * | state )

Identical to rb_eval_string_protect(), except it evaluates the given string under a module binding in an isolated binding.

This is the same as a binding for loaded libraries on `rb_load(something, true)`.

Parameters

  [in] | str | Ruby code to evaluate.
  [out] | state | State of execution.

Returns
  The evaluated result if succeeded, an undefined value if otherwise.

Postcondition
  `*state` is set to zero if succeeded. Nonzero otherwise.

Warning
  You have to clear the error info with `rb_set_errinfo(Qnil)` if you decide to ignore the caught exception.

See also
  rb_eval_string

Definition at line 1881 of file vm_eval.c.

Referenced by rb_eval_string_wrap().

## ◆ rb_funcall()

VALUE rb_funcall | ( | VALUE | recv,
|  | ID | mid,
|  | int | n,
|  |  | ... )

Calls a method.

Can call both public and private methods.

Parameters

  [in,out] | recv | Receiver of the method.
  [in] | mid | Name of the method to call.
  [in] | n | Number of arguments that follow.
  [in] | ... | Arbitrary number of method arguments.

Exceptions

  rb_eNoMethodError | No such method.
  rb_eException | Any exceptions happen inside.

Returns
  What the method evaluates to.

Definition at line 1102 of file vm_eval.c.

Referenced by rb_class_inherited(), rb_cmpint(), rb_eql(), rb_equal(), rb_fiber_scheduler_block(), rb_fiber_scheduler_io_wait(), rb_fiber_scheduler_kernel_sleep(), rb_fiber_scheduler_unblock(), rb_file_size(), rb_io_descriptor(), rb_num_coerce_bin(), rb_num_coerce_cmp(), rb_num_coerce_relop(), rb_obj_as_string(), rb_obj_dup(), rb_obj_init_clone(), and rb_obj_init_dup_clone().

## ◆ rb_funcall_passing_block()

VALUE rb_funcall_passing_block | ( | VALUE | recv,
|  | ID | mid,
|  | int | argc,
|  | const VALUE * | argv )

Identical to rb_funcallv_public(), except you can pass the passed block.

Sometimes you want to "pass" a block parameter form one method to another. Suppose you have this Ruby method `foo`:

def foo(x, y, &z)
x.open(y, &z)
end

And suppose you want to translate this into C. Then rb_funcall_passing_block() function is usable in this situation.

VALUE
foo_translated_into_C(VALUE self, VALUE x, VALUE y)
{
const auto open = rb_intern("open");
return rb_funcall_passing_block(x, open, 1, &y);
}
rb_funcall_passing_block
VALUE rb_funcall_passing_block(VALUE recv, ID mid, int argc, const VALUE *argv)
Identical to rb_funcallv_public(), except you can pass the passed block.
Definition vm_eval.c:1165
rb_intern
ID rb_intern(const char *name)
Finds or creates a symbol of the given name.
Definition symbol.c:796
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40

See also
  rb_yield_block

Parameters

  [in,out] | recv | Receiver of the method.
  [in] | mid | Name of the method to call.
  [in] | argc | Number of arguments.
  [in] | argv | Arbitrary number of method arguments.

Exceptions

  rb_eNoMethodError | No such method.
  rb_eNoMethodError | The method is private or protected.
  rb_eException | Any exceptions happen inside.

Returns
  What the method evaluates to.

Definition at line 1165 of file vm_eval.c.

## ◆ rb_funcall_passing_block_kw()

VALUE rb_funcall_passing_block_kw | ( | VALUE | recv,
|  | ID | mid,
|  | int | argc,
|  | const VALUE * | argv,
|  | int | kw_splat )

Identical to rb_funcallv_passing_block(), except you can specify how to handle the last element of the given array.

It can also be seen as a routine identical to rb_funcallv_public_kw(), except you can pass the passed block.

Parameters

  [in,out] | recv | Receiver of the method.
  [in] | mid | Name of the method to call.
  [in] | argc | Number of arguments.
  [in] | argv | Arbitrary number of method arguments.
  [in] | kw_splat | Handling of keyword parameters: RB_NO_KEYWORDS `argv`'s last is not a keyword argument. RB_PASS_KEYWORDS `argv`'s last is a keyword argument. RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.

Exceptions

  rb_eNoMethodError | No such method.
  rb_eNoMethodError | The method is private or protected.
  rb_eException | Any exceptions happen inside.

Returns
  What the method evaluates to.

Definition at line 1172 of file vm_eval.c.

Referenced by rb_fiber_scheduler_fiber().

## ◆ rb_funcall_with_block()

VALUE rb_funcall_with_block | ( | VALUE | recv,
|  | ID | mid,
|  | int | argc,
|  | const VALUE * | argv,
|  | VALUE | procval )

Identical to rb_funcallv_public(), except you can pass a block.

A block here basically is an instance of rb_cProc. If you want to exercise `to_proc` conversion, do so before passing it here. However nil and symbols are special-case allowed.

Parameters

  [in,out] | recv | Receiver of the method.
  [in] | mid | Name of the method to call.
  [in] | argc | Number of arguments.
  [in] | argv | Arbitrary number of method arguments.
  [in] | procval | An instance of Proc, Symbol, or NilClass.

Exceptions

  rb_eNoMethodError | No such method.
  rb_eNoMethodError | The method is private or protected.
  rb_eException | Any exceptions happen inside.

Returns
  What the method evaluates to.

Definition at line 1179 of file vm_eval.c.

## ◆ rb_funcall_with_block_kw()

VALUE rb_funcall_with_block_kw | ( | VALUE | recv,
|  | ID | mid,
|  | int | argc,
|  | const VALUE * | argv,
|  | VALUE | procval,
|  | int | kw_splat )

Identical to rb_funcallv_with_block(), except you can specify how to handle the last element of the given array.

It can also be seen as a routine identical to rb_funcallv_public_kw(), except you can pass a block.

Parameters

  [in,out] | recv | Receiver of the method.
  [in] | mid | Name of the method to call.
  [in] | argc | Number of arguments.
  [in] | argv | Arbitrary number of method arguments.
  [in] | procval | An instance of Proc, Symbol, or NilClass.
  [in] | kw_splat | Handling of keyword parameters: RB_NO_KEYWORDS `argv`'s last is not a keyword argument. RB_PASS_KEYWORDS `argv`'s last is a keyword argument. RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.

Exceptions

  rb_eNoMethodError | No such method.
  rb_eNoMethodError | The method is private or protected.
  rb_eException | Any exceptions happen inside.

Returns
  What the method evaluates to.

Definition at line 1189 of file vm_eval.c.

## ◆ rb_funcallv()

VALUE rb_funcallv | ( | VALUE | recv,
|  | ID | mid,
|  | int | argc,
|  | const VALUE * | argv )

Identical to rb_funcall(), except it takes the method arguments as a C array.

Parameters

  [in,out] | recv | Receiver of the method.
  [in] | mid | Name of the method to call.
  [in] | argc | Number of arguments.
  [in] | argv | Arbitrary number of method arguments.

Exceptions

  rb_eNoMethodError | No such method.
  rb_eException | Any exceptions happen inside.

Returns
  What the method evaluates to.

Definition at line 1061 of file vm_eval.c.

## ◆ rb_funcallv_kw()

VALUE rb_funcallv_kw | ( | VALUE | recv,
|  | ID | mid,
|  | int | argc,
|  | const VALUE * | argv,
|  | int | kw_splat )

Identical to rb_funcallv(), except you can specify how to handle the last element of the given array.

Parameters

  [in,out] | recv | Receiver of the method.
  [in] | mid | Name of the method to call.
  [in] | argc | Number of arguments.
  [in] | argv | Arbitrary number of method arguments.
  [in] | kw_splat | Handling of keyword parameters: RB_NO_KEYWORDS `argv`'s last is not a keyword argument. RB_PASS_KEYWORDS `argv`'s last is a keyword argument. RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.

Exceptions

  rb_eNoMethodError | No such method.
  rb_eException | Any exceptions happen inside.

Returns
  What the method evaluates to.

Definition at line 1069 of file vm_eval.c.

Referenced by rb_eval_cmd_kw(), and rb_obj_call_init_kw().

## ◆ rb_funcallv_public()

VALUE rb_funcallv_public | ( | VALUE | recv,
|  | ID | mid,
|  | int | argc,
|  | const VALUE * | argv )

Identical to rb_funcallv(), except it only takes public methods into account.

This is roughly Ruby's `Object#public_send`.

Parameters

  [in,out] | recv | Receiver of the method.
  [in] | mid | Name of the method to call.
  [in] | argc | Number of arguments.
  [in] | argv | Arbitrary number of method arguments.

Exceptions

  rb_eNoMethodError | No such method.
  rb_eNoMethodError | The method is private or protected.
  rb_eException | Any exceptions happen inside.

Returns
  What the method evaluates to.

Definition at line 1153 of file vm_eval.c.

Referenced by rb_funcall_passing_block(), rb_funcall_with_block(), and rb_random_ulong_limited().

## ◆ rb_funcallv_public_kw()

VALUE rb_funcallv_public_kw | ( | VALUE | recv,
|  | ID | mid,
|  | int | argc,
|  | const VALUE * | argv,
|  | int | kw_splat )

Identical to rb_funcallv_public(), except you can specify how to handle the last element of the given array.

It can also be seen as a routine identical to rb_funcallv_kw(), except it only takes public methods into account.

Parameters

  [in,out] | recv | Receiver of the method.
  [in] | mid | Name of the method to call.
  [in] | argc | Number of arguments.
  [in] | argv | Arbitrary number of method arguments.
  [in] | kw_splat | Handling of keyword parameters: RB_NO_KEYWORDS `argv`'s last is not a keyword argument. RB_PASS_KEYWORDS `argv`'s last is a keyword argument. RB_PASS_CALLED_KEYWORDS it depends if there is a passed block.

Exceptions

  rb_eNoMethodError | No such method.
  rb_eNoMethodError | The method is private or protected.
  rb_eException | Any exceptions happen inside.

Returns
  What the method evaluates to.

Definition at line 1159 of file vm_eval.c.