diff options
Diffstat (limited to 'README.EXT')
-rw-r--r-- | README.EXT | 492 |
1 files changed, 224 insertions, 268 deletions
diff --git a/README.EXT b/README.EXT index f169e54995..241d6fa8cd 100644 --- a/README.EXT +++ b/README.EXT @@ -1,8 +1,8 @@ .\" README.EXT - -*- Text -*- created at: Mon Aug 7 16:45:54 JST 1995 -This document explains how to make extention modules for Ruby. +This document explains how to make extention libraries for Ruby. -1��Basic knowledge +1. Basic knowledge In C, variables have types and data do not have types. In contrast, Ruby variables do not have static type and data themselves have @@ -109,35 +109,29 @@ bugs. 1.4 Convert C data into VALUE -VALUE�μºݤι�¤�� +To convert C data to the values of Ruby: - * FIXNUM�ξ�� + * FIXNUM - 1bit�����եȤ��ơ�LSB��Ω�Ƥ롥 + left shift 1 bit, and turn on LSB. - * ����¾�Υݥ��ξ�� + * Other pointer values - ���Τޤ�VALUE�˥��㥹�Ȥ��롥 + cast to VALUE. -�ȤʤäƤ��ޤ�����äơ�LSB������å������VALUE��FIXNUM���� -�����狼��櫓�Ǥ�(�ݥ���LSB��Ω�äƤ��ʤ����Ȥ��ꤷ�� -����)�� +You can determine whether VALUE is pointer or not, by checking LSB. -�Ǥ����顤FIXNUM�ʳ���Ruby�Υ��֥������Ȥι�¤�Τ�ñ��VALUE -�˥��㥹�Ȥ��������VALUE���Ѵ�����ޤ�����������Ǥ�դι�¤ -�Τ�VALUE�˥��㥹�Ƚ����櫓�ǤϤ���ޤ����㥹�Ȥ���� -��Ruby���ΤäƤ��빽¤��(ruby.h���������Ƥ���struct RXxxx -�Τ��)�����ˤ��Ƥ����Ƥ��������� +Notice Ruby does not allow arbitrary pointer value to be VALUE. They +should be pointers to the structures which Ruby knows. The known +structures are defined in <ruby.h>. -FIXNUM�˴ؤ��Ƥ��Ѵ��ޥ������ͳ����ɬ�פ�����ޤ���C������ -����VALUE���Ѵ�����ޥ����ϰʲ��Τ�Τ�����ޤ���ɬ�פ˱��� -�ƻȤ�ʬ���Ƥ��������� +To convert C numbers to Ruby value, use these macros. - INT2FIX() ��Ȥ�������31bit����˼��ޤ�� - INT2NUM() Ǥ�դ���������VALUE�� + INT2FIX() for intergers within 31bits. + INT2NUM() for arbitrary sized integer. -INT2NUM()��������FIXNUM���ϰϤ˼��ޤ�ʤ���硤Bignum���Ѵ� -���Ƥ���ޤ�(���������٤�)�� +INT2NUM() converts integers into Bignums, if it is out of FIXNUM +range, but bit slower. 1.5 Manipulate Ruby data @@ -190,23 +184,15 @@ interpreter. Useful functions are listed below (not all): 2. Extend Ruby with C -����Ū��Ruby�ǽ뤳�Ȥ�C�Ǥ�ޤ���Ruby���Τ�Τ�C�ǵ� -�Ҥ���Ƥ����Ǥ����顤�����Ȥ����������ʤ�Ǥ����ɡ������� -��Ruby�γ�ĥ�˻Ȥ����Ȥ�¿����������ͽ¬����뵡ǽ���濴�˾� -�𤷤ޤ��� - 2.1 Add new features to Ruby -Ruby������Ƥ���ؿ���Ȥ���Ruby���ץ�˿�������ǽ -���ɲä��뤳�Ȥ��Ǥ��ޤ���Ruby�Ǥϰʲ��ε�ǽ���ɲä���ؿ��� -����Ƥ��ޤ��� +You can add new features (classes, methods, etc.) to the Ruby +interpreter. Ruby provides the API to define things below: * Classes, Modules * Methods, Singleton Methods * Constants -�ǤϽ�˾Ҳ𤷤ޤ��� - 2.1.1 Class/module definition To define class or module, use functions below: @@ -327,9 +313,9 @@ by the symbol mid. 2.2.4 Accessing the variables and constants -C����ؿ���Ȥäƻ��ȡ������Ǥ���Τϡ����饹��������� -���ѿ��Ǥ�������ѿ��ϰ����Τ�Τ�C������ѿ��Ȥ��ƥ����� -���Ǥ��ޤ������������ѿ��Ȥ�����ˡ�ϸ������Ƥ��ޤ��� +You can access class variables, and instance variables using access +functions. Also, global variables can be shared between both worlds. +There's no way to access Ruby's local variables. The functions to access/modify instance variables are below: @@ -346,9 +332,7 @@ See 2.1.3 for defining new constant. 3. Informatin sharing between Ruby and C -C�����Ruby�δ֤Ǿ����ͭ������ˡ�ˤĤ��Ʋ��⤷�ޤ��� - -3.1 Ruby constant that C���黲�ȤǤ���Ruby����� +3.1 Ruby constant that C can be accessed from C Following Ruby constants can be referred from C. @@ -363,43 +347,35 @@ Ruby nil in C scope. 3.2 Global variables shared between C and Ruby -C��Ruby������ѿ���Ȥäƾ����ͭ�Ǥ��ޤ�����ͭ�Ǥ������ -�ѿ��ˤϤ����Ĥ��μ��ब����ޤ������Τʤ��Ǥ�äȤ��ɤ��Ȥ� -���Ȼפ���Τ�rb_define_variable()�Ǥ��� +Information can be shared between two worlds, using shared global +variables. To define them, you can use functions listed below: void rb_define_variable(char *name, VALUE *var) -���δؿ���Ruby��C�ȤǶ�ͭ��������ѿ���������ޤ����ѿ�̾�� -`$'�ǻϤޤ�ʤ����ˤϼ�ưŪ���ɲä���ޤ��������ѿ����ͤ��� -������ȼ�ưŪ��Ruby���б������ѿ����ͤ��Ѥ��ޤ��� +This function defines the variable which is shared by the both world. +The value of the global variable pointerd by `var', can be accessed +through Ruby's global variable named `name'. -�ޤ�Ruby¦����Ϲ����Ǥ��ʤ��ѿ��⤢��ޤ�������read only�� -�ѿ��ϰʲ��δؿ���������ޤ��� +You can define read-only (from Ruby, of course) variable by the +function below. void rb_define_readonly_variable(char *name, VALUE *var) -������ѿ���¾��hook��Ĥ�������ѿ�������Ǥ��ޤ���hook�դ� -������ѿ��ϰʲ��δؿ����Ѥ���������ޤ���hook�դ�����ѿ��� -�ͤλ��Ȥ������hook�ǹԤ�ɬ�פ�����ޤ��� +You can defined hooked variables. The accessor functions (getter and +setter) are called on access to the hooked variables. void rb_define_hooked_variable(char *name, VALUE *var, VALUE (*getter)(), VALUE (*setter)()) -���δؿ���C�δؿ��ˤ�ä�hook�ΤĤ���줿����ѿ���������� -�����ѿ������Ȥ��줿���ˤϴؿ�getter�����ѿ����ͤ����åȤ��� -�����ˤϴؿ�setter���ƤФ�롥hook����ꤷ�ʤ�����getter�� -setter��0����ꤷ�ޤ��� - -# getter��setter��0�ʤ��rb_define_variable()��Ʊ���ˤʤ롥 - -���줫�顤C�δؿ��ˤ�äƼ¸������Ruby������ѿ���������� -�ؿ�������ޤ��� +If you need to supply either setter or getter, just supply 0 for the +hook you don't need. If both hooks are 0, rb_define_hooked_variable() +works just like rb_define_variable(). void rb_define_virtual_variable(char *name, VALUE (*getter)(), VALUE (*setter)()) -���δؿ��ˤ�ä�������줿Ruby������ѿ������Ȥ��줿���ˤ� -getter�����ѿ����ͤ����åȤ��줿���ˤ�setter���ƤФ�ޤ��� +This function defines the Ruby global variable without corresponding C +variable. The value of the variable will be set/get only by hooks. The prototypes of the getter and setter functions are as following: @@ -408,54 +384,44 @@ The prototypes of the getter and setter functions are as following: 3.3 Encapsulate C data into Ruby object -C��������������줿�ǡ���(��¤��)��Ruby�Υ��֥������ȤȤ��� -��갷��������礬���ꤨ�ޤ������Τ褦�ʾ��ˤϡ�Data�Ȥ��� -Ruby���֥������Ȥ�C�ι�¤��(�ؤΥݥ���)��ळ�Ȥ�Ruby -���֥������ȤȤ��Ƽ�갷����褦�ˤʤ�ޤ��� - -Data���֥������Ȥ��������ƹ�¤�Τ�Ruby���֥������Ȥ˥��ץ��� -�����뤿��ˤϡ��ʲ��Υޥ�����Ȥ��ޤ��� +To wrapping and objectify the C pointer as Ruby object (so called +DATA), use Data_Wrap_Struct(). Data_Wrap_Struct(class,mark,free,ptr) -���Υޥ���������ͤ��������줿Data���֥������ȤǤ��� - -class�Ϥ���Data���֥������ȤΥ��饹�Ǥ���ptr�ϥ��ץ��벽���� -C�ι�¤�ΤؤΥݥ��Ǥ���mark�Ϥ��ι�¤�Τ�Ruby�Υ��֥��� -���Ȥؤλ��Ȥ�������˻Ȥ��ؿ��Ǥ������Τ褦�ʻ��Ȥ�ޤޤʤ� -���ˤ�0����ꤷ�ޤ��� +Data_Wrap_Struct() returns a created DATA object. The class argument +is the class for the DATA object. The mark argument is the function +to mark Ruby objects pointed by this data. The free argument is the +function to free the pointer allocation. The functions, mark and +free, will be called from garbage collector. -# ���Τ褦�ʻ��Ȥϴ�����ޤ��� - -free�Ϥ��ι�¤�Τ��⤦���פˤʤä����˸ƤФ��ؿ��Ǥ������� -�ؿ��������١������쥯������ƤФ�ޤ��� - -C�ι�¤�Τγ�����Data���֥������Ȥ�������Ʊ���˹Ԥ��ޥ����� -���ưʲ��Τ�Τ�����Ƥ��ޤ��� +You can allocate and wrap the structure in one step. Data_Make_Struct(class, type, mark, free, sval) -���Υޥ���������ͤ��������줿Data���֥������ȤǤ��� +This macro returns an allocated Data object, wrapping the pointer to +the structure, which is also allocated. This macro works like: + + (sval = ALLOC(type), Data_Wrap_Struct(class, mark, free, sval)) -class, mark, free��Data_Wrap_Struct��Ʊ��Ư���ޤ���type -�ϳ�����Ƥ�C��¤�Τη��Ǥ���������Ƥ�줿��¤�Τ��ѿ�sval -����������ޤ��������ѿ��η��� (type*) �Ǥ���ɬ�פ�����ޤ��� +Arguments, class, mark, free, works like thier counterpart of +Data_Wrap_Struct(). The pointer to allocated structure will be +assigned to sval, which should be the pointer to the type specified. -Data���֥������Ȥ���ݥ�����Ф��Τϰʲ��Υޥ������Ѥ� -�ޤ��� +To retrieve the C pointer from the Data object, use the macro +Data_Get_Struct(). Data_Get_Struct(obj, type, sval) -C�ι�¤�ΤؤΥݥ����ѿ�sval����������ޤ��� +The pointer to the structure will be assigned to the variable sval. -������Data�λȤ����Ϥ���ä�ʬ����ˤ����Τǡ������������ -����Ȥ��Ƥ��������� +See example below for detail. -4��Example - Create dbm module +4. Example - Creating dbm extension -�����ޤǤ������ǤȤꤢ������ĥ�饤�֥��Ϻ���Ϥ��Ǥ��� -Ruby��ext�ǥ��쥯�ȥ�ˤ��Ǥ˴ޤޤ�Ƥ���dbm�⥸�塼������ -�����ʳ�Ū���������ޤ��� +OK, here's the example to make extension library. This is the +extension to access dbm. The full source is included in ext/ +directory in the Ruby's source tree. (1) make the directory @@ -477,17 +443,17 @@ You need to design the library features, before making it. (4) write C code. -��ĥ�饤�֥�����ΤȤʤ�C����Υ�������ޤ���C����Υ��� -�����ҤȤĤλ��ˤϡ֥⥸�塼��̾.c�פ����֤��ɤ��Ǥ��礦��C -����Υ�������ʣ���ξ��ˤϵդˡ֥⥸�塼��̾.c�פȤ����ե� -����̾����ɬ�פ�����ޤ������֥������ȥե�����ȥ⥸�塼 -�������������Ū�����������֥⥸�塼��̾.o�פȤ����ե����� -�Ȥ����ͤ��뤫��Ǥ��� +You need to write C code for your extension library. If your library +has only one source file, choosing ``LIBRARY.c'' as a file name is +preferred. On the other hand, in case your library has prural source +files, avoid chooing ``LIBRARY.c'' for a file name. It may conflict +with intermediate file ``LIBRARY.o'' on some platforms. -Ruby�ϳ�ĥ�饤�֥�������ɤ�����ˡ�Init_�⥸�塼��̾�פ� -�����ؿ���ưŪ�˼¹Ԥ��ޤ���dbm�⥸�塼��ξ���Init_dbm�� -�Ǥ������δؿ�����ǥ��饹���⥸�塼�롤��åɡ�����ʤɤ� -�����Ԥ��ޤ���dbm.c����������Ѥ��ޤ��� +Ruby will execute the initializing function named ``Init_LIBRARY'' in +the library. For exapmle, ``Init_dbm()'' will be executed when loading +the library. + +Here's the example of an initializing function. -- Init_dbm() @@ -509,11 +475,7 @@ Init_dbm() } -- -DBM�⥸�塼���dbm�Υǡ������б����륪�֥������Ȥˤʤ�Ϥ��� -�����顤C��������dbm��Ruby�������˼�����ɬ�פ�����ޤ��� - - -dbm.c�Ǥ�Data_Make_Struct��ʲ��Τ褦�˻ȤäƤ��ޤ��� +The dbm extension wrap dbm struct in C world using Data_Make_Struct. -- struct dbmdata { @@ -525,12 +487,10 @@ struct dbmdata { obj = Data_Make_Struct(class,struct dbmdata,0,free_dbm,dbmp); -- -�����Ǥ�dbmstruct��¤�ΤؤΥݥ���Data�˥��ץ��벽���Ƥ� -�ޤ���DBM*��ľ�ܥ��ץ��벽���ʤ��Τ�close()�������ν������ -���ƤΤ��ȤǤ��� +This code wraps dbmdata structure into Ruby object. We avoid wrapping +DBM* directly, because we want to cache size information. -Data���֥������Ȥ���dbmstruct��¤�ΤΥݥ�����Ф����� -�˰ʲ��Υޥ�����ȤäƤ��ޤ��� +To retrieve dbmdata structure from Ruby object, we define the macro below: -- #define GetDBM(obj, dbmp) {\ @@ -539,14 +499,11 @@ Data���֥������Ȥ���dbmstruct��¤�ΤΥݥ�����Ф����� } -- -����ä�ʣ���ʥޥ����Ǥ������פ����dbmdata��¤�ΤΥݥ��� -�μ��Ф��ȡ�close����Ƥ��뤫�ɤ����Υ����å���ޤȤ�Ƥ� -������Ǥ��� +This sort of complicated macro do the retrieving and close check for +the DBM. -DBM���饹�ˤϤ��������åɤ�����ޤ�����ʬ�ह���3����� -�����μ�����������ޤ����ҤȤĤϰ����ο�������Τ�Τǡ���� -���Ƥ�delete��åɤ�����ޤ���delete��åɤ�������Ƥ��� -fdbm_delete()�Ϥ��Τ褦�ˤʤäƤ��ޤ��� +There are three kind of way to receiving method arguments. First, the +methods with fixed number of arguments receives arguments like this: -- static VALUE @@ -557,13 +514,11 @@ fdbm_delete(obj, keystr) } -- -�����ο�������Υ����פ���1������self����2�����ʹߤ���å� -�ΰ����Ȥʤ�ޤ��� +The first argument of the C function is the self, the rest are the +arguments to the method. -�����ο�������Τ�Τ�C������Ǽ������Τ�Ruby������Ǽ��� -���ΤȤ�����ޤ���dbm�⥸�塼�����ǡ�C������Ǽ������� -��DBM�Υ��饹��åɤǤ���open()�Ǥ��������������Ƥ���� -��fdbm_s_open()�Ϥ����ʤäƤ��ޤ��� +Second, the methods with arbtrary number of arguments receives +arguments like this: -- static VALUE @@ -580,36 +535,28 @@ fdbm_s_open(argc, argv, class) } -- -���Υ����פδؿ�����1������Ϳ����줿�����ο�����2������Ϳ�� -��줿���������äƤ�������ˤʤ�ޤ���self����3�����Ȥ���Ϳ -�����ޤ��� +The first argument is the number of method arguments. the second +argument is the C array of the method arguments. And the third +argument is the receiver of the method. -���������Ϳ����줿��������Ϥ��뤿��δؿ���open()�Ǥ�Ȥ� -��Ƥ���rb_scan_args()�Ǥ�����3�����˻��ꤷ���ե����ޥåȤ� -��������4�ѿ��ʹߤ˻��ꤷ���ѿ����ͤ��������Ƥ���ޤ������� -�ե����ޥåȤϡ���1ʸ���ܤ���ά�Ǥ��ʤ������ο�����2ʸ���ܤ� -��ά�Ǥ�������ο�����3ʸ���ܤ��б�������̵꤬�����ޤ�ΰ� -�������뤫�ɤ�����"*"�Ǥ���2ʸ���ܤ�3ʸ���ܤϾ�ά�Ǥ��� -����dbm.c����Ǥϡ��ե����ޥåȤ�"11"�Ǥ����顤�����Ϻ���1�� -�ǡ�2�Ĥޤǵ������Ȥ�����̣�ˤʤ�ޤ�����ά����Ƥ������ -�ѿ����ͤ�nil(C����Υ�٥�Ǥ�Qnil)�ˤʤ�ޤ��� +You can use the function rb_scan_args() to check and retrieve the +arguments. For exapmle "11" means, the method requires at least one +argument, and at most receives two arguments. -Ruby������ǰ������������Τ�indexes������ޤ��������Ϥ� -���Ǥ��� +The methods with arbtrary number of arguments can receives arguments +by Ruby's array, like this: -- static VALUE fdbm_indexes(obj, args) - VALUE obj; - struct RArray *args; + VALUE obj, args; { : } -- -��1������self����2������Ruby������Ǥ��������Ǥϥ��㥹�Ȥ� -�餹���� struct RArray* �Ǽ����Ƥ��ޤ�����VALUE�Ǥ�Ʊ������ -�Ǥ��� +The first argument is the receiver, the second one is the Ruby array +which contains the arguments to the method. ** Notice @@ -620,72 +567,82 @@ not exported to the Ruby world. You need to protect them by (5) prepare extconf.rb -�⤷�ǥ��쥯�ȥ�ˡ�extconf.rb�פȤ����ե����뤬¸�ߤ���С� -make���˼¹Ԥ���ޤ����ʤ����Ŭ����Makefile����������ޤ��� +If there exists the file named extconf.rb, it will be executed to +generate Makefile. If not, compilation scheme try to generate +Makefile anyway. -extconf.rb�ϥ⥸�塼��Υ���ѥ����ɬ�פʾ��Υ����å��ʤ� -��Ԥ����Ȥ���Ū�Ǥ���extconf.rb����Ǥϰʲ���Ruby�ؿ���Ȥ� -���Ȥ�����ޤ��� +The extconf.rb is the file to check compilation condition etc. You +need to put - have_library(lib, func): �饤�֥���¸�ߥ����å� - have_func(func): �ؿ���¸�ߥ����å� - have_header(header): �إå��ե������¸�ߥ����å� - create_makefile(target): Makefile������ + require 'mkmf' -�ʲ����ѿ���Ȥ����Ȥ��Ǥ��ޤ��� +at the top of the file. You can use the funcitons below to check the +condition. - $CFLAGS: ����ѥ�������ɲ�Ū�˻��ꤹ��ե饰(-I�ʤ�) - $LDFLAGS: ������ɲ�Ū�˻��ꤹ��ե饰(-L�ʤ�) + have_library(lib, func): check whether library containing function exists. + have_func(func): check whether function exists + have_header(header): check whether header file exists + create_makefile(target): generate Makefile -�⥸�塼���ѥ��뤹���郎·��ʤ������Υ⥸�塼��ϥ� -��ѥ��뤷�ʤ����ˤ�create_makefile��ƤФʤ����Makefile�� -�������줺������ѥ����Ԥ��ޤ��� +The value of variables below will affect Makefile. + + $CFLAGS: included in CFLAGS make variable (such as -I) + $LDFLAGS: included in LDFLAGS make variable (such as -L) + +If compilation condition is not fulfilled, you do not call +``create_makefile''. Makefile will not generated, compilation will +not be done. (6) prepare depend (optional) -�⤷���ǥ��쥯�ȥ��depend�Ȥ����ե����뤬¸�ߤ���С� -Makefile����¸�ط�������å����Ƥ���ޤ��� +If the file named depend exists, Makefile will include that file to +check dependency. You can make this file by invoking % gcc -MM *.c > depend -�ʤɤǺ�뤳�Ȥ�����ޤ������ä�»��̵���Ǥ��礦�� +It's no harm. Prepare it. -(7) MANIFEST�ե�����˥ե�����̾������� +(7) put file names into MANIFEST (optional) - % ls > MANIFEST + % find * -type f -print > MANIFEST % vi MANIFEST -*.o, *~�ʤ���ɬ�פʥե�����ʳ���MANIFEST���ɲä��Ƥ����ޤ��� -make���ˤ�MANIFEST�����Ƥϻ��Ȥ��ޤ���Τǡ����ΤޤޤǤ����� -�ϵ����ޤ����ѥå������λ��˻��Ȥ��뤳�Ȥ�����Τȡ� -ɬ�פʥե��������̤Ǥ���Τǡ��Ѱդ��Ƥ����������ɤ��Ǥ��� -���� +Append file names into MANIFEST. The compilation scheme requires +MANIFEST only to be exist. But, you'd better take this step to +distinguish required files. + +(8) generate Makefile + +Try generate Makefile by: + + ruby extconf.rb + +You don't need this step, if you put extension library under ext +directory of the ruby source tree. In that case, compilation of the +interpreter will do this step for you. + +(9) make -(8) make +Type -Ruby�Υǥ��쥯�ȥ��make��¹Ԥ����Makefile����������make�� -ɬ�פˤ�äƤϤ��Υ⥸�塼���Ruby�ؤΥ�ޤǼ�ưŪ�˼¹� -���Ƥ���ޤ���extconf.rb�������ʤɤ���Makefile�κ����� -��ɬ�פʻ��Ϥޤ�Ruby�ǥ��쥯�ȥ��make���Ƥ��������� + make + +to compile your extension. You don't need this step neither, if you +put extension library under ext directory of the ruby source tree. (9) debug -You may need to rb_debug the module. The modules can be linked -statically by adding directory name in the ext/Setup file, -so that you can inspect the module by the debugger. +You may need to rb_debug the extension. The extensions can be linked +statically by adding directory name in the ext/Setup file, so that you +can inspect the extension with the debugger. (10) done, now you have the extension library -��Ϥ��ä���Ȥ��ʤꡤ������������ʤꡤ���ʤꡤ����ͳ�ˤ� -�Ȥ�����������Ruby�κ�Ԥϳ�ĥ�饤�֥��˴ؤ��ư��ڤθ����� -��ĥ���ޤ��� - -Appendix A. Ruby�Υ����������ɤ�ʬ�� +You can do anything you want with your library. The author of Ruby +will not claim any restriction about your code depending Ruby API. +Feel free to use, modify, distribute or sell your program. -Ruby�Υ������Ϥ����Ĥ���ʬ�ह�뤳�Ȥ�����ޤ������Τ������� -���饤�֥�����ʬ�ϴ���Ū�˳�ĥ�饤�֥���Ʊ��������ˤʤ� -�Ƥ��ޤ��������Υ������Ϻ��ޤǤ������ǤۤȤ������Ǥ���� -�פ��ޤ��� +Appendix A. Ruby source files overview ruby language core @@ -737,18 +694,15 @@ class library struct.c time.c -Appendix B. ��ĥ�Ѵؿ���ե���� - -C���줫��Ruby�ε�ǽ�����Ѥ���API�ϰʲ����̤�Ǥ��롥 +Appendix B. Ruby extension API reference -** �� +** Types VALUE -Ruby���֥������Ȥ�ɽ�����뷿��ɬ�פ˱����ƥ��㥹�Ȥ����Ѥ��롥 -�Ȥ߹��߷���ɽ������C�η���ruby.h�˵��Ҥ��Ƥ���R�ǻϤޤ빽¤ -�ΤǤ��롥VALUE�����˥��㥹�Ȥ��뤿���R�ǻϤޤ빽¤�� -̾��������ʸ���ˤ���̾���Υޥ������Ѱդ���Ƥ��롥 +The type for Ruby object. Actual structures are defined in ruby.h, +such as struct RString, etc. To refer the values in structures, use +casting macros like RSTRING(obj). ** Variables and constants @@ -758,58 +712,58 @@ const: nil object Qtrue -const: Qtrue object(default true value) +const: true object(default true value) Qfalse -const: Qfalse object +const: false object -** C�ǡ����Υ��ץ��벽 +** C pointer wrapping Data_Wrap_Struct(VALUE class, void (*mark)(), void (*free)(), void *sval) -C��Ǥ�դΥݥ��ץ��벽����Ruby���֥������Ȥ��֤����� -�Υݥ���Ruby���饢����������ʤ��ʤä�����free�ǻ��ꤷ�� -�ؿ����ƤФ�롥�ޤ������Υݥ��λؤ��ǡ�����¾��Ruby���� -�������Ȥ�ؤ��Ƥ����硤mark�˻��ꤹ��ؿ��ǥޡ�������ɬ�� -�����롥 +Wrap C pointer into Ruby object. If object has references to other +Ruby object, they should be marked by using mark function during GC +process. Otherwise, mark should be 0. When this object is no longer +referred by anywhere, the pointer will be discarded by free function. Data_Make_Struct(class, type, mark, free, sval) -type���Υ����malloc�����ѿ�sval�����������塤����ץ� -�벽�����ǡ������֤��ޥ����� +This macro allocates memory using malloc(), assigns it to the variable +sval, and returns the DATA encapsulating the pointer to memory region. Data_Get_Struct(data, type, sval) -data����type���Υݥ�����Ф��ѿ�sval����������ޥ����� +This macro retrieves the pointer value from DATA, and assigns it to +the variable sval. -** ���饹/�⥸�塼����� +** defining class/module VALUE rb_define_class(char *name, VALUE super) -super�Υ��֥��饹�Ȥ��ƿ�����Ruby���饹��������롥 +Defines new Ruby class as subclass of super. VALUE rb_define_class_under(VALUE module, char *name, VALUE super) -super�Υ��֥��饹�Ȥ��ƿ�����Ruby���饹���������module���� -���Ȥ���������롥 +Creates new Ruby class as subclass of super, under the module's +namespace. VALUE rb_define_module(char *name) -������Ruby�⥸�塼���������롥 +Defines new Ruby module. VALUE rb_define_module_under(VALUE module, char *name, VALUE super) -������Ruby�⥸�塼����������module������Ȥ���������롥 +Defines new Ruby module, under the modules's namespace. void rb_include_module(VALUE class, VALUE module) -�⥸�塼��롼�ɤ��롥class�����Ǥ�module�롼 -�ɤ��Ƥ�����ˤϲ��⤷�ʤ�(¿�ť��롼�ɤζػ�)�� +Includes module into class. If class already includes it, just +ignore. void rb_extend_object(VALUE object, VALUE module) -���֥������Ȥ�⥸�塼��(���������Ƥ����å�)�dz�ĥ���롥 +Extend the object with module's attribute. ** Defining Global Variables @@ -871,115 +825,118 @@ Defines global contant. This is just work as rb_define_method(VALUE class, char *name, VALUE (*func)(), int argc) -��åɤ�������롥argc��self����������ο���argc��-1�λ�, -�ؿ��ˤϰ����ο�(self��ޤޤʤ�)����1����, �������������2�� -���Ȥ��������Ϳ������(��3������self)��argc��-2�λ�, ��1�� -����self, ��2������args(args�ϰ�����ޤ�Ruby������)�Ȥ����� -����Ϳ�����롥 +Defines a method for the class. func is the function pointer. argc +is the number of arguments. if argc is -1, the function will receive +3 arguments argc, argv, and self. if argc is -2, the function will +receive 2 arguments, self and args, where args is the Ruby array of +the method arguments. rb_define_private_method(VALUE class, char *name, VALUE (*func)(), int argc) -private��åɤ�������롥������rb_define_method()��Ʊ���� +Defines a private method for the class. Arguments are same as +rb_define_method(). rb_define_singleton_method(VALUE class, char *name, VALUE (*func)(), int argc) -�ðۥ�åɤ�������롥������rb_define_method()��Ʊ���� +Defines a singleton method. Arguments are same as rb_define_method(). - rb_scan_args(int atgc, VALUE *argv, char *fmt, ...) + rb_scan_args(int argc, VALUE *argv, char *fmt, ...) -argc,argv������Ϳ����줿������ʬ�롥fmt��ɬ�ܰ����ο�, -�ղð����ο�, �Ĥ�ΰ��������뤫����ꤹ��ʸ�����, "������ -��*"�Ȥ��������Ǥ��롥 2 ���ܤο�����"*"�Ϥ��줾���ά��ǽ�� -���롥ɬ�ܰ�������Ĥ�ʤ�����0����ꤹ�롥��3�����ʹߤ��� -���ؤΥݥ���, �����������Ǥ������ѿ��˳�Ǽ����롥�ղð� -�����б����������Ϳ�����Ƥ��ʤ������ѿ���Qnil���������� -�롥 +Retrieve argument from argc, argv. The fmt is the format string for +the arguments, such as "12" for 1 non-optinal argument, 2 optinal +aruguments. If `*' appears at the end of fmt, it means the rest of +the arguments are assigned to corresponding variable, packed in +array. -** Ruby��åɸƤӽФ� +** Invoking Ruby method VALUE rb_funcall(VALUE recv, ID mid, int narg, ...) -��åɸƤӽФ���ʸ����mid�����뤿��ˤ�rb_intern()��Ȥ��� +Invokes the method. To retrieve mid from method name, use rb_intern(). VALUE rb_funcall2(VALUE recv, ID mid, int argc, VALUE *argv) -��åɸƤӽФ���������argc,argv�������Ϥ��� +Invokes method, passing arguments by array of values. VALUE rb_eval_string(char *str) -ʸ�����Ruby�ȥ�����ץȤ��ƥ���ѥ��롦�¹Ԥ��롥 +Compiles and executes the string as Ruby program. ID rb_intern(char *name) -ʸ������б�����ID���֤��� +Returns ID corresponding the name. char *rb_id2name(ID id) -ID���б�����ʸ������֤�(�ǥХå���)�� +Returns the name corresponding ID. char *rb_class2name(VALUE class) -class��̾�����֤�(�ǥХå���)��class��̾��������ʤ����ˤ�, -������̤ä�̾������ĥ��饹��̾�����֤��� +Returns the name of the class. -** �������ѿ� +** Instance Variables VALUE rb_iv_get(VALUE obj, char *name) -obj�Υ������ѿ����ͤ����롥`@'�ǻϤޤ�ʤ������� -�ѿ��� Ruby�ץ�����फ�饢�������Ǥ��ʤ��ֱ��줿�ץ��� -���ѿ��ˤʤ롥 +Retrieve the value of the instance variable. If the name is not +prefixed by `@', that variable shall be inaccessible from Ruby. VALUE rb_iv_set(VALUE obj, char *name, VALUE val) -obj�Υ������ѿ���val�˥��åȤ��롥 +Sets the value of the instance variable. -** ���湽¤ +** Control Structure VALUE rb_iterate(VALUE (*func1)(), void *arg1, VALUE (*func2)(), void *arg2) -func2��֥��å��Ȥ������ꤷ, func1�ƥ졼���Ȥ��ƸƤ֡� -func1�ˤ� arg1�������Ȥ����Ϥ���, func2�ˤ���1�����˥��ƥ졼 -������Ϳ����줿��, ��2������arg2���Ϥ���롥 +Calls the function func1, supplying func2 as the block. func1 will be +called with the argument arg1. func2 receives the value from yield as +the first argument, arg2 as the second argument. + VALUE rb_yield(VALUE val) -val���ͤȤ��ƥ��ƥ졼���֥��å���ƤӽФ��� +Evaluates the block with value val. VALUE rb_rescue(VALUE (*func1)(), void *arg1, VALUE (*func2)(), void *arg2) -�ؿ�func1��arg1������˸ƤӽФ���func1�μ¹�����㳰��ȯ���� -�����ˤ� func2��arg2������Ȥ��ƸƤ֡�����ͤ��㳰��ȯ������ -���ä�����func1�������, �㳰��ȯ���������ˤ�func2������ͤ� -���롥 +Calls the function func1, with arg1 as the argument. If exception +occurs during func1, it calls func2 with arg2 as the argument. The +return value of rb_rescue() is the return value from func1 if no +exception occurs, from func2 otherwise. VALUE rb_ensure(VALUE (*func1)(), void *arg1, void (*func2)(), void *arg2) -�ؿ�func1��arg1������Ȥ��Ƽ¹Ԥ�, �¹Խ�λ��(���Ȥ��㳰��ȯ -�����Ƥ�) func2��arg2������Ȥ��Ƽ¹Ԥ��롥����ͤ�func1���� -���ͤǤ���(�㳰��ȯ�������������ʤ�)�� +Calls the function func1 with arg1 as the argument, then calls func2 +with arg2, whenever execution terminated. The return value from +rb_ensure() is that of func1. + +** Exceptions and Errors + + void rb_warn(char *fmt, ...) -** �㳰�����顼 +Prints warning message according to the printf-like format. void rb_warning(char *fmt, ...) -rb_verbose����ɸ�२�顼���Ϥ˷ٹ�����ɽ�����롥������printf()��Ʊ���� +Prints warning message according to the printf-like format, if +$VERBOSE is true. - void rb_raise(rb_eRuntimeError, char *fmt, ...) + void rb_raise(VALUE exception, char *fmt, ...) -�㳰��ȯ�������롥������printf()��Ʊ���� +Raises an exception of class exception. The fmt is the format string +just like printf(). void rb_fatal(char *fmt, ...) -��̿Ū�㳰��ȯ�������롥�̾���㳰�����ϹԤʤ�줺, ���� -�ץ����λ����(������ensure�ǻ��ꤵ�줿�����ɤϽ�λ���˼� -�Ԥ����)�� +Raises fatal error, terminates the interpreter. No exception handling +will be done for fatal error, but ensure blocks will be executed. void rb_bug(char *fmt, ...) -�����ץ�ʤɥץ������ΥХ��Ǥ���ȯ������Ϥ��Τʤ��� -���λ��Ƥ֡������ץ�ϥ�������פ�ľ���˽�λ���롥�㳰 -�����ϰ��ڹԤʤ��ʤ��� +Termintates the interpreter immediately. This function should be +called under the situation caused by the bug in the interpreter. No +exception handling nor ensure execution will be done. ** Initialize and Starts the Interpreter @@ -999,8 +956,7 @@ Specifies the name of the script ($0). Appendix B. Functions Available in extconf.rb -extconf.rb����Ǥ����Ѳ�ǽ�ʥ���ѥ���������å��δؿ��ϰ� -�����̤�Ǥ��롥 +These functions are available in extconf.rb: have_library(lib, func) @@ -1024,6 +980,6 @@ this method, the compilation will not be done. /* * Local variables: - * fill-column: 60 + * fill-column: 70 * end: */ |