1
1
.\" README.EXT - -*- Text -*- created at: Mon Aug 7 16:45:54 JST 1995
2
2
3
- This document explains how to make extention libraries for Ruby.
3
+ This document explains how to make extension libraries for Ruby.
4
4
5
5
1. Basic knowledge
6
6
@@ -16,23 +16,23 @@ To retrieve an C data from the VALUE, you need to:
16
16
(1) Identify VALUE's data type
17
17
(2) Convert VALUE into C data
18
18
19
- Converting to wrong data type may cause serious promblems .
19
+ Converting to wrong data type may cause serious problems .
20
20
21
21
22
22
1.1 Data-types
23
23
24
24
Ruby interpreter has data-types as below:
25
25
26
26
T_NIL nil
27
- T_OBJECT ordinaly object
27
+ T_OBJECT ordinary object
28
28
T_CLASS class
29
29
T_MODULE module
30
30
T_FLOAT floating point number
31
31
T_STRING string
32
32
T_REGEXP regular expression
33
33
T_ARRAY array
34
34
T_FIXNUM Fixnum(31bit integer)
35
- T_HASH assosiative array
35
+ T_HASH associative array
36
36
T_STRUCT (Ruby) structure
37
37
T_BIGNUM multi precision integer
38
38
T_TRUE true
@@ -88,7 +88,7 @@ The data for type T_NIL, T_FALSE, T_TRUE are nil, true, false
88
88
respectively. They are singletons for the data type.
89
89
90
90
The T_FIXNUM data is the 31bit length fixed integer (63bit length on
91
- some machines), which can be conver to the C integer by using
91
+ some machines), which can be convert to the C integer by using
92
92
FIX2INT() macro. There also be NUM2INT() which converts any Ruby
93
93
numbers into C integer. The NUM2INT() macro includes type check, so
94
94
the exception will be raised if conversion failed.
@@ -127,7 +127,7 @@ structures are defined in <ruby.h>.
127
127
128
128
To convert C numbers to Ruby value, use these macros.
129
129
130
- INT2FIX() for intergers within 31bits.
130
+ INT2FIX() for integers within 31bits.
131
131
INT2NUM() for arbitrary sized integer.
132
132
133
133
INT2NUM() converts integers into Bignums, if it is out of FIXNUM
@@ -139,7 +139,7 @@ As I already told, it is not recommended to modify object's internal
139
139
structure. To manipulate objects, use functions supplied by Ruby
140
140
interpreter. Useful functions are listed below (not all):
141
141
142
- String funtions
142
+ String functions
143
143
144
144
rb_str_new(char *ptr, int len)
145
145
@@ -200,14 +200,14 @@ To define class or module, use functions below:
200
200
VALUE rb_define_class(char *name, VALUE super)
201
201
VALUE rb_define_module(char *name)
202
202
203
- These functions return the newly created class ot module. You may
203
+ These functions return the newly created class or module. You may
204
204
want to save this reference into the variable to use later.
205
205
206
206
2.1.2 Method/singleton method definition
207
207
208
208
To define methods or singleton methods, use functions below:
209
209
210
- void rb_define_method(VALUE class , char *name,
210
+ void rb_define_method(VALUE klass , char *name,
211
211
VALUE (*func)(), int argc)
212
212
213
213
void rb_define_singleton_method(VALUE object, char *name,
@@ -237,7 +237,7 @@ actual arguments.
237
237
There're two more functions to define method. One is to define
238
238
private method:
239
239
240
- void rb_define_private_method(VALUE class , char *name,
240
+ void rb_define_private_method(VALUE klass , char *name,
241
241
VALUE (*func)(), int argc)
242
242
243
243
The other is to define module function, which is private AND singleton
@@ -266,7 +266,7 @@ in Kernel module, can be defined using:
266
266
267
267
We have 2 functions to define constants:
268
268
269
- void rb_define_const(VALUE class , char *name, VALUE val)
269
+ void rb_define_const(VALUE klass , char *name, VALUE val)
270
270
void rb_define_global_const(char *name, VALUE val)
271
271
272
272
The former is to define constant under specified class/module. The
@@ -330,7 +330,7 @@ To access the constants of the class/module:
330
330
331
331
See 2.1.3 for defining new constant.
332
332
333
- 3. Informatin sharing between Ruby and C
333
+ 3. Information sharing between Ruby and C
334
334
335
335
3.1 Ruby constant that C can be accessed from C
336
336
@@ -353,7 +353,7 @@ variables. To define them, you can use functions listed below:
353
353
void rb_define_variable(char *name, VALUE *var)
354
354
355
355
This function defines the variable which is shared by the both world.
356
- The value of the global variable pointerd by `var', can be accessed
356
+ The value of the global variable pointed by `var', can be accessed
357
357
through Ruby's global variable named `name'.
358
358
359
359
You can define read-only (from Ruby, of course) variable by the
@@ -387,7 +387,7 @@ The prototypes of the getter and setter functions are as following:
387
387
To wrapping and objectify the C pointer as Ruby object (so called
388
388
DATA), use Data_Wrap_Struct().
389
389
390
- Data_Wrap_Struct(class ,mark,free,ptr)
390
+ Data_Wrap_Struct(klass ,mark,free,ptr)
391
391
392
392
Data_Wrap_Struct() returns a created DATA object. The class argument
393
393
is the class for the DATA object. The mark argument is the function
@@ -397,14 +397,14 @@ free, will be called from garbage collector.
397
397
398
398
You can allocate and wrap the structure in one step.
399
399
400
- Data_Make_Struct(class , type, mark, free, sval)
400
+ Data_Make_Struct(klass , type, mark, free, sval)
401
401
402
402
This macro returns an allocated Data object, wrapping the pointer to
403
403
the structure, which is also allocated. This macro works like:
404
404
405
- (sval = ALLOC(type), Data_Wrap_Struct(class , mark, free, sval))
405
+ (sval = ALLOC(type), Data_Wrap_Struct(klass , mark, free, sval))
406
406
407
- Arguments, class , mark, free, works like thier counterpart of
407
+ Arguments, klass , mark, free, works like their counterpart of
408
408
Data_Wrap_Struct(). The pointer to allocated structure will be
409
409
assigned to sval, which should be the pointer to the type specified.
410
410
@@ -445,12 +445,12 @@ You need to design the library features, before making it.
445
445
446
446
You need to write C code for your extension library. If your library
447
447
has only one source file, choosing ``LIBRARY.c'' as a file name is
448
- preferred. On the other hand, in case your library has prural source
449
- files, avoid chooing ``LIBRARY.c'' for a file name. It may conflict
448
+ preferred. On the other hand, in case your library has plural source
449
+ files, avoid choosing ``LIBRARY.c'' for a file name. It may conflict
450
450
with intermediate file ``LIBRARY.o'' on some platforms.
451
451
452
452
Ruby will execute the initializing function named ``Init_LIBRARY'' in
453
- the library. For exapmle , ``Init_dbm()'' will be executed when loading
453
+ the library. For example , ``Init_dbm()'' will be executed when loading
454
454
the library.
455
455
456
456
Here's the example of an initializing function.
@@ -484,7 +484,7 @@ struct dbmdata {
484
484
};
485
485
486
486
487
- obj = Data_Make_Struct(class ,struct dbmdata,0,free_dbm,dbmp);
487
+ obj = Data_Make_Struct(klass ,struct dbmdata,0,free_dbm,dbmp);
488
488
--
489
489
490
490
This code wraps dbmdata structure into Ruby object. We avoid wrapping
@@ -517,15 +517,15 @@ fdbm_delete(obj, keystr)
517
517
The first argument of the C function is the self, the rest are the
518
518
arguments to the method.
519
519
520
- Second, the methods with arbtrary number of arguments receives
520
+ Second, the methods with arbitrary number of arguments receives
521
521
arguments like this:
522
522
523
523
--
524
524
static VALUE
525
- fdbm_s_open(argc, argv, class )
525
+ fdbm_s_open(argc, argv, klass )
526
526
int argc;
527
527
VALUE *argv;
528
- VALUE class ;
528
+ VALUE klass ;
529
529
{
530
530
:
531
531
if (rb_scan_args(argc, argv, "11", &file, &vmode) == 1) {
@@ -540,10 +540,10 @@ argument is the C array of the method arguments. And the third
540
540
argument is the receiver of the method.
541
541
542
542
You can use the function rb_scan_args() to check and retrieve the
543
- arguments. For exapmle "11" means, the method requires at least one
543
+ arguments. For example "11" means, the method requires at least one
544
544
argument, and at most receives two arguments.
545
545
546
- The methods with arbtrary number of arguments can receives arguments
546
+ The methods with arbitrary number of arguments can receives arguments
547
547
by Ruby's array, like this:
548
548
549
549
--
@@ -576,7 +576,7 @@ need to put
576
576
577
577
require 'mkmf'
578
578
579
- at the top of the file. You can use the funcitons below to check the
579
+ at the top of the file. You can use the functions below to check the
580
580
condition.
581
581
582
582
have_library(lib, func): check whether library containing function exists.
@@ -720,14 +720,14 @@ const: false object
720
720
721
721
** C pointer wrapping
722
722
723
- Data_Wrap_Struct(VALUE class , void (*mark)(), void (*free)(), void *sval)
723
+ Data_Wrap_Struct(VALUE klass , void (*mark)(), void (*free)(), void *sval)
724
724
725
725
Wrap C pointer into Ruby object. If object has references to other
726
726
Ruby object, they should be marked by using mark function during GC
727
727
process. Otherwise, mark should be 0. When this object is no longer
728
728
referred by anywhere, the pointer will be discarded by free function.
729
729
730
- Data_Make_Struct(class , type, mark, free, sval)
730
+ Data_Make_Struct(klass , type, mark, free, sval)
731
731
732
732
This macro allocates memory using malloc(), assigns it to the variable
733
733
sval, and returns the DATA encapsulating the pointer to memory region.
@@ -754,9 +754,9 @@ Defines new Ruby module.
754
754
755
755
VALUE rb_define_module_under(VALUE module, char *name, VALUE super)
756
756
757
- Defines new Ruby module, under the modules 's namespace.
757
+ Defines new Ruby module, under the module 's namespace.
758
758
759
- void rb_include_module(VALUE class , VALUE module)
759
+ void rb_include_module(VALUE klass , VALUE module)
760
760
761
761
Includes module into class. If class already includes it, just
762
762
ignore.
@@ -817,34 +817,34 @@ Defines a new constant under the class/module.
817
817
818
818
void rb_define_global_const(char *name, VALUE val)
819
819
820
- Defines global contant . This is just work as
820
+ Defines global constant . This is just work as
821
821
822
822
rb_define_const(cKernal, name, val)
823
823
824
824
** Method Definition
825
825
826
- rb_define_method(VALUE class , char *name, VALUE (*func)(), int argc)
826
+ rb_define_method(VALUE klass , char *name, VALUE (*func)(), int argc)
827
827
828
828
Defines a method for the class. func is the function pointer. argc
829
829
is the number of arguments. if argc is -1, the function will receive
830
830
3 arguments argc, argv, and self. if argc is -2, the function will
831
831
receive 2 arguments, self and args, where args is the Ruby array of
832
832
the method arguments.
833
833
834
- rb_define_private_method(VALUE class , char *name, VALUE (*func)(), int argc)
834
+ rb_define_private_method(VALUE klass , char *name, VALUE (*func)(), int argc)
835
835
836
836
Defines a private method for the class. Arguments are same as
837
837
rb_define_method().
838
838
839
- rb_define_singleton_method(VALUE class , char *name, VALUE (*func)(), int argc)
839
+ rb_define_singleton_method(VALUE klass , char *name, VALUE (*func)(), int argc)
840
840
841
841
Defines a singleton method. Arguments are same as rb_define_method().
842
842
843
843
rb_scan_args(int argc, VALUE *argv, char *fmt, ...)
844
844
845
845
Retrieve argument from argc, argv. The fmt is the format string for
846
- the arguments, such as "12" for 1 non-optinal argument, 2 optinal
847
- aruguments . If `*' appears at the end of fmt, it means the rest of
846
+ the arguments, such as "12" for 1 non-optional argument, 2 optional
847
+ arguments . If `*' appears at the end of fmt, it means the rest of
848
848
the arguments are assigned to corresponding variable, packed in
849
849
array.
850
850
@@ -870,7 +870,7 @@ Returns ID corresponding the name.
870
870
871
871
Returns the name corresponding ID.
872
872
873
- char *rb_class2name(VALUE class )
873
+ char *rb_class2name(VALUE klass )
874
874
875
875
Returns the name of the class.
876
876
@@ -934,7 +934,7 @@ will be done for fatal error, but ensure blocks will be executed.
934
934
935
935
void rb_bug(char *fmt, ...)
936
936
937
- Termintates the interpreter immediately. This function should be
937
+ Terminates the interpreter immediately. This function should be
938
938
called under the situation caused by the bug in the interpreter. No
939
939
exception handling nor ensure execution will be done.
940
940
0 commit comments