mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
include/ruby/internal/eval.h: add doxygen
Must not be a bad idea to improve documents. [ci skip]
This commit is contained in:
卜部昌平
parent
ee94fb44f4
commit
30f3319871
Notes:
git
2021-09-10 20:01:47 +09:00
2 changed files with 339 additions and 73 deletions
|
|
@ -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()
|
||||
|
|
|
|||
59
vm_eval.c
59
vm_eval.c
|
|
@ -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)
|
||||
{
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue