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