1# README.EXT - -*- RDoc -*- created at: Mon Aug 7 16:45:54 JST 1995
2
3This document explains how to make extension libraries for Ruby.
4
5= Basic Knowledge
6
7In C, variables have types and data do not have types. In contrast,
8Ruby variables do not have a static type, and data themselves have
9types, so data will need to be converted between the languages.
10
11Data in Ruby are represented by the C type `VALUE'. Each VALUE data
12has its data-type.
13
14To retrieve C data from a VALUE, you need to:
15
161. Identify the VALUE's data type
172. Convert the VALUE into C data
18
19Converting to the wrong data type may cause serious problems.
20
21== Data-Types
22
23The Ruby interpreter has the following data types:
24
25T_NIL :: nil
26T_OBJECT :: ordinary object
27T_CLASS :: class
28T_MODULE :: module
29T_FLOAT :: floating point number
30T_STRING :: string
31T_REGEXP :: regular expression
32T_ARRAY :: array
33T_HASH :: associative array
34T_STRUCT :: (Ruby) structure
35T_BIGNUM :: multi precision integer
36T_FIXNUM :: Fixnum(31bit or 63bit integer)
37T_COMPLEX :: complex number
38T_RATIONAL :: rational number
39T_FILE :: IO
40T_TRUE :: true
41T_FALSE :: false
42T_DATA :: data
43T_SYMBOL :: symbol
44
45In addition, there are several other types used internally:
46
47T_ICLASS :: included module
48T_MATCH :: MatchData object
49T_UNDEF :: undefined
50T_NODE :: syntax tree node
51T_ZOMBIE :: object awaiting finalization
52
53Most of the types are represented by C structures.
54
55== Check Data Type of the VALUE
56
57The macro TYPE() defined in ruby.h shows the data type of the VALUE.
58TYPE() returns the constant number T_XXXX described above. To handle
59data 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
77There is the data-type check function
78
79 void Check_Type(VALUE value, int type)
80
81which raises an exception if the VALUE does not have the type
82specified.
83
84There are also faster check macros for fixnums and nil.
85
86 FIXNUM_P(obj)
87 NIL_P(obj)
88
89== Convert VALUE into C Data
90
91The data for type T_NIL, T_FALSE, T_TRUE are nil, false, true
92respectively. They are singletons for the data type.
93The equivalent C constants are: Qnil, Qfalse, Qtrue.
94Note that Qfalse is false in C also (i.e. 0), but not Qnil.
95
96The T_FIXNUM data is a 31bit or 63bit length fixed integer.
97This size is depend on the size of long: if long is 32bit then
98T_FIXNUM is 31bit, if long is 64bit then T_FIXNUM is 63bit.
99T_FIXNUM can be converted to a C integer by using the
100FIX2INT() macro or FIX2LONG(). Though you have to check that the
101data is really FIXNUM before using them, they are faster. FIX2LONG()
102never raises exceptions, but FIX2INT() raises RangeError if the
103result is bigger or smaller than the size of int.
104There are also NUM2INT() and NUM2LONG() which converts any Ruby
105numbers into C integers. These macros includes a type check,
106so an exception will be raised if the conversion failed. NUM2DBL()
107can be used to retrieve the double float value in the same way.
108
109You can use the macros
110StringValue() and StringValuePtr() to get a char* from a VALUE.
111StringValue(var) replaces var's value with the result of "var.to_str()".
112StringValuePtr(var) does same replacement and returns char*
113representation of var. These macros will skip the replacement if var
114is a String. Notice that the macros take only the lvalue as their
115argument, to change the value of var in place.
116
117You can also use the macro named StringValueCStr(). This is just
118like StringValuePtr(), but always add nul character at the end of
119the result. If the result contains nul character, this macro causes
120the ArgumentError exception.
121StringValuePtr() doesn't guarantee the existence of a nul at the end
122of the result, and the result may contain nul.
123
124Other data types have corresponding C structures, e.g. struct RArray
125for T_ARRAY etc. The VALUE of the type which has the corresponding
126structure can be cast to retrieve the pointer to the struct. The
127casting macro will be of the form RXXXX for each data type; for
128instance, RARRAY(obj). See "ruby.h".
129
130There are some accessing macros for structure members, for example
131`RSTRING_LEN(str)' to get the size of the Ruby String object. The
132allocated region can be accessed by `RSTRING_PTR(str)'. For arrays,
133use `RARRAY_LEN(ary)' and `RARRAY_PTR(ary)' respectively.
134
135Notice: Do not change the value of the structure directly, unless you
136are responsible for the result. This ends up being the cause of
137interesting bugs.
138
139== Convert C Data into VALUE
140
141To convert C data to Ruby values:
142
143FIXNUM ::
144
145 left shift 1 bit, and turn on LSB.
146
147Other pointer values::
148
149 cast to VALUE.
150
151You can determine whether a VALUE is pointer or not by checking its LSB.
152
153Notice Ruby does not allow arbitrary pointer values to be a VALUE. They
154should be pointers to the structures which Ruby knows about. The known
155structures are defined in <ruby.h>.
156
157To convert C numbers to Ruby values, use these macros.
158
159INT2FIX() :: for integers within 31bits.
160INT2NUM() :: for arbitrary sized integer.
161
162INT2NUM() converts an integer into a Bignum if it is out of the FIXNUM
163range, but is a bit slower.
164
165== Manipulating Ruby Data
166
167As I already mentioned, it is not recommended to modify an object's
168internal structure. To manipulate objects, use the functions supplied
169by the Ruby interpreter. Some (not all) of the useful functions are
170listed below:
171
172=== String Functions
173
174rb_str_new(const char *ptr, long len) ::
175
176 Creates a new Ruby string.
177
178rb_str_new2(const char *ptr) ::
179rb_str_new_cstr(const char *ptr) ::
180
181 Creates a new Ruby string from a C string. This is equivalent to
182 rb_str_new(ptr, strlen(ptr)).
183
184rb_tainted_str_new(const char *ptr, long len) ::
185
186 Creates a new tainted Ruby string. Strings from external data
187 sources should be tainted.
188
189rb_tainted_str_new2(const char *ptr) ::
190rb_tainted_str_new_cstr(const char *ptr) ::
191
192 Creates a new tainted Ruby string from a C string.
193
194rb_sprintf(const char *format, ...) ::
195rb_vsprintf(const char *format, va_list ap) ::
196
197 Creates a new Ruby string with printf(3) format.
198
199 Note: In the format string, %i is used for Object#to_s (or Object#inspect if
200 '+' flag is set) output (and related argument must be a VALUE). For integers
201 in format strings, use %d.
202
203rb_str_cat(VALUE str, const char *ptr, long len) ::
204
205 Appends len bytes of data from ptr to the Ruby string.
206
207rb_str_cat2(VALUE str, const char* ptr) ::
208
209 Appends C string ptr to Ruby string str. This function is
210 equivalent to rb_str_cat(str, ptr, strlen(ptr)).
211
212rb_str_catf(VALUE str, const char* format, ...) ::
213rb_str_vcatf(VALUE str, const char* format, va_list ap) ::
214
215 Appends C string format and successive arguments to Ruby string
216 str according to a printf-like format. These functions are
217 equivalent to rb_str_cat2(str, rb_sprintf(format, ...)) and
218 rb_str_cat2(str, rb_vsprintf(format, ap)), respectively.
219
220rb_enc_str_new(const char *ptr, long len, rb_encoding *enc) ::
221
222 Creates a new Ruby string with the specified encoding.
223
224rb_usascii_str_new(const char *ptr, long len) ::
225rb_usascii_str_new_cstr(const char *ptr) ::
226
227 Creates a new Ruby string with encoding US-ASCII.
228
229rb_str_resize(VALUE str, long len) ::
230
231 Resizes Ruby string to len bytes. If str is not modifiable, this
232 function raises an exception. The length of str must be set in
233 advance. If len is less than the old length the content beyond
234 len bytes is discarded, else if len is greater than the old length
235 the content beyond the old length bytes will not be preserved but
236 will be garbage. Note that RSTRING_PTR(str) may change by calling
237 this function.
238
239rb_str_set_len(VALUE str, long len) ::
240
241 Sets the length of Ruby string. If str is not modifiable, this
242 function raises an exception. This function preserves the content
243 upto len bytes, regardless RSTRING_LEN(str). len must not exceed
244 the capacity of str.
245
246=== Array Functions
247
248rb_ary_new() ::
249
250 Creates an array with no elements.
251
252rb_ary_new2(long len) ::
253
254 Creates an array with no elements, allocating internal buffer
255 for len elements.
256
257rb_ary_new3(long n, ...) ::
258
259 Creates an n-element array from the arguments.
260
261rb_ary_new4(long n, VALUE *elts) ::
262
263 Creates an n-element array from a C array.
264
265rb_ary_to_ary(VALUE obj) ::
266
267 Converts the object into an array.
268 Equivalent to Object#to_ary.
269
270There are many functions to operate an array. They may dump core if other
271types are given.
272
273rb_ary_aref(argc, VALUE *argv, VALUE ary) ::
274
275 Equivaelent to Array#[].
276
277rb_ary_entry(VALUE ary, long offset) ::
278
279 ary[offset]
280
281rb_ary_subseq(VALUE ary, long beg, long len) ::
282
283 ary[beg, len]
284
285rb_ary_push(VALUE ary, VALUE val) ::
286rb_ary_pop(VALUE ary) ::
287rb_ary_shift(VALUE ary) ::
288rb_ary_unshift(VALUE ary, VALUE val) ::
289
290rb_ary_cat(VALUE ary, const VALUE *ptr, long len) ::
291
292 Appends len elements of objects from ptr to the array.
293
294= Extending Ruby with C
295
296== Adding New Features to Ruby
297
298You can add new features (classes, methods, etc.) to the Ruby
299interpreter. Ruby provides APIs for defining the following things:
300
301* Classes, Modules
302* Methods, Singleton Methods
303* Constants
304
305=== Class and Module Definition
306
307To define a class or module, use the functions below:
308
309 VALUE rb_define_class(const char *name, VALUE super)
310 VALUE rb_define_module(const char *name)
311
312These functions return the newly created class or module. You may
313want to save this reference into a variable to use later.
314
315To define nested classes or modules, use the functions below:
316
317 VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)
318 VALUE rb_define_module_under(VALUE outer, const char *name)
319
320=== Method and Singleton Method Definition
321
322To define methods or singleton methods, use these functions:
323
324 void rb_define_method(VALUE klass, const char *name,
325 VALUE (*func)(), int argc)
326
327 void rb_define_singleton_method(VALUE object, const char *name,
328 VALUE (*func)(), int argc)
329
330The `argc' represents the number of the arguments to the C function,
331which must be less than 17. But I doubt you'll need that many.
332
333If `argc' is negative, it specifies the calling sequence, not number of
334the arguments.
335
336If argc is -1, the function will be called as:
337
338 VALUE func(int argc, VALUE *argv, VALUE obj)
339
340where argc is the actual number of arguments, argv is the C array of
341the arguments, and obj is the receiver.
342
343If argc is -2, the arguments are passed in a Ruby array. The function
344will be called like:
345
346 VALUE func(VALUE obj, VALUE args)
347
348where obj is the receiver, and args is the Ruby array containing
349actual arguments.
350
351There are some more functions to define methods. One takes an ID
352as the name of method to be defined. See also ID or Symbol below.
353
354 void rb_define_method_id(VALUE klass, ID name,
355 VALUE (*func)(ANYARGS), int argc)
356
357There are two functions to define private/protected methods:
358
359 void rb_define_private_method(VALUE klass, const char *name,
360 VALUE (*func)(), int argc)
361 void rb_define_protected_method(VALUE klass, const char *name,
362 VALUE (*func)(), int argc)
363
364At last, rb_define_module_function defines a module functions,
365which are private AND singleton methods of the module.
366For example, sqrt is the module function defined in Math module.
367It can be called in the following way:
368
369 Math.sqrt(4)
370
371or
372
373 include Math
374 sqrt(4)
375
376To define module functions, use:
377
378 void rb_define_module_function(VALUE module, const char *name,
379 VALUE (*func)(), int argc)
380
381In addition, function-like methods, which are private methods defined
382in the Kernel module, can be defined using:
383
384 void rb_define_global_function(const char *name, VALUE (*func)(), int argc)
385
386To define an alias for the method,
387
388 void rb_define_alias(VALUE module, const char* new, const char* old);
389
390To define a reader/writer for an attribute,
391
392 void rb_define_attr(VALUE klass, const char *name, int read, int write)
393
394To define and undefine the `allocate' class method,
395
396 void rb_define_alloc_func(VALUE klass, VALUE (*func)(VALUE klass));
397 void rb_undef_alloc_func(VALUE klass);
398
399func has to take the klass as the argument and return a newly
400allocated instance. This instance should be as empty as possible,
401without any expensive (including external) resources.
402
403=== Constant Definition
404
405We have 2 functions to define constants:
406
407 void rb_define_const(VALUE klass, const char *name, VALUE val)
408 void rb_define_global_const(const char *name, VALUE val)
409
410The former is to define a constant under specified class/module. The
411latter is to define a global constant.
412
413== Use Ruby Features from C
414
415There are several ways to invoke Ruby's features from C code.
416
417=== Evaluate Ruby Programs in a String
418
419The easiest way to use Ruby's functionality from a C program is to
420evaluate the string as Ruby program. This function will do the job:
421
422 VALUE rb_eval_string(const char *str)
423
424Evaluation is done under the current context, thus current local variables
425of the innermost method (which is defined by Ruby) can be accessed.
426
427Note that the evaluation can raise an exception. There is a safer
428function:
429
430 VALUE rb_eval_string_protect(const char *str, int *state)
431
432It returns nil when an error occur. Moreover, *state is zero if str was
433successfully evaluated, or nonzero otherwise.
434
435=== ID or Symbol
436
437You can invoke methods directly, without parsing the string. First I
438need to explain about ID. ID is the integer number to represent
439Ruby's identifiers such as variable names. The Ruby data type
440corresponding to ID is Symbol. It can be accessed from Ruby in the
441form:
442
443 :Identifier
444
445or
446
447 :"any kind of string"
448
449You can get the ID value from a string within C code by using
450
451 rb_intern(const char *name)
452 rb_intern_str(VALUE name)
453
454You can retrieve ID from Ruby object (Symbol or String) given as an
455argument by using
456
457 rb_to_id(VALUE symbol)
458 rb_check_id(volatile VALUE *name)
459 rb_check_id_cstr(const char *name, long len, rb_encoding *enc)
460
461These functions try to convert the argument to a String if it was not
462a Symbol nor a String. The second function stores the converted
463result into *name, and returns 0 if the string is not a known symbol.
464After this function returned a non-zero value, *name is always a
465Symbol or a String, otherwise it is a String if the result is 0.
466The third function takes NUL-terminated C string, not Ruby VALUE.
467
468You can convert C ID to Ruby Symbol by using
469
470 VALUE ID2SYM(ID id)
471
472and to convert Ruby Symbol object to ID, use
473
474 ID SYM2ID(VALUE symbol)
475
476=== Invoke Ruby Method from C
477
478To invoke methods directly, you can use the function below
479
480 VALUE rb_funcall(VALUE recv, ID mid, int argc, ...)
481
482This function invokes a method on the recv, with the method name
483specified by the symbol mid.
484
485=== Accessing the Variables and Constants
486
487You can access class variables and instance variables using access
488functions. Also, global variables can be shared between both
489environments. There's no way to access Ruby's local variables.
490
491The functions to access/modify instance variables are below:
492
493 VALUE rb_ivar_get(VALUE obj, ID id)
494 VALUE rb_ivar_set(VALUE obj, ID id, VALUE val)
495
496id must be the symbol, which can be retrieved by rb_intern().
497
498To access the constants of the class/module:
499
500 VALUE rb_const_get(VALUE obj, ID id)
501
502See also Constant Definition above.
503
504= Information Sharing Between Ruby and C
505
506=== Ruby Constants That C Can Be Accessed From C
507
508As stated in section 1.3,
509the following Ruby constants can be referred from C.
510
511 Qtrue
512 Qfalse
513
514Boolean values. Qfalse is false in C also (i.e. 0).
515
516 Qnil
517
518Ruby nil in C scope.
519
520== Global Variables Shared Between C and Ruby
521
522Information can be shared between the two environments using shared global
523variables. To define them, you can use functions listed below:
524
525 void rb_define_variable(const char *name, VALUE *var)
526
527This function defines the variable which is shared by both environments.
528The value of the global variable pointed to by `var' can be accessed
529through Ruby's global variable named `name'.
530
531You can define read-only (from Ruby, of course) variables using the
532function below.
533
534 void rb_define_readonly_variable(const char *name, VALUE *var)
535
536You can defined hooked variables. The accessor functions (getter and
537setter) are called on access to the hooked variables.
538
539 void rb_define_hooked_variable(const char *name, VALUE *var,
540 VALUE (*getter)(), void (*setter)())
541
542If you need to supply either setter or getter, just supply 0 for the
543hook you don't need. If both hooks are 0, rb_define_hooked_variable()
544works just like rb_define_variable().
545
546The prototypes of the getter and setter functions are as follows:
547
548 VALUE (*getter)(ID id, VALUE *var);
549 void (*setter)(VALUE val, ID id, VALUE *var);
550
551
552Also you can define a Ruby global variable without a corresponding C
553variable. The value of the variable will be set/get only by hooks.
554
555 void rb_define_virtual_variable(const char *name,
556 VALUE (*getter)(), void (*setter)())
557
558The prototypes of the getter and setter functions are as follows:
559
560 VALUE (*getter)(ID id);
561 void (*setter)(VALUE val, ID id);
562
563
564== Encapsulate C Data into a Ruby Object
565
566To wrap and objectify a C pointer as a Ruby object (so called
567DATA), use Data_Wrap_Struct().
568
569 Data_Wrap_Struct(klass, mark, free, sval)
570
571Data_Wrap_Struct() returns a created DATA object. The klass argument
572is the class for the DATA object. The mark argument is the function
573to mark Ruby objects pointed by this data. The free argument is the
574function to free the pointer allocation. If this is -1, the pointer
575will be just freed. The functions mark and free will be called from
576garbage collector.
577
578These mark / free functions are invoked during GC execution. No
579object allocations are allowed during it, so do not allocate ruby
580objects inside them.
581
582You can allocate and wrap the structure in one step.
583
584 Data_Make_Struct(klass, type, mark, free, sval)
585
586This macro returns an allocated Data object, wrapping the pointer to
587the structure, which is also allocated. This macro works like:
588
589 (sval = ALLOC(type), Data_Wrap_Struct(klass, mark, free, sval))
590
591Arguments klass, mark, and free work like their counterparts in
592Data_Wrap_Struct(). A pointer to the allocated structure will be
593assigned to sval, which should be a pointer of the type specified.
594
595To retrieve the C pointer from the Data object, use the macro
596Data_Get_Struct().
597
598 Data_Get_Struct(obj, type, sval)
599
600A pointer to the structure will be assigned to the variable sval.
601
602See the example below for details.
603
604= Example - Creating dbm Extension
605
606OK, here's the example of making an extension library. This is the
607extension to access DBMs. The full source is included in the ext/
608directory in the Ruby's source tree.
609
610== Make the Directory
611
612 % mkdir ext/dbm
613
614Make a directory for the extension library under ext directory.
615
616== Design the Library
617
618You need to design the library features, before making it.
619
620== Write the C Code
621
622You need to write C code for your extension library. If your library
623has only one source file, choosing ``LIBRARY.c'' as a file name is
624preferred. On the other hand, in case your library has multiple source
625files, avoid choosing ``LIBRARY.c'' for a file name. It may conflict
626with an intermediate file ``LIBRARY.o'' on some platforms.
627Note that some functions in mkmf library described below generate
628a file ``conftest.c'' for checking with compilation. You shouldn't
629choose ``conftest.c'' as a name of a source file.
630
631Ruby will execute the initializing function named ``Init_LIBRARY'' in
632the library. For example, ``Init_dbm()'' will be executed when loading
633the library.
634
635Here's the example of an initializing function.
636
637 void
638 Init_dbm(void)
639 {
640 /* define DBM class */
641 cDBM = rb_define_class("DBM", rb_cObject);
642 /* DBM includes Enumerate module */
643 rb_include_module(cDBM, rb_mEnumerable);
644
645 /* DBM has class method open(): arguments are received as C array */
646 rb_define_singleton_method(cDBM, "open", fdbm_s_open, -1);
647
648 /* DBM instance method close(): no args */
649 rb_define_method(cDBM, "close", fdbm_close, 0);
650 /* DBM instance method []: 1 argument */
651 rb_define_method(cDBM, "[]", fdbm_fetch, 1);
652
653 /* ... */
654
655 /* ID for a instance variable to store DBM data */
656 id_dbm = rb_intern("dbm");
657 }
658
659The dbm extension wraps the dbm struct in the C environment using
660Data_Make_Struct.
661
662 struct dbmdata {
663 int di_size;
664 DBM *di_dbm;
665 };
666
667 obj = Data_Make_Struct(klass, struct dbmdata, 0, free_dbm, dbmp);
668
669This code wraps the dbmdata structure into a Ruby object. We avoid
670wrapping DBM* directly, because we want to cache size information.
671
672To retrieve the dbmdata structure from a Ruby object, we define the
673following macro:
674
675 #define GetDBM(obj, dbmp) {\
676 Data_Get_Struct(obj, struct dbmdata, dbmp);\
677 if (dbmp->di_dbm == 0) closed_dbm();\
678 }
679
680This sort of complicated macro does the retrieving and close checking for
681the DBM.
682
683There are three kinds of way to receive method arguments. First,
684methods with a fixed number of arguments receive arguments like this:
685
686 static VALUE
687 fdbm_delete(VALUE obj, VALUE keystr)
688 {
689 /* ... */
690 }
691
692The first argument of the C function is the self, the rest are the
693arguments to the method.
694
695Second, methods with an arbitrary number of arguments receive
696arguments like this:
697
698 static VALUE
699 fdbm_s_open(int argc, VALUE *argv, VALUE klass)
700 {
701 /* ... */
702 if (rb_scan_args(argc, argv, "11", &file, &vmode) == 1) {
703 mode = 0666; /* default value */
704 }
705 /* ... */
706 }
707
708The first argument is the number of method arguments, the second
709argument is the C array of the method arguments, and the third
710argument is the receiver of the method.
711
712You can use the function rb_scan_args() to check and retrieve the
713arguments. The third argument is a string that specifies how to
714capture method arguments and assign them to the following VALUE
715references.
716
717
718The following is an example of a method that takes arguments by Ruby's
719array:
720
721 static VALUE
722 thread_initialize(VALUE thread, VALUE args)
723 {
724 /* ... */
725 }
726
727The first argument is the receiver, the second one is the Ruby array
728which contains the arguments to the method.
729
730*Notice*: GC should know about global variables which refer to Ruby's objects,
731but are not exported to the Ruby world. You need to protect them by
732
733 void rb_global_variable(VALUE *var)
734
735== Prepare extconf.rb
736
737If the file named extconf.rb exists, it will be executed to generate
738Makefile.
739
740extconf.rb is the file for checking compilation conditions etc. You
741need to put
742
743 require 'mkmf'
744
745at the top of the file. You can use the functions below to check
746various conditions.
747
748 have_macro(macro[, headers[, opt]]): check whether macro is defined
749 have_library(lib[, func[, headers[, opt]]]): check whether library containing function exists
750 find_library(lib[, func, *paths]): find library from paths
751 have_func(func[, headers[, opt]): check whether function exists
752 have_var(var[, headers[, opt]]): check whether variable exists
753 have_header(header[, preheaders[, opt]]): check whether header file exists
754 find_header(header, *paths): find header from paths
755 have_framework(fw): check whether framework exists (for MacOS X)
756 have_struct_member(type, member[, headers[, opt]]): check whether struct has member
757 have_type(type[, headers[, opt]]): check whether type exists
758 find_type(type, opt, *headers): check whether type exists in headers
759 have_const(const[, headers[, opt]]): check whether constant is defined
760 check_sizeof(type[, headers[, opts]]): check size of type
761 check_signedness(type[, headers[, opts]]): check signedness of type
762 convertible_int(type[, headers[, opts]]): find convertible integer type
763 find_executable(bin[, path]): find excutable file path
764 create_header(header): generate configured header
765 create_makefile(target[, target_prefix]): generate Makefile
766
767See MakeMakefile for full documentation of these functions.
768
769The value of the variables below will affect the Makefile.
770
771 $CFLAGS: included in CFLAGS make variable (such as -O)
772 $CPPFLAGS: included in CPPFLAGS make variable (such as -I, -D)
773 $LDFLAGS: included in LDFLAGS make variable (such as -L)
774 $objs: list of object file names
775
776Normally, the object files list is automatically generated by searching
777source files, but you must define them explicitly if any sources will
778be generated while building.
779
780If a compilation condition is not fulfilled, you should not call
781``create_makefile''. The Makefile will not be generated, compilation will
782not be done.
783
784== Prepare Depend (Optional)
785
786If the file named depend exists, Makefile will include that file to
787check dependencies. You can make this file by invoking
788
789 % gcc -MM *.c > depend
790
791It's harmless. Prepare it.
792
793== Generate Makefile
794
795Try generating the Makefile by:
796
797 ruby extconf.rb
798
799If the library should be installed under vendor_ruby directory
800instead of site_ruby directory, use --vendor option as follows.
801
802 ruby extconf.rb --vendor
803
804You don't need this step if you put the extension library under the ext
805directory of the ruby source tree. In that case, compilation of the
806interpreter will do this step for you.
807
808== Run make
809
810Type
811
812 make
813
814to compile your extension. You don't need this step either if you have
815put the extension library under the ext directory of the ruby source tree.
816
817== Debug
818
819You may need to rb_debug the extension. Extensions can be linked
820statically by adding the directory name in the ext/Setup file so that
821you can inspect the extension with the debugger.
822
823== Done! Now You Have the Extension Library
824
825You can do anything you want with your library. The author of Ruby
826will not claim any restrictions on your code depending on the Ruby API.
827Feel free to use, modify, distribute or sell your program.
828
829= Appendix A. Ruby Source Files Overview
830
831== Ruby Language Core
832
833class.c :: classes and modules
834error.c :: exception classes and exception mechanism
835gc.c :: memory management
836load.c :: library loading
837object.c :: objects
838variable.c :: variables and constants
839
840== Ruby Syntax Parser
841
842parse.y :: grammar definition
843parse.c :: automatically generated from parse.y
844keywords :: reserved keywords
845lex.c :: automatically generated from keywords
846
847== Ruby Evaluator (a.k.a. YARV)
848
849 compile.c
850 eval.c
851 eval_error.c
852 eval_jump.c
853 eval_safe.c
854 insns.def : definition of VM instructions
855 iseq.c : implementation of VM::ISeq
856 thread.c : thread management and context swiching
857 thread_win32.c : thread implementation
858 thread_pthread.c : ditto
859 vm.c
860 vm_dump.c
861 vm_eval.c
862 vm_exec.c
863 vm_insnhelper.c
864 vm_method.c
865
866 opt_insns_unif.def : instruction unification
867 opt_operand.def : definitions for optimization
868
869 -> insn*.inc : automatically generated
870 -> opt*.inc : automatically generated
871 -> vm.inc : automatically generated
872
873== Regular Expression Engine (Oniguruma)
874
875 regex.c
876 regcomp.c
877 regenc.c
878 regerror.c
879 regexec.c
880 regparse.c
881 regsyntax.c
882
883== Utility Functions
884
885debug.c :: debug symbols for C debuggger
886dln.c :: dynamic loading
887st.c :: general purpose hash table
888strftime.c :: formatting times
889util.c :: misc utilities
890
891== Ruby Interpreter Implementation
892
893 dmyext.c
894 dmydln.c
895 dmyencoding.c
896 id.c
897 inits.c
898 main.c
899 ruby.c
900 version.c
901
902 gem_prelude.rb
903 prelude.rb
904
905== Class Library
906
907array.c :: Array
908bignum.c :: Bignum
909compar.c :: Comparable
910complex.c :: Complex
911cont.c :: Fiber, Continuation
912dir.c :: Dir
913enum.c :: Enumerable
914enumerator.c :: Enumerator
915file.c :: File
916hash.c :: Hash
917io.c :: IO
918marshal.c :: Marshal
919math.c :: Math
920numeric.c :: Numeric, Integer, Fixnum, Float
921pack.c :: Array#pack, String#unpack
922proc.c :: Binding, Proc
923process.c :: Process
924random.c :: random number
925range.c :: Range
926rational.c :: Rational
927re.c :: Regexp, MatchData
928signal.c :: Signal
929sprintf.c :: String#sprintf
930string.c :: String
931struct.c :: Struct
932time.c :: Time
933
934defs/known_errors.def :: Errno::* exception classes
935-> known_errors.inc :: automatically generated
936
937== Multilingualization
938
939encoding.c :: Encoding
940transcode.c :: Encoding::Converter
941enc/*.c :: encoding classes
942enc/trans/* :: codepoint mapping tables
943
944== goruby Interpreter Implementation
945
946 goruby.c
947 golf_prelude.rb : goruby specific libraries.
948 -> golf_prelude.c : automatically generated
949
950
951= Appendix B. Ruby Extension API Reference
952
953== Types
954
955VALUE ::
956
957 The type for the Ruby object. Actual structures are defined in ruby.h,
958 such as struct RString, etc. To refer the values in structures, use
959 casting macros like RSTRING(obj).
960
961== Variables and Constants
962
963Qnil::
964 nil object
965
966Qtrue::
967 true object (default true value)
968
969Qfalse::
970 false object
971
972== C Pointer Wrapping
973
974Data_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval) ::
975
976 Wrap a C pointer into a Ruby object. If object has references to other
977 Ruby objects, they should be marked by using the mark function during
978 the GC process. Otherwise, mark should be 0. When this object is no
979 longer referred by anywhere, the pointer will be discarded by free
980 function.
981
982Data_Make_Struct(klass, type, mark, free, sval) ::
983
984 This macro allocates memory using malloc(), assigns it to the variable
985 sval, and returns the DATA encapsulating the pointer to memory region.
986
987Data_Get_Struct(data, type, sval) ::
988
989 This macro retrieves the pointer value from DATA, and assigns it to
990 the variable sval.
991
992== Checking Data Types
993
994TYPE(value) ::
995
996 Internal type (T_NIL, T_FIXNUM, etc.)
997
998FIXNUM_P(value) ::
999
1000 Is +value+ a Fixnum?
1001
1002NIL_P(value) ::
1003
1004 Is +value+ nil?
1005
1006void Check_Type(VALUE value, int type) ::
1007
1008 Ensures +value+ is of the given internal +type+ or raises a TypeError
1009
1010SaveStringValue(value) ::
1011
1012 Checks that +value+ is a String and is not tainted
1013
1014== Data Type Conversion
1015
1016FIX2INT(value), INT2FIX(i) ::
1017
1018 Fixnum <-> integer
1019
1020FIX2LONG(value), LONG2FIX(l) ::
1021
1022 Fixnum <-> long
1023
1024NUM2INT(value), INT2NUM(i) ::
1025
1026 Numeric <-> integer
1027
1028NUM2UINT(value), UINT2NUM(ui) ::
1029
1030 Numeric <-> unsigned integer
1031
1032NUM2LONG(value), LONG2NUM(l) ::
1033
1034 Numeric <-> long
1035
1036NUM2ULONG(value), ULONG2NUM(ul) ::
1037
1038 Numeric <-> unsigned long
1039
1040NUM2LL(value), LL2NUM(ll) ::
1041
1042 Numeric <-> long long
1043
1044NUM2ULL(value), ULL2NUM(ull) ::
1045
1046 Numeric <-> unsigned long long
1047
1048NUM2OFFT(value), OFFT2NUM(off) ::
1049
1050 Numeric <-> off_t
1051
1052NUM2SIZET(value), SIZET2NUM(size) ::
1053
1054 Numeric <-> size_t
1055
1056NUM2SSIZET(value), SSIZET2NUM(ssize) ::
1057
1058 Numeric <-> ssize_t
1059
1060NUM2DBL(value) ::
1061
1062 Numeric -> double
1063
1064rb_float_new(f) ::
1065
1066 double -> Float
1067
1068StringValue(value) ::
1069
1070 Object with #to_str -> String
1071
1072StringValuePtr(value) ::
1073
1074 Object with #to_str -> pointer to String data
1075
1076StringValueCStr(value) ::
1077
1078 Object with #to_str -> pointer to String data without NULL bytes
1079
1080rb_str_new2(s) ::
1081
1082 char * -> String
1083
1084== Defining Class and Module
1085
1086VALUE rb_define_class(const char *name, VALUE super) ::
1087
1088 Defines a new Ruby class as a subclass of super.
1089
1090VALUE rb_define_class_under(VALUE module, const char *name, VALUE super) ::
1091
1092 Creates a new Ruby class as a subclass of super, under the module's
1093 namespace.
1094
1095VALUE rb_define_module(const char *name) ::
1096
1097 Defines a new Ruby module.
1098
1099VALUE rb_define_module_under(VALUE module, const char *name) ::
1100
1101 Defines a new Ruby module under the module's namespace.
1102
1103void rb_include_module(VALUE klass, VALUE module) ::
1104
1105 Includes module into class. If class already includes it, just ignored.
1106
1107void rb_extend_object(VALUE object, VALUE module) ::
1108
1109 Extend the object with the module's attributes.
1110
1111== Defining Global Variables
1112
1113void rb_define_variable(const char *name, VALUE *var) ::
1114
1115 Defines a global variable which is shared between C and Ruby. If name
1116 contains a character which is not allowed to be part of the symbol,
1117 it can't be seen from Ruby programs.
1118
1119void rb_define_readonly_variable(const char *name, VALUE *var) ::
1120
1121 Defines a read-only global variable. Works just like
1122 rb_define_variable(), except the defined variable is read-only.
1123
1124void rb_define_virtual_variable(const char *name, VALUE (*getter)(), VALUE (*setter)()) ::
1125
1126 Defines a virtual variable, whose behavior is defined by a pair of C
1127 functions. The getter function is called when the variable is
1128 referenced. The setter function is called when the variable is set to a
1129 value. The prototype for getter/setter functions are:
1130
1131 VALUE getter(ID id)
1132 void setter(VALUE val, ID id)
1133
1134 The getter function must return the value for the access.
1135
1136void rb_define_hooked_variable(const char *name, VALUE *var, VALUE (*getter)(), VALUE (*setter)()) ::
1137
1138 Defines hooked variable. It's a virtual variable with a C variable.
1139 The getter is called as
1140
1141 VALUE getter(ID id, VALUE *var)
1142
1143 returning a new value. The setter is called as
1144
1145 void setter(VALUE val, ID id, VALUE *var)
1146
1147 GC requires C global variables which hold Ruby values to be marked.
1148
1149void rb_global_variable(VALUE *var)
1150
1151 Tells GC to protect these variables.
1152
1153== Constant Definition
1154
1155void rb_define_const(VALUE klass, const char *name, VALUE val) ::
1156
1157 Defines a new constant under the class/module.
1158
1159void rb_define_global_const(const char *name, VALUE val) ::
1160
1161 Defines a global constant. This is just the same as
1162
1163 rb_define_const(cKernal, name, val)
1164
1165== Method Definition
1166
1167rb_define_method(VALUE klass, const char *name, VALUE (*func)(), int argc) ::
1168
1169 Defines a method for the class. func is the function pointer. argc
1170 is the number of arguments. if argc is -1, the function will receive
1171 3 arguments: argc, argv, and self. if argc is -2, the function will
1172 receive 2 arguments, self and args, where args is a Ruby array of
1173 the method arguments.
1174
1175rb_define_private_method(VALUE klass, const char *name, VALUE (*func)(), int argc) ::
1176
1177 Defines a private method for the class. Arguments are same as
1178 rb_define_method().
1179
1180rb_define_singleton_method(VALUE klass, const char *name, VALUE (*func)(), int argc) ::
1181
1182 Defines a singleton method. Arguments are same as rb_define_method().
1183
1184rb_scan_args(int argc, VALUE *argv, const char *fmt, ...) ::
1185
1186 Retrieve argument from argc and argv to given VALUE references
1187 according to the format string. The format can be described in ABNF
1188 as follows:
1189
1190 scan-arg-spec := param-arg-spec [option-hash-arg-spec] [block-arg-spec]
1191
1192 param-arg-spec := pre-arg-spec [post-arg-spec] / post-arg-spec /
1193 pre-opt-post-arg-spec
1194 pre-arg-spec := num-of-leading-mandatory-args [num-of-optional-args]
1195 post-arg-spec := sym-for-variable-length-args
1196 [num-of-trailing-mandatory-args]
1197 pre-opt-post-arg-spec := num-of-leading-mandatory-args num-of-optional-args
1198 num-of-trailing-mandatory-args
1199 option-hash-arg-spec := sym-for-option-hash-arg
1200 block-arg-spec := sym-for-block-arg
1201
1202 num-of-leading-mandatory-args := DIGIT ; The number of leading
1203 ; mandatory arguments
1204 num-of-optional-args := DIGIT ; The number of optional
1205 ; arguments
1206 sym-for-variable-length-args := "*" ; Indicates that variable
1207 ; length arguments are
1208 ; captured as a ruby array
1209 num-of-trailing-mandatory-args := DIGIT ; The number of trailing
1210 ; mandatory arguments
1211 sym-for-option-hash-arg := ":" ; Indicates that an option
1212 ; hash is captured if the last
1213 ; argument is a hash or can be
1214 ; converted to a hash with
1215 ; #to_hash. When the last
1216 ; argument is nil, it is
1217 ; captured if it is not
1218 ; ambiguous to take it as
1219 ; empty option hash; i.e. '*'
1220 ; is not specified and
1221 ; arguments are given more
1222 ; than sufficient.
1223 sym-for-block-arg := "&" ; Indicates that an iterator
1224 ; block should be captured if
1225 ; given
1226
1227 For example, "12" means that the method requires at least one
1228 argument, and at most receives three (1+2) arguments. So, the format
1229 string must be followed by three variable references, which are to be
1230 assigned to captured arguments. For omitted arguments, variables are
1231 set to Qnil. NULL can be put in place of a variable reference, which
1232 means the corresponding captured argument(s) should be just dropped.
1233
1234 The number of given arguments, excluding an option hash or iterator
1235 block, is returned.
1236
1237== Invoking Ruby method
1238
1239VALUE rb_funcall(VALUE recv, ID mid, int narg, ...) ::
1240
1241 Invokes a method. To retrieve mid from a method name, use rb_intern().
1242
1243VALUE rb_funcall2(VALUE recv, ID mid, int argc, VALUE *argv) ::
1244
1245 Invokes a method, passing arguments by an array of values.
1246
1247VALUE rb_eval_string(const char *str) ::
1248
1249 Compiles and executes the string as a Ruby program.
1250
1251ID rb_intern(const char *name) ::
1252
1253 Returns ID corresponding to the name.
1254
1255char *rb_id2name(ID id) ::
1256
1257 Returns the name corresponding ID.
1258
1259char *rb_class2name(VALUE klass) ::
1260
1261 Returns the name of the class.
1262
1263int rb_respond_to(VALUE object, ID id) ::
1264
1265 Returns true if the object responds to the message specified by id.
1266
1267== Instance Variables
1268
1269VALUE rb_iv_get(VALUE obj, const char *name) ::
1270
1271 Retrieve the value of the instance variable. If the name is not
1272 prefixed by `@', that variable shall be inaccessible from Ruby.
1273
1274VALUE rb_iv_set(VALUE obj, const char *name, VALUE val) ::
1275
1276 Sets the value of the instance variable.
1277
1278== Control Structure
1279
1280VALUE rb_block_call(VALUE recv, ID mid, int argc, VALUE * argv, VALUE (*func) (ANYARGS), VALUE data2) ::
1281
1282 Calls a method on the recv, with the method name specified by the
1283 symbol mid, with argc arguments in argv, supplying func as the
1284 block. When func is called as the block, it will receive the value
1285 from yield as the first argument, and data2 as the second argument.
1286 When yielded with multiple values (in C, rb_yield_values(),
1287 rb_yield_values2() and rb_yield_splat()), data2 is packed as an Array,
1288 whereas yielded values can be gotten via argc/argv of the third/fourth
1289 arguments.
1290
1291[OBSOLETE] VALUE rb_iterate(VALUE (*func1)(), void *arg1, VALUE (*func2)(), void *arg2) ::
1292
1293 Calls the function func1, supplying func2 as the block. func1 will be
1294 called with the argument arg1. func2 receives the value from yield as
1295 the first argument, arg2 as the second argument.
1296
1297 When rb_iterate is used in 1.9, func1 has to call some Ruby-level method.
1298 This function is obsolete since 1.9; use rb_block_call instead.
1299
1300VALUE rb_yield(VALUE val) ::
1301
1302 Evaluates the block with value val.
1303
1304VALUE rb_rescue(VALUE (*func1)(), VALUE arg1, VALUE (*func2)(), VALUE arg2) ::
1305
1306 Calls the function func1, with arg1 as the argument. If an exception
1307 occurs during func1, it calls func2 with arg2 as the argument. The
1308 return value of rb_rescue() is the return value from func1 if no
1309 exception occurs, from func2 otherwise.
1310
1311VALUE rb_ensure(VALUE (*func1)(), VALUE arg1, VALUE (*func2)(), VALUE arg2) ::
1312
1313 Calls the function func1 with arg1 as the argument, then calls func2
1314 with arg2 if execution terminated. The return value from
1315 rb_ensure() is that of func1 when no exception occured.
1316
1317VALUE rb_protect(VALUE (*func) (VALUE), VALUE arg, int *state) ::
1318
1319 Calls the function func with arg as the argument. If no exception
1320 occured during func, it returns the result of func and *state is zero.
1321 Otherwise, it returns Qnil and sets *state to nonzero. If state is
1322 NULL, it is not set in both cases.
1323 You have to clear the error info with rb_set_errinfo(Qnil) when
1324 ignoring the caught exception.
1325
1326void rb_jump_tag(int state) ::
1327
1328 Continues the exception caught by rb_protect() and rb_eval_string_protect().
1329 state must be the returned value from those functions. This function
1330 never return to the caller.
1331
1332void rb_iter_break() ::
1333
1334 Exits from the current innermost block. This function never return to
1335 the caller.
1336
1337void rb_iter_break_value(VALUE value) ::
1338
1339 Exits from the current innermost block with the value. The block will
1340 return the given argument value. This function never return to the
1341 caller.
1342
1343== Exceptions and Errors
1344
1345void rb_warn(const char *fmt, ...) ::
1346
1347 Prints a warning message according to a printf-like format.
1348
1349void rb_warning(const char *fmt, ...) ::
1350
1351 Prints a warning message according to a printf-like format, if
1352 $VERBOSE is true.
1353
1354void rb_raise(rb_eRuntimeError, const char *fmt, ...) ::
1355
1356 Raises RuntimeError. The fmt is a format string just like printf().
1357
1358void rb_raise(VALUE exception, const char *fmt, ...) ::
1359
1360 Raises a class exception. The fmt is a format string just like printf().
1361
1362void rb_fatal(const char *fmt, ...) ::
1363
1364 Raises a fatal error, terminates the interpreter. No exception handling
1365 will be done for fatal errors, but ensure blocks will be executed.
1366
1367void rb_bug(const char *fmt, ...) ::
1368
1369 Terminates the interpreter immediately. This function should be
1370 called under the situation caused by the bug in the interpreter. No
1371 exception handling nor ensure execution will be done.
1372
1373Note: In the format string, %i is used for Object#to_s (or Object#inspect if
1374'+' flag is set) output (and related argument must be a VALUE). For integers
1375in format strings, use %d.
1376
1377== Initialize and Start the Interpreter
1378
1379The embedding API functions are below (not needed for extension libraries):
1380
1381void ruby_init() ::
1382
1383 Initializes the interpreter.
1384
1385void ruby_options(int argc, char **argv) ::
1386
1387 Process command line arguments for the interpreter.
1388
1389void ruby_run() ::
1390
1391 Starts execution of the interpreter.
1392
1393void ruby_script(char *name) ::
1394
1395 Specifies the name of the script ($0).
1396
1397== Hooks for the Interpreter Events
1398
1399 void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events,
1400 VALUE data)
1401
1402Adds a hook function for the specified interpreter events.
1403events should be OR'ed value of:
1404
1405 RUBY_EVENT_LINE
1406 RUBY_EVENT_CLASS
1407 RUBY_EVENT_END
1408 RUBY_EVENT_CALL
1409 RUBY_EVENT_RETURN
1410 RUBY_EVENT_C_CALL
1411 RUBY_EVENT_C_RETURN
1412 RUBY_EVENT_RAISE
1413 RUBY_EVENT_ALL
1414
1415The definition of rb_event_hook_func_t is below:
1416
1417 typedef void (*rb_event_hook_func_t)(rb_event_t event, VALUE data,
1418 VALUE self, ID id, VALUE klass)
1419
1420The third argument `data' to rb_add_event_hook() is passed to the hook
1421function as the second argument, which was the pointer to the current
1422NODE in 1.8. See RB_EVENT_HOOKS_HAVE_CALLBACK_DATA below.
1423
1424 int rb_remove_event_hook(rb_event_hook_func_t func)
1425
1426Removes the specified hook function.
1427
1428== Macros for Compatibility
1429
1430Some macros to check API compatibilities are available by default.
1431
1432NORETURN_STYLE_NEW ::
1433
1434 Means that NORETURN macro is functional style instead of prefix.
1435
1436HAVE_RB_DEFINE_ALLOC_FUNC ::
1437
1438 Means that function rb_define_alloc_func() is provided, that means the
1439 allocation framework is used. This is same as the result of
1440 have_func("rb_define_alloc_func", "ruby.h").
1441
1442HAVE_RB_REG_NEW_STR ::
1443
1444 Means that function rb_reg_new_str() is provided, that creates Regexp
1445 object from String object. This is same as the result of
1446 have_func("rb_reg_new_str", "ruby.h").
1447
1448HAVE_RB_IO_T ::
1449
1450 Means that type rb_io_t is provided.
1451
1452USE_SYMBOL_AS_METHOD_NAME ::
1453
1454 Means that Symbols will be returned as method names, e.g.,
1455 Module#methods, #singleton_methods and so on.
1456
1457HAVE_RUBY_*_H ::
1458
1459 Defined in ruby.h and means corresponding header is available. For
1460 instance, when HAVE_RUBY_ST_H is defined you should use ruby/st.h not
1461 mere st.h.
1462
1463RB_EVENT_HOOKS_HAVE_CALLBACK_DATA ::
1464
1465 Means that rb_add_event_hook() takes the third argument `data', to be
1466 passed to the given event hook function.
1467
1468/*
1469 * Local variables:
1470 * fill-column: 70
1471 * end:
1472 */
1473
1# README.EXT.ja - -*- RDoc -*- created at: Mon Aug 7 16:45:54 JST 1995
2
3Rubyの拡張ライブラリの作り方を説明します．
4
5= 基礎知識
6
7Cの変数には型があり，データには型がありません．ですから，た
8とえばポインタをintの変数に代入すると，その値は整数として取
9り扱われます．逆にRubyの変数には型がなく，データに型がありま
10す．この違いのため，CとRubyは相互に変換しなければ，お互いの
11データをアクセスできません．
12
13RubyのデータはVALUEというCの型で表現されます．VALUE型のデー
14タはそのデータタイプを自分で知っています．このデータタイプと
15いうのはデータ(オブジェクト)の実際の構造を意味していて，Ruby
16のクラスとはまた違ったものです．
17
18VALUEからCにとって意味のあるデータを取り出すためには
19
201. VALUEのデータタイプを知る
212. VALUEをCのデータに変換する
22
23の両方が必要です．(1)を忘れると間違ったデータの変換が行われ
24て，最悪プログラムがcore dumpします．
25
26== データタイプ
27
28Rubyにはユーザが使う可能性のある以下のタイプがあります．
29
30T_NIL :: nil
31T_OBJECT :: 通常のオブジェクト
32T_CLASS :: クラス
33T_MODULE :: モジュール
34T_FLOAT :: 浮動小数点数
35T_STRING :: 文字列
36T_REGEXP :: 正規表現
37T_ARRAY :: 配列
38T_HASH :: 連想配列
39T_STRUCT :: (Rubyの)構造体
40T_BIGNUM :: 多倍長整数
41T_FIXNUM :: Fixnum(31bitまたは63bit長整数)
42T_COMPLEX :: 複素数
43T_RATIONAL :: 有理数
44T_FILE :: 入出力
45T_TRUE :: 真
46T_FALSE :: 偽
47T_DATA :: データ
48T_SYMBOL :: シンボル
49
50その他に内部で利用されている以下のタイプがあります．
51
52 T_ICLASS
53 T_MATCH
54 T_UNDEF
55 T_NODE
56 T_ZOMBIE
57
58ほとんどのタイプはCの構造体で実装されています．
59
60== VALUEのデータタイプをチェックする
61
62ruby.hではTYPE()というマクロが定義されていて，VALUEのデータ
63タイプを知ることが出来ます．TYPE()マクロは上で紹介したT_XXXX
64の形式の定数を返します．VALUEのデータタイプに応じて処理する
65場合には，TYPE()の値で分岐することになります．
66
67 switch (TYPE(obj)) {
68 case T_FIXNUM:
69 /* FIXNUMの処理 */
70 break;
71 case T_STRING:
72 /* 文字列の処理 */
73 break;
74 case T_ARRAY:
75 /* 配列の処理 */
76 break;
77 default:
78 /* 例外を発生させる */
79 rb_raise(rb_eTypeError, "not valid value");
80 break;
81 }
82
83それとデータタイプをチェックして，正しくなければ例外を発生す
84る関数が用意されています．
85
86 void Check_Type(VALUE value, int type)
87
88この関数はvalueがtypeで無ければ，例外を発生させます．引数と
89して与えられたVALUEのデータタイプが正しいかどうかチェックす
90るためには，この関数を使います．
91
92FIXNUMとNILに関してはより高速な判別マクロが用意されています．
93
94 FIXNUM_P(obj)
95 NIL_P(obj)
96
97== VALUEをCのデータに変換する
98
99データタイプがT_NIL，T_FALSE，T_TRUEである時，データはそれぞ
100れnil，false，trueです．このデータタイプのオブジェクトはひと
101つずつしか存在しません．
102
103データタイプがT_FIXNUMの時，これは31bitまたは63bitのサイズを
104持つ整数です．longのサイズが32bitのプラットフォームであれば
10531bitに，longのサイズが64bitのプラットフォームであれば63bit
106になります. FIXNUM を C の整数に変換するためにはマクロ
107「FIX2INT()」または「FIX2LONG()」を使います．これらのマクロ
108を使用する際には事前にデータタイプがFIXNUMであることを確認す
109る必要がありますが，比較的高速に変換を行うことができます．ま
110た，「FIX2LONG()」は例外を発生しませんが，「FIX2INT()」は変
111換結果がintのサイズに収まらない場合には例外を発生します．
112それから，FIXNUMに限らずRubyのデータを整数に変換する
113「NUM2INT()」および「NUM2LONG()」というマクロがあります．こ
114れらのマクロはデータタイプのチェック無しで使えます
115(整数に変換できない場合には例外が発生する)．同様にチェック無
116で使える変換マクロはdoubleを取り出す「NUM2DBL()」があります．
117
118char* を取り出す場合， StringValue() と StringValuePtr()
119を使います．
120StringValue(var) は var が String
121であれば何もせず，そうでなければ var を var.to_str() の結果
122に置き換えるマクロ，StringValuePtr(var) は同様に var を
123String に置き換えてから var のバイト列表現に対する char* を
124返すマクロです．var の内容を直接置き換える処理が入るので，
125var は lvalue である必要があります．
126また，StringValuePtr() に類似した StringValueCStr() というマ
127クロもあります．StringValueCStr(var) は var を String に置き
128換えてから var の文字列表現に対する char* を返します．返され
129る文字列の末尾には nul 文字が付加されます．なお，途中に nul
130文字が含まれる場合は ArgumentError が発生します．
131一方，StringValuePtr() では，末尾に nul 文字がある保証はなく，
132途中に nul 文字が含まれている可能性もあります．
133
134それ以外のデータタイプは対応するCの構造体があります．対応す
135る構造体のあるVALUEはそのままキャスト(型変換)すれば構造体の
136ポインタに変換できます．
137
138構造体は「struct RXxxxx」という名前でruby.hで定義されていま
139す．例えば文字列は「struct RString」です．実際に使う可能性が
140あるのは文字列と配列くらいだと思います．
141
142ruby.hでは構造体へキャストするマクロも「RXXXXX()」(全部大文
143字にしたもの)という名前で提供されています(例: RSTRING())．
144
145構造体からデータを取り出すマクロが提供されています．文字列
146strの長さを得るためには「RSTRING_LEN(str)」とし，文字列strを
147char*として得るためには「RSTRING_PTR(str)」とします．配列の
148場合には，それぞれ「RARRAY_LEN(ary)」，「RARRAY_PTR(ary)」と
149なります．
150
151Rubyの構造体を直接アクセスする時に気をつけなければならないこ
152とは，配列や文字列の構造体の中身は参照するだけで，直接変更し
153ないことです．直接変更した場合，オブジェクトの内容の整合性が
154とれなくなって，思わぬバグの原因になります．
155
156== CのデータをVALUEに変換する
157
158VALUEの実際の構造は
159
160FIXNUMの場合 ::
161
162 1bit左シフトして，LSBを立てる．
163
164その他のポインタの場合 ::
165
166 そのままVALUEにキャストする．
167
168となっています．よって，LSBをチェックすればVALUEがFIXNUMかど
169うかわかるわけです(ポインタのLSBが立っていないことを仮定して
170いる)．
171
172ですから，FIXNUM以外のRubyのオブジェクトの構造体は単にVALUE
173にキャストするだけでVALUEに変換出来ます．ただし，任意の構造
174体がVALUEにキャスト出来るわけではありません．キャストするの
175はRubyの知っている構造体(ruby.hで定義されているstruct RXxxx
176のもの)だけです．
177
178FIXNUMに関しては変換マクロを経由する必要があります．Cの整数
179からVALUEに変換するマクロは以下のものがあります．必要に応じ
180て使い分けてください．
181
182INT2FIX() :: もとの整数が31bitまたは63bit以内に収まる自信
183 がある時
184INT2NUM() :: 任意の整数からVALUEへ
185
186INT2NUM()は整数がFIXNUMの範囲に収まらない場合，Bignumに変換
187してくれます(が，少し遅い)．
188
189== Rubyのデータを操作する
190
191先程も述べた通り，Rubyの構造体をアクセスする時に内容の更新を
192行うことは勧められません．で，Rubyのデータを操作する時には
193Rubyが用意している関数を用いてください．
194
195ここではもっとも使われるであろう文字列と配列の生成/操作を行
196い関数をあげます(全部ではないです)．
197
198=== 文字列に対する関数
199
200rb_str_new(const char *ptr, long len) ::
201
202 新しいRubyの文字列を生成する．
203
204rb_str_new2(const char *ptr)
205rb_str_new_cstr(const char *ptr)
206
207 Cの文字列からRubyの文字列を生成する．この関数の機能は
208 rb_str_new(ptr, strlen(ptr))と同等である．
209
210rb_tainted_str_new(const char *ptr, long len)
211
212 汚染マークが付加された新しいRubyの文字列を生成する．外部
213 からのデータに基づく文字列には汚染マークが付加されるべき
214 である．
215
216rb_tainted_str_new2(const char *ptr)
217rb_tainted_str_new_cstr(const char *ptr)
218
219 Cの文字列から汚染マークが付加されたRubyの文字列を生成する．
220
221rb_sprintf(const char *format, ...)
222rb_vsprintf(const char *format, va_list ap)
223
224 Cの文字列formatと続く引数をprintf(3)のフォーマットにしたがって
225 整形し，Rubyの文字列を生成する．
226
227 注意: %iはObject#to_s('+'フラグが指定されているときはObject#inspect)を
228 使ったVALUEの出力に使用されているため，整数には%dを使用すること．
229
230rb_str_cat(VALUE str, const char *ptr, long len)
231
232 Rubyの文字列strにlenバイトの文字列ptrを追加する．
233
234rb_str_cat2(VALUE str, const char* ptr)
235
236 Rubyの文字列strにCの文字列ptrを追加する．この関数の機能は
237 rb_str_cat(str, ptr, strlen(ptr))と同等である．
238
239rb_str_catf(VALUE str, const char* format, ...)
240rb_str_vcatf(VALUE str, const char* format, va_list ap)
241
242 Cの文字列formatと続く引数をprintf(3)のフォーマットにしたがって
243 整形し，Rubyの文字列strに追加する．この関数の機能は，それぞれ
244 rb_str_cat2(str, rb_sprintf(format, ...)) や
245 rb_str_cat2(str, rb_vsprintf(format, ap)) と同等である．
246
247rb_enc_str_new(const char *ptr, long len, rb_encoding *enc)
248
249 指定されたエンコーディングでRubyの文字列を生成する.
250
251rb_usascii_str_new(const char *ptr, long len)
252rb_usascii_str_new_cstr(const char *ptr)
253
254 エンコーディングがUS-ASCIIのRubyの文字列を生成する.
255
256rb_str_resize(VALUE str, long len)
257
258 Rubyの文字列のサイズをlenバイトに変更する．strの長さは前
259 以てセットされていなければならない．lenが元の長さよりも短
260 い時は，lenバイトを越えた部分の内容は捨てられる．lenが元
261 の長さよりも長い時は，元の長さを越えた部分の内容は保存さ
262 れないでゴミになるだろう．この関数の呼び出しによって
263 RSTRING_PTR(str)が変更されるかもしれないことに注意．
264
265rb_str_set_len(VALUE str, long len)
266
267 Rubyの文字列のサイズをlenバイトにセットする．strが変更可
268 能でなければ例外が発生する．RSTRING_LEN(str)とは無関係に，
269 lenバイトまでの内容は保存される．lenはstrの容量を越えてい
270 てはならない．
271
272
273== 配列に対する関数
274
275rb_ary_new()
276
277 要素が0の配列を生成する．
278
279rb_ary_new2(long len)
280
281 要素が0の配列を生成する．len要素分の領域をあらかじめ割り
282 当てておく．
283
284rb_ary_new3(long n, ...)
285
286 引数で指定したn要素を含む配列を生成する．
287
288rb_ary_new4(long n, VALUE *elts)
289
290 配列で与えたn要素の配列を生成する．
291
292rb_ary_to_ary(VALUE obj)
293
294 オブジェクトを配列に変換する.
295 Object#to_aryと同等である.
296
297他にも配列を操作する関数が多数ある. これらは
298引数aryに配列を渡さなければならない. さもないと
299コアを吐く.
300
301rb_ary_aref(argc, VALUE *argv, VALUE ary)
302
303 Array#[]と同等.
304
305rb_ary_entry(VALUE ary, long offset)
306
307 ary[offset]
308
309rb_ary_subseq(VALUE ary, long beg, long len)
310
311 ary[beg, len]
312
313rb_ary_push(VALUE ary, VALUE val)
314rb_ary_pop(VALUE ary)
315rb_ary_shift(VALUE ary)
316rb_ary_unshift(VALUE ary, VALUE val)
317
318rb_ary_cat(VALUE ary, const VALUE *ptr, long len)
319
320 配列aryにptrからlen個のオブジェクトを追加する．
321
322= Rubyの機能を使う
323
324原理的にRubyで書けることはCでも書けます．RubyそのものがCで記
325述されているんですから，当然といえば当然なんですけど．ここで
326はRubyの拡張に使うことが多いだろうと予測される機能を中心に紹
327介します．
328
329== Rubyに機能を追加する
330
331Rubyで提供されている関数を使えばRubyインタプリタに新しい機能
332を追加することができます．Rubyでは以下の機能を追加する関数が
333提供されています．
334
335* クラス，モジュール
336* メソッド，特異メソッドなど
337* 定数
338
339では順に紹介します．
340
341=== クラス/モジュール定義
342
343クラスやモジュールを定義するためには，以下の関数を使います．
344
345 VALUE rb_define_class(const char *name, VALUE super)
346 VALUE rb_define_module(const char *name)
347
348これらの関数は新しく定義されたクラスやモジュールを返します．
349メソッドや定数の定義にこれらの値が必要なので，ほとんどの場合
350は戻り値を変数に格納しておく必要があるでしょう．
351
352クラスやモジュールを他のクラスの内部にネストして定義する時に
353は以下の関数を使います．
354
355 VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)
356 VALUE rb_define_module_under(VALUE outer, const char *name)
357
358=== メソッド/特異メソッド定義
359
360メソッドや特異メソッドを定義するには以下の関数を使います．
361
362 void rb_define_method(VALUE klass, const char *name,
363 VALUE (*func)(), int argc)
364
365 void rb_define_singleton_method(VALUE object, const char *name,
366 VALUE (*func)(), int argc)
367
368
369念のため説明すると「特異メソッド」とは，その特定のオブジェク
370トに対してだけ有効なメソッドです．RubyではよくSmalltalkにお
371けるクラスメソッドとして，クラスに対する特異メソッドが使われ
372ます．
373
374これらの関数の argcという引数はCの関数へ渡される引数の数(と
375形式)を決めます．argcが0以上の時は関数に引き渡す引数の数を意
376味します．16個以上の引数は使えません(が，要りませんよね，そ
377んなに)．実際の関数には先頭の引数としてselfが与えられますの
378で，指定した数より1多い引数を持つことになります．
379
380argcが負の時は引数の数ではなく，形式を指定したことになります．
381argcが-1の時は引数を配列に入れて渡されます．argcが-2の時は引
382数はRubyの配列として渡されます．
383
384メソッドを定義する関数はまだいくつかあります. ひとつはメソッド
385名としてIDを取ります. IDについては2.2.2を参照.
386
387 void rb_define_method_id(VALUE klass, ID name,
388 VALUE (*func)(ANYARGS), int argc)
389
390private/protectedなメソッドを定義するふたつの関数があります.
391
392 void rb_define_private_method(VALUE klass, const char *name,
393 VALUE (*func)(), int argc)
394 void rb_define_protected_method(VALUE klass, const char *name,
395 VALUE (*func)(), int argc)
396
397privateメソッドとは関数形式でしか呼び出すことの出来ないメソッ
398ドです．
399
400最後に， rb_define_module関数はモジュール関数を定義します．
401モジュール関数とはモジュールの特異メソッドであり，同時に
402privateメソッドでもあるものです．例をあげるとMathモジュール
403のsqrt()などがあげられます．このメソッドは
404
405 Math.sqrt(4)
406
407という形式でも
408
409 include Math
410 sqrt(4)
411
412という形式でも使えます．モジュール関数を定義する関数は以下の
413通りです．
414
415 void rb_define_module_function(VALUE module, const char *name,
416 VALUE (*func)(), int argc)
417
418関数的メソッド(Kernelモジュールのprivate method)を定義するた
419めの関数は以下の通りです．
420
421 void rb_define_global_function(const char *name, VALUE (*func)(), int argc)
422
423
424メソッドの別名を定義するための関数は以下の通りです．
425
426 void rb_define_alias(VALUE module, const char* new, const char* old);
427
428属性の取得・設定メソッドを定義するには
429
430 void rb_define_attr(VALUE klass, const char *name, int read, int write)
431
432クラスメソッドallocateを定義したり削除したりするための関数は
433以下の通りです．
434
435 void rb_define_alloc_func(VALUE klass, VALUE (*func)(VALUE klass));
436 void rb_undef_alloc_func(VALUE klass);
437
438funcはクラスを引数として受け取って，新しく割り当てられたイン
439スタンスを返さなくてはなりません．このインスタンスは，外部リ
440ソースなどを含まない，できるだけ「空」のままにしておいたほう
441がよいでしょう．
442
443=== 定数定義
444
445拡張ライブラリが必要な定数はあらかじめ定義しておいた方が良い
446でしょう．定数を定義する関数は二つあります．
447
448 void rb_define_const(VALUE klass, const char *name, VALUE val)
449 void rb_define_global_const(const char *name, VALUE val)
450
451前者は特定のクラス/モジュールに属する定数を定義するもの，後
452者はグローバルな定数を定義するものです．
453
454== Rubyの機能をCから呼び出す
455
456既に『1.5 Rubyのデータを操作する』で一部紹介したような関数を
457使えば，Rubyの機能を実現している関数を直接呼び出すことが出来
458ます．
459
460# このような関数の一覧表はいまのところありません．ソースを見
461# るしかないですね．
462
463それ以外にもRubyの機能を呼び出す方法はいくつかあります．
464
465=== Rubyのプログラムをevalする
466
467CからRubyの機能を呼び出すもっとも簡単な方法として，文字列で
468与えられたRubyのプログラムを評価する以下の関数があります．
469
470 VALUE rb_eval_string(const char *str)
471
472この評価は現在の環境で行われます．つまり，現在のローカル変数
473などを受け継ぎます．
474
475評価は例外を発生するかもしれないことに注意しましょう. より安全
476な関数もあります.
477
478 VALUE rb_eval_string_protect(const char *str, int *state)
479
480この関数はエラーが発生するとnilを返します．そして，成功時には
481*stateはゼロに，さもなくば非ゼロになります．
482
483=== IDまたはシンボル
484
485Cから文字列を経由せずにRubyのメソッドを呼び出すこともできま
486す．その前に，Rubyインタプリタ内でメソッドや変数名を指定する
487時に使われているIDについて説明しておきましょう．
488
489IDとは変数名，メソッド名を表す整数です．Rubyの中では
490
491 :識別子
492
493または
494
495 :"任意の文字列"
496
497でアクセスできます．Cからこの整数を得るためには関数
498
499 rb_intern(const char *name)
500 rb_intern_str(VALUE name)
501
502を使います．Rubyから引数として与えられたシンボル(または文字
503列)をIDに変換するには以下の関数を使います．
504
505 rb_to_id(VALUE symbol)
506 rb_check_id(volatile VALUE *name)
507 rb_check_id_cstr(const char *name, long len, rb_encoding *enc)
508
509もし引数がシンボルでも文字列でもなければ、to_strメソッドで文
510字列に変換しようとします．第二の関数はその変換結果を*nameに保
511存し,その名前が既知のシンボルでない場合は0を返します．この関
512数が0以外を返した場合は*nameは常にシンボルか文字列であり、0を
513返した場合は常に文字列です．第三の関数はRubyの文字列ではなく
514NUL終端されたCの文字列を使います．
515
516=== CからRubyのメソッドを呼び出す
517
518Cから文字列を経由せずにRubyのメソッドを呼び出すためには以下
519の関数を使います．
520
521 VALUE rb_funcall(VALUE recv, ID mid, int argc, ...)
522
523この関数はオブジェクトrecvのmidで指定されるメソッドを呼び出
524します．その他に引数の指定の仕方が違う以下の関数もあります．
525
526 VALUE rb_funcall2(VALUE recv, ID mid, int argc, VALUE *argv)
527 VALUE rb_apply(VALUE recv, ID mid, VALUE args)
528
529applyには引数としてRubyの配列を与えます．
530
531=== 変数/定数を参照/更新する
532
533Cから関数を使って参照・更新できるのは，定数，インスタンス変
534数です．大域変数は一部のものはCの大域変数としてアクセスでき
535ます．ローカル変数を参照する方法は公開していません．
536
537オブジェクトのインスタンス変数を参照・更新する関数は以下の通
538りです．
539
540 VALUE rb_ivar_get(VALUE obj, ID id)
541 VALUE rb_ivar_set(VALUE obj, ID id, VALUE val)
542
543idはrb_intern()で得られるものを使ってください．
544
545定数を参照するには以下の関数を使ってください．
546
547 VALUE rb_const_get(VALUE obj, ID id)
548
549定数を新しく定義するためには『2.1.3 定数定義』で紹介さ
550れている関数を使ってください．
551
552= RubyとCとの情報共有
553
554C言語とRubyの間で情報を共有する方法について解説します．
555
556== Cから参照できるRubyの定数
557
558以下のRubyの定数はCのレベルから参照できます．
559
560 Qtrue
561 Qfalse
562
563真偽値．QfalseはC言語でも偽とみなされます(つまり0)．
564
565 Qnil
566
567C言語から見た「nil」．
568
569== CとRubyで共有される大域変数
570
571CとRubyで大域変数を使って情報を共有できます．共有できる大域
572変数にはいくつかの種類があります．そのなかでもっとも良く使わ
573れると思われるのはrb_define_variable()です．
574
575 void rb_define_variable(const char *name, VALUE *var)
576
577この関数はRubyとCとで共有する大域変数を定義します．変数名が
578`$'で始まらない時には自動的に追加されます．この変数の値を変
579更すると自動的にRubyの対応する変数の値も変わります．
580
581またRuby側からは更新できない変数もあります．このread onlyの
582変数は以下の関数で定義します．
583
584 void rb_define_readonly_variable(const char *name, VALUE *var)
585
586これら変数の他にhookをつけた大域変数を定義できます．hook付き
587の大域変数は以下の関数を用いて定義します．hook付き大域変数の
588値の参照や設定はhookで行う必要があります．
589
590 void rb_define_hooked_variable(const char *name, VALUE *var,
591 VALUE (*getter)(), void (*setter)())
592
593この関数はCの関数によってhookのつけられた大域変数を定義しま
594す．変数が参照された時には関数getterが，変数に値がセットされ
595た時には関数setterが呼ばれる．hookを指定しない場合はgetterや
596setterに0を指定します．
597# getterもsetterも0ならばrb_define_variable()と同じになる．
598
599getterとsetterの仕様は次の通りです．
600
601 VALUE (*getter)(ID id, VALUE *var);
602 void (*setter)(VALUE val, ID id, VALUE *var);
603
604
605それから，対応するCの変数を持たないRubyの大域変数を定義する
606こともできます. その変数の値はフック関数のみによって取得・設定
607されます.
608
609 void rb_define_virtual_variable(const char *name,
610 VALUE (*getter)(), void (*setter)())
611
612この関数によって定義されたRubyの大域変数が参照された時には
613getterが，変数に値がセットされた時にはsetterが呼ばれます．
614
615getterとsetterの仕様は以下の通りです．
616
617 (*getter)(ID id);
618 (*setter)(VALUE val, ID id);
619
620== CのデータをRubyオブジェクトにする
621
622Cの世界で定義されたデータ(構造体)をRubyのオブジェクトとして
623取り扱いたい場合がありえます．このような場合には，Dataという
624RubyオブジェクトにCの構造体(へのポインタ)をくるむことでRuby
625オブジェクトとして取り扱えるようになります．
626
627Dataオブジェクトを生成して構造体をRubyオブジェクトにカプセル
628化するためには，以下のマクロを使います．
629
630 Data_Wrap_Struct(klass, mark, free, sval)
631
632このマクロの戻り値は生成されたDataオブジェクトです．
633
634klassはこのDataオブジェクトのクラスです．markはこの構造体が
635Rubyのオブジェクトへの参照がある時に使う関数です．そのような
636参照を含まない時には0を指定します．
637
638# そのような参照は勧められません．
639
640freeはこの構造体がもう不要になった時に呼ばれる関数です．この
641関数がガーベージコレクタから呼ばれます．これが-1の場合は，単
642純に開放されます．
643
644markおよびfree関数はGC実行中に呼び出されます.
645なお, GC実行中はRubyオブジェクトのアロケーションは禁止されま
646す. よって, markおよびfree関数でRubyオブジェクトのアロケーシ
647ョンは行わないでください.
648
649Cの構造体の割当とDataオブジェクトの生成を同時に行うマクロと
650して以下のものが提供されています．
651
652 Data_Make_Struct(klass, type, mark, free, sval)
653
654このマクロの戻り値は生成されたDataオブジェクトです．このマク
655ロは以下の式のように働きます:
656
657 (sval = ALLOC(type), Data_Wrap_Struct(klass, mark, free, sval))
658
659klass, mark, freeはData_Wrap_Structと同じ働きをします．type
660は割り当てるC構造体の型です．割り当てられた構造体は変数sval
661に代入されます．この変数の型は (type*) である必要があります．
662
663Dataオブジェクトからポインタを取り出すのは以下のマクロを用い
664ます．
665
666 Data_Get_Struct(obj, type, sval)
667
668Cの構造体へのポインタは変数svalに代入されます．
669
670これらのDataの使い方はちょっと分かりにくいので，後で説明する
671例題を参照してください．
672
673= 例題 - dbmパッケージを作る
674
675ここまでの説明でとりあえず拡張ライブラリは作れるはずです．
676Rubyのextディレクトリにすでに含まれているdbmライブラリを例に
677して段階的に説明します．
678
679== ディレクトリを作る
680
681 % mkdir ext/dbm
682
683Ruby 1.1からは任意のディレクトリでダイナミックライブラリを作
684ることができるようになりました．Rubyに静的にリンクする場合に
685はRubyを展開したディレクトリの下，extディレクトリの中に拡張
686ライブラリ用のディレクトリを作る必要があります．名前は適当に
687選んで構いません．
688
689== 設計する
690
691まあ，当然なんですけど，どういう機能を実現するかどうかまず設
692計する必要があります．どんなクラスをつくるか，そのクラスには
693どんなメソッドがあるか，クラスが提供する定数などについて設計
694します．
695
696== Cコードを書く
697
698拡張ライブラリ本体となるC言語のソースを書きます．C言語のソー
699スがひとつの時には「ライブラリ名.c」を選ぶと良いでしょう．C
700言語のソースが複数の場合には逆に「ライブラリ名.c」というファ
701イル名は避ける必要があります．オブジェクトファイルとモジュー
702ル生成時に中間的に生成される「ライブラリ名.o」というファイル
703とが衝突するからです．また，後述する mkmf ライブラリのいくつ
704かの関数がコンパイルを要するテストのために「conftest.c」とい
705うファイル名を使用することに注意してください．ソースファイル
706名として「conftest.c」を使用してはなりません．
707
708Rubyは拡張ライブラリをロードする時に「Init_ライブラリ名」と
709いう関数を自動的に実行します．dbmライブラリの場合「Init_dbm」
710です．この関数の中でクラス，モジュール，メソッド，定数などの
711定義を行います．dbm.cから一部引用します．
712
713 void
714 Init_dbm(void)
715 {
716 /* DBMクラスを定義する */
717 cDBM = rb_define_class("DBM", rb_cObject);
718 /* DBMはEnumerateモジュールをインクルードする */
719 rb_include_module(cDBM, rb_mEnumerable);
720
721 /* DBMクラスのクラスメソッドopen(): 引数はCの配列で受ける */
722 rb_define_singleton_method(cDBM, "open", fdbm_s_open, -1);
723
724 /* DBMクラスのメソッドclose(): 引数はなし */
725 rb_define_method(cDBM, "close", fdbm_close, 0);
726 /* DBMクラスのメソッド[]: 引数は1個 */
727 rb_define_method(cDBM, "[]", fdbm_fetch, 1);
728
729 /* ... */
730
731 /* DBMデータを格納するインスタンス変数名のためのID */
732 id_dbm = rb_intern("dbm");
733 }
734
735DBMライブラリはdbmのデータと対応するオブジェクトになるはずで
736すから，Cの世界のdbmをRubyの世界に取り込む必要があります．
737
738dbm.cではData_Make_Structを以下のように使っています．
739
740 struct dbmdata {
741 int di_size;
742 DBM *di_dbm;
743 };
744
745
746 obj = Data_Make_Struct(klass, struct dbmdata, 0, free_dbm, dbmp);
747
748ここではdbmstruct構造体へのポインタをDataにカプセル化してい
749ます．DBM*を直接カプセル化しないのはclose()した時の処理を考
750えてのことです．
751
752Dataオブジェクトからdbmstruct構造体のポインタを取り出すため
753に以下のマクロを使っています．
754
755 #define GetDBM(obj, dbmp) {\
756 Data_Get_Struct(obj, struct dbmdata, dbmp);\
757 if (dbmp->di_dbm == 0) closed_dbm();\
758 }
759
760ちょっと複雑なマクロですが，要するにdbmdata構造体のポインタ
761の取り出しと，closeされているかどうかのチェックをまとめてい
762るだけです．
763
764DBMクラスにはたくさんメソッドがありますが，分類すると3種類の
765引数の受け方があります．ひとつは引数の数が固定のもので，例と
766してはdeleteメソッドがあります．deleteメソッドを実装している
767fdbm_delete()はこのようになっています．
768
769 static VALUE
770 fdbm_delete(VALUE obj, VALUE keystr)
771 {
772 /* ... */
773 }
774
775引数の数が固定のタイプは第1引数がself，第2引数以降がメソッド
776の引数となります．
777
778引数の数が不定のものはCの配列で受けるものとRubyの配列で受け
779るものとがあります．dbmライブラリの中で，Cの配列で受けるもの
780はDBMのクラスメソッドであるopen()です．これを実装している関
781数fdbm_s_open()はこうなっています．
782
783 static VALUE
784 fdbm_s_open(int argc, VALUE *argv, VALUE klass)
785 {
786 /* ... */
787
788 if (rb_scan_args(argc, argv, "11", &file, &vmode) == 1) {
789 mode = 0666; /* default value */
790 }
791
792 /* ... */
793 }
794
795このタイプの関数は第1引数が与えられた引数の数，第2引数が与え
796られた引数の入っている配列になります．selfは第3引数として与
797えられます．
798
799この配列で与えられた引数を解析するための関数がopen()でも使わ
800れているrb_scan_args()です．第3引数に指定したフォーマットに従
801い，第4変数以降に指定したVALUEへの参照に値を代入してくれま
802す．
803
804
805引数をRubyの配列として受け取るメソッドの例には
806Thread#initializeがあります．実装はこうです．
807
808 static VALUE
809 thread_initialize(VALUE thread, VALUE args)
810 {
811 /* ... */
812 }
813
814第1引数はself，第2引数はRubyの配列です．
815
816*注意事項*
817
818Rubyと共有はしないがRubyのオブジェクトを格納する可能性のある
819Cの大域変数は以下の関数を使ってRubyインタプリタに変数の存在
820を教えてあげてください．でないとGCでトラブルを起こします．
821
822 void rb_global_variable(VALUE *var)
823
824== extconf.rbを用意する
825
826Makefileを作る場合の雛型になるextconf.rbというファイルを作り
827ます．extconf.rbはライブラリのコンパイルに必要な条件のチェッ
828クなどを行うことが目的です．まず，
829
830 require 'mkmf'
831
832をextconf.rbの先頭に置きます．extconf.rbの中では以下のRuby関
833数を使うことが出来ます．
834
835 have_library(lib, func): ライブラリの存在チェック
836 have_func(func, header): 関数の存在チェック
837 have_header(header): ヘッダファイルの存在チェック
838 create_makefile(target[, target_prefix]): Makefileの生成
839
840以下の変数を使うことができます．
841
842 $CFLAGS: コンパイル時に追加的に指定するフラグ(-Oなど)
843 $CPPFLAGS: プリプロセッサに追加的に指定するフラグ(-Iや-Dなど)
844 $LDFLAGS: リンク時に追加的に指定するフラグ(-Lなど)
845 $objs: リンクされるオブジェクトファイル名のリスト
846
847オブジェクトファイルのリストは，通常はソースファイルを検索し
848て自動的に生成されますが，makeの途中でソースを生成するような
849場合は明示的に指定する必要があります．
850
851ライブラリをコンパイルする条件が揃わず，そのライブラリをコン
852パイルしない時にはcreate_makefileを呼ばなければMakefileは生
853成されず，コンパイルも行われません．
854
855== dependを用意する
856
857もし，ディレクトリにdependというファイルが存在すれば，
858Makefileが依存関係をチェックしてくれます．
859
860 % gcc -MM *.c > depend
861
862などで作ることが出来ます．あって損は無いでしょう．
863
864== Makefileを生成する
865
866Makefileを実際に生成するためには
867
868 ruby extconf.rb
869
870とします．extconf.rbに require 'mkmf' の行がない場合にはエラー
871になりますので，引数を追加して
872
873 ruby -r mkmf extconf.rb
874
875としてください．
876
877site_ruby ディレクトリでなく，
878vendor_ruby ディレクトリにインストールする場合には
879以下のように --vendor オプションを加えてください．
880
881 ruby extconf.rb --vendor
882
883ディレクトリをext以下に用意した場合にはRuby全体のmakeの時に
884自動的にMakefileが生成されますので，このステップは不要です．
885
886== makeする
887
888動的リンクライブラリを生成する場合にはその場でmakeしてくださ
889い．必要であれば make install でインストールされます．
890
891ext以下にディレクトリを用意した場合は，Rubyのディレクトリで
892makeを実行するとMakefileを生成からmake，必要によってはそのモ
893ジュールのRubyへのリンクまで自動的に実行してくれます．
894extconf.rbを書き換えるなどしてMakefileの再生成が必要な時はま
895たRubyディレクトリでmakeしてください．
896
897拡張ライブラリはmake installでRubyライブラリのディレクトリの
898下にコピーされます．もし拡張ライブラリと協調して使うRubyで記
899述されたプログラムがあり，Rubyライブラリに置きたい場合には，
900拡張ライブラリ用のディレクトリの下に lib というディレクトリ
901を作り，そこに 拡張子 .rb のファイルを置いておけば同時にイン
902ストールされます．
903
904== デバッグ
905
906まあ，デバッグしないと動かないでしょうね．ext/Setupにディレ
907クトリ名を書くと静的にリンクするのでデバッガが使えるようにな
908ります．その分コンパイルが遅くなりますけど．
909
910== できあがり
911
912後はこっそり使うなり，広く公開するなり，売るなり，ご自由にお
913使いください．Rubyの作者は拡張ライブラリに関して一切の権利を
914主張しません．
915
916= Appendix A. Rubyのソースコードの分類
917
918Rubyのソースはいくつかに分類することが出来ます．このうちクラ
919スライブラリの部分は基本的に拡張ライブラリと同じ作り方になっ
920ています．これらのソースは今までの説明でほとんど理解できると
921思います．
922
923== Ruby言語のコア
924
925class.c :: クラスとモジュール
926error.c :: 例外クラスと例外機構
927gc.c :: 記憶領域管理
928load.c :: ライブラリのロード
929object.c :: オブジェクト
930variable.c :: 変数と定数
931
932== Rubyの構文解析器
933
934 parse.y : 字句解析器と構文定義
935 -> parse.c : 自動生成
936 keywords : 予約語
937 -> lex.c : 自動生成
938
939== Rubyの評価器 (通称YARV)
940 compile.c
941 eval.c
942 eval_error.c
943 eval_jump.c
944 eval_safe.c
945 insns.def : 仮想機械語の定義
946 iseq.c : VM::ISeqの実装
947 thread.c : スレッド管理とコンテキスト切り替え
948 thread_win32.c : スレッド実装
949 thread_pthread.c : 同上
950 vm.c
951 vm_dump.c
952 vm_eval.c
953 vm_exec.c
954 vm_insnhelper.c
955 vm_method.c
956
957 opt_insns_unif.def : 命令融合
958 opt_operand.def : 最適化のための定義
959
960 -> insn*.inc : 自動生成
961 -> opt*.inc : 自動生成
962 -> vm.inc : 自動生成
963
964== 正規表現エンジン (鬼車)
965
966 regex.c
967 regcomp.c
968 regenc.c
969 regerror.c
970 regexec.c
971 regparse.c
972 regsyntax.c
973
974== ユーティリティ関数
975
976debug.c :: Cデバッガ用のデバッグシンボル
977dln.c :: 動的ローディング
978st.c :: 汎用ハッシュ表
979strftime.c :: 時刻整形
980util.c :: その他のユーティリティ
981
982== Rubyコマンドの実装
983
984 dmyext.c
985 dmydln.c
986 dmyencoding.c
987 id.c
988 inits.c
989 main.c
990 ruby.c
991 version.c
992
993 gem_prelude.rb
994 prelude.rb
995
996== クラスライブラリ
997
998array.c :: Array
999bignum.c :: Bignum
1000compar.c :: Comparable
1001complex.c :: Complex
1002cont.c :: Fiber, Continuation
1003dir.c :: Dir
1004enum.c :: Enumerable
1005enumerator.c :: Enumerator
1006file.c :: File
1007hash.c :: Hash
1008io.c :: IO
1009marshal.c :: Marshal
1010math.c :: Math
1011numeric.c :: Numeric, Integer, Fixnum, Float
1012pack.c :: Array#pack, String#unpack
1013proc.c :: Binding, Proc
1014process.c :: Process
1015random.c :: 乱数
1016range.c :: Range
1017rational.c :: Rational
1018re.c :: Regexp, MatchData
1019signal.c :: Signal
1020sprintf.c :: String#sprintf
1021string.c :: String
1022struct.c :: Struct
1023time.c :: Time
1024defs/known_errors.def :: 例外クラス Errno::*
1025-> known_errors.inc :: 自動生成
1026
1027== 多言語化
1028
1029encoding.c :: Encoding
1030transcode.c :: Encoding::Converter
1031enc/*.c :: エンコーディングクラス群
1032enc/trans/* :: コードポイント対応表
1033
1034== gorubyコマンドの実装
1035
1036 goruby.c
1037 golf_prelude.rb : goruby固有のライブラリ
1038 -> golf_prelude.c : 自動生成
1039
1040= Appendix B. 拡張用関数リファレンス
1041
1042C言語からRubyの機能を利用するAPIは以下の通りである．
1043
1044== 型
1045
1046VALUE ::
1047
1048 Rubyオブジェクトを表現する型．必要に応じてキャストして用いる．
1049 組み込み型を表現するCの型はruby.hに記述してあるRで始まる構造
1050 体である．VALUE型をこれらにキャストするためにRで始まる構造体
1051 名を全て大文字にした名前のマクロが用意されている．
1052
1053== 変数・定数
1054
1055Qnil ::
1056
1057 定数: nilオブジェクト
1058
1059Qtrue ::
1060
1061 定数: trueオブジェクト(真のデフォルト値)
1062
1063Qfalse ::
1064
1065 定数: falseオブジェクト
1066
1067== Cデータのカプセル化
1068
1069Data_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval) ::
1070
1071 Cの任意のポインタをカプセル化したRubyオブジェクトを返す．こ
1072 のポインタがRubyからアクセスされなくなった時，freeで指定した
1073 関数が呼ばれる．また，このポインタの指すデータが他のRubyオブ
1074 ジェクトを指している場合，markに指定する関数でマークする必要
1075 がある．
1076
1077Data_Make_Struct(klass, type, mark, free, sval) ::
1078
1079 type型のメモリをmallocし，変数svalに代入した後，それをカプセ
1080 ル化したデータを返すマクロ．
1081
1082Data_Get_Struct(data, type, sval) ::
1083
1084 dataからtype型のポインタを取り出し変数svalに代入するマクロ．
1085
1086== 型チェック
1087
1088 TYPE(value)
1089 FIXNUM_P(value)
1090 NIL_P(value)
1091 void Check_Type(VALUE value, int type)
1092 SafeStringValue(value)
1093
1094== 型変換
1095
1096 FIX2INT(value), INT2FIX(i)
1097 FIX2LONG(value), LONG2FIX(l)
1098 NUM2INT(value), INT2NUM(i)
1099 NUM2UINT(value), UINT2NUM(ui)
1100 NUM2LONG(value), LONG2NUM(l)
1101 NUM2ULONG(value), ULONG2NUM(ul)
1102 NUM2LL(value), LL2NUM(ll)
1103 NUM2ULL(value), ULL2NUM(ull)
1104 NUM2OFFT(value), OFFT2NUM(off)
1105 NUM2SIZET(value), SIZET2NUM(size)
1106 NUM2SSIZET(value), SSIZET2NUM(ssize)
1107 NUM2DBL(value)
1108 rb_float_new(f)
1109 StringValue(value)
1110 StringValuePtr(value)
1111 StringValueCStr(value)
1112 rb_str_new2(s)
1113
1114== クラス/モジュール定義
1115
1116VALUE rb_define_class(const char *name, VALUE super) ::
1117
1118 superのサブクラスとして新しいRubyクラスを定義する．
1119
1120VALUE rb_define_class_under(VALUE module, const char *name, VALUE super) ::
1121
1122 superのサブクラスとして新しいRubyクラスを定義し，moduleの
1123 定数として定義する．
1124
1125VALUE rb_define_module(const char *name) ::
1126
1127 新しいRubyモジュールを定義する．
1128
1129VALUE rb_define_module_under(VALUE module, const char *name) ::
1130
1131 新しいRubyモジュールを定義し，moduleの定数として定義する．
1132
1133void rb_include_module(VALUE klass, VALUE module) ::
1134
1135 モジュールをインクルードする．classがすでにmoduleをインク
1136 ルードしている時には何もしない(多重インクルードの禁止)．
1137
1138void rb_extend_object(VALUE object, VALUE module) ::
1139
1140 オブジェクトをモジュール(で定義されているメソッド)で拡張する．
1141
1142== 大域変数定義
1143
1144void rb_define_variable(const char *name, VALUE *var) ::
1145
1146 RubyとCとで共有するグローバル変数を定義する．変数名が`$'で
1147 始まらない時には自動的に追加される．nameとしてRubyの識別子
1148 として許されない文字(例えば` ')を含む場合にはRubyプログラ
1149 ムからは見えなくなる．
1150
1151void rb_define_readonly_variable(const char *name, VALUE *var) ::
1152
1153 RubyとCとで共有するread onlyのグローバル変数を定義する．
1154 read onlyであること以外はrb_define_variable()と同じ．
1155
1156void rb_define_virtual_variable(const char *name, VALUE (*getter)(), void (*setter)()) ::
1157
1158 関数によって実現されるRuby変数を定義する．変数が参照された
1159 時にはgetterが，変数に値がセットされた時にはsetterが呼ばれ
1160 る．
1161
1162void rb_define_hooked_variable(const char *name, VALUE *var, VALUE (*getter)(), void (*setter)()) ::
1163
1164 関数によってhookのつけられたグローバル変数を定義する．変数
1165 が参照された時にはgetterが，関数に値がセットされた時には
1166 setterが呼ばれる．getterやsetterに0を指定した時にはhookを
1167 指定しないのと同じ事になる．
1168
1169void rb_global_variable(VALUE *var)
1170
1171 GCのため，Rubyプログラムからはアクセスされないが, Rubyオブ
1172 ジェクトを含む大域変数をマークする．
1173
1174== 定数
1175
1176void rb_define_const(VALUE klass, const char *name, VALUE val) ::
1177
1178 定数を定義する．
1179
1180void rb_define_global_const(const char *name, VALUE val) ::
1181
1182 大域定数を定義する．
1183
1184 rb_define_const(rb_cObject, name, val)
1185
1186 と同じ意味．
1187
1188== メソッド定義
1189
1190rb_define_method(VALUE klass, const char *name, VALUE (*func)(), int argc) ::
1191
1192 メソッドを定義する．argcはselfを除く引数の数．argcが-1の時,
1193 関数には引数の数(selfを含まない)を第1引数, 引数の配列を第2
1194 引数とする形式で与えられる(第3引数はself)．argcが-2の時,
1195 第1引数がself, 第2引数がargs(argsは引数を含むRubyの配列)と
1196 いう形式で与えられる．
1197
1198rb_define_private_method(VALUE klass, const char *name, VALUE (*func)(), int argc) ::
1199
1200 privateメソッドを定義する．引数はrb_define_method()と同じ．
1201
1202rb_define_singleton_method(VALUE klass, const char *name, VALUE (*func)(), int argc) ::
1203
1204 特異メソッドを定義する．引数はrb_define_method()と同じ．
1205
1206rb_scan_args(int argc, VALUE *argv, const char *fmt, ...) ::
1207
1208 argc, argv形式で与えられた指定されたフォーマットに従って引
1209 数を分解し，続くVALUEへの参照にセットします．このフォーマッ
1210 トは，ABNFで記述すると以下の通りです．
1211
1212 scan-arg-spec := param-arg-spec [option-hash-arg-spec] [block-arg-spec]
1213
1214 param-arg-spec := pre-arg-spec [post-arg-spec] / post-arg-spec /
1215 pre-opt-post-arg-spec
1216 pre-arg-spec := num-of-leading-mandatory-args [num-of-optional-args]
1217 post-arg-spec := sym-for-variable-length-args
1218 [num-of-trailing-mandatory-args]
1219 pre-opt-post-arg-spec := num-of-leading-mandatory-args num-of-optional-args
1220 num-of-trailing-mandatory-args
1221 option-hash-arg-spec := sym-for-option-hash-arg
1222 block-arg-spec := sym-for-block-arg
1223
1224 num-of-leading-mandatory-args := DIGIT ; 先頭に置かれる省略不能な引数の数
1225 num-of-optional-args := DIGIT ; 続いて置かれる省略可能な引数の数
1226 sym-for-variable-length-args := "*" ; 続いて置かれる可変長引数を
1227 ; Rubyの配列で取得するための指定
1228 num-of-trailing-mandatory-args := DIGIT ; 終端に置かれる省略不能な引数の数
1229 sym-for-option-hash-arg := ":" ; オプションハッシュを取得する
1230 ; ための指定; 省略不能な引数の
1231 ; 数よりも多くの引数が指定され，
1232 ; 最後の引数がハッシュ（または
1233 ; #to_hashで変換可能）の場合に
1234 ; 取得される．最後の引数がnilの
1235 ; 場合，可変長引数指定がなく，
1236 ; 省略不能引数の数よりも多くの
1237 ; 引数が指定された場合に取得される
1238 sym-for-block-arg := "&" ; イテレータブロックを取得するための
1239 ; 指定
1240
1241 フォーマットが"12"の場合，引数は最低1つで，3つ(1+2)まで許さ
1242 れるという意味になります．従って，フォーマット文字列に続い
1243 て3つのVALUEへの参照を置く必要があります．それらには取得した
1244 変数がセットされます．変数への参照の代わりにNULLを指定する
1245 こともでき，その場合は取得した引数の値は捨てられます．なお，
1246 省略可能引数が省略された時の変数の値はnil(C言語のレベルでは
1247 Qnil)になります．
1248
1249 返り値は与えられた引数の数です．オプションハッシュおよびイ
1250 テレータブロックは数えません．
1251
1252== Rubyメソッド呼び出し
1253
1254VALUE rb_funcall(VALUE recv, ID mid, int narg, ...) ::
1255
1256 メソッド呼び出し．文字列からmidを得るためにはrb_intern()を
1257 使う．
1258
1259VALUE rb_funcall2(VALUE recv, ID mid, int argc, VALUE *argv) ::
1260
1261 メソッド呼び出し．引数をargc, argv形式で渡す．
1262
1263VALUE rb_eval_string(const char *str)
1264
1265 文字列をRubyスクリプトとしてコンパイル・実行する．
1266
1267ID rb_intern(const char *name) ::
1268
1269 文字列に対応するIDを返す．
1270
1271char *rb_id2name(ID id) ::
1272
1273 IDに対応する文字列を返す(デバッグ用)．
1274
1275char *rb_class2name(VALUE klass) ::
1276
1277 クラスの名前を返す(デバッグ用)．クラスが名前を持たない時に
1278 は, 祖先を遡って名前を持つクラスの名前を返す．
1279
1280int rb_respond_to(VALUE obj, ID id) ::
1281
1282 objがidで示されるメソッドを持つかどうかを返す．
1283
1284== インスタンス変数
1285
1286VALUE rb_iv_get(VALUE obj, const char *name) ::
1287
1288 objのインスタンス変数の値を得る．`@'で始まらないインスタン
1289 ス変数は Rubyプログラムからアクセスできない「隠れた」イン
1290 スタンス変数になる．定数は大文字の名前を持つクラス(または
1291 モジュール)のインスタンス変数として実装されている．
1292
1293VALUE rb_iv_set(VALUE obj, const char *name, VALUE val) ::
1294
1295 objのインスタンス変数をvalにセットする．
1296
1297== 制御構造
1298
1299VALUE rb_block_call(VALUE obj, ID mid, int argc, VALUE * argv, VALUE (*func) (ANYARGS), VALUE data2) ::
1300
1301 funcをブロックとして設定し，objをレシーバ，argcとargvを引数
1302 としてmidメソッドを呼び出す．funcは第一引数にyieldされた値，
1303 第二引数にdata2を受け取る．複数の値がyieldされた場合(Cでは
1304 rb_yield_values()とrb_yield_values2(), rb_yield_splat())，
1305 data2はArrayとしてパックされている．第三, 第四引数のargcと
1306 argvによってyieldされた値を取り出すことができる．
1307
1308[OBSOLETE] VALUE rb_iterate(VALUE (*func1)(), VALUE arg1, VALUE (*func2)(), VALUE arg2) ::
1309
1310 func2をブロックとして設定し, func1をイテレータとして呼ぶ．
1311 func1には arg1が引数として渡され, func2には第1引数にイテレー
1312 タから与えられた値, 第2引数にarg2が渡される．
1313
1314 1.9でrb_iterateを使う場合は, func1の中でRubyレベルのメソッド
1315 を呼び出さなければならない.
1316 1.9でobsoleteとなった. 代わりにrb_block_callが用意された.
1317
1318VALUE rb_yield(VALUE val) ::
1319
1320 valを値としてイテレータブロックを呼び出す．
1321
1322VALUE rb_rescue(VALUE (*func1)(), VALUE arg1, VALUE (*func2)(), VALUE arg2) ::
1323
1324 関数func1をarg1を引数に呼び出す．func1の実行中に例外が発生
1325 した時には func2をarg2を引数として呼ぶ．戻り値は例外が発生
1326 しなかった時はfunc1の戻り値, 例外が発生した時にはfunc2の戻
1327 り値である．
1328
1329VALUE rb_ensure(VALUE (*func1)(), VALUE arg1, VALUE (*func2)(), VALUE arg2) ::
1330
1331 関数func1をarg1を引数として実行し, 実行終了後(たとえ例外が
1332 発生しても) func2をarg2を引数として実行する．戻り値はfunc1
1333 の戻り値である(例外が発生した時は戻らない)．
1334
1335VALUE rb_protect(VALUE (*func) (VALUE), VALUE arg, int *state) ::
1336
1337 関数funcをargを引数として実行し, 例外が発生しなければその戻
1338 り値を返す．例外が発生した場合は, *stateに非0をセットして
1339 Qnilを返す．
1340 rb_jump_tag()を呼ばずに捕捉した例外を無視する場合には，
1341 rb_set_errinfo(Qnil)でエラー情報をクリアしなければならない．
1342
1343void rb_jump_tag(int state) ::
1344
1345 rb_protect()やrb_eval_string_protect()で捕捉された例外を再
1346 送する．stateはそれらの関数から返された値でなければならない．
1347 この関数は直接の呼び出し元に戻らない．
1348
1349void rb_iter_break() ::
1350
1351 現在の最も内側のブロックを終了する．この関数は直接の呼び出
1352 し元に戻らない．
1353
1354void rb_iter_break_value(VALUE value) ::
1355
1356 現在の最も内側のブロックをvalueで終了する．ブロックは引数で
1357 与えられたvalueを返す．この関数は直接の呼び出し元に戻らない．
1358
1359== 例外・エラー
1360
1361void rb_warning(const char *fmt, ...) ::
1362
1363 rb_verbose時に標準エラー出力に警告情報を表示する．引数は
1364 printf()と同じ．
1365
1366void rb_raise(rb_eRuntimeError, const char *fmt, ...) ::
1367
1368 RuntimeError例外を発生させる．引数はprintf()と同じ．
1369
1370void rb_raise(VALUE exception, const char *fmt, ...) ::
1371
1372 exceptionで指定した例外を発生させる．fmt以下の引数は
1373 printf()と同じ．
1374
1375void rb_fatal(const char *fmt, ...) ::
1376
1377 致命的例外を発生させる．通常の例外処理は行なわれず, インター
1378 プリタが終了する(ただしensureで指定されたコードは終了前に
1379 実行される)．
1380
1381void rb_bug(const char *fmt, ...) ::
1382
1383 インタープリタなどプログラムのバグでしか発生するはずのない
1384 状況の時呼ぶ．インタープリタはコアダンプし直ちに終了する．
1385 例外処理は一切行なわれない．
1386
1387注意: %iはObject#to_s('+'フラグが指定されているときはObject#inspect)を
1388使ったVALUEの出力に使用されているため，整数には%dを使用すること．
1389
1390== Rubyの初期化・実行
1391
1392Rubyをアプリケーションに埋め込む場合には以下のインタフェース
1393を使う．通常の拡張ライブラリには必要ない．
1394
1395void ruby_init() ::
1396
1397 Rubyインタプリタの初期化を行なう．
1398
1399void ruby_options(int argc, char **argv) ::
1400
1401 Rubyインタプリタのコマンドライン引数の処理を行なう．
1402
1403void ruby_run() ::
1404
1405 Rubyインタプリタを実行する．
1406
1407void ruby_script(char *name) ::
1408
1409 Rubyのスクリプト名($0)を設定する．
1410
1411== インタプリタのイベントのフック
1412
1413 void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events,
1414 VALUE data)
1415
1416指定されたインタプリタのイベントに対するフック関数を追加します．
1417eventsは以下の値のorでなければなりません:
1418
1419 RUBY_EVENT_LINE
1420 RUBY_EVENT_CLASS
1421 RUBY_EVENT_END
1422 RUBY_EVENT_CALL
1423 RUBY_EVENT_RETURN
1424 RUBY_EVENT_C_CALL
1425 RUBY_EVENT_C_RETURN
1426 RUBY_EVENT_RAISE
1427 RUBY_EVENT_ALL
1428
1429rb_event_hook_func_tの定義は以下の通りです:
1430
1431 typedef void (*rb_event_hook_func_t)(rb_event_t event, VALUE data,
1432 VALUE self, ID id, VALUE klass)
1433
1434rb_add_event_hook() の第3引数 data は，フック関数の第2引数と
1435して渡されます．これは1.8では現在のNODEへのポインタでした．以
1436下の RB_EVENT_HOOKS_HAVE_CALLBACK_DATA も参照してください．
1437
1438 int rb_remove_event_hook(rb_event_hook_func_t func)
1439
1440指定されたフック関数を削除します．
1441
1442== 互換性のためのマクロ
1443
1444APIの互換性をチェックするために以下のマクロがデフォルトで定義されています．
1445
1446NORETURN_STYLE_NEW ::
1447
1448 NORETURN マクロが関数型マクロとして定義されていることを意味する．
1449
1450HAVE_RB_DEFINE_ALLOC_FUNC ::
1451
1452 rb_define_alloc_func() 関数が提供されていること，つまり
1453 allocation framework が使われることを意味する．
1454 have_func("rb_define_alloc_func", "ruby.h")
1455 の結果と同じ．
1456
1457HAVE_RB_REG_NEW_STR ::
1458
1459 StringオブジェクトからRegexpオブジェクトを作る
1460 rb_reg_new_str() 関数が提供されていることを意味する．
1461 have_func("rb_reg_new_str", "ruby.h").
1462 の結果と同じ．
1463
1464HAVE_RB_IO_T ::
1465
1466 rb_io_t 型が提供されていることを意味する．
1467
1468USE_SYMBOL_AS_METHOD_NAME ::
1469
1470 メソッド名を返すメソッド，Module#methods, #singleton_methods
1471 などがSymbolを返すことを意味する．
1472
1473HAVE_RUBY_*_H ::
1474
1475 ruby.h で定義されている．対応するヘッダが提供されていること
1476 を意味する．たとえば，HAVE_RUBY_ST_H が定義されている場合は
1477 単なる st.h ではなく ruby/st.h を使用する．
1478
1479RB_EVENT_HOOKS_HAVE_CALLBACK_DATA ::
1480
1481 rb_add_event_hook() がフック関数に渡す data を第3引数として
1482 受け取ることを意味する．
1483
1484= Appendix C. extconf.rbで使える関数たち
1485
1486extconf.rbの中では利用可能なコンパイル条件チェックの関数は以
1487下の通りである．
1488
1489have_macro(macro, headers) ::
1490
1491 ヘッダファイルheaderをインクルードしてマクロmacroが定義さ
1492 れているかどうかチェックする．マクロが定義されている時true
1493 を返す．
1494
1495have_library(lib, func) ::
1496
1497 関数funcを定義しているライブラリlibの存在をチェックする．
1498 ライブラリが存在する時，trueを返す．
1499
1500find_library(lib, func, path...) ::
1501
1502 関数funcを定義しているライブラリlibの存在を -Lpath を追加
1503 しながらチェックする．ライブラリが見付かった時，trueを返す．
1504
1505have_func(func, header) ::
1506
1507 ヘッダファイルheaderをインクルードして関数funcの存在をチェ
1508 ックする．funcが標準ではリンクされないライブラリ内のもので
1509 ある時には先にhave_libraryでそのライブラリをチェックしてお
1510 く事．関数が存在する時trueを返す．
1511
1512have_var(var, header) ::
1513
1514 ヘッダファイルheaderをインクルードして変数varの存在をチェッ
1515 クする．varが標準ではリンクされないライブラリ内のものであ
1516 る時には先にhave_libraryでそのライブラリをチェックしておく
1517 事．変数が存在する時trueを返す．
1518
1519have_header(header) ::
1520
1521 ヘッダファイルの存在をチェックする．ヘッダファイルが存在す
1522 る時trueを返す．
1523
1524find_header(header, path...) ::
1525
1526 ヘッダファイルheaderの存在を -Ipath を追加しながらチェック
1527 する．ヘッダファイルが見付かった時，trueを返す．
1528
1529have_struct_member(type, member[, header[, opt]]) ::
1530
1531 ヘッダファイルheaderをインクルードして型typeにメンバmember
1532 が存在するかをチェックする．typeが定義されていて，memberを
1533 持つする時trueを返す．
1534
1535have_type(type, header, opt) ::
1536
1537 ヘッダファイルheaderをインクルードして型typeが存在するかを
1538 チェックする．typeが定義されている時trueを返す．
1539
1540check_sizeof(type, header) ::
1541
1542 ヘッダファイルheaderをインクルードして型typeのchar単位サイ
1543 ズを調べる．typeが定義されている時そのサイズを返す．定義さ
1544 れていないときはnilを返す．
1545
1546create_makefile(target[, target_prefix]) ::
1547
1548 拡張ライブラリ用のMakefileを生成する．この関数を呼ばなけれ
1549 ばそのライブラリはコンパイルされない．targetはモジュール名
1550 を表す．
1551
1552find_executable(command, path) ::
1553
1554 コマンドcommandをFile::PATH_SEPARATORで区切られたパス名の
1555 リストpathから探す．pathがnilまたは省略された場合は，環境
1556 変数PATHの値を使用する．実行可能なコマンドが見つかった場合
1557 はパスを含むファイル名，見つからなかった場合はnilを返す．
1558
1559with_config(withval[, default=nil]) ::
1560
1561 コマンドライン上の--with-<withval>で指定されたオプション値
1562 を得る．
1563
1564enable_config(config, *defaults) ::
1565disable_config(config, *defaults) ::
1566
1567 コマンドライン上の--enable-<config>または
1568 --disable-<config>で指定された真偽値を得る．
1569 --enable-<config>が指定されていた場合はtrue，
1570 --disable-<config>が指定されていた場合はfalseを返す．
1571 どちらも指定されていない場合は，ブロックつきで呼び出されて
1572 いる場合は*defaultsをyieldした結果，ブロックなしなら
1573 *defaultsを返す．
1574
1575dir_config(target[, default_dir]) ::
1576dir_config(target[, default_include, default_lib]) ::
1577
1578 コマンドライン上の--with-<target>-dir, --with-<target>-include,
1579 --with-<target>-libのいずれかで指定されるディレクトリを
1580 $CFLAGS や $LDFLAGS に追加する．--with-<target>-dir=/pathは
1581 --with-<target>-include=/path/include --with-<target>-lib=/path/lib
1582 と等価である．追加された include ディレクトリと lib ディレ
1583 クトリの配列を返す． ([include_dir, lib_dir])
1584
1585pkg_config(pkg) ::
1586
1587 pkg-configコマンドからパッケージpkgの情報を得る．
1588 pkg-configの実際のコマンド名は，--with-pkg-configコマンド
1589 ラインオプションで指定可能．
1590
1591/*
1592 * Local variables:
1593 * fill-column: 60
1594 * end:
1595 */
1596