eval.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

Declares rb_eval_string(). More...

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

Include dependency graph for eval.h:

This graph shows which files directly or indirectly include this file:

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. More...
VALUE	rb_eval_string_protect (const char *str, int *state)
	Identical to rb_eval_string(), except it avoids potential global escapes. More...
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. More...
VALUE	rb_funcall (VALUE recv, ID mid, int n,...)
	Calls a method. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
VALUE	rb_call_super (int argc, const VALUE *argv)
	This resembles ruby's super. More...
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. More...
VALUE	rb_current_receiver (void)
	This resembles ruby's self. More...
int	rb_get_kwargs (VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values)
	Keyword argument deconstructor. More...
VALUE	rb_extract_keywords (VALUE *orighash)
	Splits a hash into two. More...

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 362 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 354 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 368 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 1975 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 1987 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 2008 of file vm_eval.c.

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 1099 of file vm_eval.c.

Referenced by 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_num_coerce_bin(), rb_num_coerce_cmp(), rb_num_coerce_relop(), rb_obj_as_string(), 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);
}

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 1162 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 1169 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 1176 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 1186 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 1058 of file vm_eval.c.

Referenced by rb_apply(), rb_enc_get_index(), rb_fiber_scheduler_kernel_sleepv(), rb_funcall(), rb_inspect(), rb_io_write(), and rb_random_real().

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 1066 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 1150 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 1156 of file vm_eval.c.