This is a reference manual of c-wrapper. 本ドキュメントはc-wrapperのリファレンスマニュアルです。

c-wrapper
*********

c-wrapper is the module which enables to use C libraries. c-wrapperとは、CのライブラリをGaucheから使えるようにするためのモジュールです。

Load a shared library
=====================

 -- Function: c-load-library file-or-list &keyword
     Load one or more shared libraries. If you omit the extension, c-wrapper add a extension (.so, .dylib, and so on) automatically. 共有ライブラリを読み込みます。 FILE-OR-LIST でリストを渡すと複数のライブラリが読み込まれます。また拡張子を省略した場合、環境に応じた拡張子 (.so や .dylib など ) が付加されます。

     Keyword arguments are: キーワード引数には以下のものを与えることができます。

     :option option-string
          Specify library names and library load paths with ld like option. ldに与えるオプションのような形式で共有ライブラリや読み込みパスの指定を行います。現状使えるのは以下のオプションです。

          -llibrary
               Load the library named LIBRARY. For example, -lc means to load 'libc'. 共有ライブラリ LIBRARY を読み込みます。例えば、-lc のように指定すると libc が読み込まれます。

          -Ldir
               Add directory DIR to the library search paths. 共有ライブラリのサーチリストにディレクトリ DIR を追加します。

 -- Function: c-ld option-string
     This function is the same (c-load-library '() :option option-string). and is designed to use with a command returning linker flags like pkg-config. (c-load-library '() :option option-string) と同じです。この関数は pkg-config などのようなリンカのフラグを返すコマンドと組み合わせて使うことを想定しています。

          (c-ld (process-output->string "pkg-config Wand --libs"))

Load a header file
==================

 -- Macro: c-include file-or-list &keyword
     Load one or more header files and define functions, global variables, constants , type definitions and macros in the current module. 指定されたヘッダファイルを読み込み、関数・グローバル変数・定数・型定義・マクロをカレントモジュールに定義します。

     Keyword arguments are: keyword 引数には以下のものを指定することができます。

     :include-dirs
          Sets up include directories. You can specify either a string file name or a list of string file names. インクルードパスを指定します。文字列もしくは文字列のリストが指定可能です。

     :option
          Sets up C preprocessor options. Cプリプロセッサに渡すオプションを指定します。文字列が指定可能です。

     :import
          Sets up symbols which you want to define. You can specify a symbol, a string, a regexp, a procedure or a list of them. If you put a procedure, it is called with two arguments, a header file name and a symbol. When the procedure returns #f, the symbol is ignored, and the symbol is defined otherwise. ヘッダファイルから読み込むシンボルを指定します。引数として、シンボル、文字列、正規表現、手続きと、それらのリストが指定可能です。手続きが渡された場合は、シンボルが見つかるたびにヘッダファイルのパス名とシンボル名を引数として、その手続きが呼び出されます。手続きが#fを返した場合そのシンボルは無視され、それ以外の値の場合にシンボルが定義されます。

     :export?
          Specifies whether symbols in header files are exported or not. If you put #t, the symbols are exported automatically, and otherwise they are not exported. 定義したシンボルをexportするかどうかを指定します。 #tの場合は定義したシンボルに対し自動的にexportが実行されます。#fの場合は何もしません。

     :compiled-lib
          Sets up a shared library file name which cwcompile command generates. At runtime, if the library is exists, loads it instead of parsing the header files. Otherwise, parses the header files. cwcompileコマンドにより作成されるパーズ済みの共有ライブラリの名前を指定します。ここで指定された共有ライブラリが存在する場合、ヘッダファイルをパーズする代わりにその共有ライブラリを読み込みます。共有ライブラリが存在しない場合は、ヘッダファイルのパーズが行われます。

     In loading header files, c-include gets these information and defines symbols.

     Function prototype
          Defines a function with the same name. It applies cast to its arguments and scm-cast to its return value.

     External variable
          Defines an object with the same name.

     enum
          Defines a constant value with the same name.

     struct
          Defines a struct class. You can use it with (c-struct tagname).

     union
          Defines a union class. You can use it with (c-union tagname).

     typedef
          Defines a class with the name <typename>.

     Objectlike macro
          Defines a value with the same name if the macro body is an expression, all identifiers in the body have been defined and the expression has no side-effect.

          You have to be careful to use the value because it is the header-load-time value, not macro-use-time value. It may be different from one you expected.

     Functionlike macro
          Defines a macro with the same name if the macro body is an expression or statements and all identifiers in the body have been defined.

     ヘッダファイル読み込み時に、以下の情報を収集し関数や変数などを定義していきます。

     関数のプロトタイプ宣言
          関数名と同名のシンボルで関数が定義されます。なおこの関数は引数に対してcastを戻り値に対してscm-castを適用します。

     外部変数定義
          変数名と同名のシンボルで外部変数を参照するオブジェクトが定義されます。

     enum
          定数名と同名のシンボルで定数が定義されます。

     struct
          構造体のクラスを定義します。このクラスは(c-struct tagname)で参照することができます。

     union
          共用体のクラスを定義します。このクラスは(c-union tagname)で参照することができます。

     typedef
          <typename>というシンボルでCの型に対応するクラスを定義します。

     オブジェクト形式 (objectlike) のマクロ
          マクロの内容が式であり、使用されている識別子がすべて宣言済みであり、かつ副作用を及ぼす式でない場合に、マクロ名と同名のシンボルで値が定義されます。なお、C言語でのマクロとは意味が異なり、この値はヘッダファイル読み込み時点での値であり、マクロ使用時点での値ではありません。

     関数形式 (functionlike) のマクロ
          マクロの内容が式もしくは文であり使用されている識別子がすべて宣言済みの場合にのみ、マクロ名と同名のシンボルでマクロが定義されます。

 -- Macro: c-load file-or-list &keyword
     Loads libraries, parses header files and defines functions, global variables, constants, type definitions and macros in current module. This macro does c-load-library and c-include at once. 指定されたヘッダファイルとライブラリを読み込み、関数・グローバル変数・定数・型定義・マクロをカレントモジュールに定義します。 c-load-libraryとc-includeを一度に行うものです。

     Keyword arguments are: keyword 引数には以下のものを指定することができます。

     :cflags
     :cppflags
     :ldflags
     :libs
          Sets up flags for parsing header files and loading libraries, :cppflags is passed to the preprocessor and :ldflags and :libs are used for loading libraries. cwcompile uses these flags, too. ヘッダファイルのパーズとライブラリのロードで使うための各種フラグを指定します。:cppflagsはプリプロセッサに渡され、:ldflags, :libsはライブラリのロードで使用されます。これらのフラグはcwcompileでも使われます。

     :cflags-cmd
     :cppflags-cmd
     :ldflags-cmd
     :libs-cmd
          Sets up commands which returns the flags. For example, if you want to parse gtk's header file, you can do the following: 各種フラグを取得するためのコマンドを指定します。例えば、gtkのヘッダファイルをパーズするときにpkg-configを使って以下のようにオプションを指定することができます。

               (c-load "gtk/gtk/h"
                       :cppflags-cmd "pkg-config gtk+-2.0 --cflags-only-I"
                       :cflags-cmd   "pkg-config gtk+-2.0 --cflags-only-other"
                       :libs-cmd     "pkg-config gtk+-2.0 --libs"
                       :compiled-lib "gtklib")

     :import
          Sets up symbols which you want to define. You can specify a symbol, a string, a regexp, a procedure or a list of them. If you put a procedure, it is called with two arguments, a header file name and a symbol. When the procedure returns #f, the symbol is ignored, and the symbol is defined otherwise. ヘッダファイルから読み込むシンボルを指定します。引数として、シンボル、文字列、正規表現、手続きと、それらのリストが指定可能です。手続きが渡された場合は、シンボルが見つかるたびにヘッダファイルのパス名とシンボル名を引数として、その手続きが呼び出されます。手続きが#fを返した場合そのシンボルは無視され、それ以外の値の場合にシンボルが定義されます。

     :hide-symbols
          Specifies symbols which doesn't export to other module. These symbols are defined internally, so you can lookup them with c-symbol. 外部に公開しないシンボルをリストで指定します。定義は内部的に行われるので、c-symbolで参照することができます。

     :compiled-lib
          Sets up a shared library file name which cwcompile command generates. At runtime, if the library is exists, loads it instead of parsing the header files. Otherwise, parses the header files. cwcompileコマンドにより作成されるパーズ済みの共有ライブラリの名前を指定します。ここで指定された共有ライブラリが存在する場合、ヘッダファイルをパーズする代わりにその共有ライブラリを読み込みます。共有ライブラリが存在しない場合は、ヘッダファイルのパーズが行われます。

     :module
          Controlls a sandbox module for C object. You can specify #t, #f or a module. #t means that c-load makes its original sandbox module and import it. This is the default behavior. #f means that c-load defines symbols in current module. a module means that c-load defines symbols in the specified module and doesn't import it. Cオブジェクトのサンドボックスモジュールを制御します。引数として、#t、#f、モジュールが指定可能です。 #tを指定した場合は、c-loadを実行するたびにサンドボックスモジュールが作成され、その中にCのオブジェクトが定義されます。そして、自動的にカレントモジュールへインポートされます。これが、デフォルトの動作です。 #fを指定した場合は、Cのオブジェクトはカレントモジュールに定義されます。モジュールが指定された場合は、Cのオブジェクトは指定されたモジュールに定義されます。なお、c-loadでは、インポートを行ないません。

Classes and functions about C types
===================================

 -- Class: <c-type>
     This is a basic class for the classes related with C types. Cの型に対応したクラスの基底クラスです。

 -- Class: <c-type-meta>
     This is a meta class for the classes related with C types. All the classes are instances of <c-type-meta>. Cの型に対応したクラスのメタクラスです。Cの型のクラスはすべて <c-type-meta> のインスタンスとなります。

 -- Class: <c-char>
 -- Class: <c-uchar>
 -- Class: <c-short>
 -- Class: <c-ushort>
 -- Class: <c-int>
 -- Class: <c-uint>
 -- Class: <c-long>
 -- Class: <c-ulong>
 -- Class: <c-longlong>
 -- Class: <c-ulonglong>
 -- Class: <c-float>
 -- Class: <c-double>
     These are classes for arithmetic types in C. you can use make to make an instance of the class. C言語の算術型 (Arithmetic types) に対応するクラスです。 make を使ってインスタンスを作成することができます。

 -- Class: <c-value-meta>
     This is a meta class for the classes related with C arithmetic types. C言語の算術型 (Arithmetic types) に対応するクラスのメタクラスです。

 -- Method: ref (obj <c-value-meta>)
     Returns the value of OBJ. OBJ の値を返します。

 -- Method: (setter ref) (obj <c-value-meta>) value
     Sets VALUE to OBJ. OBJ に値 VALUE を設定します。

 -- Class: <c-void>
     This is a class for void type in C. C言語の void 型に対応するクラスです。

 -- Class: <c-ptr>
     This is an abstract class for pointer type in C. If you use a pointer type, make a concrete class with ptr. C言語のポインタ型に対応する抽象クラスです。実際にポインタ型を使用する場合は、後述する ptr を使用して <c-ptr> の具象クラスを作成する必要があります。

 -- Method: ptr (class <c-type-meta>)
     Makes a class for a pointer type of CLASS, and it is a subclass of <c-ptr>. You can use make to make an instance of the class. CLASS で指定された型のポインタ型に対応するクラスを生成します。このクラスは <c-ptr> のサブクラスとなります。make を使って作成したクラスのインスタンスを作成することができます。

 -- Method: ptr (obj <c-type>)
     Returns a pointer object for OBJ. OBJ のポインタオブジェクトを返します。

 -- Class: <c-array>
     This is an abstract class for array type in C. If you use an array type, make a concrete class with c-array.

     <c-array> is a subclass of <sequence>, and you can use the operations of sequence framework (gauche.sequence module). C言語の配列に対応する抽象クラスです。実際に配列を使用する場合は、後述する c-array を使用して、<c-array> の具象クラスを作成する必要があります。

     また <c-array> は <sequence> を継承しており、シーケンスフレームワーク (gauche.sequence モジュール) で定義されている操作を使用することができます。

 -- Function: c-array (class <c-type-meta>) size
     Makes a class for an array type of CLASS, and it is a subclass of <c-array>. You can use make to make an instance of the class. CLASS 型で大きさ SIZE の配列クラスを生成します。このクラスは <c-array> のサブクラスとなります。make を使って作成したクラスのインスタンスを作成することができます。

 -- Class: <c-struct>
     This is an abstract class for struct type in C. C言語の構造体に対応する抽象クラスです。

 -- Class: <c-union>
     This is an abstract class for union type in C. C言語の共用体に対応する抽象クラスです。

 -- Macro: c-struct tagname
     Returns the struct class named TAGNAME. TAGNAMEという名前の構造体クラスを返します。

 -- Macro: c-union tagname
     Returns the union class named TAGNAME. TAGNAMEという名前の共用体クラスを返します。

 -- Method: ref (obj <c-struct>) member
 -- Method: ref (obj <c-union>) member
     Returns the value of the MEMBER of the struct or union OBJ. If the type of the member is arithmetic type, the type of the return value is casted to <real> or <integer>. 構造体もしくは共用体のメンバ MEMBER の値を返します。メンバが算術型 (Arithmetic types) の場合は <real> もしくは <integer> へ変換された値が返ります。

 -- Method: (setter ref) (obj <c-struct>) member value
 -- Method: (setter ref) (obj <c-union>) member value
     Sets VALUE to the MEMBER of the struct or union OBJ. 構造体もしくは共用体のメンバ MEMBER へ値をセットします。

 -- Class: <c-func-ptr>
     This is an abstract class for function pointer in C. C言語の関数ポインタに対応する抽象クラスです。

 -- Method: deref ptrobj
     Returns a deference object of PTROBJ. ('*' operator in C) ポインタオブジェクト PTROBJ の参照を返します。

 -- Method: c-sizeof (class <c-type-meta>)
 -- Method: c-sizeof (obj <c-type>)
     Returns a size of CLASS or OBJ. CLASSもしくはOBJのサイズを返します。

 -- Method: cast class obj
     Makes an instance of CLASS from OBJ. The following rules are applied to make an instance.

     CLASS   Type of OBJ   Description

     Subclasses of <c-value>
     <real>
     Makes an instance of CLASS which is the same value of OBJ.

     Subclasses of <c-value>
     <boolean>
     Makes an instance of CLASS which is 1 (if OBJ is #t) or 0 (if OBJ is #f).

     <c-ptr> or <c-func-ptr>
     <integer>
     Makes a pointer object whose address is OBJ.

     <c-ptr> or <c-func-ptr>
     <c-ptr> or <c-func-ptr>
     Makes a pointer object whose address is the same of OBJ.

     <c-ptr> or <c-func-ptr>
     <c-array>
     Makes a pointer object whose address is the same of the first address of OBJ.

     <c-ptr>
     <string>
     Makes a pointer object whose address points an internally-generated C string.

     <c-ptr>
     <uvector>
     Makes a pointer object whose address points the buffer of <uvector>.

     <c-ptr>
     <sequence>
     Makes a pointer object whost address points an internally-generated array which contains the same elements of OBJ.

     <c-array>
     <sequence>
     Makes an array which contains the same elements of OBJ.

     <c-array>
     <c-ptr>
     Makes an array object whose first address is OBJ.

     <c-func-ptr>
     <procedure>
     Makes a pointer of a function which executes calls the procedure OBJ.

     <integer> or <real>
     <c-value>
     Makes the value of OBJ.

     <boolean>
     <c-value> or <real>
     Makes #f if the value of OBJ is 0, #t otherwise.

     <integer>
     <c-ptr> or <c-func-ptr>
     Makes the pointer address of OBJ.

     <integer>
     <c-array>
     Makes the first address of the array OBJ.

     <string>
     <c-ptr> or <c-func-ptr>
     Makes a string from the address of OBJ.

     <string>
     <c-array>
     Makes a string from the array OBJ. It must be 0 terminated string.

     <collection>
     <c-array>
     Makes an instance of CLASS which contains the same values of OBJ, which are casted with scm-cast.

     OBJ から CLASS 型のインスタンスを生成します。生成のルールは以下の通りです。

     CLASS   OBJの型   説明

     <c-value> を継承したクラス
     <real>
     OBJ と同じ値を持つ CLASS のインスタンスを生成します

     <c-value> を継承したクラス
     <boolean>
     OBJ が #t の時は 1、#f の時は 0 の値を持つ CLASS のインスタンスを生成します。

     <c-ptr> または <c-func-ptr>
     <integer>
     OBJ のアドレスを持つポインタを生成します

     <c-ptr> または <c-func-ptr>
     <c-ptr> または <c-func-ptr>
     OBJ と同じアドレスを持つポインタを生成します

     <c-ptr> または <c-func-ptr>
     <c-array>
     OBJ の先頭アドレスを持つポインタを生成します。

     <c-ptr>
     <string>
     Cの文字列を生成し、その先頭アドレスを持つポインタを生成します。

     <c-ptr>
     <uvector>
     OBJ の先頭アドレスを持つポインタを生成します。

     <c-ptr>
     <sequence>
     OBJ と同じ内容の配列を生成し、その先頭アドレスを持つポインタを生成します。

     <c-array>
     <sequence>
     OBJ と同じ内容の配列を生成します。

     <c-array>
     <c-ptr>
     ポインタが指すメモリ領域を配列と見なして CLASS のインスタンスを生成します。

     <c-func-ptr>
     <procedure>
     OBJ を実行する関数のポインタを生成します。

     <integer> または <real>
     <c-value>
     OBJ と同じ値の数値を返します。

     <boolean>
     <c-value> または <real>
     値が 0 のとき #f が、そうでなければ #T が返ります。

     <integer>
     <c-ptr> または <c-func-ptr>
     ポインタのアドレスが返ります。

     <integer>
     <c-array>
     配列の先頭アドレスが返ります。

     <string>
     <c-ptr> または <c-func-ptr>
     ポインタが指し示す領域が0終端された文字列と見なし、文字列を生成します。

     <string>
     <c-array>
     配列の内容が0終端された文字列と見なし、文字列を生成します。

     <collection>
     <c-array>
     配列の内容を持つ CLASS のインスタンスを生成します。各要素の値は scm-cast でキャストされます。

 -- Function: scm-cast obj
     Returns the value of OBJ if OBJ is an instance of <c-value>. Otherwise, returns OBJ. OBJ が <c-value> 型である時は数値を返します。そうでなければ OBJ をそのまま返します。

 -- Function: make-null-ptr
     Returns NULL pointer. NULLポインタを返します。

 -- Function: null-ptr? obj
     Returns #t if OBJ is a NULL pointer, #f otherwise. OBJ がNULLポインタであれば #t が、そうでなければ #f が返されます。

 -- Function: register-finalizer! ptrobj proc
     Register the finalizer PROC to PTROBJ. It is called when PTROBJ is GCed. PTROBJ にファイナライザ PROC を登録します。PTROBJ がGCされるときに PROC が呼ばれます。

 -- Function: unregister-finalizer! ptrobj
     Deletes the finalizer of PTROBJ. PTROBJ のファイナライザを削除します。

 -- Function: finalize! ptrobj
     Calls the finalizer of PTROBJ, and deletes it from PTROBJ. PTROBJ のファイナライザを実行します。これにより PTROBJ のファイナライザは削除されます。

objc-wrapper
************

objc-wrapper is the module which enables to use Objective-C libraries. objc-wrapper とは Objective-C のライブラリを Gauche から使えるようにするためのモジュールです。

Load a framework library
========================

 -- Function: c-load-framework framework
     Load a framework library FRAMEWORK.

          (c-load-framework "Foundation")

     フレームワークライブラリ FRAMEWORK を読み込みます。

          (c-load-framework "Foundation")

Load an Objective-C header file
===============================

 -- Function: Macro c-include file-or-list &keyword
     This extends the c-include in c-wrapper module. it defines classes and methods of Objective-C code.

     If Objective-C class Foo is defined in the header file, c-include defines two symbols Foo and <Foo>. Foo is an instance of <c-struct:objc_object> and indicates the Objective-C class Foo. <Foo> is an alias of the type <id>. objc-wrapper モジュールの c-include では Objective-C のクラス定義やメソッド定義の拡張が行われています。

     Objective-C のクラス Foo がヘッダファイルで定義されていた場合、 Foo と <Foo> の2つのシンボルが定義されます。Foo は <c-struct:objc_objcect> 型のオブジェクトでクラス Foo そのものを指しています。<Foo> は <id> のエイリアスとなります。

Functions about Objective-C objects
===================================

 -- Macro: define-objc-class class-name super-class-name
     Defines Objective-C class CLASS-NAME whose super class is SUPER-CLASS-NAME. SUPER-CLASS-NAMEを継承したObjective-CのクラスCLASS-NAMEを定義します。

 -- Macro: define-objc-method objc-class ret-type (message-keyword varspec ...) body ...
     Defines an Objective-C method whose message keyword is MESSAGE-KEYWORD and return type is RET-TYPE. VARSPEC is a list, (variable-name variable-type).

     In the body, you can use two variables SELF and SUPER. SELF is the receiver object and SUPER is the object which is casted to its super class. メッセージキーワードがMESSAGE-KEYWORDであり戻り値の型がRET-TYPEであるようなOBJC-CLASSのメソッドを定義します。VARSPECは(変数名 変数型)のリストを指定します。

     BODYではSELFとSUPERの2つの変数が使えます。それぞれ、レシーバオブジェクト、レシーバをスーパクラスにキャストしたオブジェクトを指しています。

          (define-objc-method MyFooClass <id> [:doSomething (v <c-int>)]
            [super :doSomething v]
            [self :foo v]
            (bar v) ;; The result of (bar v) is the return value of this method.
            )

 -- Method: object-apply (obj <c-struct:objc_object>) selector-or-args ...
     Calls the method of OBJ.

          [[NSString :alloc) :init]

          [[NSString :startWithCString ( "Hello, world") :encoding NSASCIIStringEncoding]]

     OBJ のメソッドを呼び出します。

          [[NSString :alloc] :init]

          [[NSString :startWithCString ( "Hello, world") :encoding NSASCIIStringEncoding]]

 -- Function: @ str
     Returns Objective-C string. Objective-C文字列を返します。

 -- Function: @selector method-name
     Returns a selector of METHOD-NAME. メソッド名 METHOD-NAME のセレクタを返します。

Class Index
***********

For readability, the surrounding < and > are stripped off.