diff options
| -rw-r--r-- | include/ruby/internal/eval.h | 353 | ||||
| -rw-r--r-- | vm_eval.c | 59 |
2 files changed, 339 insertions, 73 deletions
diff --git a/include/ruby/internal/eval.h b/include/ruby/internal/eval.h index 5dda3c78bf..34a53849da 100644 --- a/include/ruby/internal/eval.h +++ b/include/ruby/internal/eval.h @@ -21,28 +21,351 @@ * @brief Declares ::rb_eval_string(). */ #include "ruby/internal/dllexport.h" +#include "ruby/internal/attr/nonnull.h" #include "ruby/internal/value.h" RBIMPL_SYMBOL_EXPORT_BEGIN() -VALUE rb_eval_string(const char*); -VALUE rb_eval_string_protect(const char*, int*); -VALUE rb_eval_string_wrap(const char*, int*); -VALUE rb_funcall(VALUE, ID, int, ...); -VALUE rb_funcallv(VALUE, ID, int, const VALUE*); -VALUE rb_funcallv_kw(VALUE, ID, int, const VALUE*, int); -VALUE rb_funcallv_public(VALUE, ID, int, const VALUE*); -VALUE rb_funcallv_public_kw(VALUE, ID, int, const VALUE*, int); +RBIMPL_ATTR_NONNULL(()) +/** + * Evaluates the given string in an isolated binding. + * + * Here "isolated" means that the binding does not inherit any other + * bindings. This behaves same as the binding for required libraries. + * + * `__FILE__` will be `"(eval)"`, and `__LINE__` starts from 1 in the + * evaluation. + * + * @param[in] str Ruby code to evaluate. + * @exception rb_eException Raises an exception on error. + * @return The evaluated result. + */ +VALUE rb_eval_string(const char *str); + +RBIMPL_ATTR_NONNULL((1)) +/** + * 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. + * + * @param[in] str Ruby code to evaluate. + * @param[out] state State of execution. + * @return The evaluated result if succeeded, an undefined value if + * otherwise. + * @post `*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 rb_eval_string + * @see rb_protect + * + * @internal + * + * The "undefined value" described above is in fact ::RUBY_Qnil for now. But + * @shyouhei doesn't think that we would never change that. + * + * Though not a part of our public API, `state` is in fact an + * enum ruby_tag_type. You can see the potential "nonzero" values by looking + * at vm_core.h. + */ +VALUE rb_eval_string_protect(const char *str, int *state); + +RBIMPL_ATTR_NONNULL((1)) +/** + * 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)`. + * + * @param[in] str Ruby code to evaluate. + * @param[out] state State of execution. + * @return The evaluated result if succeeded, an undefined value if + * otherwise. + * @post `*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 rb_eval_string + */ +VALUE rb_eval_string_wrap(const char *str, int *state); + +/** + * Calls a method. Can call both public and private methods. + * + * @param[in,out] recv Receiver of the method. + * @param[in] mid Name of the method to call. + * @param[in] n Number of arguments that follow. + * @param[in] ... Arbitrary number of method arguments. + * @exception rb_eNoMethodError No such method. + * @exception rb_eException Any exceptions happen inside. + * @return What the method evaluates to. + */ +VALUE rb_funcall(VALUE recv, ID mid, int n, ...); + +/** + * Identical to rb_funcall(), except it takes the method arguments as a C + * array. + * + * @param[in,out] recv Receiver of the method. + * @param[in] mid Name of the method to call. + * @param[in] argc Number of arguments. + * @param[in] argv Arbitrary number of method arguments. + * @exception rb_eNoMethodError No such method. + * @exception rb_eException Any exceptions happen inside. + * @return What the method evaluates to. + */ +VALUE rb_funcallv(VALUE recv, ID mid, int argc, const VALUE *argv); + +/** + * Identical to rb_funcallv(), except you can specify how to handle the last + * element of the given array. + * + * @param[in,out] recv Receiver of the method. + * @param[in] mid Name of the method to call. + * @param[in] argc Number of arguments. + * @param[in] argv Arbitrary number of method arguments. + * @param[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. + * @exception rb_eNoMethodError No such method. + * @exception rb_eException Any exceptions happen inside. + * @return What the method evaluates to. + */ +VALUE rb_funcallv_kw(VALUE recv, ID mid, int argc, const VALUE *argv, int kw_splat); + +/** + * Identical to rb_funcallv(), except it only takes public methods into + * account. This is roughly Ruby's `Object#public_send`. + * + * @param[in,out] recv Receiver of the method. + * @param[in] mid Name of the method to call. + * @param[in] argc Number of arguments. + * @param[in] argv Arbitrary number of method arguments. + * @exception rb_eNoMethodError No such method. + * @exception rb_eNoMethodError The method is private or protected. + * @exception rb_eException Any exceptions happen inside. + * @return What the method evaluates to. + */ +VALUE rb_funcallv_public(VALUE recv, ID mid, int argc, const VALUE *argv); + +/** + * 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. + * + * @param[in,out] recv Receiver of the method. + * @param[in] mid Name of the method to call. + * @param[in] argc Number of arguments. + * @param[in] argv Arbitrary number of method arguments. + * @param[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. + * @exception rb_eNoMethodError No such method. + * @exception rb_eNoMethodError The method is private or protected. + * @exception rb_eException Any exceptions happen inside. + * @return What the method evaluates to. + */ +VALUE rb_funcallv_public_kw(VALUE recv, ID mid, int argc, const VALUE *argv, int kw_splat); + +/** + * @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. + */ #define rb_funcall2 rb_funcallv + +/** + * @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. + */ #define rb_funcall3 rb_funcallv_public -VALUE rb_funcall_passing_block(VALUE, ID, int, const VALUE*); -VALUE rb_funcall_passing_block_kw(VALUE, ID, int, const VALUE*, int); -VALUE rb_funcall_with_block(VALUE, ID, int, const VALUE*, VALUE); -VALUE rb_funcall_with_block_kw(VALUE, ID, int, const VALUE*, VALUE, int); -VALUE rb_call_super(int, const VALUE*); -VALUE rb_call_super_kw(int, const VALUE*, int); + +/** + * 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`: + * + * ```ruby + * 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. + * + * ```CXX + * 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 rb_yield_block + * @param[in,out] recv Receiver of the method. + * @param[in] mid Name of the method to call. + * @param[in] argc Number of arguments. + * @param[in] argv Arbitrary number of method arguments. + * @exception rb_eNoMethodError No such method. + * @exception rb_eNoMethodError The method is private or protected. + * @exception rb_eException Any exceptions happen inside. + * @return What the method evaluates to. + */ +VALUE rb_funcall_passing_block(VALUE recv, ID mid, int argc, const VALUE *argv); + +/** + * 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. + * + * @param[in,out] recv Receiver of the method. + * @param[in] mid Name of the method to call. + * @param[in] argc Number of arguments. + * @param[in] argv Arbitrary number of method arguments. + * @param[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. + * @exception rb_eNoMethodError No such method. + * @exception rb_eNoMethodError The method is private or protected. + * @exception rb_eException Any exceptions happen inside. + * @return What the method evaluates to. + */ +VALUE rb_funcall_passing_block_kw(VALUE recv, ID mid, int argc, const VALUE *argv, int kw_splat); + +/** + * 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. + * + * @param[in,out] recv Receiver of the method. + * @param[in] mid Name of the method to call. + * @param[in] argc Number of arguments. + * @param[in] argv Arbitrary number of method arguments. + * @param[in] procval An instance of Proc, Symbol, or NilClass. + * @exception rb_eNoMethodError No such method. + * @exception rb_eNoMethodError The method is private or protected. + * @exception rb_eException Any exceptions happen inside. + * @return What the method evaluates to. + * + * @internal + * + * Implementation-wise, `procval` is in fact a "block handler" object. You + * could also pass an IFUNC (block_handler_ifunc) here to say precise. --- But + * AFAIK there is no 3rd party way to even know that there are objects called + * IFUNC behind-the-scene. + */ +VALUE rb_funcall_with_block(VALUE recv, ID mid, int argc, const VALUE *argv, VALUE procval); + +/** + * 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. + * + * @param[in,out] recv Receiver of the method. + * @param[in] mid Name of the method to call. + * @param[in] argc Number of arguments. + * @param[in] argv Arbitrary number of method arguments. + * @param[in] procval An instance of Proc, Symbol, or NilClass. + * @param[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. + * @exception rb_eNoMethodError No such method. + * @exception rb_eNoMethodError The method is private or protected. + * @exception rb_eException Any exceptions happen inside. + * @return What the method evaluates to. + */ +VALUE rb_funcall_with_block_kw(VALUE recv, ID mid, int argc, const VALUE *argv, VALUE procval, int kw_splat); + +/** + * This resembles ruby's `super`. + * + * @param[in] argc Number of arguments. + * @param[in] argv Arbitrary number of method arguments. + * @exception rb_eNoMethodError No super method are there. + * @exception rb_eException Any exceptions happen inside. + * @return What the super method evaluates to. + */ +VALUE rb_call_super(int argc, const VALUE *argv); + +/** + * Identical to rb_call_super(), except you can specify how to handle the last + * element of the given array. + * + * @param[in] argc Number of arguments. + * @param[in] argv Arbitrary number of method arguments. + * @param[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. + * @exception rb_eNoMethodError No super method are there. + * @exception rb_eException Any exceptions happen inside. + * @return What the super method evaluates to. + */ +VALUE rb_call_super_kw(int argc, const VALUE *argv, int kw_splat); + +/** + * This resembles ruby's `self`. + * + * @exception rb_eRuntimeError Called from outside of method context. + * @return Current receiver. + */ VALUE rb_current_receiver(void); -int rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optional, VALUE *); + +RBIMPL_ATTR_NONNULL((2)) +/** + * 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 https://bugs.ruby-lang.org/issues/11339 + * @param[out] keyword_hash Target hash to deconstruct. + * @param[in] table List of keywords that you are interested in. + * @param[in] required Number of mandatory keywords. + * @param[in] optional Number of optional keywords (can be negative). + * @param[out] values Buffer to be filled. + * @exception rb_eArgError Absence of a mandatory keyword. + * @exception rb_eArgError Found an unknown keyword. + * @return Number of found values that are stored into `values`. + */ +int rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values); + +RBIMPL_ATTR_NONNULL(()) +/** + * 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. + * + * @param[in,out] orighash Pointer to a target hash to split. + * @return An extracted keyword hash. + * @post 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. + */ VALUE rb_extract_keywords(VALUE *orighash); RBIMPL_SYMBOL_EXPORT_END() @@ -1045,13 +1045,6 @@ rb_funcallv_scope(VALUE recv, ID mid, int argc, const VALUE *argv, call_type sco #ifdef rb_funcallv #undef rb_funcallv #endif -/*! - * Calls a method - * \param recv receiver of the method - * \param mid an ID that represents the name of the method - * \param argc the number of arguments - * \param argv pointer to an array of method arguments - */ VALUE rb_funcallv(VALUE recv, ID mid, int argc, const VALUE *argv) { @@ -1100,15 +1093,7 @@ rb_apply(VALUE recv, ID mid, VALUE args) #ifdef rb_funcall #undef rb_funcall #endif -/*! - * Calls a method - * \param recv receiver of the method - * \param mid an ID that represents the name of the method - * \param n the number of arguments - * \param ... arbitrary number of method arguments - * - * \pre each of arguments after \a n must be a VALUE. - */ + VALUE rb_funcall(VALUE recv, ID mid, int n, ...) { @@ -1160,15 +1145,6 @@ rb_check_funcall_basic_kw(VALUE recv, ID mid, VALUE ancestor, int argc, const VA return Qundef; } -/*! - * Calls a method. - * - * Same as rb_funcallv but this function can call only public methods. - * \param recv receiver of the method - * \param mid an ID that represents the name of the method - * \param argc the number of arguments - * \param argv pointer to an array of method arguments - */ VALUE rb_funcallv_public(VALUE recv, ID mid, int argc, const VALUE *argv) { @@ -1851,18 +1827,6 @@ ruby_eval_string_from_file(const char *str, const char *filename) return eval_string_with_cref(rb_vm_top_self(), rb_str_new2(str), NULL, file, 1); } -/** - * Evaluates the given string in an isolated binding. - * - * Here "isolated" means the binding does not inherit any other binding. This - * behaves same as the binding for required libraries. - * - * __FILE__ will be "(eval)", and __LINE__ starts from 1 in the evaluation. - * - * @param str Ruby code to evaluate. - * @return The evaluated result. - * @throw Exception Raises an exception on error. - */ VALUE rb_eval_string(const char *str) { @@ -1875,16 +1839,6 @@ eval_string_protect(VALUE str) return rb_eval_string((char *)str); } -/** - * Evaluates the given string in an isolated binding. - * - * __FILE__ will be "(eval)", and __LINE__ starts from 1 in the evaluation. - * - * @sa rb_eval_string - * @param str Ruby code to evaluate. - * @param state Being set to zero if succeeded. Nonzero if an error occurred. - * @return The evaluated result if succeeded, an undefined value if otherwise. - */ VALUE rb_eval_string_protect(const char *str, int *pstate) { @@ -1906,17 +1860,6 @@ eval_string_wrap_protect(VALUE data) return eval_string_with_cref(arg->top_self, rb_str_new_cstr(arg->str), cref, rb_str_new_cstr("eval"), 1); } -/** - * Evaluates the given string under a module binding in an isolated binding. - * This is the same as the binding for loaded libraries on "load('foo', true)". - * - * __FILE__ will be "(eval)", and __LINE__ starts from 1 in the evaluation. - * - * @sa rb_eval_string - * @param str Ruby code to evaluate. - * @param state Being set to zero if succeeded. Nonzero if an error occurred. - * @return The evaluated result if succeeded, an undefined value if otherwise. - */ VALUE rb_eval_string_wrap(const char *str, int *pstate) { |