U:RDoc::TopLevel[	iI"README.EXT:ETcRDoc::Parser::Simpleo:RDoc::Markup::Document:@parts[?o:RDoc::Markup::Paragraph;[I"EThis document explains how to make extension libraries for Ruby.;To:RDoc::Markup::BlankLineS:RDoc::Markup::Heading:
leveli:	textI"Basic Knowledge;T@o;	;[I"JIn C, variables have types and data do not have types.  In contrast, ;TI"HRuby variables do not have a static type, and data themselves have ;TI"Dtypes, so data will need to be converted between the languages.;T@o;	;[I"JData in Ruby are represented by the C type `VALUE'.  Each VALUE data ;TI"has its data-type.;T@o;	;[I"2To retrieve C data from a VALUE, you need to:;T@o:RDoc::Markup::List:
@type:NUMBER:@items[o:RDoc::Markup::ListItem:@label0;[o;	;[I"#Identify the VALUE's data type;To;;0;[o;	;[I""Convert the VALUE into C data;T@o;	;[I"BConverting to the wrong data type may cause serious problems.;T@S;;i;
I"Data-Types;T@o;	;[I"7The Ruby interpreter has the following data types:;T@o;;:	NOTE;[o;;[I"T_NIL       ;T;[o;	;[I"nil;To;;[I"T_OBJECT    ;T;[o;	;[I"ordinary object;To;;[I"T_CLASS     ;T;[o;	;[I"
class;To;;[I"T_MODULE    ;T;[o;	;[I"module;To;;[I"T_FLOAT     ;T;[o;	;[I"floating point number;To;;[I"T_STRING    ;T;[o;	;[I"string;To;;[I"T_REGEXP    ;T;[o;	;[I"regular expression;To;;[I"T_ARRAY     ;T;[o;	;[I"
array;To;;[I"T_HASH      ;T;[o;	;[I"associative array;To;;[I"T_STRUCT    ;T;[o;	;[I"(Ruby) structure;To;;[I"T_BIGNUM    ;T;[o;	;[I"multi precision integer;To;;[I"T_FIXNUM    ;T;[o;	;[I"#Fixnum(31bit or 63bit integer);To;;[I"T_COMPLEX   ;T;[o;	;[I"complex number;To;;[I"T_RATIONAL  ;T;[o;	;[I"rational number;To;;[I"T_FILE      ;T;[o;	;[I"IO;To;;[I"T_TRUE      ;T;[o;	;[I"	true;To;;[I"T_FALSE     ;T;[o;	;[I"
false;To;;[I"T_DATA      ;T;[o;	;[I"	data;To;;[I"T_SYMBOL    ;T;[o;	;[I"symbol;T@o;	;[I"@In addition, there are several other types used internally:;T@o;;;;[
o;;[I"T_ICLASS    ;T;[o;	;[I"included module;To;;[I"T_MATCH     ;T;[o;	;[I"MatchData object;To;;[I"T_UNDEF     ;T;[o;	;[I"undefined;To;;[I"T_NODE      ;T;[o;	;[I"syntax tree node;To;;[I"T_ZOMBIE    ;T;[o;	;[I"!object awaiting finalization;T@o;	;[I"7Most of the types are represented by C structures.;T@S;;i;
I"!Check Data Type of the VALUE;T@o;	;[I"JThe macro TYPE() defined in ruby.h shows the data type of the VALUE. ;TI"KTYPE() returns the constant number T_XXXX described above.  To handle ;TI"9data types, your code will look something like this:;T@o:RDoc::Markup::Verbatim;[I"switch (TYPE(obj)) {
;TI"  case T_FIXNUM:
;TI"       process Fixnum   
;TI"    break;
;TI"  case T_STRING:
;TI"       process String   
;TI"    break;
;TI"  case T_ARRAY:
;TI"    /* process Array */
;TI"    break;
;TI"  default:
;TI"    /* raise exception */
;TI"5    rb_raise(rb_eTypeError, "not valid value");
;TI"    break;
;TI"}
;T:@format0o;	;[I"*There is the data-type check function;T@o;;[I",void Check_Type(VALUE value, int type)
;T;0o;	;[I"Cwhich raises an exception if the VALUE does not have the type ;TI"specified.;T@o;	;[I"<There are also faster check macros for fixnums and nil.;T@o;;[I"FIXNUM_P(obj)
;TI"NIL_P(obj)
;T;0S;;i;
I"Convert VALUE into C Data;T@o;	;[	I"CThe data for type T_NIL, T_FALSE, T_TRUE are nil, false, true ;TI";respectively.  They are singletons for the data type. ;TI":The equivalent C constants are: Qnil, Qfalse, Qtrue. ;TI"@Note that Qfalse is false in C also (i.e. 0), but not Qnil.;T@o;	;[I"AThe T_FIXNUM data is a 31bit or 63bit length fixed integer. ;TI"DThis size is depend on the size of long: if long is 32bit then ;TI"AT_FIXNUM is 31bit, if long is 64bit then T_FIXNUM is 63bit. ;TI";T_FIXNUM can be converted to a C integer by using the ;TI"GFIX2INT() macro or FIX2LONG().  Though you have to check that the ;TI"Kdata is really FIXNUM before using them, they are faster.  FIX2LONG() ;TI"Enever raises exceptions, but FIX2INT() raises RangeError if the ;TI"7result is bigger or smaller than the size of int. ;TI"EThere are also NUM2INT() and NUM2LONG() which converts any Ruby ;TI"Cnumbers into C integers.  These macros includes a type check, ;TI"Iso an exception will be raised if the conversion failed.  NUM2DBL() ;TI"Dcan be used to retrieve the double float value in the same way.;T@o;	;[I"You can use the macros ;TI"EStringValue() and StringValuePtr() to get a char* from a VALUE. ;TI"NStringValue(var) replaces var's value with the result of "var.to_str()". ;TI"AStringValuePtr(var) does same replacement and returns char* ;TI"Krepresentation of var.  These macros will skip the replacement if var ;TI"His a String.  Notice that the macros take only the lvalue as their ;TI"3argument, to change the value of var in place.;T@o;	;[I"FYou can also use the macro named StringValueCStr(). This is just ;TI"Glike StringValuePtr(), but always add nul character at the end of ;TI"Ithe result. If the result contains nul character, this macro causes ;TI""the ArgumentError exception. ;TI"JStringValuePtr() doesn't guarantee the existence of a nul at the end ;TI"3of the result, and the result may contain nul.;T@o;	;[I"JOther data types have corresponding C structures, e.g. struct RArray ;TI"Hfor T_ARRAY etc. The VALUE of the type which has the corresponding ;TI"Gstructure can be cast to retrieve the pointer to the struct.  The ;TI"Ecasting macro will be of the form RXXXX for each data type; for ;TI"Iinstance, RARRAY(obj).  See "ruby.h".  However, we do not recommend ;TI"Lto access RXXXX data directly because these data structure is complex. ;TI"EUse corresponding rb_xxx() functions to access internal struct. ;TI"MFor example, to access an entry of array, use rb_ary_entry(ary, offset) ;TI"(and rb_ary_store(ary, offset, obj).;T@o;	;[I"HThere are some accessing macros for structure members, for example ;TI"H`RSTRING_LEN(str)' to get the size of the Ruby String object.  The ;TI"<allocated region can be accessed by `RSTRING_PTR(str)'.;T@o;	;[I"KNotice: Do not change the value of the structure directly, unless you ;TI"Fare responsible for the result.  This ends up being the cause of ;TI"interesting bugs.;T@S;;i;
I"Convert C Data into VALUE;T@o;	;[I"&To convert C data to Ruby values:;T@o;;;;[o;;[I"FIXNUM ;T;[o;	;[I"'left shift 1 bit, and turn on LSB.;T@o;;[I"Other pointer values;T;[o;	;[I"cast to VALUE.;T@o;	;[I"MYou can determine whether a VALUE is pointer or not by checking its LSB.;T@o;	;[I"NNotice Ruby does not allow arbitrary pointer values to be a VALUE.  They ;TI"Mshould be pointers to the structures which Ruby knows about.  The known ;TI"(structures are defined in <ruby.h>.;T@o;	;[I";To convert C numbers to Ruby values, use these macros.;T@o;;;;[o;;[I"INT2FIX() ;T;[o;	;[I" for integers within 31bits.;To;;[I"INT2NUM() ;T;[o;	;[I"!for arbitrary sized integer.;T@o;	;[I"LINT2NUM() converts an integer into a Bignum if it is out of the FIXNUM ;TI" range, but is a bit slower.;T@S;;i;
I"Manipulating Ruby Data;T@o;	;[	I"IAs I already mentioned, it is not recommended to modify an object's ;TI"Linternal structure.  To manipulate objects, use the functions supplied ;TI"Iby the Ruby interpreter. Some (not all) of the useful functions are ;TI"listed below:;T@S;;i;
I"String Functions;T@o;;;;[o;;[I"+rb_str_new(const char *ptr, long len) ;T;[o;	;[I"Creates a new Ruby string.;T@o;;[I""rb_str_new2(const char *ptr) ;TI"&rb_str_new_cstr(const char *ptr) ;T;[o;	;[I"GCreates a new Ruby string from a C string.  This is equivalent to ;TI""rb_str_new(ptr, strlen(ptr)).;T@o;;[I")rb_str_new_literal(const char *ptr) ;T;[o;	;[I"7Creates a new Ruby string from a C string literal.;T@o;;[I"3rb_tainted_str_new(const char *ptr, long len) ;T;[o;	;[I"DCreates a new tainted Ruby string.  Strings from external data ;TI"sources should be tainted.;T@o;;[I"*rb_tainted_str_new2(const char *ptr) ;TI".rb_tainted_str_new_cstr(const char *ptr) ;T;[o;	;[I"7Creates a new tainted Ruby string from a C string.;T@o;;[I")rb_sprintf(const char *format, ...) ;TI"1rb_vsprintf(const char *format, va_list ap) ;T;[	o;	;[I"5Creates a new Ruby string with printf(3) format.;T@o;	;[	I"JNote: In the format string, "%"PRIsVALUE can be used for Object#to_s ;TI"I(or Object#inspect if '+' flag is set) output (and related argument ;TI"Fmust be a VALUE).  Since it conflicts with "%i", for integers in ;TI"format strings, use "%d".;T@o;;[I"6rb_str_cat(VALUE str, const char *ptr, long len) ;T;[o;	;[I";Appends len bytes of data from ptr to the Ruby string.;T@o;;[I"-rb_str_cat2(VALUE str, const char* ptr) ;TI"1rb_str_cat_cstr(VALUE str, const char* ptr) ;T;[o;	;[I"@Appends C string ptr to Ruby string str.  This function is ;TI"5equivalent to rb_str_cat(str, ptr, strlen(ptr)).;T@o;;[I"5rb_str_catf(VALUE str, const char* format, ...) ;TI"=rb_str_vcatf(VALUE str, const char* format, va_list ap) ;T;[o;	;[	I"EAppends C string format and successive arguments to Ruby string ;TI"Astr according to a printf-like format.  These functions are ;TI"Aequivalent to rb_str_cat2(str, rb_sprintf(format, ...)) and ;TI"=rb_str_cat2(str, rb_vsprintf(format, ap)), respectively.;T@o;;[I"Arb_enc_str_new(const char *ptr, long len, rb_encoding *enc) ;TI"<rb_enc_str_new_cstr(const char *ptr, rb_encoding *enc) ;T;[o;	;[I";Creates a new Ruby string with the specified encoding.;T@o;;[I"-rb_enc_str_new_literal(const char *ptr) ;T;[o;	;[I"JCreates a new Ruby string from a C string literal with the specified ;TI"encoding.;T@o;;[I"3rb_usascii_str_new(const char *ptr, long len) ;TI".rb_usascii_str_new_cstr(const char *ptr) ;T;[o;	;[I"6Creates a new Ruby string with encoding US-ASCII.;T@o;;[I"1rb_usascii_str_new_literal(const char *ptr) ;T;[o;	;[I"ECreates a new Ruby string from a C string literal with encoding ;TI"US-ASCII.;T@o;;[I"0rb_utf8_str_new(const char *ptr, long len) ;TI"+rb_utf8_str_new_cstr(const char *ptr) ;T;[o;	;[I"3Creates a new Ruby string with encoding UTF-8.;T@o;;[I".rb_utf8_str_new_literal(const char *ptr) ;T;[o;	;[I"ECreates a new Ruby string from a C string literal with encoding ;TI"UTF-8.;T@o;;[I"(rb_str_resize(VALUE str, long len) ;T;[o;	;[I"GResizes Ruby string to len bytes.  If str is not modifiable, this ;TI"Efunction raises an exception.  The length of str must be set in ;TI"Eadvance.  If len is less than the old length the content beyond ;TI"Hlen bytes is discarded, else if len is greater than the old length ;TI"Gthe content beyond the old length bytes will not be preserved but ;TI"Hwill be garbage.  Note that RSTRING_PTR(str) may change by calling ;TI"this function.;T@o;;[I")rb_str_set_len(VALUE str, long len) ;T;[o;	;[	I"ESets the length of Ruby string.  If str is not modifiable, this ;TI"Hfunction raises an exception.  This function preserves the content ;TI"Gupto len bytes, regardless RSTRING_LEN(str).  len must not exceed ;TI"the capacity of str.;T@S;;i;
I"Array Functions;T@o;;;;[
o;;[I"rb_ary_new() ;T;[o;	;[I"'Creates an array with no elements.;T@o;;[I"rb_ary_new2(long len) ;TI"rb_ary_new_capa(long len) ;T;[o;	;[I"CCreates an array with no elements, allocating internal buffer ;TI"for len elements.;T@o;;[I"rb_ary_new3(long n, ...) ;TI"'rb_ary_new_from_args(long n, ...) ;T;[o;	;[I"3Creates an n-element array from the arguments.;T@o;;[I"&rb_ary_new4(long n, VALUE *elts) ;TI"1rb_ary_new_from_values(long n, VALUE *elts) ;T;[o;	;[I"/Creates an n-element array from a C array.;T@o;;[I"rb_ary_to_ary(VALUE obj) ;T;[o;	;[I"(Converts the object into an array. ;TI"!Equivalent to Object#to_ary.;T@o;	;[I"PThere are many functions to operate an array.  They may dump core if other ;TI"types are given.;T@o;;;;[
o;;[I"/rb_ary_aref(argc, VALUE *argv, VALUE ary) ;T;[o;	;[I"Equivalent to Array#[].;T@o;;[I"*rb_ary_entry(VALUE ary, long offset) ;T;[o;	;[I"ary[offset];T@o;;[I"5rb_ary_store(VALUE ary, long offset, VALUE obj) ;T;[o;	;[I"ary[offset] = obj;T@o;;[I"2rb_ary_subseq(VALUE ary, long beg, long len) ;T;[o;	;[I"ary[beg, len];T@o;;[
I"'rb_ary_push(VALUE ary, VALUE val) ;TI"rb_ary_pop(VALUE ary) ;TI"rb_ary_shift(VALUE ary) ;TI"*rb_ary_unshift(VALUE ary, VALUE val) ;TI"7rb_ary_cat(VALUE ary, const VALUE *ptr, long len) ;T;[o;	;[I";Appends len elements of objects from ptr to the array.;T@S;;i;
I"Extending Ruby with C;T@S;;i;
I" Adding New Features to Ruby;T@o;	;[I"CYou can add new features (classes, methods, etc.) to the Ruby ;TI"Hinterpreter.  Ruby provides APIs for defining the following things:;T@o;;[I"Classes, Modules
;TI" Methods, Singleton Methods
;TI"Constants
;T;0S;;i;
I" Class and Module Definition;T@o;	;[I":To define a class or module, use the functions below:;T@o;;[I":VALUE rb_define_class(const char *name, VALUE super)
;TI".VALUE rb_define_module(const char *name)
;T;0o;	;[I"HThese functions return the newly created class or module.  You may ;TI">want to save this reference into a variable to use later.;T@o;	;[I"BTo define nested classes or modules, use the functions below:;T@o;;[I"MVALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)
;TI"AVALUE rb_define_module_under(VALUE outer, const char *name)
;T;0S;;i;
I"+Method and Singleton Method Definition;T@o;	;[I"ATo define methods or singleton methods, use these functions:;T@o;;[
I":void rb_define_method(VALUE klass, const char *name,
;TI"6                      VALUE (*func)(), int argc)
;TI"
;TI"Evoid rb_define_singleton_method(VALUE object, const char *name,
;TI"@                                VALUE (*func)(), int argc)
;T;0o;	;[I"JThe `argc' represents the number of the arguments to the C function, ;TI"Dwhich must be less than 17.  But I doubt you'll need that many.;T@o;	;[I"MIf `argc' is negative, it specifies the calling sequence, not number of ;TI"the arguments.;T@o;	;[I"3If argc is -1, the function will be called as:;T@o;;[I"2VALUE func(int argc, VALUE *argv, VALUE obj)
;T;0o;	;[I"Jwhere argc is the actual number of arguments, argv is the C array of ;TI",the arguments, and obj is the receiver.;T@o;	;[I"KIf argc is -2, the arguments are passed in a Ruby array. The function ;TI"will be called like:;T@o;;[I"'VALUE func(VALUE obj, VALUE args)
;T;0o;	;[I"Fwhere obj is the receiver, and args is the Ruby array containing ;TI"actual arguments.;T@o;	;[I"FThere are some more functions to define methods. One takes an ID ;TI"Fas the name of method to be defined. See also ID or Symbol below.;T@o;;[I"4void rb_define_method_id(VALUE klass, ID name,
;TI"@                         VALUE (*func)(ANYARGS), int argc)
;T;0o;	;[I"AThere are two functions to define private/protected methods:;T@o;;[	I"Bvoid rb_define_private_method(VALUE klass, const char *name,
;TI">                              VALUE (*func)(), int argc)
;TI"Dvoid rb_define_protected_method(VALUE klass, const char *name,
;TI"@                                VALUE (*func)(), int argc)
;T;0o;	;[	I"DAt last, rb_define_module_function defines a module functions, ;TI"<which are private AND singleton methods of the module. ;TI"FFor example, sqrt is the module function defined in Math module. ;TI"+It can be called in the following way:;T@o;;[I"Math.sqrt(4)
;T;0o;	;[I"or;T@o;;[I"include Math
;TI"
sqrt(4)
;T;0o;	;[I"%To define module functions, use:;T@o;;[I"Dvoid rb_define_module_function(VALUE module, const char *name,
;TI"?                               VALUE (*func)(), int argc)
;T;0o;	;[I"KIn addition, function-like methods, which are private methods defined ;TI"0in the Kernel module, can be defined using:;T@o;;[I"Qvoid rb_define_global_function(const char *name, VALUE (*func)(), int argc)
;T;0o;	;[I"'To define an alias for the method,;T@o;;[I"Kvoid rb_define_alias(VALUE module, const char* new, const char* old);
;T;0o;	;[I"0To define a reader/writer for an attribute,;T@o;;[I"Mvoid rb_define_attr(VALUE klass, const char *name, int read, int write)
;T;0o;	;[I"8To define and undefine the `allocate' class method,;T@o;;[I"Ivoid rb_define_alloc_func(VALUE klass, VALUE (*func)(VALUE klass));
;TI",void rb_undef_alloc_func(VALUE klass);
;T;0o;	;[I"Cfunc has to take the klass as the argument and return a newly ;TI"Hallocated instance.  This instance should be as empty as possible, ;TI":without any expensive (including external) resources.;T@o;	;[I"MIf you are overriding an existing method of any ancestor of your class, ;TI"you may rely on:;T@o;;[I"6VALUE rb_call_super(int argc, const VALUE *argv)
;T;0o;	;[I"FTo achieve the receiver of the current scope (if no other way is ;TI"available), you can use:;T@o;;[I"%VALUE rb_current_receiver(void)
;T;0S;;i;
I"Constant Definition;T@o;	;[I"-We have 2 functions to define constants:;T@o;;[I"Dvoid rb_define_const(VALUE klass, const char *name, VALUE val)
;TI">void rb_define_global_const(const char *name, VALUE val)
;T;0o;	;[I"KThe former is to define a constant under specified class/module.  The ;TI"+latter is to define a global constant.;T@S;;i;
I"Use Ruby Features from C;T@o;	;[I"BThere are several ways to invoke Ruby's features from C code.;T@S;;i;
I"'Evaluate Ruby Programs in a String;T@o;	;[I"HThe easiest way to use Ruby's functionality from a C program is to ;TI"Ievaluate the string as Ruby program.  This function will do the job:;T@o;;[I"+VALUE rb_eval_string(const char *str)
;T;0o;	;[I"PEvaluation is done under the current context, thus current local variables ;TI"Hof the innermost method (which is defined by Ruby) can be accessed.;T@o;	;[I"GNote that the evaluation can raise an exception. There is a safer ;TI"function:;T@o;;[I"?VALUE rb_eval_string_protect(const char *str, int *state)
;T;0o;	;[I"MIt returns nil when an error occur. Moreover, *state is zero if str was ;TI"2successfully evaluated, or nonzero otherwise.;T@S;;i;
I"ID or Symbol;T@o;	;[
I"KYou can invoke methods directly, without parsing the string.  First I ;TI"Fneed to explain about ID.  ID is the integer number to represent ;TI"DRuby's identifiers such as variable names.  The Ruby data type ;TI"Icorresponding to ID is Symbol.  It can be accessed from Ruby in the ;TI"
form:;T@o;;[I":Identifier
;T;0o;	;[I"or;T@o;;[I":"any kind of string"
;T;0o;	;[I"BYou can get the ID value from a string within C code by using;T@o;;[I"!rb_intern(const char *name)
;TI"rb_intern_str(VALUE name)
;T;0o;	;[I"IYou can retrieve ID from Ruby object (Symbol or String) given as an ;TI"argument by using;T@o;;[I"rb_to_id(VALUE symbol)
;TI"'rb_check_id(volatile VALUE *name)
;TI"Drb_check_id_cstr(const char *name, long len, rb_encoding *enc)
;T;0o;	;[I"KThese functions try to convert the argument to a String if it was not ;TI"Fa Symbol nor a String.  The second function stores the converted ;TI"Kresult into *name, and returns 0 if the string is not a known symbol. ;TI"FAfter this function returned a non-zero value, *name is always a ;TI"FSymbol or a String, otherwise it is a String if the result is 0. ;TI"FThe third function takes NUL-terminated C string, not Ruby VALUE.;T@o;	;[I"JYou can retrieve Symbol from Ruby object (Symbol or String) given as ;TI"an argument by using;T@o;;[I"rb_to_symbol(VALUE name)
;TI",rb_check_symbol(volatile VALUE *namep)
;TI"Grb_check_symbol_cstr(const char *ptr, long len, rb_encoding *enc)
;T;0o;	;[I"FThese functions are similar to above functions except that these ;TI"&return a Symbol instead of an ID.;T@o;	;[I"1You can convert C ID to Ruby Symbol by using;T@o;;[I"VALUE ID2SYM(ID id)
;T;0o;	;[I"1and to convert Ruby Symbol object to ID, use;T@o;;[I"ID SYM2ID(VALUE symbol)
;T;0S;;i;
I"Invoke Ruby Method from C;T@o;	;[I"?To invoke methods directly, you can use the function below;T@o;;[I"9VALUE rb_funcall(VALUE recv, ID mid, int argc, ...)
;T;0o;	;[I"FThis function invokes a method on the recv, with the method name ;TI"!specified by the symbol mid.;T@S;;i;
I"*Accessing the Variables and Constants;T@o;	;[I"HYou can access class variables and instance variables using access ;TI"Cfunctions.  Also, global variables can be shared between both ;TI"Denvironments.  There's no way to access Ruby's local variables.;T@o;	;[I"AThe functions to access/modify instance variables are below:;T@o;;[I")VALUE rb_ivar_get(VALUE obj, ID id)
;TI"4VALUE rb_ivar_set(VALUE obj, ID id, VALUE val)
;T;0o;	;[I"Bid must be the symbol, which can be retrieved by rb_intern().;T@o;	;[I"1To access the constants of the class/module:;T@o;;[I"*VALUE rb_const_get(VALUE obj, ID id)
;T;0o;	;[I"(See also Constant Definition above.;T@S;;i;
I"+Information Sharing Between Ruby and C;T@S;;i;
I"1Ruby Constants That C Can Be Accessed From C;T@o;	;[I"As stated in section 1.3, ;TI"9the following Ruby constants can be referred from C.;T@o;;[I"Qtrue
;TI"Qfalse
;T;0o;	;[I"9Boolean values.  Qfalse is false in C also (i.e. 0).;T@o;;[I"
Qnil
;T;0o;	;[I"Ruby nil in C scope.;T@S;;i;
I"/Global Variables Shared Between C and Ruby;T@o;	;[I"PInformation can be shared between the two environments using shared global ;TI"Dvariables.  To define them, you can use functions listed below:;T@o;;[I";void rb_define_variable(const char *name, VALUE *var)
;T;0o;	;[I"NThis function defines the variable which is shared by both environments. ;TI"JThe value of the global variable pointed to by `var' can be accessed ;TI"1through Ruby's global variable named `name'.;T@o;	;[I"IYou can define read-only (from Ruby, of course) variables using the ;TI"function below.;T@o;;[I"Dvoid rb_define_readonly_variable(const char *name, VALUE *var)
;T;0o;	;[I"KYou can defined hooked variables.  The accessor functions (getter and ;TI":setter) are called on access to the hooked variables.;T@o;;[I"Bvoid rb_define_hooked_variable(const char *name, VALUE *var,
;TI"I                               VALUE (*getter)(), void (*setter)())
;T;0o;	;[I"JIf you need to supply either setter or getter, just supply 0 for the ;TI"Lhook you don't need.  If both hooks are 0, rb_define_hooked_variable() ;TI"*works just like rb_define_variable().;T@o;	;[I"FThe prototypes of the getter and setter functions are as follows:;T@o;;[I")VALUE (*getter)(ID id, VALUE *var);
;TI"3void (*setter)(VALUE val, ID id, VALUE *var);
;T;0o;	;[I"JAlso you can define a Ruby global variable without a corresponding C ;TI"Hvariable.  The value of the variable will be set/get only by hooks.;T@o;;[I"7void rb_define_virtual_variable(const char *name,
;TI"J                                VALUE (*getter)(), void (*setter)())
;T;0o;	;[I"FThe prototypes of the getter and setter functions are as follows:;T@o;;[I"VALUE (*getter)(ID id);
;TI"'void (*setter)(VALUE val, ID id);
;T;0S;;i;
I"*Encapsulate C Data into a Ruby Object;T@o;	;[I"CTo wrap and objectify a C pointer as a Ruby object (so called ;TI"#DATA), use Data_Wrap_Struct().;T@o;;[I"/Data_Wrap_Struct(klass, mark, free, sval)
;T;0o;	;[I"KData_Wrap_Struct() returns a created DATA object.  The klass argument ;TI"Jis the class for the DATA object.  The mark argument is the function ;TI"Jto mark Ruby objects pointed by this data.  The free argument is the ;TI"Jfunction to free the pointer allocation.  If this is -1, the pointer ;TI"Jwill be just freed.  The functions mark and free will be called from ;TI"garbage collector.;T@o;	;[I"FThese mark / free functions are invoked during GC execution.  No ;TI"Gobject allocations are allowed during it, so do not allocate ruby ;TI"objects inside them.;T@o;	;[I"9You can allocate and wrap the structure in one step.;T@o;;[I"5Data_Make_Struct(klass, type, mark, free, sval)
;T;0o;	;[I"JThis macro returns an allocated Data object, wrapping the pointer to ;TI"Dthe structure, which is also allocated.  This macro works like:;T@o;;[I"E(sval = ALLOC(type), Data_Wrap_Struct(klass, mark, free, sval))
;T;0o;	;[I"EArguments klass, mark, and free work like their counterparts in ;TI"GData_Wrap_Struct().  A pointer to the allocated structure will be ;TI"Gassigned to sval, which should be a pointer of the type specified.;T@o;	;[I"CTo retrieve the C pointer from the Data object, use the macro ;TI"Data_Get_Struct().;T@o;;[I"&Data_Get_Struct(obj, type, sval)
;T;0o;	;[I"FA pointer to the structure will be assigned to the variable sval.;T@o;	;[I"'See the example below for details.;T@S;;i;
I"%Example - Creating dbm Extension;T@o;	;[I"IOK, here's the example of making an extension library.  This is the ;TI"Hextension to access DBMs.  The full source is included in the ext/ ;TI")directory in the Ruby's source tree.;T@S;;i;
I"Make the Directory;T@o;;[I"% mkdir ext/dbm
;T;0o;	;[I"DMake a directory for the extension library under ext directory.;T@S;;i;
I"Design the Library;T@o;	;[I"?You need to design the library features, before making it.;T@S;;i;
I"Write the C Code;T@o;	;[
I"KYou need to write C code for your extension library.  If your library ;TI"Hhas only one source file, choosing ``LIBRARY.c'' as a file name is ;TI"Mpreferred.  On the other hand, in case your library has multiple source ;TI"Kfiles, avoid choosing ``LIBRARY.c'' for a file name.  It may conflict ;TI"@with an intermediate file ``LIBRARY.o'' on some platforms. ;TI"GNote that some functions in mkmf library described below generate ;TI"Ia file ``conftest.c'' for checking with compilation.  You shouldn't ;TI"6choose ``conftest.c'' as a name of a source file.;T@o;	;[I"KRuby will execute the initializing function named ``Init_LIBRARY'' in ;TI"Mthe library.  For example, ``Init_dbm()'' will be executed when loading ;TI"the library.;T@o;	;[I"4Here's the example of an initializing function.;T@o;;[I"
void
;TI"Init_dbm(void)
;TI"{
;TI"     /* define DBM class */
;TI":    VALUE cDBM = rb_define_class("DBM", rb_cObject);
;TI".    /* DBM includes Enumerable module */
;TI"2    rb_include_module(cDBM, rb_mEnumerable);
;TI"
;TI"N    /* DBM has class method open(): arguments are received as C array */
;TI"D    rb_define_singleton_method(cDBM, "open", fdbm_s_open, -1);
;TI"
;TI"4    /* DBM instance method close(): no args */
;TI"9    rb_define_method(cDBM, "close", fdbm_close, 0);
;TI"2    /* DBM instance method []: 1 argument */
;TI"6    rb_define_method(cDBM, "[]", fdbm_fetch, 1);
;TI"
;TI"    /* ... */
;TI"
;TI"<    /* ID for a instance variable to store DBM data */
;TI"$    id_dbm = rb_intern("dbm");
;TI"}
;T;0o;	;[I"GThe dbm extension wraps the dbm struct in the C environment using ;TI"Data_Make_Struct.;T@o;;[I"struct dbmdata {
;TI"    int  di_size;
;TI"    DBM *di_dbm;
;TI"};
;TI"
;TI"Gobj = Data_Make_Struct(klass, struct dbmdata, 0, free_dbm, dbmp);
;T;0o;	;[I"IThis code wraps the dbmdata structure into a Ruby object.  We avoid ;TI"Gwrapping DBM* directly, because we want to cache size information.;T@o;	;[I"ITo retrieve the dbmdata structure from a Ruby object, we define the ;TI"following macro:;T@o;;[	I"%#define GetDBM(obj, dbmp) do {\
;TI"6    Data_Get_Struct(obj, struct dbmdata, dbmp);\
;TI"/    if (dbmp->di_dbm == 0) closed_dbm();\
;TI"} while (0)
;T;0o;	;[I"OThis sort of complicated macro does the retrieving and close checking for ;TI"
the DBM.;T@o;	;[I"GThere are three kinds of way to receive method arguments.  First, ;TI"Jmethods with a fixed number of arguments receive arguments like this:;T@o;;[
I"static VALUE
;TI"*fdbm_delete(VALUE obj, VALUE keystr)
;TI"{
;TI"      /* ... */
;TI"}
;T;0o;	;[I"HThe first argument of the C function is the self, the rest are the ;TI"arguments to the method.;T@o;	;[I"CSecond, methods with an arbitrary number of arguments receive ;TI"arguments like this:;T@o;;[I"static VALUE
;TI"5fdbm_s_open(int argc, VALUE *argv, VALUE klass)
;TI"{
;TI"    /* ... */
;TI"C    if (rb_scan_args(argc, argv, "11", &file, &vmode) == 1) {
;TI"7        mode = 0666;          /* default value */
;TI"    }
;TI"    /* ... */
;TI"}
;T;0o;	;[I"FThe first argument is the number of method arguments, the second ;TI"Dargument is the C array of the method arguments, and the third ;TI",argument is the receiver of the method.;T@o;	;[	I"GYou can use the function rb_scan_args() to check and retrieve the ;TI"Farguments.  The third argument is a string that specifies how to ;TI"Ecapture method arguments and assign them to the following VALUE ;TI"references.;T@o;	;[I"LThe following is an example of a method that takes arguments by Ruby's ;TI"array:;T@o;;[
I"static VALUE
;TI"1thread_initialize(VALUE thread, VALUE args)
;TI"{
;TI"    /* ... */
;TI"}
;T;0o;	;[I"JThe first argument is the receiver, the second one is the Ruby array ;TI"0which contains the arguments to the method.;T@o;;[I"SNotice*: GC should know about global variables which refer to Ruby's objects,
;T;0o;	;[I"Ibut are not exported to the Ruby world.  You need to protect them by;T@o;;[I")void rb_global_variable(VALUE *var)
;T;0S;;i;
I"Prepare extconf.rb;T@o;	;[I"JIf the file named extconf.rb exists, it will be executed to generate ;TI"Makefile.;T@o;	;[I"Jextconf.rb is the file for checking compilation conditions etc.  You ;TI"need to put;T@o;;[I"require 'mkmf'
;T;0o;	;[I"Gat the top of the file.  You can use the functions below to check ;TI"various conditions.;T@o;;[I"Ihave_macro(macro[, headers[, opt]]): check whether macro is defined
;TI"chave_library(lib[, func[, headers[, opt]]]): check whether library containing function exists
;TI"@find_library(lib[, func, *paths]): find library from paths
;TI"Ehave_func(func[, headers[, opt]): check whether function exists
;TI"Dhave_var(var[, headers[, opt]]): check whether variable exists
;TI"Phave_header(header[, preheaders[, opt]]): check whether header file exists
;TI"9find_header(header, *paths): find header from paths
;TI"Fhave_framework(fw): check whether framework exists (for MacOS X)
;TI"Yhave_struct_member(type, member[, headers[, opt]]): check whether struct has member
;TI"Bhave_type(type[, headers[, opt]]): check whether type exists
;TI"Jfind_type(type, opt, *headers): check whether type exists in headers
;TI"Lhave_const(const[, headers[, opt]]): check whether constant is defined
;TI"?check_sizeof(type[, headers[, opts]]): check size of type
;TI"Icheck_signedness(type[, headers[, opts]]): check signedness of type
;TI"Mconvertible_int(type[, headers[, opts]]): find convertible integer type
;TI"=find_executable(bin[, path]): find executable file path
;TI"7create_header(header): generate configured header
;TI"Acreate_makefile(target[, target_prefix]): generate Makefile
;T;0o;	;[I"@See MakeMakefile for full documentation of these functions.;T@o;	;[I"?The value of the variables below will affect the Makefile.;T@o;;[	I"<$CFLAGS: included in CFLAGS make variable (such as -O)
;TI"D$CPPFLAGS: included in CPPFLAGS make variable (such as -I, -D)
;TI">$LDFLAGS: included in LDFLAGS make variable (such as -L)
;TI"&$objs: list of object file names
;T;0o;	;[I"MNormally, the object files list is automatically generated by searching ;TI"Ksource files, but you must define them explicitly if any sources will ;TI"!be generated while building.;T@o;	;[I"FIf a compilation condition is not fulfilled, you should not call ;TI"P``create_makefile''.  The Makefile will not be generated, compilation will ;TI"not be done.;T@S;;i;
I"Prepare Depend (Optional);T@o;	;[I"IIf the file named depend exists, Makefile will include that file to ;TI"<check dependencies.  You can make this file by invoking;T@o;;[I"% gcc -MM *.c > depend
;T;0o;	;[I" It's harmless.  Prepare it.;T@S;;i;
I"Generate Makefile;T@o;	;[I"$Try generating the Makefile by:;T@o;;[I"ruby extconf.rb
;T;0o;	;[I"DIf the library should be installed under vendor_ruby directory ;TI"Dinstead of site_ruby directory, use --vendor option as follows.;T@o;;[I"ruby extconf.rb --vendor
;T;0o;	;[I"MYou don't need this step if you put the extension library under the ext ;TI"Jdirectory of the ruby source tree.  In that case, compilation of the ;TI"+interpreter will do this step for you.;T@S;;i;
I"
Run make;T@o;	;[I"	Type;T@o;;[I"
make
;T;0o;	;[I"Mto compile your extension.  You don't need this step either if you have ;TI"Oput the extension library under the ext directory of the ruby source tree.;T@S;;i;
I"
Debug;T@o;	;[I"GYou may need to rb_debug the extension.  Extensions can be linked ;TI"Kstatically by adding the directory name in the ext/Setup file so that ;TI"5you can inspect the extension with the debugger.;T@S;;i;
I"-Done! Now You Have the Extension Library;T@o;	;[I"IYou can do anything you want with your library.  The author of Ruby ;TI"Mwill not claim any restrictions on your code depending on the Ruby API. ;TI"?Feel free to use, modify, distribute or sell your program.;T@S;;i;
I"+Appendix A. Ruby Source Files Overview;T@S;;i;
I"Ruby Language Core;T@o;;;;[o;;[I"class.c    ;T;[o;	;[I"classes and modules;To;;[I"error.c    ;T;[o;	;[I".exception classes and exception mechanism;To;;[I"gc.c       ;T;[o;	;[I"memory management;To;;[I"load.c     ;T;[o;	;[I"library loading;To;;[I"object.c   ;T;[o;	;[I"objects;To;;[I"variable.c ;T;[o;	;[I"variables and constants;T@S;;i;
I"Ruby Syntax Parser;T@o;;;;[	o;;[I"parse.y  ;T;[o;	;[I"grammar definition;To;;[I"parse.c  ;T;[o;	;[I")automatically generated from parse.y;To;;[I"keywords ;T;[o;	;[I"reserved keywords;To;;[I"lex.c    ;T;[o;	;[I"*automatically generated from keywords;T@S;;i;
I"!Ruby Evaluator (a.k.a. YARV);T@o;;[I"compile.c
;TI"eval.c
;TI"eval_error.c
;TI"eval_jump.c
;TI"eval_safe.c
;TI"9insns.def           : definition of VM instructions
;TI"6iseq.c              : implementation of VM::ISeq
;TI"Cthread.c            : thread management and context switching
;TI"1thread_win32.c      : thread implementation
;TI"!thread_pthread.c    : ditto
;TI"
vm.c
;TI"vm_dump.c
;TI"vm_eval.c
;TI"vm_exec.c
;TI"vm_insnhelper.c
;TI"vm_method.c
;TI"
;TI"3opt_insns_unif.def  : instruction unification
;TI"8opt_operand.def     : definitions for optimization
;TI"
;TI"3  -> insn*.inc      : automatically generated
;TI"3  -> opt*.inc       : automatically generated
;TI"3  -> vm.inc         : automatically generated
;T;0S;;i;
I"*Regular Expression Engine (Oniguruma);T@o;;[I"
regex.c
;TI"regcomp.c
;TI"regenc.c
;TI"regerror.c
;TI"regexec.c
;TI"regparse.c
;TI"regsyntax.c
;T;0S;;i;
I"Utility Functions;T@o;;;;[
o;;[I"debug.c    ;T;[o;	;[I"!debug symbols for C debugger;To;;[I"dln.c      ;T;[o;	;[I"dynamic loading;To;;[I"st.c       ;T;[o;	;[I"general purpose hash table;To;;[I"strftime.c ;T;[o;	;[I"formatting times;To;;[I"util.c     ;T;[o;	;[I"misc utilities;T@S;;i;
I"$Ruby Interpreter Implementation;T@o;;[I"dmyext.c
;TI"dmydln.c
;TI"dmyencoding.c
;TI"
id.c
;TI"
inits.c
;TI"main.c
;TI"ruby.c
;TI"version.c
;TI"
;TI"gem_prelude.rb
;TI"prelude.rb
;T;0S;;i;
I"Class Library;T@o;;;;[!o;;[I"array.c      ;T;[o;	;[I"
Array;To;;[I"bignum.c     ;T;[o;	;[I"Bignum;To;;[I"compar.c     ;T;[o;	;[I"Comparable;To;;[I"complex.c    ;T;[o;	;[I"Complex;To;;[I"cont.c       ;T;[o;	;[I"Fiber, Continuation;To;;[I"dir.c        ;T;[o;	;[I"Dir;To;;[I"enum.c       ;T;[o;	;[I"Enumerable;To;;[I"enumerator.c ;T;[o;	;[I"Enumerator;To;;[I"file.c       ;T;[o;	;[I"	File;To;;[I"hash.c       ;T;[o;	;[I"	Hash;To;;[I"io.c         ;T;[o;	;[I"IO;To;;[I"marshal.c    ;T;[o;	;[I"Marshal;To;;[I"math.c       ;T;[o;	;[I"	Math;To;;[I"numeric.c    ;T;[o;	;[I"$Numeric, Integer, Fixnum, Float;To;;[I"pack.c       ;T;[o;	;[I"Array#pack, String#unpack;To;;[I"proc.c       ;T;[o;	;[I"Binding, Proc;To;;[I"process.c    ;T;[o;	;[I"Process;To;;[I"random.c     ;T;[o;	;[I"random number;To;;[I"range.c      ;T;[o;	;[I"
Range;To;;[I"rational.c   ;T;[o;	;[I"
Rational;To;;[I"re.c         ;T;[o;	;[I"Regexp, MatchData;To;;[I"signal.c     ;T;[o;	;[I"Signal;To;;[I"sprintf.c    ;T;[o;	;[I"String#sprintf;To;;[I"string.c     ;T;[o;	;[I"String;To;;[I"struct.c     ;T;[o;	;[I"Struct;To;;[I"time.c       ;T;[o;	;[I"	Time;T@o;;[I"defs/known_errors.def ;T;[o;	;[I"Errno::* exception classes;To;;[I"-> known_errors.inc   ;T;[o;	;[I"automatically generated;T@S;;i;
I"Multilingualization;T@o;;;;[	o;;[I"encoding.c  ;T;[o;	;[I"
Encoding;To;;[I"transcode.c ;T;[o;	;[I"Encoding::Converter;To;;[I"enc/*.c     ;T;[o;	;[I"encoding classes;To;;[I"enc/trans/* ;T;[o;	;[I"codepoint mapping tables;T@S;;i;
I"&goruby Interpreter Implementation;T@o;;[I"goruby.c
;TI"6golf_prelude.rb     : goruby specific libraries.
;TI"3  -> golf_prelude.c : automatically generated
;T;0S;;i;
I"-Appendix B. Ruby Extension API Reference;T@S;;i;
I"
Types;T@o;;;;[o;;[I"VALUE ;T;[o;	;[I"MThe type for the Ruby object.  Actual structures are defined in ruby.h, ;TI"Jsuch as struct RString, etc.  To refer the values in structures, use ;TI"&casting macros like RSTRING(obj).;T@S;;i;
I"Variables and Constants;T@o;;;;[o;;[I"	Qnil;T;[o;	;[I"nil object;T@o;;[I"
Qtrue;T;[o;	;[I"%true object (default true value);T@o;;[I"Qfalse;T;[o;	;[I"false object;T@S;;i;
I"C Pointer Wrapping;T@o;;;;[o;;[I"OData_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval) ;T;[o;	;[
I"MWrap a C pointer into a Ruby object.  If object has references to other ;TI"KRuby objects, they should be marked by using the mark function during ;TI"Kthe GC process.  Otherwise, mark should be 0.  When this object is no ;TI"Hlonger referred by anywhere, the pointer will be discarded by free ;TI"function.;T@o;;[I"5Data_Make_Struct(klass, type, mark, free, sval) ;T;[o;	;[I"LThis macro allocates memory using malloc(), assigns it to the variable ;TI"Ksval, and returns the DATA encapsulating the pointer to memory region.;T@o;;[I"'Data_Get_Struct(data, type, sval) ;T;[o;	;[I"IThis macro retrieves the pointer value from DATA, and assigns it to ;TI"the variable sval.;T@S;;i;
I"Checking Data Types;T@o;;;;[
o;;[I"TYPE(value) ;T;[o;	;[I"*Internal type (T_NIL, T_FIXNUM, etc.);T@o;;[I"FIXNUM_P(value) ;T;[o;	;[I"Is +value+ a Fixnum?;T@o;;[I"NIL_P(value) ;T;[o;	;[I"Is +value+ nil?;T@o;;[I",void Check_Type(VALUE value, int type) ;T;[o;	;[I"JEnsures +value+ is of the given internal +type+ or raises a TypeError;T@o;;[I"SaveStringValue(value) ;T;[o;	;[I"7Checks that +value+ is a String and is not tainted;T@S;;i;
I"Data Type Conversion;T@o;;;;[o;;[I" FIX2INT(value), INT2FIX(i) ;T;[o;	;[I"Fixnum <-> integer;T@o;;[I""FIX2LONG(value), LONG2FIX(l) ;T;[o;	;[I"Fixnum <-> long;T@o;;[I" NUM2INT(value), INT2NUM(i) ;T;[o;	;[I"Numeric <-> integer;T@o;;[I"#NUM2UINT(value), UINT2NUM(ui) ;T;[o;	;[I"!Numeric <-> unsigned integer;T@o;;[I""NUM2LONG(value), LONG2NUM(l) ;T;[o;	;[I"Numeric <-> long;T@o;;[I"%NUM2ULONG(value), ULONG2NUM(ul) ;T;[o;	;[I"Numeric <-> unsigned long;T@o;;[I"NUM2LL(value), LL2NUM(ll) ;T;[o;	;[I"Numeric <-> long long;T@o;;[I""NUM2ULL(value), ULL2NUM(ull) ;T;[o;	;[I"#Numeric <-> unsigned long long;T@o;;[I"$NUM2OFFT(value), OFFT2NUM(off) ;T;[o;	;[I"Numeric <-> off_t;T@o;;[I"'NUM2SIZET(value), SIZET2NUM(size) ;T;[o;	;[I"Numeric <-> size_t;T@o;;[I"*NUM2SSIZET(value), SSIZET2NUM(ssize) ;T;[o;	;[I"Numeric <-> ssize_t;T@o;;[I"
|rb_integer_pack(value, words, numwords, wordsize, nails, flags), rb_integer_unpack(words, numwords, wordsize, nails, flags) ;T;[o;	;[I".Numeric <-> Arbitrary size integer buffer;T@o;;[I"NUM2DBL(value) ;T;[o;	;[I"Numeric -> double;T@o;;[I"rb_float_new(f) ;T;[o;	;[I"double -> Float;T@o;;[I"RSTRING_LEN(str) ;T;[o;	;[I"-String -> length of String data in bytes;T@o;;[I"RSTRING_PTR(str) ;T;[o;	;[I"&String -> pointer to String data ;TI";Note that the result pointer may not be NUL-terminated;T@o;;[I"StringValue(value) ;T;[o;	;[I""Object with #to_str -> String;T@o;;[I"StringValuePtr(value) ;T;[o;	;[I"2Object with #to_str -> pointer to String data;T@o;;[I"StringValueCStr(value) ;T;[o;	;[I"EObject with #to_str -> pointer to String data without NUL bytes ;TI"<It is guaranteed that the result data is NUL-terminated;T@o;;[I"rb_str_new2(s) ;T;[o;	;[I"char * -> String;T@S;;i;
I"Defining Class and Module;T@o;;;;[o;;[I":VALUE rb_define_class(const char *name, VALUE super) ;T;[o;	;[I"5Defines a new Ruby class as a subclass of super.;T@o;;[I"NVALUE rb_define_class_under(VALUE module, const char *name, VALUE super) ;T;[o;	;[I"ICreates a new Ruby class as a subclass of super, under the module's ;TI"namespace.;T@o;;[I".VALUE rb_define_module(const char *name) ;T;[o;	;[I"Defines a new Ruby module.;T@o;;[I"BVALUE rb_define_module_under(VALUE module, const char *name) ;T;[o;	;[I"<Defines a new Ruby module under the module's namespace.;T@o;;[I"7void rb_include_module(VALUE klass, VALUE module) ;T;[o;	;[I"MIncludes module into class.  If class already includes it, just ignored.;T@o;;[I"7void rb_extend_object(VALUE object, VALUE module) ;T;[o;	;[I"4Extend the object with the module's attributes.;T@S;;i;
I"Defining Global Variables;T@o;;;;[	o;;[I";void rb_define_variable(const char *name, VALUE *var) ;T;[o;	;[I"LDefines a global variable which is shared between C and Ruby.  If name ;TI"Icontains a character which is not allowed to be part of the symbol, ;TI")it can't be seen from Ruby programs.;T@o;;[I"Dvoid rb_define_readonly_variable(const char *name, VALUE *var) ;T;[o;	;[I";Defines a read-only global variable.  Works just like ;TI"Drb_define_variable(), except the defined variable is read-only.;T@o;;[I"]void rb_define_virtual_variable(const char *name, VALUE (*getter)(), VALUE (*setter)()) ;T;[
o;	;[	I"JDefines a virtual variable, whose behavior is defined by a pair of C ;TI"Dfunctions.  The getter function is called when the variable is ;TI"Nreferenced.  The setter function is called when the variable is set to a ;TI";value.  The prototype for getter/setter functions are:;T@o;;[I"VALUE getter(ID id)
;TI"#void setter(VALUE val, ID id)
;T;0o;	;[I">The getter function must return the value for the access.;T@o;;[I"hvoid rb_define_hooked_variable(const char *name, VALUE *var, VALUE (*getter)(), VALUE (*setter)()) ;T;[
o;	;[I"JDefines hooked variable.  It's a virtual variable with a C variable. ;TI"The getter is called as;T@o;;[I"%VALUE getter(ID id, VALUE *var)
;T;0o;	;[I"4returning a new value.  The setter is called as;T@o;;[I"/void setter(VALUE val, ID id, VALUE *var)
;T;0o;	;[I"HGC requires C global variables which hold Ruby values to be marked.;T@o;	;[I"(void rb_global_variable(VALUE *var);T@o;;[I"*Tells GC to protect these variables.
;T;0S;;i;
I"Constant Definition;T@o;;;;[o;;[I"Dvoid rb_define_const(VALUE klass, const char *name, VALUE val) ;T;[o;	;[I"3Defines a new constant under the class/module.;T@o;;[I">void rb_define_global_const(const char *name, VALUE val) ;T;[o;	;[I"9Defines a global constant.  This is just the same as;T@o;;[I")rb_define_const(cKernal, name, val)
;T;0S;;i;
I"Method Definition;T@o;;;;[	o;;[I"Prb_define_method(VALUE klass, const char *name, VALUE (*func)(), int argc) ;T;[o;	;[
I"JDefines a method for the class.  func is the function pointer.  argc ;TI"Kis the number of arguments.  if argc is -1, the function will receive ;TI"J3 arguments: argc, argv, and self.  if argc is -2, the function will ;TI"Greceive 2 arguments, self and args, where args is a Ruby array of ;TI"the method arguments.;T@o;;[I"Xrb_define_private_method(VALUE klass, const char *name, VALUE (*func)(), int argc) ;T;[o;	;[I"DDefines a private method for the class.  Arguments are same as ;TI"rb_define_method().;T@o;;[I"Zrb_define_singleton_method(VALUE klass, const char *name, VALUE (*func)(), int argc) ;T;[o;	;[I"KDefines a singleton method.  Arguments are same as rb_define_method().;T@o;;[I"?rb_scan_args(int argc, VALUE *argv, const char *fmt, ...) ;T;[o;	;[I"DRetrieve argument from argc and argv to given VALUE references ;TI"Jaccording to the format string.  The format can be described in ABNF ;TI"as follows:;T@o;;[)I"Nscan-arg-spec  := param-arg-spec [option-hash-arg-spec] [block-arg-spec]
;TI"
;TI"Fparam-arg-spec := pre-arg-spec [post-arg-spec] / post-arg-spec /
;TI"-                  pre-opt-post-arg-spec
;TI"Lpre-arg-spec   := num-of-leading-mandatory-args [num-of-optional-args]
;TI"4post-arg-spec  := sym-for-variable-length-args
;TI"8                  [num-of-trailing-mandatory-args]
;TI"Qpre-opt-post-arg-spec := num-of-leading-mandatory-args num-of-optional-args
;TI"=                         num-of-trailing-mandatory-args
;TI"5option-hash-arg-spec := sym-for-option-hash-arg
;TI")block-arg-spec := sym-for-block-arg
;TI"
;TI"Enum-of-leading-mandatory-args  := DIGIT ; The number of leading
;TI"C                                        ; mandatory arguments
;TI"Fnum-of-optional-args           := DIGIT ; The number of optional
;TI"9                                        ; arguments
;TI"Gsym-for-variable-length-args   := "*"   ; Indicates that variable
;TI"D                                        ; length arguments are
;TI"H                                        ; captured as a ruby array
;TI"Fnum-of-trailing-mandatory-args := DIGIT ; The number of trailing
;TI"C                                        ; mandatory arguments
;TI"Hsym-for-option-hash-arg        := ":"   ; Indicates that an option
;TI"L                                        ; hash is captured if the last
;TI"L                                        ; argument is a hash or can be
;TI"H                                        ; converted to a hash with
;TI"H                                        ; #to_hash.  When the last
;TI"F                                        ; argument is nil, it is
;TI"E                                        ; captured if it is not
;TI"G                                        ; ambiguous to take it as
;TI"K                                        ; empty option hash; i.e. '*'
;TI"D                                        ; is not specified and
;TI"H                                        ; arguments are given more
;TI"@                                        ; than sufficient.
;TI"Jsym-for-block-arg              := "&"   ; Indicates that an iterator
;TI"K                                        ; block should be captured if
;TI"5                                        ; given
;T;0o;	;[I"CFor example, "12" means that the method requires at least one ;TI"Kargument, and at most receives three (1+2) arguments.  So, the format ;TI"Kstring must be followed by three variable references, which are to be ;TI"Kassigned to captured arguments.  For omitted arguments, variables are ;TI"Kset to Qnil.  NULL can be put in place of a variable reference, which ;TI"Imeans the corresponding captured argument(s) should be just dropped.;T@o;	;[I"IThe number of given arguments, excluding an option hash or iterator ;TI"block, is returned.;T@o;	;[I"fint rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values);T@o;;[I"LRetrieves argument VALUEs bound to keywords, which directed by +table+
;TI"Linto +values+.  First +required+ number of IDs referred by +table+ are
;TI"?mandatory, and succeeding +optional+ (- +optional+ - 1 if
;TI"?+optional+ is negative) number of IDs are optional.  If a
;TI"Gmandatory key is not contained in +keyword_hash+, raises "missing
;TI"Ekeyword" +ArgumentError+.  If an optional key is not present in
;TI"K+keyword_hash+, the corresponding element in +values+ is not changed.
;TI"IIf +optional+ is negative, rest of +keyword_hash+ are stored in the
;TI"Hnext to optional +values+ as a new Hash, otherwise raises "unknown
;TI"keyword" +ArgumentError+.
;T;0o;	;[I"4VALUE rb_extract_keywords(VALUE *original_hash);T@o;;[	I"FExtracts pairs whose key is a symbol into a new hash from a hash
;TI"Hobject referred by +original_hash+.  If the original hash contains
;TI"Lnon-symbol keys, then they are copied to another hash and the new hash
;TI":is stored through +original_hash+, else 0 is stored.
;T;0S;;i;
I"Invoking Ruby method;T@o;;;;[
o;;[I"9VALUE rb_funcall(VALUE recv, ID mid, int narg, ...) ;T;[o;	;[I"MInvokes a method.  To retrieve mid from a method name, use rb_intern(). ;TI"1Able to call even private/protected methods.;T@o;;[I"BVALUE rb_funcall2(VALUE recv, ID mid, int argc, VALUE *argv) ;TI"BVALUE rb_funcallv(VALUE recv, ID mid, int argc, VALUE *argv) ;T;[o;	;[I"@Invokes a method, passing arguments as an array of values. ;TI"1Able to call even private/protected methods.;T@o;;[I"IVALUE rb_funcallv_public(VALUE recv, ID mid, int argc, VALUE *argv) ;T;[o;	;[I"@Invokes a method, passing arguments as an array of values. ;TI"&Able to call only public methods.;T@o;;[I"+VALUE rb_eval_string(const char *str) ;T;[o;	;[I"8Compiles and executes the string as a Ruby program.;T@o;;[I"$ID rb_intern(const char *name) ;T;[o;	;[I"*Returns ID corresponding to the name.;T@o;;[I"char *rb_id2name(ID id) ;T;[o;	;[I"'Returns the name corresponding ID.;T@o;;[I"&char *rb_class2name(VALUE klass) ;T;[o;	;[I"#Returns the name of the class.;T@o;;[I",int rb_respond_to(VALUE object, ID id) ;T;[o;	;[I"HReturns true if the object responds to the message specified by id.;T@S;;i;
I"Instance Variables;T@o;;;;[o;;[I"2VALUE rb_iv_get(VALUE obj, const char *name) ;T;[o;	;[I"FRetrieve the value of the instance variable.  If the name is not ;TI"Dprefixed by `@', that variable shall be inaccessible from Ruby.;T@o;;[I"=VALUE rb_iv_set(VALUE obj, const char *name, VALUE val) ;T;[o;	;[I"-Sets the value of the instance variable.;T@S;;i;
I"Control Structure;T@o;;;;[o;;[I"kVALUE rb_block_call(VALUE recv, ID mid, int argc, VALUE * argv, VALUE (*func) (ANYARGS), VALUE data2) ;T;[o;	;[
I"GCalls a method on the recv, with the method name specified by the ;TI"Dsymbol mid, with argc arguments in argv, supplying func as the ;TI"Hblock. When func is called as the block, it will receive the value ;TI"Ifrom yield as the first argument, and data2 as the second argument. ;TI"AWhen yielded with multiple values (in C, rb_yield_values(), ;TI"Lrb_yield_values2() and rb_yield_splat()), data2 is packed as an Array, ;TI"Lwhereas yielded values can be gotten via argc/argv of the third/fourth ;TI"arguments.;T@o;;:
LABEL;[o;;[I"
OBSOLETE;T;[o;;;;[o;;[I"RVALUE rb_iterate(VALUE (*func1)(), void *arg1, VALUE (*func2)(), void *arg2) ;T;[@o;;[I"LCalls the function func1, supplying func2 as the block.  func1 will be
;TI"Lcalled with the argument arg1.  func2 receives the value from yield as
;TI"6the first argument, arg2 as the second argument.
;TI"
;TI"OWhen rb_iterate is used in 1.9, func1 has to call some Ruby-level method.
;TI"EThis function is obsolete since 1.9; use rb_block_call instead.
;T;0o;;;;[o;;[I"VALUE rb_yield(VALUE val) ;T;[o;	;[I"(Evaluates the block with value val.;T@o;;[I"QVALUE rb_rescue(VALUE (*func1)(), VALUE arg1, VALUE (*func2)(), VALUE arg2) ;T;[o;	;[	I"KCalls the function func1, with arg1 as the argument.  If an exception ;TI"Ioccurs during func1, it calls func2 with arg2 as the argument.  The ;TI"Freturn value of rb_rescue() is the return value from func1 if no ;TI",exception occurs, from func2 otherwise.;T@o;;[I"QVALUE rb_ensure(VALUE (*func1)(), VALUE arg1, VALUE (*func2)(), VALUE arg2) ;T;[o;	;[I"JCalls the function func1 with arg1 as the argument, then calls func2 ;TI"?with arg2 if execution terminated.  The return value from ;TI"=rb_ensure() is that of func1 when no exception occurred.;T@o;;[I"DVALUE rb_protect(VALUE (*func) (VALUE), VALUE arg, int *state) ;T;[o;	;[I"HCalls the function func with arg as the argument.  If no exception ;TI"Moccurred during func, it returns the result of func and *state is zero. ;TI"IOtherwise, it returns Qnil and sets *state to nonzero.  If state is ;TI"(NULL, it is not set in both cases. ;TI"EYou have to clear the error info with rb_set_errinfo(Qnil) when ;TI"#ignoring the caught exception.;T@o;;[I"!void rb_jump_tag(int state) ;T;[o;	;[I"RContinues the exception caught by rb_protect() and rb_eval_string_protect(). ;TI"Kstate must be the returned value from those functions.  This function ;TI" never return to the caller.;T@o;;[I"void rb_iter_break() ;T;[o;	;[I"LExits from the current innermost block.  This function never return to ;TI"the caller.;T@o;;[I"+void rb_iter_break_value(VALUE value) ;T;[o;	;[I"LExits from the current innermost block with the value.  The block will ;TI"Ireturn the given argument value.  This function never return to the ;TI"caller.;T@S;;i;
I"Exceptions and Errors;T@o;;;;[o;;[I"(void rb_warn(const char *fmt, ...) ;T;[o;	;[I"@Prints a warning message according to a printf-like format.;T@o;;[I"+void rb_warning(const char *fmt, ...) ;T;[o;	;[I"DPrints a warning message according to a printf-like format, if ;TI"$VERBOSE is true.;T@o;;[I";void rb_raise(rb_eRuntimeError, const char *fmt, ...) ;T;[o;	;[I"IRaises RuntimeError.  The fmt is a format string just like printf().;T@o;;[I":void rb_raise(VALUE exception, const char *fmt, ...) ;T;[o;	;[I"NRaises a class exception.  The fmt is a format string just like printf().;T@o;;[I")void rb_fatal(const char *fmt, ...) ;T;[o;	;[I"NRaises a fatal error, terminates the interpreter.  No exception handling ;TI"Gwill be done for fatal errors, but ensure blocks will be executed.;T@o;;[I"'void rb_bug(const char *fmt, ...) ;T;[o;	;[I"FTerminates the interpreter immediately.  This function should be ;TI"Jcalled under the situation caused by the bug in the interpreter.  No ;TI":exception handling nor ensure execution will be done.;T@o;	;[	I"JNote: In the format string, "%"PRIsVALUE can be used for Object#to_s ;TI"I(or Object#inspect if '+' flag is set) output (and related argument ;TI"Fmust be a VALUE).  Since it conflicts with "%i", for integers in ;TI"format strings, use "%d".;T@S;;i;
I")Initialize and Start the Interpreter;T@o;	;[I"PThe embedding API functions are below (not needed for extension libraries):;T@o;;;;[	o;;[I"void ruby_init() ;T;[o;	;[I"!Initializes the interpreter.;T@o;;[I"/void *ruby_options(int argc, char **argv) ;T;[o;	;[	I"9Process command line arguments for the interpreter. ;TI".And compiles the Ruby source to execute. ;TI"9It returns an opaque pointer to the compiled source ;TI""or an internal special value.;T@o;;[I" int ruby_run_node(void *n) ;T;[o;	;[I"<Runs the given compiled source and exits this process. ;TI">It returns EXIT_SUCCESS if successfully runs the source. ;TI"'Otherwise, it returns other value.;T@o;;[I""void ruby_script(char *name) ;T;[o;	;[I"+Specifies the name of the script ($0).;T@S;;i;
I"%Hooks for the Interpreter Events;T@o;;[I"Ovoid rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events,
;TI"(                       VALUE data)
;T;0o;	;[I"@Adds a hook function for the specified interpreter events. ;TI"%events should be OR'ed value of:;T@o;;[I"RUBY_EVENT_LINE
;TI"RUBY_EVENT_CLASS
;TI"RUBY_EVENT_END
;TI"RUBY_EVENT_CALL
;TI"RUBY_EVENT_RETURN
;TI"RUBY_EVENT_C_CALL
;TI"RUBY_EVENT_C_RETURN
;TI"RUBY_EVENT_RAISE
;TI"RUBY_EVENT_ALL
;T;0o;	;[I"5The definition of rb_event_hook_func_t is below:;T@o;;[I"Htypedef void (*rb_event_hook_func_t)(rb_event_t event, VALUE data,
;TI"J                                     VALUE self, ID id, VALUE klass)
;T;0o;	;[I"LThe third argument `data' to rb_add_event_hook() is passed to the hook ;TI"Kfunction as the second argument, which was the pointer to the current ;TI"?NODE in 1.8.  See RB_EVENT_HOOKS_HAVE_CALLBACK_DATA below.;T@o;;[I"9int rb_remove_event_hook(rb_event_hook_func_t func)
;T;0o;	;[I")Removes the specified hook function.;T@S;;i;
I"Macros for Compatibility;T@o;	;[I"GSome macros to check API compatibilities are available by default.;T@o;;;;[o;;[I"NORETURN_STYLE_NEW ;T;[o;	;[I"EMeans that NORETURN macro is functional style instead of prefix.;T@o;;[I"HAVE_RB_DEFINE_ALLOC_FUNC ;T;[o;	;[I"LMeans that function rb_define_alloc_func() is provided, that means the ;TI"Ballocation framework is used.  This is same as the result of ;TI"1have_func("rb_define_alloc_func", "ruby.h").;T@o;;[I"HAVE_RB_REG_NEW_STR ;T;[o;	;[I"KMeans that function rb_reg_new_str() is provided, that creates Regexp ;TI"?object from String object.  This is same as the result of ;TI"+have_func("rb_reg_new_str", "ruby.h").;T@o;;[I"HAVE_RB_IO_T ;T;[o;	;[I")Means that type rb_io_t is provided.;T@o;;[I"USE_SYMBOL_AS_METHOD_NAME ;T;[o;	;[I"@Means that Symbols will be returned as method names, e.g., ;TI"2Module#methods, #singleton_methods and so on.;T@o;;[I"HAVE_RUBY_*_H ;T;[o;	;[I"IDefined in ruby.h and means corresponding header is available.  For ;TI"Kinstance, when HAVE_RUBY_ST_H is defined you should use ruby/st.h not ;TI"mere st.h.;T@o;;[I"'RB_EVENT_HOOKS_HAVE_CALLBACK_DATA ;T;[o;	;[I"KMeans that rb_add_event_hook() takes the third argument `data', to be ;TI"-passed to the given event hook function.;T@S;;i;
I":Appendix C. Functions available for use in extconf.rb;T@o;	;[I"9See documentation for {mkmf}[rdoc-ref:MakeMakefile].;T@S;;i;
I" Appendix D. Generational GC;T@o;	;[I"KRuby 2.1 introduced a generational garbage collector (called RGenGC). ;TI")RGenGC (mostly) keeps compatibility.;T@o;	;[	I"NGenerally, the use of the technique called write barriers is required in ;TI"-extension libraries for generational GC ;TI"O(http://en.wikipedia.org/wiki/Garbage_collection_%28computer_science%29). ;TI"ERGenGC works fine without write barriers in extension libraries.;T@o;	;[I"DIf your library adheres to the following tips, performance can ;TI"Ube further improved. Especially, the "Don't touch pointers directly" section is ;TI"important.;T@S;;i;
I"Incompatibility;T@o;	;[I"KYou can't write RBASIC(obj)->klass field directly because it is const ;TI"value now.;T@o;	;[I"LBasically you should not write this field because MRI expects it to be ;TI"Lan immutable field, but if you want to do it in your extension you can ;TI"!use the following functions:;T@o;;;;[o;;[I""VALUE rb_obj_hide(VALUE obj) ;T;[o;	;[I"GClear RBasic::klass field. The object will be an internal object. ;TI"5ObjectSpace::each_object can't find this object.;T@o;;[I"1VALUE rb_obj_reveal(VALUE obj, VALUE klass) ;T;[o;	;[I"&Reset RBasic::klass to be klass. ;TI"<We expect the `klass' is hidden class by rb_obj_hide().;T@S;;i;
I"Write barriers;T@o;	;[I"GRGenGC doesn't require write barriers to support generational GC. ;TI"HHowever, caring about write barrier can improve the performance of ;TI"-RGenGC. Please check the following tips.;T@S;;i;
I""Don't touch pointers directly;T@o;	;[I"JIn MRI (include/ruby/ruby.h), some macros to acquire pointers to the ;TI"Binternal data structures are supported such as RARRAY_PTR(), ;TI"RSTRUCT_PTR() and so on.;T@o;	;[I"NDO NOT USE THESE MACROS and instead use the corresponding C-APIs such as ;TI"-rb_ary_aref(), rb_ary_store() and so on.;T@S;;i;
I".Consider whether to insert write barriers;T@o;	;[I"JYou don't need to care about write barriers if you only use built-in ;TI"types.;T@o;	;[I"JIf you support T_DATA objects, you may consider using write barriers.;T@o;	;[
I"FInserting write barriers into T_DATA objects only works with the ;TI"Lfollowing type objects: (a) long-lived objects, (b) when a huge number ;TI"Gof objects are generated and (c) container-type objects that have ;TI"Lreferences to other objects. If your extension provides such a type of ;TI"7T_DATA objects, consider inserting write barriers.;T@o;	;[I"C(a): short-lived objects don't become old generation objects. ;TI"C(b): only a few oldgen objects don't have performance impact. ;TI">(c): only a few references don't have performance impact.;T@o;	;[	I"FInserting write barriers is a very difficult hack, it is easy to ;TI"Mintroduce critical bugs. And inserting write barriers has several areas ;TI"Jof overhead. Basically we don't recommend you insert write barriers. ;TI")Please carefully consider the risks.;T@S;;i;
I" Combine with built-in types;T@o;	;[I"KPlease consider utilizing built-in types. Most built-in types support ;TI"Jwrite barrier, so you can use them to avoid manually inserting write ;TI"barriers.;T@o;	;[
I"KFor example, if your T_DATA has references to other objects, then you ;TI"Ncan move these references to Array. A T_DATA object only has a reference ;TI"Ito an array object. Or you can also use a Struct object to gather a ;TI"GT_DATA object (without any references) and an that Array contains ;TI"references.;T@o;	;[I"JWith use of such techniques, you don't need to insert write barriers ;TI"
anymore.;T@S;;i;
I"Insert write barriers;T@o;;;;[o;;[I"
AGAIN;T;[o;	;[I"AInserting write barriers is a very difficult hack, and it is;To;	;[I"Geasy to introduce critical bugs. And inserting write barriers has ;TI"Nseveral areas of overhead. Basically we don't recommend you insert write ;TI"3barriers. Please carefully consider the risks.;T@o;	;[I"NBefore inserting write barriers, you need to know about RGenGC algorithm ;TI"M(gc.c will help you). Macros and functions to insert write barriers are ;TI"Lavailable in in include/ruby/ruby.h. An example is available in iseq.c.;T@o;	;[I"IFor a complete guide for RGenGC and write barriers, please refer to ;TI"B<https://bugs.ruby-lang.org/projects/ruby-trunk/wiki/RGenGC>.;T@S;;i;
I"9Appendix E. RB_GC_GUARD to protect from premature GC;T@o;	;[I"GC Ruby currently uses conservative garbage collection, thus VALUE ;TI"Kvariables must remain visible on the stack or registers to ensure any ;TI"Nassociated data remains usable.  Optimizing C compilers are not designed ;TI"Mwith conservative garbage collection in mind, so they may optimize away ;TI"Nthe original VALUE even if the code depends on data associated with that ;TI"VALUE.;T@o;	;[I"HThe following example illustrates the use of RB_GC_GUARD to ensure ;TI"Fthe contents of sptr remain valid while the second invocation of ;TI" rb_str_new_cstr is running.;T@o;;[
I"VALUE s, w;
;TI"const char *sptr;
;TI"
;TI"Ls = rb_str_new_cstr("hello world!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!");
;TI"sptr = RSTRING_PTR(s);
;TI"Aw = rb_str_new_cstr(sptr + 6); /* Possible GC invocation */
;TI"
;TI"ERB_GC_GUARD(s); /* ensure s (and thus sptr) do not get GC-ed */
;T;0o;	;[	I"NIn the above example, RB_GC_GUARD must be placed _after_ the last use of ;TI"Nsptr.  Placing RB_GC_GUARD before dereferencing sptr would be of no use. ;TI"KRB_GC_GUARD is only effective on the VALUE data type, not converted C ;TI"data types.;T@o;	;[	I"GRB_GC_GUARD would not be necessary at all in the above example if ;TI"Hnon-inlined function calls are made on the `s' VALUE after sptr is ;TI"Gdereferenced.  Thus, in the above example, calling any un-inlined ;TI"function on `s' such as:;T@o;;[I"rb_str_modify(s);
;T;0o;	;[I"AWill ensure `s' stays on the stack or register to prevent a ;TI"/GC invocation from prematurely freeing it.;T@o;	;[I"GUsing the RB_GC_GUARD macro is preferable to using the "volatile" ;TI"=keyword in C.  RB_GC_GUARD has the following advantages:;T@o;	;[I",1) the intent of the macro use is clear;T@o;	;[I"I2) RB_GC_GUARD only affects its call site, "volatile" generates some;To;;[I"Gextra code every time the variable is used, hurting optimization.
;T;0o;	;[I"D3) "volatile" implementations may be buggy/inconsistent in some;To;;[I"Icompilers and architectures. RB_GC_GUARD is customizable for broken
;TI"Hsystems/compilers without those without negatively affecting other
;TI"systems.
;T;0o;	;[I"/*;To;;[	I" Local variables:
;TI" fill-column: 70
;TI" end:
;TI"/;T;0:
@file@:0@omit_headings_from_table_of_contents_below0