From 9527d909511cf8f726cd936856adb5f98e9f433c Mon Sep 17 00:00:00 2001 From: matz Date: Thu, 5 Oct 2000 09:57:04 +0000 Subject: matz git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@988 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- README.EXT | 106 ++++++++++++++++++++++++++++++------------------------------- 1 file changed, 52 insertions(+), 54 deletions(-) (limited to 'README.EXT') diff --git a/README.EXT b/README.EXT index 12d379e09b..5079adb558 100644 --- a/README.EXT +++ b/README.EXT @@ -38,11 +38,13 @@ Ruby interpreter has data-types as below: T_TRUE true T_FALSE false T_DATA data + T_SYMBOL symbol Otherwise, there are several other types used internally: T_ICLASS T_MATCH + T_UNDEF T_VARMAP T_SCOPE T_NODE @@ -141,25 +143,25 @@ interpreter. Useful functions are listed below (not all): String functions - rb_str_new(char *ptr, int len) + rb_str_new(const char *ptr, long len) Creates a new Ruby string. - rb_str_new2(char *ptr) + rb_str_new2(const char *ptr) Creates a new Ruby string from C string. This is equivalent to rb_str_new(ptr, strlen(ptr)). - rb_tainted_str_new(char *ptr, int len) + rb_tainted_str_new(const char *ptr, long len) Creates a new tainted Ruby string. Strings from external data should be tainted. - rb_tainted_str_new2(char *ptr) + rb_tainted_str_new2(const char *ptr) Creates a new tainted Ruby string from C string. - rb_str_cat(VALUE str, char *ptr, int len) + rb_str_cat(VALUE str, const char *ptr, long len) Appends len bytes data from ptr to the Ruby string. @@ -169,16 +171,16 @@ interpreter. Useful functions are listed below (not all): Creates an array with no element. - rb_ary_new2(int len) + rb_ary_new2(long len) Creates an array with no element, with allocating internal buffer for len elements. - rb_ary_new3(int n, ...) + rb_ary_new3(long n, ...) Creates an n-elements array from arguments. - rb_ary_new4(int n, VALUE *elts) + rb_ary_new4(long n, VALUE *elts) Creates an n-elements array from C array. @@ -186,7 +188,6 @@ interpreter. Useful functions are listed below (not all): rb_ary_pop(VALUE ary) rb_ary_shift(VALUE ary) rb_ary_unshift(VALUE ary, VALUE val) - rb_ary_entry(VALUE ary, int idx) Array operations. The first argument to each functions must be an array. They may dump core if other types given. @@ -206,25 +207,25 @@ interpreter. Ruby provides the API to define things below: To define class or module, use functions below: - VALUE rb_define_class(char *name, VALUE super) - VALUE rb_define_module(char *name) + VALUE rb_define_class(const char *name, VALUE super) + VALUE rb_define_module(const char *name) These functions return the newly created class or module. You may want to save this reference into the variable to use later. To define nested class or module, use functions below: - VALUE rb_define_class_under(VALUE outer, char *name, VALUE super) - VALUE rb_define_module_under(VALUE outer, char *name) + VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super) + VALUE rb_define_module_under(VALUE outer, const char *name) 2.1.2 Method/singleton method definition To define methods or singleton methods, use functions below: - void rb_define_method(VALUE klass, char *name, + void rb_define_method(VALUE klass, const char *name, VALUE (*func)(), int argc) - void rb_define_singleton_method(VALUE object, char *name, + void rb_define_singleton_method(VALUE object, const char *name, VALUE (*func)(), int argc) The `argc' represents the number of the arguments to the C function, @@ -251,7 +252,7 @@ actual arguments. There're two more functions to define method. One is to define private method: - void rb_define_private_method(VALUE klass, char *name, + void rb_define_private_method(VALUE klass, const char *name, VALUE (*func)(), int argc) The other is to define module function, which is private AND singleton @@ -267,13 +268,13 @@ or To define module function - void rb_define_module_function(VALUE module, char *name, + void rb_define_module_function(VALUE module, const char *name, VALUE (*func)(), int argc) Oh, in addition, function-like method, which is private method defined in Kernel module, can be defined using: - void rb_define_global_function(char *name, VALUE (*func)(), int argc) + void rb_define_global_function(const char *name, VALUE (*func)(), int argc) To define alias to the method, @@ -283,8 +284,8 @@ To define alias to the method, We have 2 functions to define constants: - void rb_define_const(VALUE klass, char *name, VALUE val) - void rb_define_global_const(char *name, VALUE val) + void rb_define_const(VALUE klass, const char *name, VALUE val) + void rb_define_global_const(const char *name, VALUE val) The former is to define constant under specified class/module. The latter is to define global constant. @@ -298,7 +299,7 @@ There are several ways to invoke Ruby's features from C code. Easiest way to call Ruby's function from C program is to evaluate the string as Ruby program. This function will do the job. - VALUE rb_eval_string(char *str) + VALUE rb_eval_string(const char *str) Evaluation is done under current context, thus current local variables of the innermost method (which is defined by Ruby) can be accessed. @@ -314,10 +315,7 @@ It can be accessed from Ruby in the form like: You can get the symbol value from string within C code, by using - rb_intern(char *name) - -In addition, the symbols for one character operators (e.g +) is the -code for that character. + rb_intern(const char *name) 2.2.3 Invoke Ruby method from C @@ -367,7 +365,7 @@ Ruby nil in C scope. Information can be shared between two worlds, using shared global variables. To define them, you can use functions listed below: - void rb_define_variable(char *name, VALUE *var) + void rb_define_variable(const char *name, VALUE *var) This function defines the variable which is shared by the both world. The value of the global variable pointed by `var', can be accessed @@ -376,20 +374,20 @@ through Ruby's global variable named `name'. You can define read-only (from Ruby, of course) variable by the function below. - void rb_define_readonly_variable(char *name, VALUE *var) + void rb_define_readonly_variable(const char *name, VALUE *var) You can defined hooked variables. The accessor functions (getter and setter) are called on access to the hooked variables. - void rb_define_hooked_variable(char *name, VALUE *var, - VALUE (*getter)(), VALUE (*setter)()) + void rb_define_hooked_variable(constchar *name, VALUE *var, + VALUE (*getter)(), void (*setter)()) If you need to supply either setter or getter, just supply 0 for the hook you don't need. If both hooks are 0, rb_define_hooked_variable() works just like rb_define_variable(). - void rb_define_virtual_variable(char *name, - VALUE (*getter)(), VALUE (*setter)()) + void rb_define_virtual_variable(const char *name, + VALUE (*getter)(), void (*setter)()) This function defines the Ruby global variable without corresponding C variable. The value of the variable will be set/get only by hooks. @@ -756,20 +754,20 @@ the variable sval. ** defining class/module - VALUE rb_define_class(char *name, VALUE super) + VALUE rb_define_class(const char *name, VALUE super) Defines new Ruby class as subclass of super. - VALUE rb_define_class_under(VALUE module, char *name, VALUE super) + VALUE rb_define_class_under(VALUE module, const char *name, VALUE super) Creates new Ruby class as subclass of super, under the module's namespace. - VALUE rb_define_module(char *name) + VALUE rb_define_module(const char *name) Defines new Ruby module. - VALUE rb_define_module_under(VALUE module, char *name, VALUE super) + VALUE rb_define_module_under(VALUE module, const char *name, VALUE super) Defines new Ruby module, under the module's namespace. @@ -784,18 +782,18 @@ Extend the object with module's attribute. ** Defining Global Variables - void rb_define_variable(char *name, VALUE *var) + void rb_define_variable(const char *name, VALUE *var) Defines a global variable which is shared between C and Ruby. If name contains the character which is not allowed to be part of the symbol, it can't be seen from Ruby programs. - void rb_define_readonly_variable(char *name, VALUE *var) + void rb_define_readonly_variable(const char *name, VALUE *var) Defines a read-only global variable. Works just like rb_define_variable(), except defined variable is read-only. - void rb_define_virtual_variable(char *name, + void rb_define_virtual_variable(const char *name, VALUE (*getter)(), VALUE (*setter)()) Defines a virtual variable, whose behavior is defined by pair of C @@ -808,7 +806,7 @@ variable. The prototype for getter/setter functions are: The getter function must return the value for the access. - void rb_define_hooked_variable(char *name, VALUE *var, + void rb_define_hooked_variable(const char *name, VALUE *var, VALUE (*getter)(), VALUE (*setter)()) Defines hooked variable. It's virtual variable with C variable. The @@ -828,11 +826,11 @@ Tells GC to protect these variables. ** Constant Definition - void rb_define_const(VALUE klass, char *name, VALUE val) + void rb_define_const(VALUE klass, const char *name, VALUE val) Defines a new constant under the class/module. - void rb_define_global_const(char *name, VALUE val) + void rb_define_global_const(const char *name, VALUE val) Defines global constant. This is just work as @@ -840,7 +838,7 @@ Defines global constant. This is just work as ** Method Definition - rb_define_method(VALUE klass, char *name, VALUE (*func)(), int argc) + rb_define_method(VALUE klass, const char *name, VALUE (*func)(), int argc) Defines a method for the class. func is the function pointer. argc is the number of arguments. if argc is -1, the function will receive @@ -848,16 +846,16 @@ is the number of arguments. if argc is -1, the function will receive receive 2 arguments, self and args, where args is the Ruby array of the method arguments. - rb_define_private_method(VALUE klass, char *name, VALUE (*func)(), int argc) + rb_define_private_method(VALUE klass, const char *name, VALUE (*func)(), int argc) Defines a private method for the class. Arguments are same as rb_define_method(). - rb_define_singleton_method(VALUE klass, char *name, VALUE (*func)(), int argc) + rb_define_singleton_method(VALUE klass, const char *name, VALUE (*func)(), int argc) Defines a singleton method. Arguments are same as rb_define_method(). - rb_scan_args(int argc, VALUE *argv, char *fmt, ...) + rb_scan_args(int argc, VALUE *argv, const char *fmt, ...) Retrieve argument from argc, argv. The fmt is the format string for the arguments, such as "12" for 1 non-optional argument, 2 optional @@ -875,11 +873,11 @@ Invokes the method. To retrieve mid from method name, use rb_intern(). Invokes method, passing arguments by array of values. - VALUE rb_eval_string(char *str) + VALUE rb_eval_string(const char *str) Compiles and executes the string as Ruby program. - ID rb_intern(char *name) + ID rb_intern(const char *name) Returns ID corresponding the name. @@ -897,12 +895,12 @@ Returns true if the object responds to the message specified by id. ** Instance Variables - VALUE rb_iv_get(VALUE obj, char *name) + VALUE rb_iv_get(VALUE obj, const char *name) Retrieve the value of the instance variable. If the name is not prefixed by `@', that variable shall be inaccessible from Ruby. - VALUE rb_iv_set(VALUE obj, char *name, VALUE val) + VALUE rb_iv_set(VALUE obj, const char *name, VALUE val) Sets the value of the instance variable. @@ -933,26 +931,26 @@ rb_ensure() is that of func1. ** Exceptions and Errors - void rb_warn(char *fmt, ...) + void rb_warn(const char *fmt, ...) Prints warning message according to the printf-like format. - void rb_warning(char *fmt, ...) + void rb_warning(const char *fmt, ...) Prints warning message according to the printf-like format, if $VERBOSE is true. - void rb_raise(VALUE exception, char *fmt, ...) + void rb_raise(VALUE exception, const char *fmt, ...) Raises an exception of class exception. The fmt is the format string just like printf(). - void rb_fatal(char *fmt, ...) + void rb_fatal(const char *fmt, ...) Raises fatal error, terminates the interpreter. No exception handling will be done for fatal error, but ensure blocks will be executed. - void rb_bug(char *fmt, ...) + void rb_bug(const char *fmt, ...) Terminates the interpreter immediately. This function should be called under the situation caused by the bug in the interpreter. No -- cgit v1.2.3