diff options
| -rw-r--r-- | eval.c | 65 | ||||
| -rw-r--r-- | include/ruby/internal/intern/eval.h | 181 |
2 files changed, 172 insertions, 74 deletions
@@ -683,10 +683,6 @@ rb_exc_fatal(VALUE mesg) rb_exc_exception(mesg, TAG_FATAL, Qnil); } -/*! - * Raises an \c Interrupt exception. - * \ingroup exception - */ void rb_interrupt(void) { @@ -814,26 +810,6 @@ make_exception(int argc, const VALUE *argv, int isstr) return mesg; } -/*! - * Make an \c Exception object from the list of arguments in a manner - * similar to \c Kernel\#raise. - * - * \param[in] argc the number of arguments - * \param[in] argv a pointer to the array of arguments. - * - * The first form of this function takes a \c String argument. Then - * it returns a \c RuntimeError whose error message is the given value. - * - * The second from of this function takes an \c Exception object. Then - * it just returns the given value. - * - * The last form takes an exception class, an optional error message and - * an optional array of backtrace. Then it passes the optional arguments - * to \c #exception method of the exception class. - * - * \return the exception object, or \c Qnil if \c argc is 0. - * \ingroup exception - */ VALUE rb_make_exception(int argc, const VALUE *argv) { @@ -858,14 +834,6 @@ rb_raise_jump(VALUE mesg, VALUE cause) rb_longjmp(ec, TAG_RAISE, mesg, cause); } -/*! - * Continues the exception caught by rb_protect() and rb_eval_string_protect(). - * - * This function never return to the caller. - * \param[in] the value of \c *state which the protect function has set to the - * their last parameter. - * \ingroup exception - */ void rb_jump_tag(int tag) { @@ -1060,35 +1028,12 @@ frame_called_id(rb_control_frame_t *cfp) } } -/*! - * 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 - * \sa rb_frame_callee - * \ingroup defmethod - */ ID rb_frame_this_func(void) { return frame_func_id(GET_EC()->cfp); } -/*! - * 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. - * \sa rb_frame_this_func - * \ingroup defmethod - */ ID rb_frame_callee(void) { @@ -1554,16 +1499,6 @@ rb_mod_s_used_modules(VALUE _) return rb_funcall(ary, rb_intern("uniq"), 0); } -/*! - * Calls \c #initialize method of \a obj with the given arguments. - * - * It also forwards the given block to \c #initialize if given. - * - * \param[in] obj the receiver object - * \param[in] argc the number of arguments - * \param[in] argv a pointer to the array of arguments - * \ingroup object - */ void rb_obj_call_init(VALUE obj, int argc, const VALUE *argv) { diff --git a/include/ruby/internal/intern/eval.h b/include/ruby/internal/intern/eval.h index 7b2847abcd..2230f7ab0c 100644 --- a/include/ruby/internal/intern/eval.h +++ b/include/ruby/internal/intern/eval.h @@ -28,31 +28,194 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() /* eval.c */ RBIMPL_ATTR_NORETURN() -void rb_exc_raise(VALUE); +/** + * Identical to rb_raise(), except it raises the passed exception instance as- + * is instead of creating new one. + * + * @param[in] exc An instance of a subclass of ::rb_eException. + * @exception exc What is passed. + * @exception rb_eTypeError `exc` is not an exception. + * @note It never returns. + * + * @internal + * + * Wellll actually, it can take more than what is described above. This + * function tries to call `exception` method of the passed object. If that + * function returns an exception object that is used instead. + */ +void rb_exc_raise(VALUE exc); RBIMPL_ATTR_NORETURN() -void rb_exc_fatal(VALUE); +/** + * Identical to rb_fatal(), except it raises the passed exception instance as- + * is instead of creating new one. + * + * @param[in] exc An instance of a subclass of ::rb_eException. + * @exception exc What is passed. + * @note It never returns. + * + * @internal + * + * You know what...? Using this API you can make arbitrary exceptions, like + * `RuntimeError`, that doesn't interface with `rescue` clause. This is very + * confusing. + */ +void rb_exc_fatal(VALUE exc); + +/* process.c */ RBIMPL_ATTR_NORETURN() -VALUE rb_f_exit(int, const VALUE*); +/** + * Identical to rb_exit(), except how arguments are passed. + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Contains at most one of the following: + * - ::RUBY_Qtrue - means `EXIT_SUCCESS`. + * - ::RUBY_Qfalse - means `EXIT_FAILURE`. + * - Numerical value - takes that value. + * @exception rb_eArgError Wrong `argc`. + * @exception rb_eSystemExit Exception representing the exit status. + * @note It never returns. + */ +VALUE rb_f_exit(int argc, const VALUE *argv); RBIMPL_ATTR_NORETURN() -VALUE rb_f_abort(int, const VALUE*); +/** + * This is similar to rb_f_exit(). In fact on some situation it internally + * calls rb_exit(). But can be very esoteric on occasions. + * + * It takes up to one argument. If an argument is passed, it tries to display + * that. Otherwise if there is `$!`, displays that exception instead. It + * finally raise ::rb_eSystemExit in both cases. + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Contains at most one string-ish object. + * @exception rb_eArgError Wrong `argc`. + * @exception rb_eTypeError No conversion from `argv[0]` to String. + * @exception rb_eSystemExit Exception representing `EXIT_FAILURE`. + * @note It never returns. + */ +VALUE rb_f_abort(int argc, const VALUE *argv); + +/* eval.c*/ RBIMPL_ATTR_NORETURN() +/** + * Raises an instance of ::rb_eInterrupt. + * + * @exception rb_eInterrupt Always raises this exception. + * @note It never returns. + */ void rb_interrupt(void); + +/** + * Queries the name of the Ruby level method that is calling this function. + * The "name" in this context is the one assigned to the function for the first + * time (note that methods can have multiple names via aliases). + * + * @retval 0 There is no method (e.g. toplevel context). + * @retval otherwise The name of the current method. + */ ID rb_frame_this_func(void); RBIMPL_ATTR_NORETURN() -void rb_jump_tag(int); -void rb_obj_call_init(VALUE, int, const VALUE*); +/** + * This function is to re-throw global escapes. Such global escapes include + * exceptions, `throw`, `break`, for example. + * + * It makes sense only when used in conjunction with "protect" series APIs + * e.g. rb_protect(), rb_load_protect(), rb_eval_string_protect(), etc. In + * case these functions experience global escapes, they fill their opaque + * `state` return buffer. You can ignore such escapes. But if you decide + * otherwise, you have to somehow escape globally again. This function is used + * for that purpose. + * + * @param[in] state Opaque state of execution. + * @note It never returns. + * + * @internal + * + * Though not a part of our public API, `state` is in fact an enum + * ruby_tag_type. You can see the potential values by looking at vm_core.h. + */ +void rb_jump_tag(int state); + +/** + * Calls `initialize` method of the passed object with the passed arguments. + * It also forwards the implicitly passed block to the method. + * + * @param[in] obj Receiver object. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Passed as-is to `obj.initialize`. + * @exception rb_eException Any exceptions happen inside. + */ +void rb_obj_call_init(VALUE obj, int argc, const VALUE *argv); + +/** + * Identical to rb_obj_call_init(), except you can specify how to handle the + * last element of the given array. + * + * @param[in] obj Receiver object. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Passed as-is to `obj.initialize`. + * @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. + */ void rb_obj_call_init_kw(VALUE, int, const VALUE*, int); -VALUE rb_protect(VALUE (*)(VALUE), VALUE, int*); + +/** + * Identical to rb_frame_this_func(), except it returns the named used to call + * the method. + * + * @retval 0 There is no method (e.g. toplevel context). + * @retval otherwise The name of the current method. + */ ID rb_frame_callee(void); -VALUE rb_make_exception(int, const VALUE*); + +/** + * Constructs an exception object from the list of arguments, in a manner + * similar to Ruby's `raise`. This function can take: + * + * - No arguments at all, i.e. `argc == 0`. This is not a failure. It + * returns ::RUBY_Qnil then. + * + * - An object, which is an instance of ::rb_cString. In this case an + * instance of ::rb_eRuntimeError whose message is the passed string is + * created then returned. + * + * - An object, which responds to `exception` method, and optionally its + * argument, and optionally its backtrace. For example instances of + * subclasses of ::rb_eException have this method. What is returned from + * the method is returned. + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv 0 up to 3 objects. + * @exception rb_eArgError Wrong `argc`. + * @exception rb_eTypeError `argv[0].exception` returned non-exception. + * @return An instance of a subclass of ::rb_eException. + * + * @internal + * + * Historically this was _the_ way `raise` converted its arguments to an + * exception. However they diverged. + */ +VALUE rb_make_exception(int argc, const VALUE *argv); /* eval_jump.c */ -void rb_set_end_proc(void (*)(VALUE), VALUE); + +/** + * Registers a function that shall run on process exit. Registered functions + * run in reverse-chronological order, mixed with syntactic `END` block and + * `Kernel#at_exit`. + * + * @param[in] func Function to run at process exit. + * @param[in] arg Passed as-is to `func`. + */ +void rb_set_end_proc(void (*func)(VALUE arg), VALUE arg); RBIMPL_SYMBOL_EXPORT_END() |