| Current File : //proc/thread-self/root/opt/alt/ruby33/include/ruby/internal/intern/class.h |
#ifndef RBIMPL_INTERN_CLASS_H /*-*-C++-*-vi:se ft=cpp:*/
#define RBIMPL_INTERN_CLASS_H
/**
* @file
* @author Ruby developers <ruby-core@ruby-lang.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.
* @brief Public APIs related to ::rb_cClass/::rb_cModule.
*/
#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"
#include "ruby/backward/2/stdarg.h"
RBIMPL_SYMBOL_EXPORT_BEGIN()
/* class.c */
/**
* Creates a new, anonymous class.
*
* @param[in] super What would become a parent class.
* @exception rb_eTypeError `super` is not something inheritable.
* @return An anonymous class that inherits `super`.
*/
VALUE rb_class_new(VALUE super);
/**
* The comment that comes with this function says `:nodoc:`. Not sure what
* that means though.
*
* @param[out] clone Destination object.
* @param[in] orig Source object.
* @exception rb_eTypeError Cannot copy `orig`.
* @return The passed `clone`.
*/
VALUE rb_mod_init_copy(VALUE clone, VALUE orig);
/**
* Asserts that the given class can derive a child class. A class might or
* might not be able to do so; for instance a singleton class cannot.
*
* @param[in] super Possible super class.
* @exception rb_eTypeError No it cannot.
* @post Upon successful return `super` can derive.
*/
void rb_check_inheritable(VALUE super);
/**
* This is a very badly designed API that creates an anonymous class.
*
* @param[in] id Discarded for no reason (why...).
* @param[in] super What would become a parent class. 0 means
* ::rb_cObject.
* @exception rb_eTypeError `super` is not something inheritable.
* @return An anonymous class that inherits `super`.
* @warning You must explicitly name the return value.
*/
VALUE rb_define_class_id(ID id, VALUE super);
/**
* Identical to rb_define_class_under(), except it takes the name in ::ID
* instead of C's string.
*
* @param[out] outer A class which contains the new class.
* @param[in] id 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 `id` 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::id` refers the returned class.
* @note If a class named `id` 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_id_under(VALUE outer, ID id, VALUE super);
/**
* Creates a new, anonymous module.
*
* @return An anonymous module.
*/
VALUE rb_module_new(void);
/**
* Creates a new, anonymous refinement.
*
* @return An anonymous refinement.
*/
VALUE rb_refinement_new(void);
/**
* This is a very badly designed API that creates an anonymous module.
*
* @param[in] id Discarded for no reason (why...).
* @return An anonymous module.
* @warning You must explicitly name the return value.
*/
VALUE rb_define_module_id(ID id);
/**
* Identical to rb_define_module_under(), except it takes the name in ::ID
* instead of C's string.
*
* @param[out] outer A class which contains the new module.
* @param[in] id Name of the new module
* @exception rb_eTypeError The constant name `id` is already taken but the
* constant is not a module.
* @return The created module.
* @post `outer::id` refers the returned module.
* @note The compaction GC does not move classes returned by this
* function.
*/
VALUE rb_define_module_id_under(VALUE outer, ID id);
/**
* Queries the list of included modules. It can also be seen as a routine to
* first call rb_mod_ancestors(), then rejects non-modules from the return
* value.
*
* @param[in] mod Class or Module.
* @return An array of modules that are either included or prepended in any
* of `mod`'s ancestry tree (including itself).
*/
VALUE rb_mod_included_modules(VALUE mod);
/**
* Queries if the passed module is included by the module. It can also be seen
* as a routine to first call rb_mod_included_modules(), then see if the return
* value contains the passed module.
*
* @param[in] child A Module.
* @param[in] parent Another Module.
* @exception rb_eTypeError `child` is not an instance of ::rb_cModule.
* @retval RUBY_Qtrue `parent` is either included or prepended in any
* of `child`'s ancestry tree (including itself).
* @return RUBY_Qfalse Otherwise.
*/
VALUE rb_mod_include_p(VALUE child, VALUE parent);
/**
* Queries the module's ancestors. This routine gathers classes and modules
* that the passed module either inherits, includes, or prepends, then
* recursively applies that routine again and again to the collected entries
* until the list doesn't grow up.
*
* @param[in] mod A module or a class.
* @return An array of classes or modules that `mod` possibly recursively
* inherits, includes, or prepends.
*
* @internal
*
* Above description is written in a recursive language but in practice it
* computes the return value iteratively.
*/
VALUE rb_mod_ancestors(VALUE mod);
/**
* Queries the class's descendants. This routine gathers classes that are
* subclasses of the given class (or subclasses of those subclasses, etc.),
* returning an array of classes that have the given class as an ancestor.
* The returned array does not include the given class or singleton classes.
*
* @param[in] klass A class.
* @return An array of classes where `klass` is an ancestor.
*
* @internal
*/
VALUE rb_class_descendants(VALUE klass);
/**
* Queries the class's direct descendants. This routine gathers classes that are
* direct subclasses of the given class,
* returning an array of classes that have the given class as a superclass.
* The returned array does not include singleton classes.
*
* @param[in] klass A class.
* @return An array of classes where `klass` is the `superclass`.
*
* @internal
*/
VALUE rb_class_subclasses(VALUE klass);
/**
* Returns the attached object for a singleton class.
* If the given class is not a singleton class, raises a TypeError.
*
* @param[in] klass A class.
* @return The object which has the singleton class `klass`.
*
* @internal
*/
VALUE rb_class_attached_object(VALUE klass);
/**
* Generates an array of symbols, which are the list of method names defined in
* the passed class.
*
* @param[in] argc Number of objects of `argv`.
* @param[in] argv Array of at most one object, which controls (if
* any) whether the return array includes the names
* of methods defined in ancestors or not.
* @param[in] mod A module or a class.
* @exception rb_eArgError `argc` out of range.
* @return An array of symbols collecting names of instance methods that
* are not private, defined at `mod`.
*/
VALUE rb_class_instance_methods(int argc, const VALUE *argv, VALUE mod);
/**
* Identical to rb_class_instance_methods(), except it returns names of methods
* that are public only.
*
* @param[in] argc Number of objects of `argv`.
* @param[in] argv Array of at most one object, which controls (if
* any) whether the return array includes the names
* of methods defined in ancestors or not.
* @param[in] mod A module or a class.
* @exception rb_eArgError `argc` out of range.
* @return An array of symbols collecting names of instance methods that
* are public, defined at `mod`.
*/
VALUE rb_class_public_instance_methods(int argc, const VALUE *argv, VALUE mod);
/**
* Identical to rb_class_instance_methods(), except it returns names of methods
* that are protected only.
*
* @param[in] argc Number of objects of `argv`.
* @param[in] argv Array of at most one object, which controls (if
* any) whether the return array includes the names
* of methods defined in ancestors or not.
* @param[in] mod A module or a class.
* @exception rb_eArgError `argc` out of range.
* @return An array of symbols collecting names of instance methods that
* are protected, defined at `mod`.
*/
VALUE rb_class_protected_instance_methods(int argc, const VALUE *argv, VALUE mod);
/**
* Identical to rb_class_instance_methods(), except it returns names of methods
* that are private only.
*
* @param[in] argc Number of objects of `argv`.
* @param[in] argv Array of at most one object, which controls (if
* any) whether the return array includes the names
* of methods defined in ancestors or not.
* @param[in] mod A module or a class.
* @exception rb_eArgError `argc` out of range.
* @return An array of symbols collecting names of instance methods that
* are protected, defined at `mod`.
*/
VALUE rb_class_private_instance_methods(int argc, const VALUE *argv, VALUE mod);
/**
* Identical to rb_class_instance_methods(), except it returns names of
* singleton methods instead of instance methods.
*
* @param[in] argc Number of objects of `argv`.
* @param[in] argv Array of at most one object, which controls (if
* any) whether the return array includes the names
* of methods defined in ancestors or not.
* @param[in] obj Arbitrary ruby object.
* @exception rb_eArgError `argc` out of range.
* @return An array of symbols collecting names of instance methods that
* are not private, defined at the singleton class of `obj`.
*/
VALUE rb_obj_singleton_methods(int argc, const VALUE *argv, VALUE obj);
/**
* Identical to rb_define_method(), except it takes the name of the method in
* ::ID instead of C's string.
*
* @param[out] klass A module or a class.
* @param[in] mid Name of the function.
* @param[in] func The method body.
* @param[in] arity The number of parameters. See @ref defmethod.
* @note There are in fact 18 different prototypes for func.
* @see ::ruby::backward::cxxanyargs::define_method::rb_define_method_id
*/
void rb_define_method_id(VALUE klass, ID mid, VALUE (*func)(ANYARGS), int arity);
/* vm_method.c */
/**
* Inserts a method entry that hides previous method definition of the given
* name. This is not a deletion of a method. Method of the same name defined
* in a parent class is kept invisible in this way.
*
* @param[out] mod The module to insert an undef.
* @param[in] mid Name of the undef.
* @exception rb_eTypeError `klass` is a non-module.
* @exception rb_eFrozenError `klass` is frozen.
* @exception rb_eNameError No such method named `klass#name`.
* @post `klass#name` is undefined.
* @see rb_undef_method
*
* @internal
*
* @shyouhei doesn't understand why this is not the ::ID -taking variant of
* rb_undef_method(), given rb_remove_method() has its ::ID -taking counterpart
* named rb_remove_method_id().
*/
void rb_undef(VALUE mod, ID mid);
/* class.c */
RBIMPL_ATTR_NONNULL(())
/**
* Identical to rb_define_method(), except it defines a protected method.
*
* @param[out] klass A module or a class.
* @param[in] mid Name of the function.
* @param[in] func The method body.
* @param[in] arity The number of parameters. See @ref defmethod.
* @note There are in fact 18 different prototypes for func.
* @see ::ruby::backward::cxxanyargs::define_method::rb_define_protected_method
*/
void rb_define_protected_method(VALUE klass, const char *mid, VALUE (*func)(ANYARGS), int arity);
RBIMPL_ATTR_NONNULL(())
/**
* Identical to rb_define_method(), except it defines a private method.
*
* @param[out] klass A module or a class.
* @param[in] mid Name of the function.
* @param[in] func The method body.
* @param[in] arity The number of parameters. See @ref defmethod.
* @note There are in fact 18 different prototypes for func.
* @see ::ruby::backward::cxxanyargs::define_method::rb_define_protected_method
*/
void rb_define_private_method(VALUE klass, const char *mid, VALUE (*func)(ANYARGS), int arity);
RBIMPL_ATTR_NONNULL(())
/**
* Identical to rb_define_method(), except it defines a singleton method.
*
* @param[out] obj Arbitrary ruby object.
* @param[in] mid Name of the function.
* @param[in] func The method body.
* @param[in] arity The number of parameters. See @ref defmethod.
* @note There are in fact 18 different prototypes for func.
* @see ::ruby::backward::cxxanyargs::define_method::rb_define_singleton_method
*/
void rb_define_singleton_method(VALUE obj, const char *mid, VALUE(*func)(ANYARGS), int arity);
/**
* Finds or creates the singleton class of the passed object.
*
* @param[out] obj Arbitrary ruby object.
* @exception rb_eTypeError `obj` cannot have its singleton class.
* @return A (possibly newly allocated) instance of ::rb_cClass.
* @post `obj` has its singleton class, which is the return value.
* @post In case `obj` is a class, the returned singleton class also has
* its own singleton class in order to keep consistency of the
* inheritance structure of metaclasses.
* @note A new singleton class will be created if `obj` did not have
* one.
* @note The singleton classes for ::RUBY_Qnil, ::RUBY_Qtrue, and
* ::RUBY_Qfalse are ::rb_cNilClass, ::rb_cTrueClass, and
* ::rb_cFalseClass respectively.
*
* @internal
*
* You can _create_ a singleton class of a frozen object. Intentional or ...?
*
* Nowadays there are wider range of objects who cannot have singleton classes
* than before. For instance some string instances cannot for some reason.
*/
VALUE rb_singleton_class(VALUE obj);
RBIMPL_SYMBOL_EXPORT_END()
#endif /* RBIMPL_INTERN_CLASS_H */