1: .\" README.EXT -  -*- Text -*- created at: Mon Aug  7 16:45:54 JST 1995
    2: 
    3: This document explains how to make extension libraries for Ruby.
    4: 
    5: 1. Basic knowledge
    6: 
    7: In C, variables have types and data do not have types.  In contrast,
    8: Ruby variables do not have a static type, and data themselves have
    9: types, so data will need to be converted between the languages.
   10: 
   11: Data in Ruby are represented by the C type `VALUE'.  Each VALUE data
   12: has its data-type.
   13: 
   14: To retrieve C data from a VALUE, you need to:
   15: 
   16:  (1) Identify the VALUE's data type
   17:  (2) Convert the VALUE into C data
   18: 
   19: Converting to the wrong data type may cause serious problems.
   20: 
   21: 
   22: 1.1 Data-types
   23: 
   24: The Ruby interpreter has the following data types:
   25: 
   26:         T_NIL          nil
   27:         T_OBJECT       ordinary object
   28:         T_CLASS                class
   29:         T_MODULE       module
   30:         T_FLOAT                floating point number
   31:         T_STRING       string
   32:         T_REGEXP       regular expression
   33:         T_ARRAY                array
   34:         T_FIXNUM       Fixnum(31bit integer)
   35:         T_HASH         associative array
   36:         T_STRUCT       (Ruby) structure
   37:         T_BIGNUM       multi precision integer
   38:         T_FILE         IO
   39:         T_TRUE         true
   40:         T_FALSE                false
   41:         T_DATA         data
   42:         T_SYMBOL        symbol
   43: 
   44: In addition, there are several other types used internally:
   45: 
   46:         T_ICLASS
   47:         T_MATCH
   48:         T_UNDEF
   49:         T_VARMAP
   50:         T_SCOPE
   51:         T_NODE
   52: 
   53: Most of the types are represented by C structures.
   54: 
   55: 1.2 Check Data Type of the VALUE
   56: 
   57: The macro TYPE() defined in ruby.h shows the data type of the VALUE.
   58: TYPE() returns the constant number T_XXXX described above.  To handle
   59: data types, your code will look something like this:
   60: 
   61:   switch (TYPE(obj)) {
   62:     case T_FIXNUM:
   63:       /* process Fixnum */
   64:       break;
   65:     case T_STRING:
   66:       /* process String */
   67:       break;
   68:     case T_ARRAY:
   69:       /* process Array */
   70:       break;
   71:     default:
   72:       /* raise exception */
   73:       rb_raise(rb_eTypeError, "not valid value");
   74:       break;
   75:   }
   76: 
   77: There is the data-type check function
   78: 
   79:   void Check_Type(VALUE value, int type)
   80: 
   81: which raises an exception if the VALUE does not have the type
   82: specified.
   83: 
   84: There are also faster check macros for fixnums and nil.
   85: 
   86:   FIXNUM_P(obj)
   87:   NIL_P(obj)
   88: 
   89: 1.3 Convert VALUE into C data
   90: 
   91: The data for type T_NIL, T_FALSE, T_TRUE are nil, true, false
   92: respectively.  They are singletons for the data type.
   93: 
   94: The T_FIXNUM data is a 31bit length fixed integer (63bit length on
   95: some machines), which can be converted to a C integer by using the
   96: FIX2INT() macro.  There is also NUM2INT() which converts any Ruby
   97: numbers into C integers.  The NUM2INT() macro includes a type check,
   98: so an exception will be raised if the conversion failed.  NUM2DBL()
   99: can be used to retrieve the double float value in the same way.
  100: 
  101: In version 1.7 or later it is recommended that you use the new macros
  102: StringValue() and StringValuePtr() to get a char* from a VALUE.
  103: StringValue(var) replaces var's value with the result of "var.to_str()".
  104: StringValuePtr(var) does same replacement and returns char*
  105: representation of var.  These macros will skip the replacement if var
  106: is a String.  Notice that the macros take only the lvalue as their
  107: argument, to change the value of var in place.
  108: 
  109: In version 1.6 or earlier, STR2CSTR() was used to do the same thing
  110: but now it is deprecated in version 1.7, because STR2CSTR() has a risk
  111: of a dangling pointer problem in the to_str() implicit conversion.
  112: 
  113: Other data types have corresponding C structures, e.g. struct RArray
  114: for T_ARRAY etc. The VALUE of the type which has the corresponding
  115: structure can be cast to retrieve the pointer to the struct.  The
  116: casting macro will be of the form RXXXX for each data type; for
  117: instance, RARRAY(obj).  See "ruby.h".
  118: 
  119: There are some accessing macros for structure members, for example
  120: `RSTRING_LEN(s)' to to get the size of the Ruby String object.  The
  121: allocated region can be accessed by `RSTRING_PTR(str).  For arrays, use
  122: `RARRAY_LEN(ary) and `RARRAY_PTR(ary) respectively.
  123: 
  124: Notice: Do not change the value of the structure directly, unless you
  125: are responsible for the result.  This ends up being the cause of
  126: interesting bugs.
  127: 
  128: 1.4 Convert C data into VALUE
  129: 
  130: To convert C data to Ruby values:
  131: 
  132:   * FIXNUM
  133: 
  134:     left shift 1 bit, and turn on LSB.
  135: 
  136:   * Other pointer values
  137: 
  138:     cast to VALUE.
  139: 
  140: You can determine whether a VALUE is pointer or not by checking its LSB.  
  141: 
  142: Notice Ruby does not allow arbitrary pointer values to be a VALUE.  They
  143: should be pointers to the structures which Ruby knows about.  The known
  144: structures are defined in <ruby.h>.
  145: 
  146: To convert C numbers to Ruby values, use these macros.
  147: 
  148:   INT2FIX()     for integers within 31bits.
  149:   INT2NUM()     for arbitrary sized integer.
  150: 
  151: INT2NUM() converts an integer into a Bignum if it is out of the FIXNUM
  152: range, but is a bit slower.
  153: 
  154: 1.5 Manipulating Ruby data
  155: 
  156: As I already mentioned, it is not recommended to modify an object's
  157: internal structure.  To manipulate objects, use the functions supplied
  158: by the Ruby interpreter. Some (not all) of the useful functions are
  159: listed below:
  160: 
  161:  String functions
  162: 
  163:   rb_str_new(const char *ptr, long len)
  164: 
  165:     Creates a new Ruby string.
  166: 
  167:   rb_str_new2(const char *ptr)
  168: 
  169:     Creates a new Ruby string from a C string.  This is equivalent to
  170:     rb_str_new(ptr, strlen(ptr)).
  171: 
  172:   rb_tainted_str_new(const char *ptr, long len)
  173: 
  174:     Creates a new tainted Ruby string.  Strings from external data
  175:     sources should be tainted.
  176: 
  177:   rb_tainted_str_new2(const char *ptr)
  178: 
  179:     Creates a new tainted Ruby string from a C string.
  180: 
  181:   rb_str_cat(VALUE str, const char *ptr, long len)
  182: 
  183:     Appends len bytes of data from ptr to the Ruby string.
  184: 
  185:  Array functions
  186: 
  187:   rb_ary_new()
  188: 
  189:     Creates an array with no elements.
  190: 
  191:   rb_ary_new2(long len)
  192: 
  193:     Creates an array with no elements, allocating internal buffer
  194:     for len elements.
  195: 
  196:   rb_ary_new3(long n, ...)
  197: 
  198:     Creates an n-element array from the arguments.
  199: 
  200:   rb_ary_new4(long n, VALUE *elts)
  201: 
  202:     Creates an n-element array from a C array.
  203: 
  204:   rb_ary_push(VALUE ary, VALUE val)
  205:   rb_ary_pop(VALUE ary)
  206:   rb_ary_shift(VALUE ary)
  207:   rb_ary_unshift(VALUE ary, VALUE val)
  208: 
  209:     Array operations.  The first argument to each functions must be an 
  210:     array.  They may dump core if other types are given.
  211: 
  212: 2. Extending Ruby with C
  213: 
  214: 2.1 Adding new features to Ruby
  215: 
  216: You can add new features (classes, methods, etc.) to the Ruby
  217: interpreter.  Ruby provides APIs for defining the following things:
  218: 
  219:  * Classes, Modules
  220:  * Methods, Singleton Methods
  221:  * Constants
  222: 
  223: 2.1.1 Class/module definition
  224: 
  225: To define a class or module, use the functions below:
  226: 
  227:   VALUE rb_define_class(const char *name, VALUE super)
  228:   VALUE rb_define_module(const char *name)
  229: 
  230: These functions return the newly created class or module.  You may
  231: want to save this reference into a variable to use later.
  232: 
  233: To define nested classes or modules, use the functions below:
  234: 
  235:   VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)
  236:   VALUE rb_define_module_under(VALUE outer, const char *name)
  237: 
  238: 2.1.2 Method/singleton method definition
  239: 
  240: To define methods or singleton methods, use these functions:
  241: 
  242:   void rb_define_method(VALUE klass, const char *name, 
  243:                         VALUE (*func)(), int argc)
  244: 
  245:   void rb_define_singleton_method(VALUE object, const char *name, 
  246:                                   VALUE (*func)(), int argc)
  247: 
  248: The `argc' represents the number of the arguments to the C function,
  249: which must be less than 17.  But I doubt you'll need that many.
  250: 
  251: If `argc' is negative, it specifies the calling sequence, not number of
  252: the arguments.  
  253: 
  254: If argc is -1, the function will be called as:
  255: 
  256:   VALUE func(int argc, VALUE *argv, VALUE obj)
  257: 
  258: where argc is the actual number of arguments, argv is the C array of
  259: the arguments, and obj is the receiver.
  260: 
  261: If argc is -2, the arguments are passed in a Ruby array. The function
  262: will be called like:
  263: 
  264:   VALUE func(VALUE obj, VALUE args)
  265: 
  266: where obj is the receiver, and args is the Ruby array containing
  267: actual arguments.
  268: 
  269: There are two more functions to define methods.  One is to define
  270: private methods:
  271: 
  272:   void rb_define_private_method(VALUE klass, const char *name, 
  273:                                 VALUE (*func)(), int argc)
  274: 
  275: The other is to define module functions, which are private AND singleton
  276: methods of the module.  For example, sqrt is the module function
  277: defined in Math module.  It can be called in the following way:
  278: 
  279:   Math.sqrt(4)
  280: 
  281: or
  282: 
  283:   include Math
  284:   sqrt(4)
  285: 
  286: To define module functions, use:
  287: 
  288:   void rb_define_module_function(VALUE module, const char *name, 
  289:                                  VALUE (*func)(), int argc)
  290: 
  291: Oh, in addition, function-like methods, which are private methods defined
  292: in the Kernel module, can be defined using:
  293: 
  294:   void rb_define_global_function(const char *name, VALUE (*func)(), int argc)
  295: 
  296: To define an alias for the method,
  297: 
  298:   void rb_define_alias(VALUE module, const char* new, const char* old);
  299: 
  300: To define and undefine the `allocate' class method,
  301: 
  302:   void rb_define_alloc_func(VALUE klass, VALUE (*func)(VALUE klass));
  303:   void rb_undef_alloc_func(VALUE klass);
  304: 
  305: func have to take the klass as the argument and return a newly
  306: allocated instance.  This instance should be empty as possible,
  307: without any expensive (including external) resources.
  308: 
  309: 2.1.3 Constant definition
  310: 
  311: We have 2 functions to define constants:
  312: 
  313:   void rb_define_const(VALUE klass, const char *name, VALUE val)
  314:   void rb_define_global_const(const char *name, VALUE val)
  315: 
  316: The former is to define a constant under specified class/module.  The
  317: latter is to define a global constant.
  318: 
  319: 2.2 Use Ruby features from C
  320: 
  321: There are several ways to invoke Ruby's features from C code.
  322: 
  323: 2.2.1 Evaluate Ruby Programs in a String
  324: 
  325: The easiest way to use Ruby's functionality from a C program is to
  326: evaluate the string as Ruby program.  This function will do the job:
  327: 
  328:   VALUE rb_eval_string(const char *str)
  329: 
  330: Evaluation is done under the current context, thus current local variables
  331: of the innermost method (which is defined by Ruby) can be accessed.
  332: 
  333: 2.2.2 ID or Symbol
  334: 
  335: You can invoke methods directly, without parsing the string.  First I
  336: need to explain about ID.  ID is the integer number to represent
  337: Ruby's identifiers such as variable names.  The Ruby data type
  338: corresponding to ID is Symbol.  It can be accessed from Ruby in the
  339: form:
  340: 
  341:  :Identifier
  342: 
  343: You can get the ID value from a string within C code by using
  344: 
  345:   rb_intern(const char *name)
  346: 
  347: You can retrieve ID from Ruby object (Symbol or String) given as an
  348: argument by using
  349: 
  350:   rb_to_id(VALUE symbol)
  351: 
  352: You can convert C ID to Ruby Symbol by using
  353: 
  354:   VALUE ID2SYM(ID id)
  355: 
  356: and to convert Ruby Symbol object to ID, use
  357: 
  358:   ID SYM2ID(VALUE symbol)
  359: 
  360: 2.2.3 Invoke Ruby method from C
  361: 
  362: To invoke methods directly, you can use the function below
  363: 
  364:   VALUE rb_funcall(VALUE recv, ID mid, int argc, ...)
  365: 
  366: This function invokes a method on the recv, with the method name
  367: specified by the symbol mid.
  368: 
  369: 2.2.4 Accessing the variables and constants
  370: 
  371: You can access class variables and instance variables using access
  372: functions.  Also, global variables can be shared between both
  373: environments.  There's no way to access Ruby's local variables.
  374: 
  375: The functions to access/modify instance variables are below:
  376: 
  377:   VALUE rb_ivar_get(VALUE obj, ID id)
  378:   VALUE rb_ivar_set(VALUE obj, ID id, VALUE val)
  379: 
  380: id must be the symbol, which can be retrieved by rb_intern().
  381: 
  382: To access the constants of the class/module:
  383: 
  384:   VALUE rb_const_get(VALUE obj, ID id)
  385: 
  386: See 2.1.3 for defining new constant.
  387: 
  388: 3. Information sharing between Ruby and C
  389: 
  390: 3.1 Ruby constants that C can be accessed from C
  391: 
  392: The following Ruby constants can be referred from C.
  393: 
  394:   Qtrue
  395:   Qfalse
  396: 
  397: Boolean values.  Qfalse is false in C also (i.e. 0).
  398: 
  399:   Qnil
  400: 
  401: Ruby nil in C scope.
  402: 
  403: 3.2 Global variables shared between C and Ruby
  404: 
  405: Information can be shared between the two environments using shared global
  406: variables.  To define them, you can use functions listed below:
  407: 
  408:   void rb_define_variable(const char *name, VALUE *var)
  409: 
  410: This function defines the variable which is shared by both environments.
  411: The value of the global variable pointed to by `var' can be accessed
  412: through Ruby's global variable named `name'.
  413: 
  414: You can define read-only (from Ruby, of course) variables using the
  415: function below.
  416: 
  417:   void rb_define_readonly_variable(const char *name, VALUE *var)
  418: 
  419: You can defined hooked variables.  The accessor functions (getter and
  420: setter) are called on access to the hooked variables.
  421: 
  422:   void rb_define_hooked_variable(constchar *name, VALUE *var,
  423:                                  VALUE (*getter)(), void (*setter)())
  424: 
  425: If you need to supply either setter or getter, just supply 0 for the
  426: hook you don't need.  If both hooks are 0, rb_define_hooked_variable()
  427: works just like rb_define_variable().
  428: 
  429:   void rb_define_virtual_variable(const char *name,
  430:                                   VALUE (*getter)(), void (*setter)())
  431: 
  432: This function defines a Ruby global variable without a corresponding C
  433: variable.  The value of the variable will be set/get only by hooks.
  434: 
  435: The prototypes of the getter and setter functions are as follows:
  436: 
  437:   (*getter)(ID id, void *data, struct global_entry* entry);
  438:   (*setter)(VALUE val, ID id, void *data, struct global_entry* entry);
  439: 
  440: 3.3 Encapsulate C data into a Ruby object
  441: 
  442: To wrap and objectify a C pointer as a Ruby object (so called
  443: DATA), use Data_Wrap_Struct().
  444: 
  445:   Data_Wrap_Struct(klass, mark, free, ptr)
  446: 
  447: Data_Wrap_Struct() returns a created DATA object.  The klass argument
  448: is the class for the DATA object.  The mark argument is the function
  449: to mark Ruby objects pointed by this data.  The free argument is the
  450: function to free the pointer allocation.  If this is -1, the pointer
  451: will be just freed.  The functions mark and free will be called from
  452: garbage collector.
  453: 
  454: You can allocate and wrap the structure in one step.
  455: 
  456:   Data_Make_Struct(klass, type, mark, free, sval)
  457: 
  458: This macro returns an allocated Data object, wrapping the pointer to
  459: the structure, which is also allocated.  This macro works like:
  460: 
  461:   (sval = ALLOC(type), Data_Wrap_Struct(klass, mark, free, sval))
  462: 
  463: Arguments klass, mark, and free work like their counterparts in
  464: Data_Wrap_Struct().  A pointer to the allocated structure will be
  465: assigned to sval, which should be a pointer of the type specified.
  466: 
  467: To retrieve the C pointer from the Data object, use the macro
  468: Data_Get_Struct().
  469: 
  470:   Data_Get_Struct(obj, type, sval)
  471: 
  472: A pointer to the structure will be assigned to the variable sval.
  473: 
  474: See the example below for details. 
  475: 
  476: 4. Example - Creating dbm extension
  477: 
  478: OK, here's the example of making an extension library.  This is the
  479: extension to access DBMs.  The full source is included in the ext/
  480: directory in the Ruby's source tree.
  481: 
  482: (1) make the directory
  483: 
  484:   % mkdir ext/dbm
  485: 
  486: Make a directory for the extension library under ext directory.
  487: 
  488: (2) design the library
  489: 
  490: You need to design the library features, before making it.
  491: 
  492: (3) write C code.
  493: 
  494: You need to write C code for your extension library.  If your library
  495: has only one source file, choosing ``LIBRARY.c'' as a file name is
  496: preferred.  On the other hand, in case your library has multiple source
  497: files, avoid choosing ``LIBRARY.c'' for a file name.  It may conflict
  498: with an intermediate file ``LIBRARY.o'' on some platforms.
  499: 
  500: Ruby will execute the initializing function named ``Init_LIBRARY'' in
  501: the library.  For example, ``Init_dbm()'' will be executed when loading
  502: the library.
  503: 
  504: Here's the example of an initializing function.
  505: 
  506: --
  507: void
  508: Init_dbm(void)
  509: {
  510:     /* define DBM class */
  511:     cDBM = rb_define_class("DBM", rb_cObject);
  512:     /* DBM includes Enumerate module */
  513:     rb_include_module(cDBM, rb_mEnumerable);
  514: 
  515:     /* DBM has class method open(): arguments are received as C array */
  516:     rb_define_singleton_method(cDBM, "open", fdbm_s_open, -1);
  517: 
  518:     /* DBM instance method close(): no args */
  519:     rb_define_method(cDBM, "close", fdbm_close, 0);
  520:     /* DBM instance method []: 1 argument */
  521:     rb_define_method(cDBM, "[]", fdbm_fetch, 1);
  522:                 :
  523: 
  524:     /* ID for a instance variable to store DBM data */
  525:     id_dbm = rb_intern("dbm");
  526: }
  527: --
  528: 
  529: The dbm extension wraps the dbm struct in the C environment using 
  530: Data_Make_Struct.
  531: 
  532: --
  533: struct dbmdata {
  534:     int  di_size;
  535:     DBM *di_dbm;
  536: };
  537: 
  538: 
  539: obj = Data_Make_Struct(klass, struct dbmdata, 0, free_dbm, dbmp);
  540: --
  541: 
  542: This code wraps the dbmdata structure into a Ruby object.  We avoid
  543: wrapping DBM* directly, because we want to cache size information.
  544: 
  545: To retrieve the dbmdata structure from a Ruby object, we define the
  546: following macro:
  547: 
  548: --
  549: #define GetDBM(obj, dbmp) {\
  550:     Data_Get_Struct(obj, struct dbmdata, dbmp);\
  551:     if (dbmp->di_dbm == 0) closed_dbm();\
  552: }
  553: --
  554: 
  555: This sort of complicated macro does the retrieving and close checking for
  556: the DBM.
  557: 
  558: There are three kinds of way to receive method arguments.  First,
  559: methods with a fixed number of arguments receive arguments like this:
  560: 
  561: --
  562: static VALUE
  563: fdbm_delete(VALUE obj, VALUE keystr)
  564: {
  565:         :
  566: }
  567: --
  568: 
  569: The first argument of the C function is the self, the rest are the
  570: arguments to the method.
  571: 
  572: Second, methods with an arbitrary number of arguments receive
  573: arguments like this:
  574: 
  575: --
  576: static VALUE
  577: fdbm_s_open(int argc, VALUE *argv, VALUE klass)
  578: {
  579:         :
  580:     if (rb_scan_args(argc, argv, "11", &file, &vmode) == 1) {
  581:         mode = 0666;           /* default value */
  582:     }
  583:         :
  584: }
  585: --
  586: 
  587: The first argument is the number of method arguments, the second
  588: argument is the C array of the method arguments, and the third
  589: argument is the receiver of the method.
  590: 
  591: You can use the function rb_scan_args() to check and retrieve the
  592: arguments.  For example, "11" means that the method requires at least one
  593: argument, and at most receives two arguments.
  594: 
  595: Methods with an arbitrary number of arguments can receive arguments
  596: by Ruby's array, like this:
  597: 
  598: --
  599: static VALUE
  600: fdbm_indexes(VALUE obj, VALUE args)
  601: {
  602:         :
  603: }
  604: --
  605: 
  606: The first argument is the receiver, the second one is the Ruby array
  607: which contains the arguments to the method.
  608: 
  609: ** Notice
  610: 
  611: GC should know about global variables which refer to Ruby's objects, but
  612: are not exported to the Ruby world.  You need to protect them by
  613: 
  614:   void rb_global_variable(VALUE *var)
  615: 
  616: (4) prepare extconf.rb
  617: 
  618: If the file named extconf.rb exists, it will be executed to generate
  619: Makefile.
  620: 
  621: extconf.rb is the file for checking compilation conditions etc.  You
  622: need to put
  623: 
  624:   require 'mkmf'
  625: 
  626: at the top of the file.  You can use the functions below to check
  627: various conditions.
  628: 
  629:   have_library(lib, func): check whether library containing function exists.
  630:   have_func(func, header): check whether function exists
  631:   have_header(header): check whether header file exists
  632:   create_makefile(target): generate Makefile
  633: 
  634: The value of the variables below will affect the Makefile.
  635: 
  636:   $CFLAGS: included in CFLAGS make variable (such as -O)
  637:   $CPPFLAGS: included in CPPFLAGS make variable (such as -I, -D)
  638:   $LDFLAGS: included in LDFLAGS make variable (such as -L)
  639:   $objs: list of object file names
  640: 
  641: Normally, the object files list is automatically generated by searching
  642: source files, but you must define them explicitly if any sources will
  643: be generated while building.
  644: 
  645: If a compilation condition is not fulfilled, you should not call
  646: ``create_makefile''.  The Makefile will not be generated, compilation will
  647: not be done.
  648: 
  649: (5) prepare depend (optional)
  650: 
  651: If the file named depend exists, Makefile will include that file to
  652: check dependencies.  You can make this file by invoking
  653: 
  654:   % gcc -MM *.c > depend
  655: 
  656: It's harmless.  Prepare it.
  657: 
  658: (6) generate Makefile
  659: 
  660: Try generating the Makefile by:
  661: 
  662:   ruby extconf.rb
  663: 
  664: If the library should be installed under vendor_ruby directory
  665: instead of site_ruby directory, use --vendor option as follows.
  666: 
  667:   ruby extconf.rb --vendor
  668: 
  669: You don't need this step if you put the extension library under the ext
  670: directory of the ruby source tree.  In that case, compilation of the
  671: interpreter will do this step for you.
  672: 
  673: (7) make
  674: 
  675: Type
  676: 
  677:   make
  678: 
  679: to compile your extension.  You don't need this step either if you have
  680: put the extension library under the ext directory of the ruby source tree.
  681: 
  682: (8) debug
  683: 
  684: You may need to rb_debug the extension.  Extensions can be linked
  685: statically by adding the directory name in the ext/Setup file so that
  686: you can inspect the extension with the debugger.
  687: 
  688: (9) done, now you have the extension library
  689: 
  690: You can do anything you want with your library.  The author of Ruby
  691: will not claim any restrictions on your code depending on the Ruby API.
  692: Feel free to use, modify, distribute or sell your program.
  693: 
  694: Appendix A. Ruby source files overview
  695: 
  696: ruby language core
  697: 
  698:   class.c
  699:   error.c
  700:   eval.c
  701:   gc.c
  702:   object.c
  703:   parse.y
  704:   variable.c
  705: 
  706: utility functions
  707: 
  708:   dln.c
  709:   regex.c
  710:   st.c
  711:   util.c
  712: 
  713: ruby interpreter implementation
  714: 
  715:   dmyext.c
  716:   inits.c
  717:   main.c
  718:   ruby.c
  719:   version.c
  720: 
  721: class library
  722: 
  723:   array.c
  724:   bignum.c
  725:   compar.c
  726:   dir.c
  727:   enum.c
  728:   file.c
  729:   hash.c
  730:   io.c
  731:   marshal.c
  732:   math.c
  733:   numeric.c
  734:   pack.c
  735:   prec.c
  736:   process.c
  737:   random.c
  738:   range.c
  739:   re.c
  740:   signal.c
  741:   sprintf.c
  742:   string.c
  743:   struct.c
  744:   time.c
  745: 
  746: Appendix B. Ruby extension API reference
  747: 
  748: ** Types
  749: 
  750:  VALUE
  751: 
  752: The type for the Ruby object.  Actual structures are defined in ruby.h,
  753: such as struct RString, etc.  To refer the values in structures, use
  754: casting macros like RSTRING(obj).
  755: 
  756: ** Variables and constants
  757: 
  758:  Qnil
  759: 
  760: const: nil object
  761: 
  762:  Qtrue
  763: 
  764: const: true object(default true value)
  765: 
  766:  Qfalse
  767: 
  768: const: false object
  769: 
  770: ** C pointer wrapping
  771: 
  772:  Data_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval)
  773: 
  774: Wrap a C pointer into a Ruby object.  If object has references to other
  775: Ruby objects, they should be marked by using the mark function during
  776: the GC process.  Otherwise, mark should be 0.  When this object is no
  777: longer referred by anywhere, the pointer will be discarded by free
  778: function.
  779: 
  780:  Data_Make_Struct(klass, type, mark, free, sval)
  781: 
  782: This macro allocates memory using malloc(), assigns it to the variable
  783: sval, and returns the DATA encapsulating the pointer to memory region.
  784: 
  785:  Data_Get_Struct(data, type, sval)
  786: 
  787: This macro retrieves the pointer value from DATA, and assigns it to
  788: the variable sval. 
  789: 
  790: ** Checking data types
  791: 
  792: TYPE(value)
  793: FIXNUM_P(value)
  794: NIL_P(value)
  795: void Check_Type(VALUE value, int type)
  796: void Check_SafeStr(VALUE value)
  797: 
  798: ** Data type conversion
  799: 
  800: FIX2INT(value)
  801: INT2FIX(i)
  802: NUM2INT(value)
  803: INT2NUM(i)
  804: NUM2DBL(value)
  805: rb_float_new(f)
  806: StringValue(value)
  807: StringValuePtr(value)
  808: StringValueCStr(value)
  809: rb_str_new2(s)
  810: 
  811: ** defining class/module
  812: 
  813:  VALUE rb_define_class(const char *name, VALUE super)
  814: 
  815: Defines a new Ruby class as a subclass of super.
  816: 
  817:  VALUE rb_define_class_under(VALUE module, const char *name, VALUE super)
  818: 
  819: Creates a new Ruby class as a subclass of super, under the module's
  820: namespace.
  821: 
  822:  VALUE rb_define_module(const char *name)
  823: 
  824: Defines a new Ruby module.
  825: 
  826:  VALUE rb_define_module_under(VALUE module, const char *name)
  827: 
  828: Defines a new Ruby module under the module's namespace.
  829: 
  830:  void rb_include_module(VALUE klass, VALUE module)
  831: 
  832: Includes module into class.  If class already includes it, just
  833: ignored.
  834: 
  835:  void rb_extend_object(VALUE object, VALUE module)
  836: 
  837: Extend the object with the module's attributes.
  838: 
  839: ** Defining Global Variables
  840: 
  841:  void rb_define_variable(const char *name, VALUE *var)
  842: 
  843: Defines a global variable which is shared between C and Ruby.  If name
  844: contains a character which is not allowed to be part of the symbol,
  845: it can't be seen from Ruby programs.
  846: 
  847: