Ruby 3.2.1p31 (2023-02-08 revision 31819e82c88c6f8ecfaeb162519bfa26a14b21fd)
|
Public APIs related to names inside of a Ruby program. More...
#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/attr/noreturn.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"
#include "ruby/st.h"
Go to the source code of this file.
Functions | |
VALUE | rb_mod_name (VALUE mod) |
Queries the name of a module. | |
VALUE | rb_class_path (VALUE mod) |
Identical to rb_mod_name(), except it returns #<Class: ...> style inspection for anonymous modules. | |
VALUE | rb_class_path_cached (VALUE mod) |
Just another name of rb_mod_name. | |
void | rb_set_class_path (VALUE klass, VALUE space, const char *name) |
Names a class. | |
void | rb_set_class_path_string (VALUE klass, VALUE space, VALUE name) |
Identical to rb_set_class_path(), except it accepts the name as Ruby's string instead of C's. | |
VALUE | rb_path_to_class (VALUE path) |
Identical to rb_path2class(), except it accepts the path as Ruby's string instead of C's. | |
VALUE | rb_path2class (const char *path) |
Resolves a Q::W::E::R -style path string to the actual class it points. | |
VALUE | rb_class_name (VALUE obj) |
Queries the name of the given object's class. | |
VALUE | rb_autoload_load (VALUE space, ID name) |
Kicks the autoload procedure as if it was "touched". | |
VALUE | rb_autoload_p (VALUE space, ID name) |
Queries if an autoload is defined at a point. | |
VALUE | rb_f_trace_var (int argc, const VALUE *argv) |
Traces a global variable. | |
VALUE | rb_f_untrace_var (int argc, const VALUE *argv) |
Deletes the passed tracer from the passed global variable, or if omitted, deletes everything. | |
VALUE | rb_f_global_variables (void) |
Queries the list of global variables. | |
void | rb_alias_variable (ID dst, ID src) |
Aliases a global variable. | |
void | rb_free_generic_ivar (VALUE obj) |
Frees the list of instance variables. | |
VALUE | rb_ivar_get (VALUE obj, ID name) |
Identical to rb_iv_get(), except it accepts the name as an ID instead of a C string. | |
VALUE | rb_ivar_set (VALUE obj, ID name, VALUE val) |
Identical to rb_iv_set(), except it accepts the name as an ID instead of a C string. | |
VALUE | rb_ivar_defined (VALUE obj, ID name) |
Queries if the instance variable is defined at the object. | |
void | rb_ivar_foreach (VALUE obj, int(*func)(ID name, VALUE val, st_data_t arg), st_data_t arg) |
Iterates over an object's instance variables. | |
st_index_t | rb_ivar_count (VALUE obj) |
Number of instance variables defined on an object. | |
VALUE | rb_attr_get (VALUE obj, ID name) |
Identical to rb_ivar_get() | |
VALUE | rb_obj_instance_variables (VALUE obj) |
Resembles Object#instance_variables . | |
VALUE | rb_obj_remove_instance_variable (VALUE obj, VALUE name) |
Resembles Object#remove_instance_variable . | |
void * | rb_mod_const_at (VALUE, void *) |
This API is mysterious. | |
void * | rb_mod_const_of (VALUE, void *) |
This is a variant of rb_mod_const_at(). | |
VALUE | rb_const_list (void *) |
This is another mysterious API that comes with no documents at all. | |
VALUE | rb_mod_constants (int argc, const VALUE *argv, VALUE recv) |
Resembles Module#constants . | |
VALUE | rb_mod_remove_const (VALUE space, VALUE name) |
Resembles Module#remove_const . | |
int | rb_const_defined (VALUE space, ID name) |
Queries if the constant is defined at the namespace. | |
int | rb_const_defined_at (VALUE space, ID name) |
Identical to rb_const_defined(), except it doesn't look for parent classes. | |
int | rb_const_defined_from (VALUE space, ID name) |
Identical to rb_const_defined(), except it returns false for private constants. | |
VALUE | rb_const_get (VALUE space, ID name) |
Identical to rb_const_defined(), except it returns the actual defined value. | |
VALUE | rb_const_get_at (VALUE space, ID name) |
Identical to rb_const_defined_at(), except it returns the actual defined value. | |
VALUE | rb_const_get_from (VALUE space, ID name) |
Identical to rb_const_defined_at(), except it returns the actual defined value. | |
void | rb_const_set (VALUE space, ID name, VALUE val) |
Names a constant. | |
VALUE | rb_const_remove (VALUE space, ID name) |
Identical to rb_mod_remove_const(), except it takes the name as ID instead of VALUE. | |
VALUE | rb_cvar_defined (VALUE klass, ID name) |
Queries if the given class has the given class variable. | |
void | rb_cvar_set (VALUE klass, ID name, VALUE val) |
Assigns a value to a class variable. | |
VALUE | rb_cvar_get (VALUE klass, ID name) |
Obtains a value from a class variable. | |
VALUE | rb_cvar_find (VALUE klass, ID name, VALUE *front) |
Identical to rb_cvar_get(), except it takes additional "front" pointer. | |
void | rb_cv_set (VALUE klass, const char *name, VALUE val) |
Identical to rb_cvar_set(), except it accepts C's string instead of ID. | |
VALUE | rb_cv_get (VALUE klass, const char *name) |
Identical to rb_cvar_get(), except it accepts C's string instead of ID. | |
void | rb_define_class_variable (VALUE, const char *, VALUE) |
Just another name of rb_cv_set. | |
VALUE | rb_mod_class_variables (int argc, const VALUE *argv, VALUE recv) |
Resembles Module#class_variables . | |
VALUE | rb_mod_remove_cvar (VALUE mod, VALUE name) |
Resembles Module#remove_class_variable . | |
Public APIs related to names inside of a Ruby program.
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. __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. Definition in file variable.h.
Aliases a global variable.
Did you know that you can alias a global variable? It is like aliasing methods:
This C function does the same thing.
[in] | dst | Destination name. |
[in] | src | Source name. |
dst
is defined to be an alias of a global variable named src
. Definition at line 856 of file variable.c.
Referenced by rb_alias_variable().
Identical to rb_ivar_get()
[in] | obj | Target object. |
[in] | name | Target instance variable to query. |
RUBY_nil | No such instance variable. |
otherwise | The value assigned to the instance variable. |
Definition at line 1223 of file variable.c.
Referenced by rb_attr_get(), rb_class_attached_object(), rb_error_frozen_object(), and rb_singleton_class_get().
Kicks the autoload procedure as if it was "touched".
[out] | space | Namespace where autoload is defined. |
[in] | name | Name of the autoloaded constant. |
RUBY_Qfalse | No such autoload. |
RUBY_Qtrue | Autoload successfully initiated. |
space::name
, it is a nature of this function to have process-global side effects. Definition at line 2718 of file variable.c.
Referenced by rb_autoload_load().
Queries if an autoload is defined at a point.
[in] | space | Namespace where autoload is defined. |
[in] | name | Name of the autoloaded constant. |
RUBY_Qnil | No such autoload. |
otherwise | The feature (path) registered at space::name . |
Definition at line 2756 of file variable.c.
Referenced by rb_autoload_p().
Queries the name of the given object's class.
[in] | obj | Arbitrary object. |
obj
's class' path. Definition at line 307 of file variable.c.
Referenced by rb_any_to_s(), and rb_class_name().
Identical to rb_mod_name(), except it returns #<Class: ...>
style inspection for anonymous modules.
[in] | mod | An instance of rb_cModule. |
mod
's path. Definition at line 185 of file variable.c.
Referenced by rb_class_name(), rb_class_path(), rb_define_class_id_under(), and rb_profile_frame_classpath().
Just another name of rb_mod_name.
Definition at line 194 of file variable.c.
Referenced by rb_class_path_cached().
Queries if the constant is defined at the namespace.
[in] | space | Target namespace. |
[in] | name | Target name to query. |
RUBY_Qtrue | There is a constant. |
RUBY_Qfalse | No such constant. |
Definition at line 3191 of file variable.c.
Referenced by rb_define_class(), and rb_define_module().
Identical to rb_const_defined(), except it doesn't look for parent classes.
For instance Array
is a toplevel constant, which is visible from everywhere. But this function does not take such things into account. It concerns only what is directly defined inside of the given namespace.
[in] | space | Target namespace. |
[in] | name | Target name to query. |
RUBY_Qtrue | There is a constant. |
RUBY_Qfalse | No such constant. |
Definition at line 3197 of file variable.c.
Referenced by rb_const_remove(), rb_define_class_id_under(), and rb_define_module_id_under().
Identical to rb_const_defined(), except it returns false for private constants.
[in] | space | Target namespace. |
[in] | name | Target name to query. |
RUBY_Qtrue | There is a constant. |
RUBY_Qfalse | No such constant. |
Definition at line 3185 of file variable.c.
Identical to rb_const_defined(), except it returns the actual defined value.
[in] | space | Target namespace. |
[in] | name | Target name to query. |
rb_eNameError | No such constant. |
Definition at line 2883 of file variable.c.
Referenced by rb_const_get(), rb_define_class(), and rb_define_module().
Identical to rb_const_defined_at(), except it returns the actual defined value.
It can also be seen as a routine identical to rb_const_get(), except it doesn't look for parent classes.
[in] | space | Target namespace. |
[in] | name | Target name to query. |
rb_eNameError | No such constant. |
Definition at line 2889 of file variable.c.
Referenced by rb_const_get_at(), rb_define_class_id_under(), and rb_define_module_id_under().
Identical to rb_const_defined_at(), except it returns the actual defined value.
It can also be seen as a routine identical to rb_const_get(), except it doesn't return a private constant.
[in] | space | Target namespace. |
[in] | name | Target name to query. |
rb_eNameError | No such constant. |
Definition at line 2877 of file variable.c.
Referenced by rb_const_get_from().
VALUE rb_const_list | ( | void * | data | ) |
This is another mysterious API that comes with no documents at all.
It seems it expects some specific data structure for the passed pointer. But the details has never been made explicit. It seems nobody should use this API.
Definition at line 3103 of file variable.c.
Referenced by rb_mod_constants().
Identical to rb_mod_remove_const(), except it takes the name as ID instead of VALUE.
[out] | space | Target namespace. |
[in] | name | Variable name to remove, either in Symbol or String. |
space::name
is deleted. p
etc., it still introduces itself using the deleted name. Can confuse people. Definition at line 2986 of file variable.c.
Referenced by rb_const_remove(), and rb_mod_remove_const().
Names a constant.
[out] | space | Target namespace. |
[in] | name | Target name to query. |
[in] | val | Value to define. |
rb_eTypeError | `space` is not a module. |
name
is a constant under space
, whose value is val
. Definition at line 3333 of file variable.c.
Referenced by Init_class_hierarchy(), rb_const_set(), rb_define_class(), rb_define_class_id_under(), rb_define_const(), rb_define_module(), rb_define_module_id_under(), and ruby_init_loadpath().
Identical to rb_cvar_get(), except it accepts C's string instead of ID.
[in] | klass | Target class. |
[in] | name | Variable name. |
rb_eNameError | Uninitialised class variable. |
rb_eRuntimeError | `[Bug#14541]` situation. |
name
under klass
. Definition at line 3766 of file variable.c.
Identical to rb_cvar_set(), except it accepts C's string instead of ID.
[out] | klass | Target class. |
[in] | name | Variable name. |
[in] | val | Value to be assigned. |
klass
has a class variable named name
whose value is val
. Definition at line 3759 of file variable.c.
Referenced by rb_define_class_variable().
Queries if the given class has the given class variable.
[in] | klass | Target class. |
[in] | name | Name to query. |
klass
must be an instance of rb_cModule. Definition at line 3740 of file variable.c.
Referenced by rb_cvar_defined(), and rb_mod_remove_cvar().
Identical to rb_cvar_get(), except it takes additional "front" pointer.
This extra parameter is a buffer, which will have the class where the queried class variable actually resides.
[in] | klass | Target class. |
[in] | name | Variable name. |
[out] | front | Return buffer. |
rb_eNameError | Uninitialised class variable. |
rb_eRuntimeError | `[Bug#14541]` situation. |
name
under klass
. front
has the class object, which is an ancestor of klass
, where the queried class variable actually resides. Definition at line 3718 of file variable.c.
Referenced by rb_cvar_get().
Obtains a value from a class variable.
[in] | klass | Target class. |
[in] | name | Variable name. |
rb_eNameError | Uninitialised class variable. |
rb_eRuntimeError | `[Bug#14541]` situation. |
name
under klass
. Definition at line 3733 of file variable.c.
Referenced by rb_cv_get(), and rb_cvar_get().
Assigns a value to a class variable.
[out] | klass | Target class. |
[in] | name | Variable name. |
[in] | val | Value to be assigned. |
klass
has a class variable named name
whose value is val
. Definition at line 3664 of file variable.c.
Referenced by rb_cv_set(), and rb_cvar_set().
Just another name of rb_cv_set.
Definition at line 3773 of file variable.c.
VALUE rb_f_global_variables | ( | void | ) |
Queries the list of global variables.
Definition at line 824 of file variable.c.
Referenced by rb_f_global_variables().
Traces a global variable.
[in] | argc | Either 1 or 2. |
[in] | argv | Variable name, optionally a Proc. |
RUBY_Qnil | No previous tracers. |
otherwise | Previous tracers. |
Definition at line 624 of file variable.c.
Referenced by rb_f_trace_var().
Deletes the passed tracer from the passed global variable, or if omitted, deletes everything.
[in] | argc | Either 1 or 2. |
[in] | argv | Variable name, optionally a Proc. |
RUBY_Qnil | No previous tracers. |
otherwise | Deleted tracers. |
Definition at line 670 of file variable.c.
Referenced by rb_f_trace_var(), and rb_f_untrace_var().
void rb_free_generic_ivar | ( | VALUE | obj | ) |
Frees the list of instance variables.
3rd parties need not know, but there are several ways to store an object's instance variables, depending on its internal structure. This function makes sense when the passed objects is using so-called "generic" backend storage. People need not be aware of this working behind-the-scenes.
[out] | obj | The object in question. |
Definition at line 1062 of file variable.c.
Referenced by rb_copy_generic_ivar(), and rb_free_generic_ivar().
st_index_t rb_ivar_count | ( | VALUE | obj | ) |
Number of instance variables defined on an object.
[in] | obj | Target object. |
obj
. Definition at line 1825 of file variable.c.
Referenced by rb_ivar_count().
Queries if the instance variable is defined at the object.
This roughly resembles defined?(@name)
in obj
's context.
[in] | obj | Target object. |
[in] | name | Target instance variable to query. |
RUBY_Qtrue | There is an instance variable. |
RUBY_Qfalse | No such instance variable. |
Definition at line 1610 of file variable.c.
Referenced by rb_ivar_defined().
Iterates over an object's instance variables.
[in] | obj | Target object. |
[in] | func | Callback function. |
[in] | arg | Passed as-is to the last argument of func . |
Identical to rb_iv_get(), except it accepts the name as an ID instead of a C string.
[in] | obj | Target object. |
[in] | name | Target instance variable to query. |
RUBY_nil | No such instance variable. |
otherwise | The value assigned to the instance variable. |
Definition at line 1215 of file variable.c.
Referenced by rb_class_modify_check(), rb_iv_get(), rb_ivar_get(), and rb_profile_frame_classpath().
Identical to rb_iv_set(), except it accepts the name as an ID instead of a C string.
[out] | obj | Target object. |
[in] | name | Target instance variable. |
[in] | val | Value to assign. |
rb_eFrozenError | Can't modify `obj`. |
rb_eArgError | `obj` has too many instance variables. |
name
is defined if absent on obj
, whose value is set to val
. Definition at line 1593 of file variable.c.
Referenced by rb_error_frozen_object(), rb_frozen_error_raise(), rb_iv_set(), rb_ivar_set(), rb_memory_view_register(), rb_set_class_path_string(), and ruby_init_loadpath().
Resembles Module#class_variables
.
List up the variables defined at the receiver. This includes the names of constants in any included modules, unless argv[0]
is RUBY_Qfalse.
The implementation makes no guarantees about the order in which the constants are yielded.
[in] | argc | Either 0 or 1. |
[in] | argv | Pointer to RUBY_Qfalse, if argc == 1 . |
[in] | recv | Target class. |
recv
. Definition at line 3864 of file variable.c.
Referenced by rb_mod_class_variables().
void * rb_mod_const_at | ( | VALUE | mod, |
void * | data | ||
) |
This API is mysterious.
It has been there since the initial revision. No single bits of documents has ever been written. The function name doesn't describe anything. What should be passed to the argument, or what should be the return value, are not obvious. Yet it has evolved over time. The source code is written in counter-intuitive way (as of 3.0).
Simply put, don't try to understand this API.
Definition at line 3064 of file variable.c.
Referenced by rb_mod_const_of().
void * rb_mod_const_of | ( | VALUE | mod, |
void * | data | ||
) |
This is a variant of rb_mod_const_at().
As a result, it is also mysterious. It seems it iterates over the ancestry tree of the module. But what that means is beyond a human brain.
Definition at line 3081 of file variable.c.
Referenced by rb_mod_constants().
Resembles Module#constants
.
List up the constants defined at the receiver. This includes the names of constants in any included modules, unless argv[0]
is RUBY_Qfalse.
The implementation makes no guarantees about the order in which the constants are yielded.
[in] | argc | Either 0 or 1. |
[in] | argv | Pointer to RUBY_Qfalse, if argc == 1 . |
[in] | recv | Target namespace. |
recv
. Definition at line 3135 of file variable.c.
Queries the name of a module.
[in] | mod | An instance of rb_cModule. |
RUBY_Qnil | mod is anonymous. |
otherwise | mod is onymous. |
Definition at line 134 of file variable.c.
Referenced by rb_class_path_cached(), and rb_mod_name().
Resembles Module#remove_const
.
[out] | space | Target namespace. |
[in] | name | Variable name to remove, either in Symbol or String. |
space::name
is deleted. p
etc., it still introduces itself using the deleted name. Can confuse people. Definition at line 2975 of file variable.c.
Referenced by rb_mod_remove_const().
Resembles Module#remove_class_variable
.
[out] | mod | Target class. |
[in] | name | Variable name to remove, either in Symbol or String. |
name
is deleted from obj
. Definition at line 3899 of file variable.c.
Referenced by rb_mod_remove_cvar().
Resembles Object#instance_variables
.
[in] | obj | Target object to query. |
Definition at line 1909 of file variable.c.
Referenced by rb_obj_instance_variables().
Resembles Object#remove_instance_variable
.
[out] | obj | Target object. |
[in] | name | Variable name to remove, either in Symbol or String. |
name
is deleted from obj
. Definition at line 1964 of file variable.c.
Referenced by rb_obj_remove_instance_variable().
VALUE rb_path2class | ( | const char * | path | ) |
Resolves a Q::W::E::R
-style path string to the actual class it points.
[in] | path | Path to query. |
rb_eArgError | No such constant. |
rb_eTypeError | The path resolved to a non-module. |
Definition at line 301 of file variable.c.
Identical to rb_path2class(), except it accepts the path as Ruby's string instead of C's.
[in] | path | Path to query. |
rb_eArgError | No such constant. |
rb_eTypeError | The path resolved to a non-module. |
Definition at line 256 of file variable.c.
Referenced by rb_path2class(), and rb_path_to_class().
Names a class.
[out] | klass | Target module to name. |
[out] | space | Namespace that klass shall reside. |
[in] | name | Name of klass . |
klass
has space::klass
name. Definition at line 248 of file variable.c.
Identical to rb_set_class_path(), except it accepts the name as Ruby's string instead of C's.
[out] | klass | Target module to name. |
[out] | space | Namespace that klass shall reside. |
[in] | name | Name of klass . |
klass
has space::klass
name. Definition at line 228 of file variable.c.
Referenced by Init_class_hierarchy(), rb_define_class_id_under(), rb_define_module_id_under(), rb_set_class_path(), and rb_set_class_path_string().