<?xml version="1.0" encoding="EUC-JP" ?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>ruby-src:README.EXT</title>
<meta http-equiv="Content-type" content="text/html; charset=EUC-JP" />
<link href="default.css" type="text/css" rel="stylesheet" />
<link href="refm475.html" rel="next" />
<link href="refm473.html" rel="prev" />
<link href="index.html" rel="start" />
</head>
<body>
<div class="navigator"><span class="navigator">[<a href="index.html">MAIN</a>][<a href="refm482.html">INDEX</a>][<a href="refm483.html">KEYWORD</a>][<a href="refm594.html">METHOD</a>(<a href="refm633.html">NC</a>)] [<a href="index.html">TOP</a>][<a href="index.html">UP</a>][<a href="refm473.html"><-PREV</a>][<a href="refm475.html">NEXT-></a>]</span></div>
<hr />
<h1>ruby-src:README.EXT</h1>
.\" README.EXT - -*- Text -*- created at: Mon Aug 7 16:45:54 JST 1995<br />
<br />
This document explains how to make extension libraries for Ruby.<br />
<br />
1. Basic knowledge<br />
<br />
In C, variables have types and data do not have types. In contrast,<br />
Ruby variables do not have a static type, and data themselves have<br />
types, so data will need to be converted between the languages.<br />
<br />
Data in Ruby are represented by C type `VALUE'. Each VALUE data has<br />
its data-type.<br />
<br />
To retrieve C data from a VALUE, you need to:<br />
<br />
(1) Identify the VALUE's data type<br />
(2) Convert the VALUE into C data<br />
<br />
Converting to the wrong data type may cause serious problems.<br />
<br />
<br />
1.1 Data-types<br />
<br />
The Ruby interpreter has the following data types:<br />
<br />
T_NIL nil<br />
T_OBJECT ordinary object<br />
T_CLASS class<br />
T_MODULE module<br />
T_FLOAT floating point number<br />
T_STRING string<br />
T_REGEXP regular expression<br />
T_ARRAY array<br />
T_FIXNUM Fixnum(31bit integer)<br />
T_HASH associative array<br />
T_STRUCT (Ruby) structure<br />
T_BIGNUM multi precision integer<br />
T_FILE IO<br />
T_TRUE true<br />
T_FALSE false<br />
T_DATA data<br />
T_SYMBOL symbol<br />
<br />
In addition, there are several other types used internally:<br />
<br />
T_ICLASS<br />
T_MATCH<br />
T_UNDEF<br />
T_VARMAP<br />
T_SCOPE<br />
T_NODE<br />
<br />
Most of the types are represented by C structures.<br />
<br />
1.2 Check Data Type of the VALUE<br />
<br />
The macro TYPE() defined in ruby.h shows the data type of the VALUE.<br />
TYPE() returns the constant number T_XXXX described above. To handle<br />
data types, your code will look something like this:<br />
<br />
switch (TYPE(obj)) {<br />
case T_FIXNUM:<br />
/* process Fixnum */<br />
break;<br />
case T_STRING:<br />
/* process String */<br />
break;<br />
case T_ARRAY:<br />
/* process Array */<br />
break;<br />
default:<br />
/* raise exception */<br />
rb_raise(rb_eTypeError, "not valid value");<br />
break;<br />
}<br />
<br />
There is the data-type check function<br />
<br />
void Check_Type(VALUE value, int type)<br />
<br />
which raises an exception if the VALUE does not have the type specified.<br />
<br />
There are also faster check macros for fixnums and nil.<br />
<br />
FIXNUM_P(obj)<br />
NIL_P(obj)<br />
<br />
1.3 Convert VALUE into C data<br />
<br />
The data for type T_NIL, T_FALSE, T_TRUE are nil, true, false<br />
respectively. They are singletons for the data type.<br />
<br />
The T_FIXNUM data is a 31bit length fixed integer (63bit length on<br />
some machines), which can be convert to a C integer by using the<br />
FIX2INT() macro. There is also NUM2INT() which converts any Ruby<br />
numbers into C integers. The NUM2INT() macro includes a type check, so<br />
an exception will be raised if the conversion failed. NUM2DBL() can<br />
be used to retrieve the double float value in same way.<br />
<br />
To get char* from a VALUE, version 1.7 recommend to use new macros<br />
StringValue() and StringValuePtr(). StringValue(var) replaces var's<br />
value to the result of "var.to_str()". StringValuePtr(var) does same<br />
replacement and returns char* representation of var. These macros<br />
will skip the replacement if var is a String. Notice that the macros<br />
requires to take only lvalue as their argument, to change the value<br />
of var in the replacement. <br />
<br />
In version 1.6 or earlier, STR2CSTR() was used to do same thing<br />
but now it is obsoleted in version 1.7 because of STR2CSTR() has<br />
a risk of dangling pointer problem in to_str() impliclit conversion.<br />
<br />
Other data types have corresponding C structures, e.g. struct RArray<br />
for T_ARRAY etc. The VALUE of the type which has corresponding structure<br />
can be cast to retrieve the pointer to the struct. The casting macro<br />
will be of the form RXXXX for each data type; for instance, RARRAY(obj). <br />
See "ruby.h".<br />
<br />
For example, `RSTRING(str)->len' is the way to get the size of the<br />
Ruby String object. The allocated region can be accessed by<br />
`RSTRING(str)->ptr'. For arrays, use `RARRAY(ary)->len' and<br />
`RARRAY(ary)->ptr' respectively.<br />
<br />
Notice: Do not change the value of the structure directly, unless you<br />
are responsible for the result. This ends up being the cause of interesting<br />
bugs.<br />
<br />
1.4 Convert C data into VALUE<br />
<br />
To convert C data to Ruby values:<br />
<br />
* FIXNUM<br />
<br />
left shift 1 bit, and turn on LSB.<br />
<br />
* Other pointer values<br />
<br />
cast to VALUE.<br />
<br />
You can determine whether a VALUE is pointer or not by checking its LSB. <br />
<br />
Notice Ruby does not allow arbitrary pointer values to be a VALUE. They<br />
should be pointers to the structures which Ruby knows about. The known<br />
structures are defined in <ruby.h>.<br />
<br />
To convert C numbers to Ruby values, use these macros.<br />
<br />
INT2FIX() for integers within 31bits.<br />
INT2NUM() for arbitrary sized integer.<br />
<br />
INT2NUM() converts an integer into a Bignum if it is out of the FIXNUM<br />
range, but is a bit slower.<br />
<br />
1.5 Manipulating Ruby data<br />
<br />
As I already mentioned, it is not recommended to modify an object's internal<br />
structure. To manipulate objects, use the functions supplied by the Ruby<br />
interpreter. Some (not all) of the useful functions are listed below:<br />
<br />
String functions<br />
<br />
rb_str_new(const char *ptr, long len)<br />
<br />
Creates a new Ruby string.<br />
<br />
rb_str_new2(const char *ptr)<br />
<br />
Creates a new Ruby string from a C string. This is equivalent to<br />
rb_str_new(ptr, strlen(ptr)).<br />
<br />
rb_tainted_str_new(const char *ptr, long len)<br />
<br />
Creates a new tainted Ruby string. Strings from external data<br />
sources should be tainted.<br />
<br />
rb_tainted_str_new2(const char *ptr)<br />
<br />
Creates a new tainted Ruby string from a C string.<br />
<br />
rb_str_cat(VALUE str, const char *ptr, long len)<br />
<br />
Appends len bytes of data from ptr to the Ruby string.<br />
<br />
Array functions<br />
<br />
rb_ary_new()<br />
<br />
Creates an array with no elements.<br />
<br />
rb_ary_new2(long len)<br />
<br />
Creates an array with no elements, allocating internal buffer<br />
for len elements.<br />
<br />
rb_ary_new3(long n, ...)<br />
<br />
Creates an n-element array from the arguments.<br />
<br />
rb_ary_new4(long n, VALUE *elts)<br />
<br />
Creates an n-element array from a C array.<br />
<br />
rb_ary_push(VALUE ary, VALUE val)<br />
rb_ary_pop(VALUE ary)<br />
rb_ary_shift(VALUE ary)<br />
rb_ary_unshift(VALUE ary, VALUE val)<br />
<br />
Array operations. The first argument to each functions must be an <br />
array. They may dump core if other types given.<br />
<br />
2. Extending Ruby with C<br />
<br />
2.1 Addding new features to Ruby<br />
<br />
You can add new features (classes, methods, etc.) to the Ruby<br />
interpreter. Ruby provides APIs for defining the following things:<br />
<br />
* Classes, Modules<br />
* Methods, Singleton Methods<br />
* Constants<br />
<br />
2.1.1 Class/module definition<br />
<br />
To define a class or module, use the functions below:<br />
<br />
VALUE rb_define_class(const char *name, VALUE super)<br />
VALUE rb_define_module(const char *name)<br />
<br />
These functions return the newly created class or module. You may<br />
want to save this reference into a variable to use later.<br />
<br />
To define nested classes or modules, use the functions below:<br />
<br />
VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)<br />
VALUE rb_define_module_under(VALUE outer, const char *name)<br />
<br />
2.1.2 Method/singleton method definition<br />
<br />
To define methods or singleton methods, use these functions:<br />
<br />
void rb_define_method(VALUE klass, const char *name, <br />
VALUE (*func)(), int argc)<br />
<br />
void rb_define_singleton_method(VALUE object, const char *name, <br />
VALUE (*func)(), int argc)<br />
<br />
The `argc' represents the number of the arguments to the C function,<br />
which must be less than 17. But I believe you don't need that much. :-)<br />
<br />
If `argc' is negative, it specifies the calling sequence, not number of<br />
the arguments. <br />
<br />
If argc is -1, the function will be called as:<br />
<br />
VALUE func(int argc, VALUE *argv, VALUE obj)<br />
<br />
where argc is the actual number of arguments, argv is the C array of<br />
the arguments, and obj is the receiver.<br />
<br />
If argc is -2, the arguments are passed in a Ruby array. The function<br />
will be called like:<br />
<br />
VALUE func(VALUE obj, VALUE args)<br />
<br />
where obj is the receiver, and args is the Ruby array containing<br />
actual arguments.<br />
<br />
There are two more functions to define methods. One is to define<br />
private methods:<br />
<br />
void rb_define_private_method(VALUE klass, const char *name, <br />
VALUE (*func)(), int argc)<br />
<br />
The other is to define module functions, which are private AND singleton<br />
methods of the module. For example, sqrt is the module function<br />
defined in Math module. It can be call in the form like:<br />
<br />
Math.sqrt(4)<br />
<br />
or<br />
<br />
include Math<br />
sqrt(4)<br />
<br />
To define module functions, use:<br />
<br />
void rb_define_module_function(VALUE module, const char *name, <br />
VALUE (*func)(), int argc)<br />
<br />
Oh, in addition, function-like methods, which are private methods defined<br />
in the Kernel module, can be defined using:<br />
<br />
void rb_define_global_function(const char *name, VALUE (*func)(), int argc)<br />
<br />
To define alias to the method,<br />
<br />
void rb_define_alias(VALUE module, const char* new, const char* old);<br />
<br />
2.1.3 Constant definition<br />
<br />
We have 2 functions to define constants:<br />
<br />
void rb_define_const(VALUE klass, const char *name, VALUE val)<br />
void rb_define_global_const(const char *name, VALUE val)<br />
<br />
The former is to define a constant under specified class/module. The<br />
latter is to define a global constant.<br />
<br />
2.2 Use Ruby features from C<br />
<br />
There are several ways to invoke Ruby's features from C code.<br />
<br />
2.2.1 Evaluate Ruby Programs in a String<br />
<br />
The easiest way to use Ruby's functionality from a C program is to<br />
evaluate the string as Ruby program. This function will do the job.<br />
<br />
VALUE rb_eval_string(const char *str)<br />
<br />
Evaluation is done under the current context, thus current local variables<br />
of the innermost method (which is defined by Ruby) can be accessed.<br />
<br />
2.2.2 ID or Symbol<br />
<br />
You can invoke methods directly, without parsing the string. First I<br />
need to explain about symbols (whose data type is ID). ID is the<br />
integer number to represent Ruby's identifiers such as variable names.<br />
It can be accessed from Ruby in the form:<br />
<br />
:Identifier<br />
<br />
You can get the symbol value from a string within C code by using<br />
<br />
rb_intern(const char *name)<br />
<br />
2.2.3 Invoke Ruby method from C<br />
<br />
To invoke methods directly, you can use the function below<br />
<br />
VALUE rb_funcall(VALUE recv, ID mid, int argc, ...)<br />
<br />
This function invokes a method on the recv, with the method name<br />
specified by the symbol mid.<br />
<br />
2.2.4 Accessing the variables and constants<br />
<br />
You can access class variables and instance variables using access<br />
functions. Also, global variables can be shared between both environments.<br />
There's no way to access Ruby's local variables.<br />
<br />
The functions to access/modify instance variables are below:<br />
<br />
VALUE rb_ivar_get(VALUE obj, ID id)<br />
VALUE rb_ivar_set(VALUE obj, ID id, VALUE val)<br />
<br />
id must be the symbol, which can be retrieved by rb_intern().<br />
<br />
To access the constants of the class/module:<br />
<br />
VALUE rb_const_get(VALUE obj, ID id)<br />
<br />
See 2.1.3 for defining new constant.<br />
<br />
3. Information sharing between Ruby and C<br />
<br />
3.1 Ruby constants that C can be accessed from C<br />
<br />
The following Ruby constants can be referred from C.<br />
<br />
Qtrue<br />
Qfalse<br />
<br />
Boolean values. Qfalse is false in C also (i.e. 0).<br />
<br />
Qnil<br />
<br />
Ruby nil in C scope.<br />
<br />
3.2 Global variables shared between C and Ruby<br />
<br />
Information can be shared between the two environments using shared global<br />
variables. To define them, you can use functions listed below:<br />
<br />
void rb_define_variable(const char *name, VALUE *var)<br />
<br />
This function defines the variable which is shared by both environments.<br />
The value of the global variable pointed to by `var' can be accessed<br />
through Ruby's global variable named `name'.<br />
<br />
You can define read-only (from Ruby, of course) variables using the<br />
function below.<br />
<br />
void rb_define_readonly_variable(const char *name, VALUE *var)<br />
<br />
You can defined hooked variables. The accessor functions (getter and<br />
setter) are called on access to the hooked variables.<br />
<br />
void rb_define_hooked_variable(constchar *name, VALUE *var,<br />
VALUE (*getter)(), void (*setter)())<br />
<br />
If you need to supply either setter or getter, just supply 0 for the<br />
hook you don't need. If both hooks are 0, rb_define_hooked_variable()<br />
works just like rb_define_variable().<br />
<br />
void rb_define_virtual_variable(const char *name,<br />
VALUE (*getter)(), void (*setter)())<br />
<br />
This function defines a Ruby global variable without a corresponding C<br />
variable. The value of the variable will be set/get only by hooks.<br />
<br />
The prototypes of the getter and setter functions are as follows:<br />
<br />
(*getter)(ID id, void *data, struct global_entry* entry);<br />
(*setter)(VALUE val, ID id, void *data, struct global_entry* entry);<br />
<br />
3.3 Encapsulate C data into Ruby object<br />
<br />
To wrap and objectify a C pointer as a Ruby object (so called<br />
DATA), use Data_Wrap_Struct().<br />
<br />
Data_Wrap_Struct(klass, mark, free, ptr)<br />
<br />
Data_Wrap_Struct() returns a created DATA object. The klass argument<br />
is the class for the DATA object. The mark argument is the function<br />
to mark Ruby objects pointed by this data. The free argument is the<br />
function to free the pointer allocation. If this is -1, the pointer<br />
will be just freed. The functions mark and free will be called from<br />
garbage collector.<br />
<br />
You can allocate and wrap the structure in one step.<br />
<br />
Data_Make_Struct(klass, type, mark, free, sval)<br />
<br />
This macro returns an allocated Data object, wrapping the pointer to<br />
the structure, which is also allocated. This macro works like:<br />
<br />
(sval = ALLOC(type), Data_Wrap_Struct(klass, mark, free, sval))<br />
<br />
Arguments klass, mark, and free work like their counterparts in<br />
Data_Wrap_Struct(). A pointer to the allocated structure will be<br />
assigned to sval, which should be a pointer of the type specified.<br />
<br />
To retrieve the C pointer from the Data object, use the macro<br />
Data_Get_Struct().<br />
<br />
Data_Get_Struct(obj, type, sval)<br />
<br />
A pointer to the structure will be assigned to the variable sval.<br />
<br />
See the example below for details. <br />
<br />
4. Example - Creating dbm extension<br />
<br />
OK, here's the example of making an extension library. This is the<br />
extension to access DBMs. The full source is included in the ext/<br />
directory in the Ruby's source tree.<br />
<br />
(1) make the directory<br />
<br />
% mkdir ext/dbm<br />
<br />
Make a directory for the extension library under ext directory.<br />
<br />
(2) create MANIFEST file<br />
<br />
% cd ext/dbm<br />
% touch MANIFEST<br />
<br />
There should be MANIFEST file in the directory for the extension<br />
library. Make an empty file for now.<br />
<br />
(3) design the library<br />
<br />
You need to design the library features, before making it.<br />
<br />
(4) write C code.<br />
<br />
You need to write C code for your extension library. If your library<br />
has only one source file, choosing ``LIBRARY.c'' as a file name is<br />
preferred. On the other hand, in case your library has multiple source<br />
files, avoid choosing ``LIBRARY.c'' for a file name. It may conflict<br />
with an intermediate file ``LIBRARY.o'' on some platforms.<br />
<br />
Ruby will execute the initializing function named ``Init_LIBRARY'' in<br />
the library. For example, ``Init_dbm()'' will be executed when loading<br />
the library.<br />
<br />
Here's the example of an initializing function.<br />
<br />
--<br />
Init_dbm()<br />
{<br />
/* define DBM class */<br />
cDBM = rb_define_class("DBM", rb_cObject);<br />
/* DBM includes Enumerate module */<br />
rb_include_module(cDBM, rb_mEnumerable);<br />
<br />
/* DBM has class method open(): arguments are received as C array */<br />
rb_define_singleton_method(cDBM, "open", fdbm_s_open, -1);<br />
<br />
/* DBM instance method close(): no args */<br />
rb_define_method(cDBM, "close", fdbm_close, 0);<br />
/* DBM instance method []: 1 argument */<br />
rb_define_method(cDBM, "[]", fdbm_fetch, 1);<br />
:<br />
<br />
/* ID for a instance variable to store DBM data */<br />
id_dbm = rb_intern("dbm");<br />
}<br />
--<br />
<br />
The dbm extension wraps the dbm struct in the C environment using <br />
Data_Make_Struct.<br />
<br />
--<br />
struct dbmdata {<br />
int di_size;<br />
DBM *di_dbm;<br />
};<br />
<br />
<br />
obj = Data_Make_Struct(klass, struct dbmdata, 0, free_dbm, dbmp);<br />
--<br />
<br />
This code wraps the dbmdata structure into a Ruby object. We avoid wrapping<br />
DBM* directly, because we want to cache size information.<br />
<br />
To retrieve the dbmdata structure from a Ruby object, we define the<br />
following macro:<br />
<br />
--<br />
#define GetDBM(obj, dbmp) {\<br />
Data_Get_Struct(obj, struct dbmdata, dbmp);\<br />
if (dbmp->di_dbm == 0) closed_dbm();\<br />
}<br />
--<br />
<br />
This sort of complicated macro does the retrieving and close checking for<br />
the DBM.<br />
<br />
There are three kinds of way to receive method arguments. First,<br />
methods with a fixed number of arguments receive arguments like this:<br />
<br />
--<br />
static VALUE<br />
fdbm_delete(obj, keystr)<br />
VALUE obj, keystr;<br />
{<br />
:<br />
}<br />
--<br />
<br />
The first argument of the C function is the self, the rest are the<br />
arguments to the method.<br />
<br />
Second, methods with an arbitrary number of arguments receive<br />
arguments like this:<br />
<br />
--<br />
static VALUE<br />
fdbm_s_open(argc, argv, klass)<br />
int argc;<br />
VALUE *argv;<br />
VALUE klass;<br />
{<br />
:<br />
if (rb_scan_args(argc, argv, "11", &file, &vmode) == 1) {<br />
mode = 0666; /* default value */<br />
}<br />
:<br />
}<br />
--<br />
<br />
The first argument is the number of method arguments, the second<br />
argument is the C array of the method arguments, and the third<br />
argument is the receiver of the method.<br />
<br />
You can use the function rb_scan_args() to check and retrieve the<br />
arguments. For example, "11" means that the method requires at least one<br />
argument, and at most receives two arguments.<br />
<br />
Methods with an arbitrary number of arguments can receive arguments<br />
by Ruby's array, like this:<br />
<br />
--<br />
static VALUE<br />
fdbm_indexes(obj, args)<br />
VALUE obj, args;<br />
{<br />
:<br />
}<br />
--<br />
<br />
The first argument is the receiver, the second one is the Ruby array<br />
which contains the arguments to the method.<br />
<br />
** Notice<br />
<br />
GC should know about global variables which refer to Ruby's objects, but<br />
are not exported to the Ruby world. You need to protect them by<br />
<br />
void rb_global_variable(VALUE *var)<br />
<br />
(5) prepare extconf.rb<br />
<br />
If the file named extconf.rb exists, it will be executed to generate<br />
Makefile. If not, the compilation scheme will try to generate Makefile<br />
anyway.<br />
<br />
extconf.rb is the file for check compilation conditions etc. You<br />
need to put<br />
<br />
require 'mkmf'<br />
<br />
at the top of the file. You can use the functions below to check<br />
various conditions.<br />
<br />
have_library(lib, func): check whether library containing function exists.<br />
have_func(func, header): check whether function exists<br />
have_header(header): check whether header file exists<br />
create_makefile(target): generate Makefile<br />
<br />
The value of the variables below will affect the Makefile.<br />
<br />
$CFLAGS: included in CFLAGS make variable (such as -I)<br />
$LDFLAGS: included in LDFLAGS make variable (such as -L)<br />
<br />
If a compilation condition is not fulfilled, you should not call<br />
``create_makefile''. The Makefile will not generated, compilation will<br />
not be done.<br />
<br />
(6) prepare depend (optional)<br />
<br />
If the file named depend exists, Makefile will include that file to<br />
check dependencies. You can make this file by invoking<br />
<br />
% gcc -MM *.c > depend<br />
<br />
It's no harm. Prepare it.<br />
<br />
(7) put file names into MANIFEST (optional)<br />
<br />
% find * -type f -print > MANIFEST<br />
% vi MANIFEST<br />
<br />
Append file names into MANIFEST. The compilation scheme requires<br />
MANIFEST only to exist, but it's better to take this step in order<br />
to distinguish which files are required.<br />
<br />
(8) generate Makefile<br />
<br />
Try generating the Makefile by:<br />
<br />
ruby extconf.rb<br />
<br />
You don't need this step if you put the extension library under the ext<br />
directory of the ruby source tree. In that case, compilation of the<br />
interpreter will do this step for you.<br />
<br />
(9) make<br />
<br />
Type<br />
<br />
make<br />
<br />
to compile your extension. You don't need this step either if you have<br />
put extension library under the ext directory of the ruby source tree.<br />
<br />
(9) debug<br />
<br />
You may need to rb_debug the extension. Extensions can be linked<br />
statically by the adding directory name in the ext/Setup file so that<br />
you can inspect the extension with the debugger.<br />
<br />
(10) done, now you have the extension library<br />
<br />
You can do anything you want with your library. The author of Ruby<br />
will not claim any restrictions on your code depending on the Ruby API.<br />
Feel free to use, modify, distribute or sell your program.<br />
<br />
Appendix A. Ruby source files overview<br />
<br />
ruby language core<br />
<br />
class.c<br />
error.c<br />
eval.c<br />
gc.c<br />
object.c<br />
parse.y<br />
variable.c<br />
<br />
utility functions<br />
<br />
dln.c<br />
regex.c<br />
st.c<br />
util.c<br />
<br />
ruby interpreter implementation<br />
<br />
dmyext.c<br />
inits.c<br />
main.c<br />
ruby.c<br />
version.c<br />
<br />
class library<br />
<br />
array.c<br />
bignum.c<br />
compar.c<br />
dir.c<br />
enum.c<br />
file.c<br />
hash.c<br />
io.c<br />
marshal.c<br />
math.c<br />
numeric.c<br />
pack.c<br />
prec.c<br />
process.c<br />
random.c<br />
range.c<br />
re.c<br />
signal.c<br />
sprintf.c<br />
string.c<br />
struct.c<br />
time.c<br />
<br />
Appendix B. Ruby extension API reference<br />
<br />
** Types<br />
<br />
VALUE<br />
<br />
The type for the Ruby object. Actual structures are defined in ruby.h,<br />
such as struct RString, etc. To refer the values in structures, use<br />
casting macros like RSTRING(obj).<br />
<br />
** Variables and constants<br />
<br />
Qnil<br />
<br />
const: nil object<br />
<br />
Qtrue<br />
<br />
const: true object(default true value)<br />
<br />
Qfalse<br />
<br />
const: false object<br />
<br />
** C pointer wrapping<br />
<br />
Data_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval)<br />
<br />
Wrap a C pointer into a Ruby object. If object has references to other<br />
Ruby objects, they should be marked by using the mark function during<br />
the GC process. Otherwise, mark should be 0. When this object is no<br />
longer referred by anywhere, the pointer will be discarded by free<br />
function.<br />
<br />
Data_Make_Struct(klass, type, mark, free, sval)<br />
<br />
This macro allocates memory using malloc(), assigns it to the variable<br />
sval, and returns the DATA encapsulating the pointer to memory region.<br />
<br />
Data_Get_Struct(data, type, sval)<br />
<br />
This macro retrieves the pointer value from DATA, and assigns it to<br />
the variable sval. <br />
<br />
** Checking data types<br />
<br />
TYPE(value)<br />
FIXNUM_P(value)<br />
NIL_P(value)<br />
void Check_Type(VALUE value, int type)<br />
void Check_SafeStr(VALUE value)<br />
<br />
** Data type conversion<br />
<br />
FIX2INT(value)<br />
INT2FIX(i)<br />
NUM2INT(value)<br />
INT2NUM(i)<br />
NUM2DBL(value)<br />
rb_float_new(f)<br />
STR2CSTR(value)<br />
rb_str_new2(s)<br />
<br />
** defining class/module<br />
<br />
VALUE rb_define_class(const char *name, VALUE super)<br />
<br />
Defines a new Ruby class as a subclass of super.<br />
<br />
VALUE rb_define_class_under(VALUE module, const char *name, VALUE super)<br />
<br />
Creates a new Ruby class as a subclass of super, under the module's<br />
namespace.<br />
<br />
VALUE rb_define_module(const char *name)<br />
<br />
Defines a new Ruby module.<br />
<br />
VALUE rb_define_module_under(VALUE module, const char *name)<br />
<br />
Defines a new Ruby module under the module's namespace.<br />
<br />
void rb_include_module(VALUE klass, VALUE module)<br />
<br />
Includes module into class. If class already includes it, just<br />
ignored.<br />
<br />
void rb_extend_object(VALUE object, VALUE module)<br />
<br />
Extend the object with the module's attributes.<br />
<br />
** Defining Global Variables<br />
<br />
void rb_define_variable(const char *name, VALUE *var)<br />
<br />
Defines a global variable which is shared between C and Ruby. If name<br />
contains a character which is not allowed to be part of the symbol,<br />
it can't be seen from Ruby programs.<br />
<br />
void rb_define_readonly_variable(const char *name, VALUE *var)<br />
<br />
Defines a read-only global variable. Works just like<br />
rb_define_variable(), except defined variable is read-only.<br />
<br />
void rb_define_virtual_variable(const char *name,<br />
VALUE (*getter)(), VALUE (*setter)())<br />
<br />
Defines a virtual variable, whose behavior is defined by a pair of C<br />
functions. The getter function is called when the variable is<br />
referred. The setter function is called when the value is set to the<br />
variable. The prototype for getter/setter functions are:<br />
<br />
VALUE getter(ID id)<br />
void setter(VALUE val, ID id)<br />
<br />
The getter function must return the value for the access.<br />
<br />
void rb_define_hooked_variable(const char *name, VALUE *var,<br />
VALUE (*getter)(), VALUE (*setter)())<br />
<br />
Defines hooked variable. It's a virtual variable with a C variable. <br />
The getter is called as<br />
<br />
VALUE getter(ID id, VALUE *var)<br />
<br />
returning a new value. The setter is called as<br />
<br />
void setter(VALUE val, ID id, VALUE *var)<br />
<br />
GC requires C global variables which hold Ruby values to be marked.<br />
<br />
void rb_global_variable(VALUE *var)<br />
<br />
Tells GC to protect these variables.<br />
<br />
** Constant Definition<br />
<br />
void rb_define_const(VALUE klass, const char *name, VALUE val)<br />
<br />
Defines a new constant under the class/module.<br />
<br />
void rb_define_global_const(const char *name, VALUE val)<br />
<br />
Defines a global constant. This is just the same as<br />
<br />
rb_define_const(cKernal, name, val)<br />
<br />
** Method Definition<br />
<br />
rb_define_method(VALUE klass, const char *name, VALUE (*func)(), int argc)<br />
<br />
Defines a method for the class. func is the function pointer. argc<br />
is the number of arguments. if argc is -1, the function will receive<br />
3 arguments: argc, argv, and self. if argc is -2, the function will<br />
receive 2 arguments, self and args, where args is a Ruby array of<br />
the method arguments.<br />
<br />
rb_define_private_method(VALUE klass, const char *name, VALUE (*func)(), int argc)<br />
<br />
Defines a private method for the class. Arguments are same as<br />
rb_define_method().<br />
<br />
rb_define_singleton_method(VALUE klass, const char *name, VALUE (*func)(), int argc)<br />
<br />
Defines a singleton method. Arguments are same as rb_define_method().<br />
<br />
rb_scan_args(int argc, VALUE *argv, const char *fmt, ...)<br />
<br />
Retrieve argument from argc, argv. The fmt is the format string for<br />
the arguments, such as "12" for 1 non-optional argument, 2 optional<br />
arguments. If `*' appears at the end of fmt, it means the rest of<br />
the arguments are assigned to the corresponding variable, packed in<br />
an array.<br />
<br />
** Invoking Ruby method<br />
<br />
VALUE rb_funcall(VALUE recv, ID mid, int narg, ...)<br />
<br />
Invokes a method. To retrieve mid from a method name, use rb_intern().<br />
<br />
VALUE rb_funcall2(VALUE recv, ID mid, int argc, VALUE *argv)<br />
<br />
Invokes a method, passing arguments by an array of values.<br />
<br />
VALUE rb_eval_string(const char *str)<br />
<br />
Compiles and executes the string as a Ruby program.<br />
<br />
ID rb_intern(const char *name)<br />
<br />
Returns ID corresponding to the name.<br />
<br />
char *rb_id2name(ID id)<br />
<br />
Returns the name corresponding ID.<br />
<br />
char *rb_class2name(VALUE klass)<br />
<br />
Returns the name of the class.<br />
<br />
int rb_respond_to(VALUE object, ID id)<br />
<br />
Returns true if the object responds to the message specified by id.<br />
<br />
** Instance Variables<br />
<br />
VALUE rb_iv_get(VALUE obj, const char *name)<br />
<br />
Retrieve the value of the instance variable. If the name is not<br />
prefixed by `@', that variable shall be inaccessible from Ruby.<br />
<br />
VALUE rb_iv_set(VALUE obj, const char *name, VALUE val)<br />
<br />
Sets the value of the instance variable.<br />
<br />
** Control Structure<br />
<br />
VALUE rb_iterate(VALUE (*func1)(), void *arg1, VALUE (*func2)(), void *arg2)<br />
<br />
Calls the function func1, supplying func2 as the block. func1 will be<br />
called with the argument arg1. func2 receives the value from yield as<br />
the first argument, arg2 as the second argument.<br />
<br />
VALUE rb_yield(VALUE val)<br />
<br />
Evaluates the block with value val.<br />
<br />
VALUE rb_rescue(VALUE (*func1)(), void *arg1, VALUE (*func2)(), void *arg2)<br />
<br />
Calls the function func1, with arg1 as the argument. If an exception<br />
occurs during func1, it calls func2 with arg2 as the argument. The<br />
return value of rb_rescue() is the return value from func1 if no<br />
exception occurs, from func2 otherwise.<br />
<br />
VALUE rb_ensure(VALUE (*func1)(), void *arg1, void (*func2)(), void *arg2)<br />
<br />
Calls the function func1 with arg1 as the argument, then calls func2<br />
with arg2 if execution terminated. The return value from<br />
rb_ensure() is that of func1.<br />
<br />
** Exceptions and Errors<br />
<br />
void rb_warn(const char *fmt, ...)<br />
<br />
Prints a warning message according to a printf-like format.<br />
<br />
void rb_warning(const char *fmt, ...)<br />
<br />
Prints a warning message according to a printf-like format, if<br />
$VERBOSE is true.<br />
<br />
void rb_raise(rb_eRuntimeError, const char *fmt, ...)<br />
<br />
Raises RuntimeError. The fmt is a format string just like printf().<br />
<br />
void rb_raise(VALUE exception, const char *fmt, ...)<br />
<br />
Raises a class exception. The fmt is a format string just like printf().<br />
<br />
void rb_fatal(const char *fmt, ...)<br />
<br />
Raises a fatal error, terminates the interpreter. No exception handling<br />
will be done for fatal errors, but ensure blocks will be executed.<br />
<br />
void rb_bug(const char *fmt, ...)<br />
<br />
Terminates the interpreter immediately. This function should be<br />
called under the situation caused by the bug in the interpreter. No<br />
exception handling nor ensure execution will be done.<br />
<br />
** Initialize and Starts the Interpreter<br />
<br />
The embedding API functions are below (not needed for extension libraries):<br />
<br />
void ruby_init()<br />
<br />
Initializes the interpreter.<br />
<br />
void ruby_options(int argc, char **argv)<br />
<br />
Process command line arguments for the interpreter.<br />
<br />
void ruby_run()<br />
<br />
Starts execution of the interpreter.<br />
<br />
void ruby_script(char *name)<br />
<br />
Specifies the name of the script ($0).<br />
<br />
Appendix C. Functions Available in extconf.rb<br />
<br />
These functions are available in extconf.rb:<br />
<br />
have_library(lib, func)<br />
<br />
Checks whether the library exists, containing the specified function.<br />
Returns true if the library exists.<br />
<br />
find_library(lib, func, path...)<br />
<br />
Checks whether a library which contains the specified function exists in<br />
path. Returns true if the library exists.<br />
<br />
have_func(func, header)<br />
<br />
Checks whether func exists with header. Returns true if the function<br />
exists. To check functions in an additional library, you need to<br />
check that library first using have_library().<br />
<br />
have_header(header)<br />
<br />
Checks whether header exists. Returns true if the header file exists.<br />
<br />
create_makefile(target)<br />
<br />
Generates the Makefile for the extension library. If you don't invoke<br />
this method, the compilation will not be done.<br />
<br />
with_config(withval[, default=nil])<br />
<br />
Parses the command line options and returns the value specified by<br />
--with-<withval>.<br />
<br />
dir_config(target[, default_dir])<br />
dir_config(target[, default_include, default_lib])<br />
<br />
Parses the command line options and adds the directories specified by<br />
--with-<target>-dir, --with-<target>-include, and/or --with-<target>-lib<br />
to $CFLAGS and/or $LDFLAGS. --with-<target>-dir=/path is equivalent to<br />
--with-<target>-include=/path/include --with-<target>-lib=/path/lib.<br />
Returns an array of the added directories ([include_dir, lib_dir]).<br />
<br />
/*<br />
* Local variables:<br />
* fill-column: 70<br />
* end:<br />
*/<br />
<hr />
<div class="navigator"><span class="navigator">[<a href="index.html">MAIN</a>][<a href="refm482.html">INDEX</a>][<a href="refm483.html">KEYWORD</a>][<a href="refm594.html">METHOD</a>(<a href="refm633.html">NC</a>)] [<a href="index.html">TOP</a>][<a href="index.html">UP</a>][<a href="refm473.html"><-PREV</a>][<a href="refm475.html">NEXT-></a>]</span></div>
</body>
</html>
