ruby-changes:26113
From: drbrain <ko1@a...>
Date: Tue, 4 Dec 2012 08:35:42 +0900 (JST)
Subject: [ruby-changes:26113] drbrain:r38170 (trunk): * README.EXT: Converted to RDoc format
drbrain 2012-12-04 08:34:17 +0900 (Tue, 04 Dec 2012) New Revision: 38170 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=38170 Log: * README.EXT: Converted to RDoc format * README.EXT.ja: ditto Modified files: trunk/ChangeLog trunk/README.EXT trunk/README.EXT.ja Index: README.EXT =================================================================== --- README.EXT (revision 38169) +++ README.EXT (revision 38170) @@ -1,8 +1,8 @@ -.\" README.EXT - -*- Text -*- created at: Mon Aug 7 16:45:54 JST 1995 +# README.EXT - -*- RDoc -*- created at: Mon Aug 7 16:45:54 JST 1995 This document explains how to make extension libraries for Ruby. -1. Basic knowledge += Basic Knowledge In C, variables have types and data do not have types. In contrast, Ruby variables do not have a static type, and data themselves have @@ -13,47 +13,46 @@ To retrieve C data from a VALUE, you need to: - (1) Identify the VALUE's data type - (2) Convert the VALUE into C data +1. Identify the VALUE's data type +2. Convert the VALUE into C data Converting to the wrong data type may cause serious problems. +== Data-Types -1.1 Data-types - The Ruby interpreter has the following data types: - T_NIL nil - T_OBJECT ordinary object - T_CLASS class - T_MODULE module - T_FLOAT floating point number - T_STRING string - T_REGEXP regular expression - T_ARRAY array - T_HASH associative array - T_STRUCT (Ruby) structure - T_BIGNUM multi precision integer - T_FIXNUM Fixnum(31bit or 63bit integer) - T_COMPLEX complex number - T_RATIONAL rational number - T_FILE IO - T_TRUE true - T_FALSE false - T_DATA data - T_SYMBOL symbol +T_NIL :: nil +T_OBJECT :: ordinary object +T_CLASS :: class +T_MODULE :: module +T_FLOAT :: floating point number +T_STRING :: string +T_REGEXP :: regular expression +T_ARRAY :: array +T_HASH :: associative array +T_STRUCT :: (Ruby) structure +T_BIGNUM :: multi precision integer +T_FIXNUM :: Fixnum(31bit or 63bit integer) +T_COMPLEX :: complex number +T_RATIONAL :: rational number +T_FILE :: IO +T_TRUE :: true +T_FALSE :: false +T_DATA :: data +T_SYMBOL :: symbol In addition, there are several other types used internally: - T_ICLASS - T_MATCH - T_UNDEF - T_NODE - T_ZOMBIE +T_ICLASS :: included module +T_MATCH :: MatchData object +T_UNDEF :: undefined +T_NODE :: syntax tree node +T_ZOMBIE :: object awaiting finalization Most of the types are represented by C structures. -1.2 Check Data Type of the VALUE +== Check Data Type of the VALUE The macro TYPE() defined in ruby.h shows the data type of the VALUE. TYPE() returns the constant number T_XXXX described above. To handle @@ -87,7 +86,7 @@ FIXNUM_P(obj) NIL_P(obj) -1.3 Convert VALUE into C data +== Convert VALUE into C Data The data for type T_NIL, T_FALSE, T_TRUE are nil, false, true respectively. They are singletons for the data type. @@ -137,17 +136,17 @@ are responsible for the result. This ends up being the cause of interesting bugs. -1.4 Convert C data into VALUE +== Convert C Data into VALUE To convert C data to Ruby values: - * FIXNUM +FIXNUM :: - left shift 1 bit, and turn on LSB. + left shift 1 bit, and turn on LSB. - * Other pointer values +Other pointer values:: - cast to VALUE. + cast to VALUE. You can determine whether a VALUE is pointer or not by checking its LSB. @@ -157,149 +156,149 @@ To convert C numbers to Ruby values, use these macros. - INT2FIX() for integers within 31bits. - INT2NUM() for arbitrary sized integer. +INT2FIX() :: for integers within 31bits. +INT2NUM() :: for arbitrary sized integer. INT2NUM() converts an integer into a Bignum if it is out of the FIXNUM range, but is a bit slower. -1.5 Manipulating Ruby data +== Manipulating Ruby Data As I already mentioned, it is not recommended to modify an object's internal structure. To manipulate objects, use the functions supplied by the Ruby interpreter. Some (not all) of the useful functions are listed below: - String functions +=== String Functions - rb_str_new(const char *ptr, long len) +rb_str_new(const char *ptr, long len) :: - Creates a new Ruby string. + Creates a new Ruby string. - rb_str_new2(const char *ptr) - rb_str_new_cstr(const char *ptr) +rb_str_new2(const char *ptr) :: +rb_str_new_cstr(const char *ptr) :: - Creates a new Ruby string from a C string. This is equivalent to - rb_str_new(ptr, strlen(ptr)). + Creates a new Ruby string from a C string. This is equivalent to + rb_str_new(ptr, strlen(ptr)). - rb_tainted_str_new(const char *ptr, long len) +rb_tainted_str_new(const char *ptr, long len) :: - Creates a new tainted Ruby string. Strings from external data - sources should be tainted. + Creates a new tainted Ruby string. Strings from external data + sources should be tainted. - rb_tainted_str_new2(const char *ptr) - rb_tainted_str_new_cstr(const char *ptr) +rb_tainted_str_new2(const char *ptr) :: +rb_tainted_str_new_cstr(const char *ptr) :: - Creates a new tainted Ruby string from a C string. + Creates a new tainted Ruby string from a C string. - rb_sprintf(const char *format, ...) - rb_vsprintf(const char *format, va_list ap) +rb_sprintf(const char *format, ...) :: +rb_vsprintf(const char *format, va_list ap) :: - Creates a new Ruby string with printf(3) format. + Creates a new Ruby string with printf(3) format. - rb_str_cat(VALUE str, const char *ptr, long len) +rb_str_cat(VALUE str, const char *ptr, long len) :: - Appends len bytes of data from ptr to the Ruby string. + Appends len bytes of data from ptr to the Ruby string. - rb_str_cat2(VALUE str, const char* ptr) +rb_str_cat2(VALUE str, const char* ptr) :: - Appends C string ptr to Ruby string str. This function is - equivalent to rb_str_cat(str, ptr, strlen(ptr)). + Appends C string ptr to Ruby string str. This function is + equivalent to rb_str_cat(str, ptr, strlen(ptr)). - rb_str_catf(VALUE str, const char* format, ...) - rb_str_vcatf(VALUE str, const char* format, va_list ap) +rb_str_catf(VALUE str, const char* format, ...) :: +rb_str_vcatf(VALUE str, const char* format, va_list ap) :: - Appends C string format and successive arguments to Ruby string - str according to a printf-like format. These functions are - equivalent to rb_str_cat2(str, rb_sprintf(format, ...)) and - rb_str_cat2(str, rb_vsprintf(format, ap)), respectively. + Appends C string format and successive arguments to Ruby string + str according to a printf-like format. These functions are + equivalent to rb_str_cat2(str, rb_sprintf(format, ...)) and + rb_str_cat2(str, rb_vsprintf(format, ap)), respectively. - rb_enc_str_new(const char *ptr, long len, rb_encoding *enc) +rb_enc_str_new(const char *ptr, long len, rb_encoding *enc) :: - Creates a new Ruby string with the specified encoding. + Creates a new Ruby string with the specified encoding. - rb_usascii_str_new(const char *ptr, long len) - rb_usascii_str_new_cstr(const char *ptr) +rb_usascii_str_new(const char *ptr, long len) :: +rb_usascii_str_new_cstr(const char *ptr) :: - Creates a new Ruby string with encoding US-ASCII. + Creates a new Ruby string with encoding US-ASCII. - rb_str_resize(VALUE str, long len) +rb_str_resize(VALUE str, long len) :: - Resizes Ruby string to len bytes. If str is not modifiable, this - function raises an exception. The length of str must be set in - advance. If len is less than the old length the content beyond - len bytes is discarded, else if len is greater than the old length - the content beyond the old length bytes will not be preserved but - will be garbage. Note that RSTRING_PTR(str) may change by calling - this function. + Resizes Ruby string to len bytes. If str is not modifiable, this + function raises an exception. The length of str must be set in + advance. If len is less than the old length the content beyond + len bytes is discarded, else if len is greater than the old length + the content beyond the old length bytes will not be preserved but + will be garbage. Note that RSTRING_PTR(str) may change by calling + this function. - rb_str_set_len(VALUE str, long len) +rb_str_set_len(VALUE str, long len) :: - Sets the length of Ruby string. If str is not modifiable, this - function raises an exception. This function preserves the content - upto len bytes, regardless RSTRING_LEN(str). len must not exceed - the capacity of str. + Sets the length of Ruby string. If str is not modifiable, this + function raises an exception. This function preserves the content + upto len bytes, regardless RSTRING_LEN(str). len must not exceed + the capacity of str. - Array functions +=== Array Functions - rb_ary_new() +rb_ary_new() :: - Creates an array with no elements. + Creates an array with no elements. - rb_ary_new2(long len) +rb_ary_new2(long len) :: - Creates an array with no elements, allocating internal buffer - for len elements. + Creates an array with no elements, allocating internal buffer + for len elements. - rb_ary_new3(long n, ...) +rb_ary_new3(long n, ...) :: - Creates an n-element array from the arguments. + Creates an n-element array from the arguments. - rb_ary_new4(long n, VALUE *elts) +rb_ary_new4(long n, VALUE *elts) :: - Creates an n-element array from a C array. + Creates an n-element array from a C array. - rb_ary_to_ary(VALUE obj) +rb_ary_to_ary(VALUE obj) :: - Converts the object into an array. - Equivalent to Object#to_ary. + Converts the object into an array. + Equivalent to Object#to_ary. - There are many functions to operate an array. - They may dump core if other types are given. +There are many functions to operate an array. They may dump core if other +types are given. - rb_ary_aref(argc, VALUE *argv, VALUE ary) +rb_ary_aref(argc, VALUE *argv, VALUE ary) :: - Equivaelent to Array#[]. + Equivaelent to Array#[]. - rb_ary_entry(VALUE ary, long offset) +rb_ary_entry(VALUE ary, long offset) :: - ary[offset] + ary[offset] - rb_ary_subseq(VALUE ary, long beg, long len) +rb_ary_subseq(VALUE ary, long beg, long len) :: - ary[beg, len] + ary[beg, len] - rb_ary_push(VALUE ary, VALUE val) - rb_ary_pop(VALUE ary) - rb_ary_shift(VALUE ary) - rb_ary_unshift(VALUE ary, VALUE val) +rb_ary_push(VALUE ary, VALUE val) :: +rb_ary_pop(VALUE ary) :: +rb_ary_shift(VALUE ary) :: +rb_ary_unshift(VALUE ary, VALUE val) :: - rb_ary_cat(VALUE ary, const VALUE *ptr, long len) +rb_ary_cat(VALUE ary, const VALUE *ptr, long len) :: - Appends len elements of objects from ptr to the array. + Appends len elements of objects from ptr to the array. -2. Extending Ruby with C += Extending Ruby with C -2.1 Adding new features to Ruby +== Adding New Features to Ruby You can add new features (classes, methods, etc.) to the Ruby interpreter. Ruby provides APIs for defining the following things: - * Classes, Modules - * Methods, Singleton Methods - * Constants +* Classes, Modules +* Methods, Singleton Methods +* Constants -2.1.1 Class/module definition +=== Class and Module Definition To define a class or module, use the functions below: @@ -314,7 +313,7 @@ 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 +=== Method and Singleton Method Definition To define methods or singleton methods, use these functions: @@ -346,7 +345,7 @@ actual arguments. There are some more functions to define methods. One takes an ID -as the name of method to be defined. See 2.2.2 for IDs. +as the name of method to be defined. See also ID or Symbol below. void rb_define_method_id(VALUE klass, ID name, VALUE (*func)(ANYARGS), int argc) @@ -397,7 +396,7 @@ allocated instance. This instance should be as empty as possible, without any expensive (including external) resources. -2.1.3 Constant definition +=== Constant Definition We have 2 functions to define constants: @@ -407,11 +406,11 @@ The former is to define a constant under specified class/module. The latter is to define a global constant. -2.2 Use Ruby features from C +== Use Ruby Features from C There are several ways to invoke Ruby's features from C code. -2.2.1 Evaluate Ruby Programs in a String +=== Evaluate Ruby Programs in a String The easiest way to use Ruby's functionality from a C program is to evaluate the string as Ruby program. This function will do the job: @@ -429,19 +428,20 @@ It returns nil when an error occur. Moreover, *state is zero if str was successfully evaluated, or nonzero otherwise. +=== ID or Symbol -2.2.2 ID or Symbol - You can invoke methods directly, without parsing the string. First I need to explain about ID. ID is the integer number to represent Ruby's identifiers such as variable names. The Ruby data type corresponding to ID is Symbol. It can be accessed from Ruby in the form: - :Identifier + :Identifier + or - :"any kind of string" + :"any kind of string" + You can get the ID value from a string within C code by using rb_intern(const char *name) @@ -469,7 +469,7 @@ ID SYM2ID(VALUE symbol) -2.2.3 Invoke Ruby method from C +=== Invoke Ruby Method from C To invoke methods directly, you can use the function below @@ -478,7 +478,7 @@ This function invokes a method on the recv, with the method name specified by the symbol mid. -2.2.4 Accessing the variables and constants +=== Accessing the Variables and Constants You can access class variables and instance variables using access functions. Also, global variables can be shared between both @@ -495,11 +495,11 @@ VALUE rb_const_get(VALUE obj, ID id) -See 2.1.3 for defining new constant. +See also Constant Definition above. -3. Information sharing between Ruby and C += Information Sharing Between Ruby and C -3.1 Ruby constants that C can be accessed from C +=== Ruby Constants That C Can Be Accessed From C As stated in section 1.3, the following Ruby constants can be referred from C. @@ -513,7 +513,7 @@ Ruby nil in C scope. -3.2 Global variables shared between C and Ruby +== Global Variables Shared Between C and Ruby Information can be shared between the two environments using shared global variables. To define them, you can use functions listed below: @@ -557,7 +557,7 @@ void (*setter)(VALUE val, ID id); -3.3 Encapsulate C data into a Ruby object +== Encapsulate C Data into a Ruby Object To wrap and objectify a C pointer as a Ruby object (so called DATA), use Data_Wrap_Struct(). @@ -597,23 +597,23 @@ See the example below for details. -4. Example - Creating dbm extension += Example - Creating dbm Extension OK, here's the example of making an extension library. This is the extension to access DBMs. The full source is included in the ext/ directory in the Ruby's source tree. -(1) make the directory +== Make the Directory % mkdir ext/dbm Make a directory for the extension library under ext directory. -(2) design the library +== Design the Library You need to design the library features, before making it. -(3) write C code. +== Write the C Code You need to write C code for your extension library. If your library has only one source file, choosing ``LIBRARY.c'' as a file name is @@ -630,54 +630,48 @@ Here's the example of an initializing function. --- -void -Init_dbm(void) -{ - /* define DBM class */ - cDBM = rb_define_class("DBM", rb_cObject); - /* DBM includes Enumerate module */ - rb_include_module(cDBM, rb_mEnumerable); + void + Init_dbm(void) + { + /* define DBM class */ + cDBM = rb_define_class("DBM", rb_cObject); + /* DBM includes Enumerate module */ + rb_include_module(cDBM, rb_mEnumerable); - /* DBM has class method open(): arguments are received as C array */ - rb_define_singleton_method(cDBM, "open", fdbm_s_open, -1); + /* DBM has class method open(): arguments are received as C array */ + rb_define_singleton_method(cDBM, "open", fdbm_s_open, -1); - /* DBM instance method close(): no args */ - rb_define_method(cDBM, "close", fdbm_close, 0); - /* DBM instance method []: 1 argument */ - rb_define_method(cDBM, "[]", fdbm_fetch, 1); - : + /* DBM instance method close(): no args */ + rb_define_method(cDBM, "close", fdbm_close, 0); + /* DBM instance method []: 1 argument */ + rb_define_method(cDBM, "[]", fdbm_fetch, 1); - /* ID for a instance variable to store DBM data */ - id_dbm = rb_intern("dbm"); -} --- + /* ... */ + /* ID for a instance variable to store DBM data */ + id_dbm = rb_intern("dbm"); + } + The dbm extension wraps the dbm struct in the C environment using Data_Make_Struct. --- -struct dbmdata { - int di_size; - DBM *di_dbm; -}; + struct dbmdata { + int di_size; + DBM *di_dbm; + }; + obj = Data_Make_Struct(klass, struct dbmdata, 0, free_dbm, dbmp); -obj = Data_Make_Struct(klass, struct dbmdata, 0, free_dbm, dbmp); --- - This code wraps the dbmdata structure into a Ruby object. We avoid wrapping DBM* directly, because we want to cache size information. To retrieve the dbmdata structure from a Ruby object, we define the following macro: --- -#define GetDBM(obj, dbmp) {\ - Data_Get_Struct(obj, struct dbmdata, dbmp);\ - if (dbmp->di_dbm == 0) closed_dbm();\ -} --- + #define GetDBM(obj, dbmp) {\ + Data_Get_Struct(obj, struct dbmdata, dbmp);\ + if (dbmp->di_dbm == 0) closed_dbm();\ + } This sort of complicated macro does the retrieving and close checking for the DBM. @@ -685,13 +679,11 @@ There are three kinds of way to receive method arguments. First, methods with a fixed number of arguments receive arguments like this: --- -static VALUE -fdbm_delete(VALUE obj, VALUE keystr) -{ - : -} --- + static VALUE + fdbm_delete(VALUE obj, VALUE keystr) + { + /* ... */ + } The first argument of the C function is the self, the rest are the arguments to the method. @@ -699,17 +691,15 @@ Second, methods with an arbitrary number of arguments receive arguments like this: --- -static VALUE -fdbm_s_open(int argc, VALUE *argv, VALUE klass) -{ - : - if (rb_scan_args(argc, argv, "11", &file, &vmode) == 1) { - mode = 0666; /* default value */ - } - : -} --- + static VALUE + fdbm_s_open(int argc, VALUE *argv, VALUE klass) + { + /* ... */ + if (rb_scan_args(argc, argv, "11", &file, &vmode) == 1) { + mode = 0666; /* default value */ + } + /* ... */ + } The first argument is the number of method arguments, the second argument is the C array of the method arguments, and the third @@ -724,25 +714,21 @@ The following is an example of a method that takes arguments by Ruby's array: --- -static VALUE -thread_initialize(VALUE thread, VALUE args) -{ - : -} --- + static VALUE + thread_initialize(VALUE thread, VALUE args) + { + /* ... */ + } The first argument is the receiver, the second one is the Ruby array which contains the arguments to the method. -** Notice +*Notice*: GC should know about global variables which refer to Ruby's objects, +but are not exported to the Ruby world. You need to protect them by -GC should know about global variables which refer to Ruby's objects, but -are not exported to the Ruby world. You need to protect them by - void rb_global_variable(VALUE *var) -(4) prepare extconf.rb +== Prepare extconf.rb If the file named extconf.rb exists, it will be executed to generate Makefile. @@ -791,7 +777,7 @@ ``create_makefile''. The Makefile will not be generated, compilation will not be done. -(5) prepare depend (optional) +== Prepare Depend (Optional) If the file named depend exists, Makefile will include that file to check dependencies. You can make this file by invoking @@ -800,7 +786,7 @@ It's harmless. Prepare it. -(6) generate Makefile +== Generate Makef (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/