summaryrefslogtreecommitdiff
path: root/README.EXT
diff options
context:
space:
mode:
Diffstat (limited to 'README.EXT')
-rw-r--r--README.EXT492
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:
*/