rb_cdio 0.1.0 → 0.1.1

data/ChangeLog.txt

@@ -0,0 +1,26 @@
+<b>Release 0.1.1</b>
+
+* Deleted all "get_" at the begin of methods
+* Unit tests on test dir
+* New class CdIo::Tracks
+* Added constants for tracks formats
+* <i>CdIo::Track</i> 
+  	* Verification for track number
+	* New attribute @leadout
+	
+<b>Release 0.1.0 (2005.05.24)</b>
+
+* Library packaged as rubygem
+
+<b>Release 0.0.2 (2005.05.22)</b>
+
+* Indentation of C files changed to KR style
+* New file: CdIo_Common.c
+* Better CdIo_test.rb
+* Implemented:
+	- CdIo.open
+	- CdIo::Cd.get_hwinfo
+	- CdIo::Cd.close
+	- CdIo::Cd.get_cdtext
+	- CdIo::Track.get_cdtext
+

data/LICENSE

@@ -0,0 +1,340 @@
+		    GNU GENERAL PUBLIC LICENSE
+		       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+                       59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+			    Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+		    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+			    NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+		     END OF TERMS AND CONDITIONS
+
+	    How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) 19yy  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) 19yy name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Library General
+Public License instead of this License.

data/README.EXT

@@ -0,0 +1,1051 @@
+.\" README.EXT -  -*- Text -*- created at: Mon Aug  7 16:45:54 JST 1995
+
+This document explains how to make extension libraries for Ruby.
+
+1. Basic knowledge
+
+In C, variables have types and data do not have types.  In contrast,
+Ruby variables do not have a static type, and data themselves have
+types, so data will need to be converted between the languages.
+
+Data in Ruby are represented by C type `VALUE'.  Each VALUE data has
+its data-type.
+
+To retrieve C data from a VALUE, you need to:
+
+ (1) Identify the VALUE's data type
+ (2) Convert the VALUE into C data
+
+Converting to the wrong data type may cause serious problems.
+
+
+1.1 Data-types
+
+The Ruby interpreter has the following data types:
+
+	T_NIL		nil
+	T_OBJECT	ordinary object
+	T_CLASS		class
+	T_MODULE	module
+	T_FLOAT		floating point number
+	T_STRING	string
+	T_REGEXP	regular expression
+	T_ARRAY		array
+	T_FIXNUM	Fixnum(31bit integer)
+	T_HASH		associative array
+	T_STRUCT	(Ruby) structure
+	T_BIGNUM	multi precision integer
+	T_FILE		IO
+	T_TRUE		true
+	T_FALSE		false
+	T_DATA		data
+	T_SYMBOL        symbol
+
+In addition, there are several other types used internally:
+
+	T_ICLASS
+	T_MATCH
+	T_UNDEF
+	T_VARMAP
+	T_SCOPE
+	T_NODE
+
+Most of the types are represented by C structures.
+
+1.2 Check Data Type of the VALUE
+
+The macro TYPE() defined in ruby.h shows the data type of the VALUE.
+TYPE() returns the constant number T_XXXX described above.  To handle
+data types, your code will look something like this:
+
+  switch (TYPE(obj)) {
+    case T_FIXNUM:
+      /* process Fixnum */
+      break;
+    case T_STRING:
+      /* process String */
+      break;
+    case T_ARRAY:
+      /* process Array */
+      break;
+    default:
+      /* raise exception */
+      rb_raise(rb_eTypeError, "not valid value");
+      break;
+  }
+
+There is the data-type check function
+
+  void Check_Type(VALUE value, int type)
+
+which raises an exception if the VALUE does not have the type specified.
+
+There are also faster check macros for fixnums and nil.
+
+  FIXNUM_P(obj)
+  NIL_P(obj)
+
+1.3 Convert VALUE into C data
+
+The data for type T_NIL, T_FALSE, T_TRUE are nil, true, false
+respectively.  They are singletons for the data type.
+
+The T_FIXNUM data is a 31bit length fixed integer (63bit length on
+some machines), which can be convert to a C integer by using the
+FIX2INT() macro.  There is also NUM2INT() which converts any Ruby
+numbers into C integers.  The NUM2INT() macro includes a type check, so
+an exception will be raised if the conversion failed.  NUM2DBL() can
+be used to retrieve the double float value in same way.
+
+To get char* from a VALUE, version 1.7 recommend to use new macros
+StringValue() and StringValuePtr().  StringValue(var) replaces var's
+value to the result of "var.to_str()".  StringValuePtr(var) does same
+replacement and returns char* representation of var.  These macros
+will skip the replacement if var is a String.  Notice that the macros
+requires to take only lvalue as their argument, to change the value
+of var in the replacement. 
+
+In version 1.6 or earlier, STR2CSTR() was used to do same thing
+but now it is obsoleted in version 1.7 because of STR2CSTR() has
+a risk of dangling pointer problem in to_str() impliclit conversion.
+
+Other data types have corresponding C structures, e.g. struct RArray
+for T_ARRAY etc. The VALUE of the type which has corresponding structure
+can be cast to retrieve the pointer to the struct.  The casting macro
+will be of the form RXXXX for each data type; for instance, RARRAY(obj). 
+See "ruby.h".
+
+For example, `RSTRING(str)->len' is the way to get the size of the
+Ruby String object.  The allocated region can be accessed by
+`RSTRING(str)->ptr'.  For arrays, use `RARRAY(ary)->len' and
+`RARRAY(ary)->ptr' respectively.
+
+Notice: Do not change the value of the structure directly, unless you
+are responsible for the result.  This ends up being the cause of interesting
+bugs.
+
+1.4 Convert C data into VALUE
+
+To convert C data to Ruby values:
+
+  * FIXNUM
+
+    left shift 1 bit, and turn on LSB.
+
+  * Other pointer values
+
+    cast to VALUE.
+
+You can determine whether a VALUE is pointer or not by checking its LSB.  
+
+Notice Ruby does not allow arbitrary pointer values to be a VALUE.  They
+should be pointers to the structures which Ruby knows about.  The known
+structures are defined in <ruby.h>.
+
+To convert C numbers to Ruby values, use these macros.
+
+  INT2FIX()	for integers within 31bits.
+  INT2NUM()	for arbitrary sized integer.
+
+INT2NUM() converts an integer into a Bignum if it is out of the FIXNUM
+range, but is a bit slower.
+
+1.5 Manipulating Ruby data
+
+As I already mentioned, it is not recommended to modify an object's internal
+structure.  To manipulate objects, use the functions supplied by the Ruby
+interpreter. Some (not all) of the useful functions are listed below:
+
+ String functions
+
+  rb_str_new(const char *ptr, long len)
+
+    Creates a new Ruby string.
+
+  rb_str_new2(const char *ptr)
+
+    Creates a new Ruby string from a C string.  This is equivalent to
+    rb_str_new(ptr, strlen(ptr)).
+
+  rb_tainted_str_new(const char *ptr, long len)
+
+    Creates a new tainted Ruby string.  Strings from external data
+    sources should be tainted.
+
+  rb_tainted_str_new2(const char *ptr)
+
+    Creates a new tainted Ruby string from a C string.
+
+  rb_str_cat(VALUE str, const char *ptr, long len)
+
+    Appends len bytes of data from ptr to the Ruby string.
+
+ Array functions
+
+  rb_ary_new()
+
+    Creates an array with no elements.
+
+  rb_ary_new2(long len)
+
+    Creates an array with no elements, allocating internal buffer
+    for len elements.
+
+  rb_ary_new3(long n, ...)
+
+    Creates an n-element array from the arguments.
+
+  rb_ary_new4(long n, VALUE *elts)
+
+    Creates an n-element array from a C array.
+
+  rb_ary_push(VALUE ary, VALUE val)
+  rb_ary_pop(VALUE ary)
+  rb_ary_shift(VALUE ary)
+  rb_ary_unshift(VALUE ary, VALUE val)
+
+    Array operations.  The first argument to each functions must be an 
+    array.  They may dump core if other types given.
+
+2. Extending Ruby with C
+
+2.1 Addding new features to Ruby
+
+You can add new features (classes, methods, etc.) to the Ruby
+interpreter.  Ruby provides APIs for defining the following things:
+
+ * Classes, Modules
+ * Methods, Singleton Methods
+ * Constants
+
+2.1.1 Class/module definition
+
+To define a class or module, use the functions below:
+
+  VALUE rb_define_class(const char *name, VALUE super)
+  VALUE rb_define_module(const char *name)
+
+These functions return the newly created class or module.  You may
+want to save this reference into a variable to use later.
+
+To define nested classes or modules, use the functions below:
+
+  VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)
+  VALUE rb_define_module_under(VALUE outer, const char *name)
+
+2.1.2 Method/singleton method definition
+
+To define methods or singleton methods, use these functions:
+
+  void rb_define_method(VALUE klass, const char *name, 
+		        VALUE (*func)(), int argc)
+
+  void rb_define_singleton_method(VALUE object, const char *name, 
+			          VALUE (*func)(), int argc)
+
+The `argc' represents the number of the arguments to the C function,
+which must be less than 17.  But I believe you don't need that much. :-)
+
+If `argc' is negative, it specifies the calling sequence, not number of
+the arguments.  
+
+If argc is -1, the function will be called as:
+
+  VALUE func(int argc, VALUE *argv, VALUE obj)
+
+where argc is the actual number of arguments, argv is the C array of
+the arguments, and obj is the receiver.
+
+If argc is -2, the arguments are passed in a Ruby array. The function
+will be called like:
+
+  VALUE func(VALUE obj, VALUE args)
+
+where obj is the receiver, and args is the Ruby array containing
+actual arguments.
+
+There are two more functions to define methods.  One is to define
+private methods:
+
+  void rb_define_private_method(VALUE klass, const char *name, 
+			        VALUE (*func)(), int argc)
+
+The other is to define module functions, which are private AND singleton
+methods of the module.  For example, sqrt is the module function
+defined in Math module.  It can be call in the form like:
+
+  Math.sqrt(4)
+
+or
+
+  include Math
+  sqrt(4)
+
+To define module functions, use:
+
+  void rb_define_module_function(VALUE module, const char *name, 
+				 VALUE (*func)(), int argc)
+
+Oh, in addition, function-like methods, which are private methods defined
+in the Kernel module, can be defined using:
+
+  void rb_define_global_function(const char *name, VALUE (*func)(), int argc)
+
+To define alias to the method,
+
+  void rb_define_alias(VALUE module, const char* new, const char* old);
+
+2.1.3 Constant definition
+
+We have 2 functions to define constants:
+
+  void rb_define_const(VALUE klass, const char *name, VALUE val)
+  void rb_define_global_const(const char *name, VALUE val)
+
+The former is to define a constant under specified class/module.  The
+latter is to define a global constant.
+
+2.2 Use Ruby features from C
+
+There are several ways to invoke Ruby's features from C code.
+
+2.2.1 Evaluate Ruby Programs in a String
+
+The easiest way to use Ruby's functionality from a C program is to
+evaluate the string as Ruby program.  This function will do the job.
+
+  VALUE rb_eval_string(const char *str)
+
+Evaluation is done under the current context, thus current local variables
+of the innermost method (which is defined by Ruby) can be accessed.
+
+2.2.2 ID or Symbol
+
+You can invoke methods directly, without parsing the string.  First I
+need to explain about symbols (whose data type is ID).  ID is the
+integer number to represent Ruby's identifiers such as variable names.
+It can be accessed from Ruby in the form:
+
+ :Identifier
+
+You can get the symbol value from a string within C code by using
+
+  rb_intern(const char *name)
+
+2.2.3 Invoke Ruby method from C
+
+To invoke methods directly, you can use the function below
+
+  VALUE rb_funcall(VALUE recv, ID mid, int argc, ...)
+
+This function invokes a method on the recv, with the method name
+specified by the symbol mid.
+
+2.2.4 Accessing the variables and constants
+
+You can access class variables and instance variables using access
+functions.  Also, global variables can be shared between both environments.
+There's no way to access Ruby's local variables.
+
+The functions to access/modify instance variables are below:
+
+  VALUE rb_ivar_get(VALUE obj, ID id)
+  VALUE rb_ivar_set(VALUE obj, ID id, VALUE val)
+
+id must be the symbol, which can be retrieved by rb_intern().
+
+To access the constants of the class/module:
+
+  VALUE rb_const_get(VALUE obj, ID id)
+
+See 2.1.3 for defining new constant.
+
+3. Information sharing between Ruby and C
+
+3.1 Ruby constants that C can be accessed from C
+
+The following Ruby constants can be referred from C.
+
+  Qtrue
+  Qfalse
+
+Boolean values.  Qfalse is false in C also (i.e. 0).
+
+  Qnil
+
+Ruby nil in C scope.
+
+3.2 Global variables shared between C and Ruby
+
+Information can be shared between the two environments using shared global
+variables.  To define them, you can use functions listed below:
+
+  void rb_define_variable(const char *name, VALUE *var)
+
+This function defines the variable which is shared by both environments.
+The value of the global variable pointed to by `var' can be accessed
+through Ruby's global variable named `name'.
+
+You can define read-only (from Ruby, of course) variables using the
+function below.
+
+  void rb_define_readonly_variable(const char *name, VALUE *var)
+
+You can defined hooked variables.  The accessor functions (getter and
+setter) are called on access to the hooked variables.
+
+  void rb_define_hooked_variable(constchar *name, VALUE *var,
+				 VALUE (*getter)(), void (*setter)())
+
+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(const char *name,
+				  VALUE (*getter)(), void (*setter)())
+
+This function defines a Ruby global variable without a 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 follows:
+
+  (*getter)(ID id, void *data, struct global_entry* entry);
+  (*setter)(VALUE val, ID id, void *data, struct global_entry* entry);
+
+3.3 Encapsulate C data into Ruby object
+
+To wrap and objectify a C pointer as a Ruby object (so called
+DATA), use Data_Wrap_Struct().
+
+  Data_Wrap_Struct(klass, mark, free, ptr)
+
+Data_Wrap_Struct() returns a created DATA object.  The klass 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.  If this is -1, the pointer
+will be just freed.  The functions mark and free will be called from
+garbage collector.
+
+You can allocate and wrap the structure in one step.
+
+  Data_Make_Struct(klass, type, mark, free, sval)
+
+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(klass, mark, free, sval))
+
+Arguments klass, mark, and free work like their counterparts in
+Data_Wrap_Struct().  A pointer to the allocated structure will be
+assigned to sval, which should be a pointer of the type specified.
+
+To retrieve the C pointer from the Data object, use the macro
+Data_Get_Struct().
+
+  Data_Get_Struct(obj, type, sval)
+
+A pointer to the structure will be assigned to the variable sval.
+
+See the example below for details. 
+
+4. Example - Creating dbm extension
+
+OK, here's the example of making an extension library.  This is the
+extension to access DBMs.  The full source is included in the ext/
+directory in the Ruby's source tree.
+
+(1) make the directory
+
+  % mkdir ext/dbm
+
+Make a directory for the extension library under ext directory.
+
+(2) design the library
+
+You need to design the library features, before making it.
+
+(3) write C code.
+
+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 multiple source
+files, avoid choosing ``LIBRARY.c'' for a file name.  It may conflict
+with an intermediate file ``LIBRARY.o'' on some platforms.
+
+Ruby will execute the initializing function named ``Init_LIBRARY'' in
+the library.  For example, ``Init_dbm()'' will be executed when loading
+the library.
+
+Here's the example of an initializing function.
+
+--
+Init_dbm()
+{
+    /* define DBM class */
+    cDBM = rb_define_class("DBM", rb_cObject);
+    /* DBM includes Enumerate module */
+    rb_include_module(cDBM, rb_mEnumerable);
+
+    /* DBM has class method open(): arguments are received as C array */
+    rb_define_singleton_method(cDBM, "open", fdbm_s_open, -1);
+
+    /* DBM instance method close(): no args */
+    rb_define_method(cDBM, "close", fdbm_close, 0);
+    /* DBM instance method []: 1 argument */
+    rb_define_method(cDBM, "[]", fdbm_fetch, 1);
+		:
+
+    /* ID for a instance variable to store DBM data */
+    id_dbm = rb_intern("dbm");
+}
+--
+
+The dbm extension wraps the dbm struct in the C environment using 
+Data_Make_Struct.
+
+--
+struct dbmdata {
+    int  di_size;
+    DBM *di_dbm;
+};
+
+
+obj = Data_Make_Struct(klass, struct dbmdata, 0, free_dbm, dbmp);
+--
+
+This code wraps the dbmdata structure into a Ruby object.  We avoid wrapping
+DBM* directly, because we want to cache size information.
+
+To retrieve the dbmdata structure from a Ruby object, we define the
+following macro:
+
+--
+#define GetDBM(obj, dbmp) {\
+    Data_Get_Struct(obj, struct dbmdata, dbmp);\
+    if (dbmp->di_dbm == 0) closed_dbm();\
+}
+--
+
+This sort of complicated macro does the retrieving and close checking for
+the DBM.
+
+There are three kinds of way to receive method arguments.  First,
+methods with a fixed number of arguments receive arguments like this:
+
+--
+static VALUE
+fdbm_delete(obj, keystr)
+    VALUE obj, keystr;
+{
+	:
+}
+--
+
+The first argument of the C function is the self, the rest are the
+arguments to the method.
+
+Second, methods with an arbitrary number of arguments receive
+arguments like this:
+
+--
+static VALUE
+fdbm_s_open(argc, argv, klass)
+    int argc;
+    VALUE *argv;
+    VALUE klass;
+{
+	:
+    if (rb_scan_args(argc, argv, "11", &file, &vmode) == 1) {
+	mode = 0666;		/* default value */
+    }
+	:
+}
+--
+
+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.
+
+You can use the function rb_scan_args() to check and retrieve the
+arguments.  For example, "11" means that the method requires at least one
+argument, and at most receives two arguments.
+
+Methods with an arbitrary number of arguments can receive arguments
+by Ruby's array, like this:
+
+--
+static VALUE
+fdbm_indexes(obj, args)
+    VALUE obj, args;
+{
+	:
+}
+--
+
+The first argument is the receiver, the second one is the Ruby array
+which contains the arguments to the method.
+
+** Notice
+
+GC should know about global variables which refer to Ruby's objects, but
+are not exported to the Ruby world.  You need to protect them by
+
+  void rb_global_variable(VALUE *var)
+
+(4) prepare extconf.rb
+
+If the file named extconf.rb exists, it will be executed to generate
+Makefile.
+
+extconf.rb is the file for check compilation conditions etc.  You
+need to put
+
+  require 'mkmf'
+
+at the top of the file.  You can use the functions below to check
+various conditions.
+
+  have_library(lib, func): check whether library containing function exists.
+  have_func(func, header): check whether function exists
+  have_header(header): check whether header file exists
+  create_makefile(target): generate Makefile
+
+The value of the variables below will affect the Makefile.
+
+  $CFLAGS: included in CFLAGS make variable (such as -I)
+  $LDFLAGS: included in LDFLAGS make variable (such as -L)
+
+If a compilation condition is not fulfilled, you should not call
+``create_makefile''.  The Makefile will not generated, compilation will
+not be done.
+
+(5) prepare depend (optional)
+
+If the file named depend exists, Makefile will include that file to
+check dependencies.  You can make this file by invoking
+
+  % gcc -MM *.c > depend
+
+It's no harm.  Prepare it.
+
+(6) generate Makefile
+
+Try generating the Makefile by:
+
+  ruby extconf.rb
+
+You don't need this step if you put the extension library under the ext
+directory of the ruby source tree.  In that case, compilation of the
+interpreter will do this step for you.
+
+(7) make
+
+Type
+
+  make
+
+to compile your extension.  You don't need this step either if you have
+put extension library under the ext directory of the ruby source tree.
+
+(8) debug
+
+You may need to rb_debug the extension.  Extensions can be linked
+statically by the adding directory name in the ext/Setup file so that
+you can inspect the extension with the debugger.
+
+(9) done, now you have the extension library
+
+You can do anything you want with your library.  The author of Ruby
+will not claim any restrictions on your code depending on the Ruby API.
+Feel free to use, modify, distribute or sell your program.
+
+Appendix A. Ruby source files overview
+
+ruby language core
+
+  class.c
+  error.c
+  eval.c
+  gc.c
+  object.c
+  parse.y
+  variable.c
+
+utility functions
+
+  dln.c
+  regex.c
+  st.c
+  util.c
+
+ruby interpreter implementation
+
+  dmyext.c
+  inits.c
+  main.c
+  ruby.c
+  version.c
+
+class library
+
+  array.c
+  bignum.c
+  compar.c
+  dir.c
+  enum.c
+  file.c
+  hash.c
+  io.c
+  marshal.c
+  math.c
+  numeric.c
+  pack.c
+  prec.c
+  process.c
+  random.c
+  range.c
+  re.c
+  signal.c
+  sprintf.c
+  string.c
+  struct.c
+  time.c
+
+Appendix B. Ruby extension API reference
+
+** Types
+
+ VALUE
+
+The type for the 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
+
+ Qnil
+
+const: nil object
+
+ Qtrue
+
+const: true object(default true value)
+
+ Qfalse
+
+const: false object
+
+** C pointer wrapping
+
+ Data_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval)
+
+Wrap a C pointer into a Ruby object.  If object has references to other
+Ruby objects, they should be marked by using the mark function during
+the 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(klass, type, mark, free, 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)
+
+This macro retrieves the pointer value from DATA, and assigns it to
+the variable sval. 
+
+** Checking data types
+
+TYPE(value)
+FIXNUM_P(value)
+NIL_P(value)
+void Check_Type(VALUE value, int type)
+void Check_SafeStr(VALUE value)
+
+** Data type conversion
+
+FIX2INT(value)
+INT2FIX(i)
+NUM2INT(value)
+INT2NUM(i)
+NUM2DBL(value)
+rb_float_new(f)
+STR2CSTR(value)
+rb_str_new2(s)
+
+** defining class/module
+
+ VALUE rb_define_class(const char *name, VALUE super)
+
+Defines a new Ruby class as a subclass of super.
+
+ VALUE rb_define_class_under(VALUE module, const char *name, VALUE super)
+
+Creates a new Ruby class as a subclass of super, under the module's
+namespace.
+
+ VALUE rb_define_module(const char *name)
+
+Defines a new Ruby module.
+
+ VALUE rb_define_module_under(VALUE module, const char *name)
+
+Defines a new Ruby module under the module's namespace.
+
+ void rb_include_module(VALUE klass, VALUE module)
+
+Includes module into class.  If class already includes it, just
+ignored.
+
+ void rb_extend_object(VALUE object, VALUE module)
+
+Extend the object with the module's attributes.
+
+** Defining Global Variables
+
+ void rb_define_variable(const char *name, VALUE *var)
+
+Defines a global variable which is shared between C and Ruby.  If name
+contains a character which is not allowed to be part of the symbol,
+it can't be seen from Ruby programs.
+
+ void rb_define_readonly_variable(const char *name, VALUE *var)
+
+Defines a read-only global variable.  Works just like
+rb_define_variable(), except defined variable is read-only.
+
+ void rb_define_virtual_variable(const char *name,
+				 VALUE (*getter)(), VALUE (*setter)())
+
+Defines a virtual variable, whose behavior is defined by a pair of C
+functions.  The getter function is called when the variable is
+referred.  The setter function is called when the value is set to the
+variable.  The prototype for getter/setter functions are:
+
+	VALUE getter(ID id)
+	void setter(VALUE val, ID id)
+
+The getter function must return the value for the access.
+
+ void rb_define_hooked_variable(const char *name, VALUE *var,
+				VALUE (*getter)(), VALUE (*setter)())
+
+Defines hooked variable.  It's a virtual variable with a C variable.  
+The getter is called as
+
+	VALUE getter(ID id, VALUE *var)
+
+returning a new value.  The setter is called as
+
+	void setter(VALUE val, ID id, VALUE *var)
+
+GC requires C global variables which hold Ruby values to be marked.
+
+ void rb_global_variable(VALUE *var)
+
+Tells GC to protect these variables.
+
+** Constant Definition
+
+ void rb_define_const(VALUE klass, const char *name, VALUE val)
+
+Defines a new constant under the class/module.
+
+ void rb_define_global_const(const char *name, VALUE val)
+
+Defines a global constant.  This is just the same as
+
+     rb_define_const(cKernal, name, val)
+
+** Method Definition
+
+ rb_define_method(VALUE klass, const char *name, VALUE (*func)(), int argc)
+
+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 a Ruby array of
+the method arguments.
+
+ rb_define_private_method(VALUE klass, const char *name, VALUE (*func)(), int argc)
+
+Defines a private method for the class.  Arguments are same as
+rb_define_method().
+
+ rb_define_singleton_method(VALUE klass, const char *name, VALUE (*func)(), int argc)
+
+Defines a singleton method.  Arguments are same as rb_define_method().
+
+ rb_scan_args(int argc, VALUE *argv, const char *fmt, ...)
+
+Retrieve argument from argc, argv.  The fmt is the format string for
+the arguments, such as "12" for 1 non-optional argument, 2 optional
+arguments.  If `*' appears at the end of fmt, it means the rest of
+the arguments are assigned to the corresponding variable, packed in
+an array.
+
+** Invoking Ruby method
+
+ VALUE rb_funcall(VALUE recv, ID mid, int narg, ...)
+
+Invokes a method.  To retrieve mid from a method name, use rb_intern().
+
+ VALUE rb_funcall2(VALUE recv, ID mid, int argc, VALUE *argv)
+
+Invokes a method, passing arguments by an array of values.
+
+ VALUE rb_eval_string(const char *str)
+
+Compiles and executes the string as a Ruby program.
+
+ ID rb_intern(const char *name)
+
+Returns ID corresponding to the name.
+
+ char *rb_id2name(ID id)
+
+Returns the name corresponding ID.
+
+ char *rb_class2name(VALUE klass)
+
+Returns the name of the class.
+
+ int rb_respond_to(VALUE object, ID id)
+
+Returns true if the object responds to the message specified by id.
+
+** Instance Variables
+
+ VALUE rb_iv_get(VALUE obj, const char *name)
+
+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, const char *name, VALUE val)
+
+Sets the value of the instance variable.
+
+** Control Structure
+
+ VALUE rb_iterate(VALUE (*func1)(), void *arg1, VALUE (*func2)(), void *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)
+
+Evaluates the block with value val.
+
+ VALUE rb_rescue(VALUE (*func1)(), void *arg1, VALUE (*func2)(), void *arg2)
+
+Calls the function func1, with arg1 as the argument.  If an 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)
+
+Calls the function func1 with arg1 as the argument, then calls func2
+with arg2 if execution terminated.  The return value from
+rb_ensure() is that of func1.
+
+** Exceptions and Errors
+
+ void rb_warn(const char *fmt, ...)
+
+Prints a warning message according to a printf-like format.
+
+ void rb_warning(const char *fmt, ...)
+
+Prints a warning message according to a printf-like format, if
+$VERBOSE is true.
+
+void rb_raise(rb_eRuntimeError, const char *fmt, ...)
+
+Raises RuntimeError.  The fmt is a format string just like printf().
+
+ void rb_raise(VALUE exception, const char *fmt, ...)
+
+Raises a class exception.  The fmt is a format string just like printf().
+
+ void rb_fatal(const char *fmt, ...)
+
+Raises a fatal error, terminates the interpreter.  No exception handling
+will be done for fatal errors, but ensure blocks will be executed.
+
+ void rb_bug(const char *fmt, ...)
+
+Terminates 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
+
+The embedding API functions are below (not needed for extension libraries):
+
+ void ruby_init()
+
+Initializes the interpreter.
+
+ void ruby_options(int argc, char **argv)
+
+Process command line arguments for the interpreter.
+
+ void ruby_run()
+
+Starts execution of the interpreter.
+
+ void ruby_script(char *name)
+
+Specifies the name of the script ($0).
+
+Appendix C. Functions Available in extconf.rb
+
+These functions are available in extconf.rb:
+
+ have_library(lib, func)
+
+Checks whether the library exists, containing the specified function.
+Returns true if the library exists.
+
+ find_library(lib, func, path...)
+
+Checks whether a library which contains the specified function exists in
+path.  Returns true if the library exists.
+
+ have_func(func, header)
+
+Checks whether func exists with header.  Returns true if the function
+exists.  To check functions in an additional library, you need to
+check that library first using have_library().
+
+ have_header(header)
+
+Checks whether header exists.  Returns true if the header file exists.
+
+ create_makefile(target)
+
+Generates the Makefile for the extension library.  If you don't invoke
+this method, the compilation will not be done.
+
+ with_config(withval[, default=nil])
+
+Parses the command line options and returns the value specified by
+--with-<withval>.
+
+ dir_config(target[, default_dir])
+ dir_config(target[, default_include, default_lib])
+
+Parses the command line options and adds the directories specified by
+--with-<target>-dir, --with-<target>-include, and/or --with-<target>-lib
+to $CFLAGS and/or $LDFLAGS.  --with-<target>-dir=/path is equivalent to
+--with-<target>-include=/path/include --with-<target>-lib=/path/lib.
+Returns an array of the added directories ([include_dir, lib_dir]).
+
+/*
+ * Local variables:
+ * fill-column: 70
+ * end:
+ */