Ruby
3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
|
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. More... | |
VALUE | rb_class_path (VALUE mod) |
Identical to rb_mod_name(), except it returns #<Class: ...> style inspection for anonymous modules. More... | |
VALUE | rb_class_path_cached (VALUE mod) |
Just another name of rb_mod_name. More... | |
void | rb_set_class_path (VALUE klass, VALUE space, const char *name) |
Names a class. More... | |
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. More... | |
VALUE | rb_path_to_class (VALUE path) |
Identical to rb_path2class(), except it accepts the path as Ruby's string instead of C's. More... | |
VALUE | rb_path2class (const char *path) |
Resolves a Q::W::E::R -style path string to the actual class it points. More... | |
VALUE | rb_class_name (VALUE obj) |
Queries the name of the given object's class. More... | |
VALUE | rb_autoload_load (VALUE space, ID name) |
Kicks the autoload procedure as if it was "touched". More... | |
VALUE | rb_autoload_p (VALUE space, ID name) |
Queries if an autoload is defined at a point. More... | |
VALUE | rb_f_trace_var (int argc, const VALUE *argv) |
Traces a global variable. More... | |
VALUE | rb_f_untrace_var (int argc, const VALUE *argv) |
Deletes the passed tracer from the passed global variable, or if omitted, deletes everything. More... | |
VALUE | rb_f_global_variables (void) |
Queries the list of global variables. More... | |
void | rb_alias_variable (ID dst, ID src) |
Aliases a global variable. More... | |
void | rb_free_generic_ivar (VALUE obj) |
Frees the list of instance variables. More... | |
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. More... | |
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. More... | |
VALUE | rb_ivar_defined (VALUE obj, ID name) |
Queries if the instance variable is defined at the object. More... | |
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. More... | |
st_index_t | rb_ivar_count (VALUE obj) |
Number of instance variables defined on an object. More... | |
VALUE | rb_attr_get (VALUE obj, ID name) |
Identical to rb_ivar_get() More... | |
VALUE | rb_obj_instance_variables (VALUE obj) |
Resembles Object#instance_variables . More... | |
VALUE | rb_obj_remove_instance_variable (VALUE obj, VALUE name) |
Resembles Object#remove_instance_variable . More... | |
void * | rb_mod_const_at (VALUE, void *) |
This API is mysterious. More... | |
void * | rb_mod_const_of (VALUE, void *) |
This is a variant of rb_mod_const_at(). More... | |
VALUE | rb_const_list (void *) |
This is another mysterious API that comes with no documents at all. More... | |
VALUE | rb_mod_constants (int argc, const VALUE *argv, VALUE recv) |
Resembles Module#constants . More... | |
VALUE | rb_mod_remove_const (VALUE space, VALUE name) |
Resembles Module#remove_const . More... | |
int | rb_const_defined (VALUE space, ID name) |
Queries if the constant is defined at the namespace. More... | |
int | rb_const_defined_at (VALUE space, ID name) |
Identical to rb_const_defined(), except it doesn't look for parent classes. More... | |
int | rb_const_defined_from (VALUE space, ID name) |
Identical to rb_const_defined(), except it returns false for private constants. More... | |
VALUE | rb_const_get (VALUE space, ID name) |
Identical to rb_const_defined(), except it returns the actual defined value. More... | |
VALUE | rb_const_get_at (VALUE space, ID name) |
Identical to rb_const_defined_at(), except it returns the actual defined value. More... | |
VALUE | rb_const_get_from (VALUE space, ID name) |
Identical to rb_const_defined_at(), except it returns the actual defined value. More... | |
void | rb_const_set (VALUE space, ID name, VALUE val) |
Names a constant. More... | |
VALUE | rb_const_remove (VALUE space, ID name) |
Identical to rb_mod_remove_const(), except it takes the name as ID instead of VALUE. More... | |
VALUE | rb_cvar_defined (VALUE klass, ID name) |
Queries if the given class has the given class variable. More... | |
void | rb_cvar_set (VALUE klass, ID name, VALUE val) |
Assigns a value to a class variable. More... | |
VALUE | rb_cvar_get (VALUE klass, ID name) |
Obtains a value from a class variable. More... | |
VALUE | rb_cvar_find (VALUE klass, ID name, VALUE *front) |
Identical to rb_cvar_get(), except it takes additional "front" pointer. More... | |
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. More... | |
VALUE | rb_cv_get (VALUE klass, const char *name) |
Identical to rb_cvar_get(), except it accepts C's string instead of ID. More... | |
void | rb_define_class_variable (VALUE, const char *, VALUE) |
Just another name of rb_cv_set. More... | |
VALUE | rb_mod_class_variables (int argc, const VALUE *argv, VALUE recv) |
Resembles Module#class_variables . More... | |
VALUE | rb_mod_remove_cvar (VALUE mod, VALUE name) |
Resembles Module#remove_class_variable . More... | |
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 987 of file variable.c.
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 1358 of file variable.c.
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 2986 of file variable.c.
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 3024 of file variable.c.
Queries the name of the given object's class.
[in] | obj | Arbitrary object. |
obj
's class' path. Definition at line 412 of file variable.c.
Referenced by rb_any_to_s().
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 293 of file variable.c.
Referenced by rb_class_name(), and rb_profile_frame_classpath().
Just another name of rb_mod_name.
Definition at line 302 of file variable.c.
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 3472 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 3478 of file variable.c.
Referenced by 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 3466 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 3151 of file variable.c.
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 3157 of file variable.c.
Referenced by 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 3145 of file variable.c.
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 3384 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 3267 of file variable.c.
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 3619 of file variable.c.
Referenced by rb_define_const(), 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 4045 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 4038 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 4019 of file variable.c.
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 3997 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 4012 of file variable.c.
Referenced by rb_cv_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 3942 of file variable.c.
Referenced by rb_cv_set().
Just another name of rb_cv_set.
Definition at line 4052 of file variable.c.
VALUE rb_f_global_variables | ( | void | ) |
Queries the list of global variables.
Definition at line 955 of file variable.c.
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 755 of file variable.c.
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 801 of file variable.c.
Referenced by rb_f_trace_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 1155 of file variable.c.
st_index_t rb_ivar_count | ( | VALUE | obj | ) |
Number of instance variables defined on an object.
[in] | obj | Target object. |
obj
. Definition at line 2143 of file variable.c.
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 1876 of file variable.c.
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 . |
Referenced by rb_obj_instance_variables().
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 1350 of file variable.c.
Referenced by rb_iv_get().
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 1859 of file variable.c.
Referenced by rb_error_frozen_object(), rb_frozen_error_raise(), rb_iv_set(), rb_memory_view_register(), 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 4142 of file variable.c.
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 3345 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 3362 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 3416 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 130 of file variable.c.
Referenced by rb_class_path_cached().
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 3256 of file variable.c.
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 4177 of file variable.c.
Resembles Object#instance_variables
.
[in] | obj | Target object to query. |
Definition at line 2195 of file variable.c.
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 2249 of file variable.c.
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 406 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 361 of file variable.c.
Referenced by rb_path2class().
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 353 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 336 of file variable.c.
Referenced by rb_define_module_id_under(), and rb_set_class_path().