diff options
| -rw-r--r-- | class.c | 52 | ||||
| -rw-r--r-- | eval.c | 6 | ||||
| -rw-r--r-- | include/ruby/internal/module.h | 152 |
3 files changed, 144 insertions, 66 deletions
@@ -10,16 +10,7 @@ **********************************************************************/ /*! - * \defgroup class Classes and their hierarchy. - * \par Terminology - * - class: same as in Ruby. - * - singleton class: class for a particular object - * - eigenclass: = singleton class - * - metaclass: class of a class. metaclass is a kind of singleton class. - * - metametaclass: class of a metaclass. - * - meta^(n)-class: class of a meta^(n-1)-class. - * - attached object: A singleton class knows its unique instance. - * The instance is called the attached object for the singleton class. + * \addtogroup class * \{ */ @@ -734,23 +725,6 @@ rb_class_inherited(VALUE super, VALUE klass) return rb_funcall(super, inherited, 1, klass); } - - -/*! - * Defines a top-level class. - * \param name name of the class - * \param super a class from which the new class will derive. - * \return the created class - * \throw TypeError if the constant name \a name is already taken but - * the constant is not a \c Class. - * \throw TypeError if the class is already defined but the class can not - * be reopened because its superclass is not \a super. - * \throw ArgumentError if the \a super is NULL. - * \post top-level constant named \a name refers the returned class. - * - * \note if a class named \a name is already defined and its superclass is - * \a super, the function just returns the defined class. - */ VALUE rb_define_class(const char *name, VALUE super) { @@ -783,24 +757,6 @@ rb_define_class(const char *name, VALUE super) return klass; } - -/*! - * Defines a class under the namespace of \a outer. - * \param outer a class which contains the new class. - * \param name name of the new class - * \param super a class from which the new class will derive. - * NULL means \c Object class. - * \return the created class - * \throw TypeError if the constant name \a name is already taken but - * the constant is not a \c Class. - * \throw TypeError if the class is already defined but the class can not - * be reopened because its superclass is not \a super. - * \post top-level constant named \a name refers the returned class. - * - * \note if a class named \a name is already defined and its superclass is - * \a super, the function just returns the defined class. - * \note the compaction GC does not move classes returned by this function. - */ VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super) { @@ -876,9 +832,6 @@ rb_define_module_id(ID id) return rb_module_new(); } -/*! - * \note the compaction GC does not move modules returned by this function. - */ VALUE rb_define_module(const char *name) { @@ -903,9 +856,6 @@ rb_define_module(const char *name) return module; } -/*! - * \note the compaction GC does not move modules returned by this function. - */ VALUE rb_define_module_under(VALUE outer, const char *name) { @@ -1713,12 +1713,6 @@ rb_obj_call_init_kw(VALUE obj, int argc, const VALUE *argv, int kw_splat) rb_funcallv_kw(obj, idInitialize, argc, argv, kw_splat); } -/*! - * Extend the object with the module. - * - * Same as \c Module\#extend_object. - * \ingroup class - */ void rb_extend_object(VALUE obj, VALUE module) { diff --git a/include/ruby/internal/module.h b/include/ruby/internal/module.h index f32e0b95ee..d678dd2102 100644 --- a/include/ruby/internal/module.h +++ b/include/ruby/internal/module.h @@ -23,20 +23,154 @@ #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" +/** + * @defgroup class Classes and their hierarchy. + * + * @par Terminology + * - class: same as in Ruby. + * - singleton class: class for a particular object. + * - eigenclass: = singleton class + * - metaclass: class of a class. Metaclass is a kind of singleton class. + * - metametaclass: class of a metaclass. + * - meta^(n)-class: class of a meta^(n-1)-class. + * - attached object: A singleton class knows its unique instance. + * The instance is called the attached object for the singleton class. + * @{ + */ + RBIMPL_SYMBOL_EXPORT_BEGIN() +RBIMPL_ATTR_NONNULL(()) +/** + * Defines a top-level class. + * + * @param[in] name Name of the class. + * @param[in] super A class from which the new class will derive. + * @exception rb_eTypeError The constant name `name` is already taken but the + * constant is not a class. + * @exception rb_eTypeError The class is already defined but the class can + * not be reopened because its superclass is not + * `super`. + * @exception rb_eArgError `super` is NULL. + * @return The created class. + * @post Top-level constant named `name` refers the returned class. + * @note If a class named `name` is already defined and its superclass is + * `super`, the function just returns the defined class. + * @note The compaction GC does not move classes returned by this + * function. + * + * @internal + * + * There are classes without names, but you can't pass NULL here. You have to + * use other ways to create one. + */ +VALUE rb_define_class(const char *name, VALUE super); + +RBIMPL_ATTR_NONNULL(()) +/** + * Defines a top-level module. + * + * @param[in] name Name of the module. + * @exception rb_eTypeError The constant name `name` is already taken but the + * constant is not a module. + * @return The created module. + * @post Top-level constant named `name` refers the returned module. + * @note The compaction GC does not move classes returned by this + * function. + * + * @internal + * + * There are modules without names, but you can't pass NULL here. You have to + * use other ways to create one. + */ +VALUE rb_define_module(const char *name); + +RBIMPL_ATTR_NONNULL(()) +/** + * Defines a class under the namespace of `outer`. + * + * @param[out] outer A class which contains the new class. + * @param[in] name Name of the new class + * @param[in] super A class from which the new class will derive. + * 0 means ::rb_cObject. + * @exception rb_eTypeError The constant name `name` is already taken but + * the constant is not a class. + * @exception rb_eTypeError The class is already defined but the class can + * not be reopened because its superclass is not + * `super`. + * @exception rb_eArgError `super` is NULL. + * @return The created class. + * @post `outer::name` refers the returned class. + * @note If a class named `name` is already defined and its superclass + * is `super`, the function just returns the defined class. + * @note The compaction GC does not move classes returned by this + * function. + */ +VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super); + +RBIMPL_ATTR_NONNULL(()) +/** + * Defines a module under the namespace of `outer`. + * + * @param[out] outer A class which contains the new module. + * @param[in] name Name of the new module + * @exception rb_eTypeError The constant name `name` is already taken but + * the constant is not a class. + * @return The created module. + * @post `outer::name` refers the returned module. + * @note The compaction GC does not move classes returned by this + * function. + */ +VALUE rb_define_module_under(VALUE outer, const char *name); + +/** + * Includes a module to a class. + * + * @param[out] klass Inclusion destination. + * @param[in] module Inclusion source. + * @exception rb_eArgError Cyclic inclusion. + * + * @internal + * + * :FIXME: @shyouhei suspects this function lacks assertion that the arguments + * being modules... Could silently SEGV if non-module was passed? + */ +void rb_include_module(VALUE klass, VALUE module); + +/** + * Extend the object with the module. + * + * @warning This is the same as `Module#extend_object`, not + * `Object#extend`! These two methods are very similar, but not + * identical. The difference is the hook. `Module#extend_object` + * does not invoke `Module#extended`, while `Object#extend` does. + * @param[out] obj Object to extend. + * @param[in] mod Module of extension. + */ +void rb_extend_object(VALUE obj, VALUE mod); + /** - * GC compaction note: class and modules returned by these four functions - * do not move. + * Identical to rb_include_module(), except it "prepends" the passed module to + * the klass, instead of includes. This affects how `super` resolves. For + * instance: + * + * ```ruby + * class Q; def foo; "<q/>" end end + * module W; def foo; "<w>#{super}</w>" end end + * class E < Q; include W; def foo; "<e>#{super}</e>" end end + * class R < Q; prepend W; def foo; "<r>#{super}</r>" end end + * + * E.new.foo # => "<e><w><q/></w></e>" + * r.new.foo # => "<W><r><q/></r></w>" + * ``` + * + * @param[out] klass Target class to modify. + * @param[in] module Module to prepend. + * @exception rb_eArgError Cyclic inclusion. */ -VALUE rb_define_class(const char*,VALUE); -VALUE rb_define_module(const char*); -VALUE rb_define_class_under(VALUE, const char*, VALUE); -VALUE rb_define_module_under(VALUE, const char*); +void rb_prepend_module(VALUE klass, VALUE module); -void rb_include_module(VALUE,VALUE); -void rb_extend_object(VALUE,VALUE); -void rb_prepend_module(VALUE,VALUE); +/** @} */ RBIMPL_SYMBOL_EXPORT_END() |