c-wrapper reference manual: Top

[Top] | [Contents] | [Index] | [ ? ]

# c-wrapper reference manual

This is a reference manual of c-wrapper.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 1. c-wrapper

`c-wrapper` is the module which enables to use C libraries.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.1 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.

  Keyword arguments are:

  `:option option-string`

    Specify library names and library load paths with ld like option.

    `-llibrary`

      Load the library named library. For example, -lc means to load 'libc'.

    `-Ldir`

      Add directory dir to the library search paths.

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-ld (process-output->string "pkg-config Wand --libs"))

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.2 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:

  `: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.

  `: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.

  `: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.

  `: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.

  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.

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.

  Keyword arguments are:

  `: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.

  `: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:

        (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.

  `: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.

  `: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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.3 Classes and functions about C types

Class: <c-type>

  This is a basic class for the classes related with C types.

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>`.

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.

Class: <c-value-meta>

  This is a meta class for the classes related with C arithmetic types.

Method: ref (obj <c-value-meta>)

  Returns the value of obj.

Method: (setter ref) (obj <c-value-meta>) value

  Sets value to obj.

Class: <c-void>

  This is a class for void type in C.

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`.

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.

Method: ptr (obj <c-type>)

  Returns a pointer object for 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).

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: <c-struct>

  This is an abstract class for struct type in C.

Class: <c-union>

  This is an abstract class for union type in C.

Macro: c-struct tagname

  Returns the struct class named tagname.

Macro: c-union tagname

  Returns the union class named 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>`.

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.

Class: <c-func-ptr>

  This is an abstract class for function pointer in C.

Method: deref ptrobj

  Returns a deference object of ptrobj. ('*' operator in C)

Method: c-sizeof (class <c-type-meta>)
Method: c-sizeof (obj <c-type>)

  Returns a size of class or 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`.

Function: scm-cast obj

  Returns the value of obj if obj is an instance of `<c-value>`. Otherwise, returns obj.

Function: make-null-ptr

  Returns NULL pointer.

Function: null-ptr? obj

  Returns `#t` if obj is a NULL pointer, `#f` otherwise.

Function: register-finalizer! ptrobj proc

  Register the finalizer proc to ptrobj. It is called when ptrobj is GCed.

Function: unregister-finalizer! ptrobj

  Deletes the finalizer of ptrobj.

Function: finalize! ptrobj

  Calls the finalizer of ptrobj, and deletes it from ptrobj.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 2. objc-wrapper

`objc-wrapper` is the module which enables to use Objective-C libraries.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.1 Load a framework library

Function: c-load-framework framework

  Load a framework library framework.

      (c-load-framework "Foundation")

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.2 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>`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.3 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.

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.

      (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]]

Function: @ str

  Returns Objective-C string.

Function: @selector method-name

  Returns a selector of method-name.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# A. Function and Syntax Index

Jump to: | ( @ C D F M N O P R S U

| Index Entry | Section
( |  |
| `(setter` | 1.3 Classes and functions about C types
| `(setter` | 1.3 Classes and functions about C types
| `(setter` | 1.3 Classes and functions about C types
@ |  |
| `@` | 2.3 Functions about Objective-C objects
| `@selector` | 2.3 Functions about Objective-C objects
C |  |
| `c-array` | 1.3 Classes and functions about C types
| `c-include` | 1.2 Load a header file
| `c-ld` | 1.1 Load a shared library
| `c-load` | 1.2 Load a header file
| `c-load-framework` | 2.1 Load a framework library
| `c-load-library` | 1.1 Load a shared library
| `c-sizeof` | 1.3 Classes and functions about C types
| `c-sizeof` | 1.3 Classes and functions about C types
| `c-struct` | 1.3 Classes and functions about C types
| `c-union` | 1.3 Classes and functions about C types
| `cast` | 1.3 Classes and functions about C types
D |  |
| `define-objc-class` | 2.3 Functions about Objective-C objects
| `define-objc-method` | 2.3 Functions about Objective-C objects
| `deref` | 1.3 Classes and functions about C types
F |  |
| `finalize!` | 1.3 Classes and functions about C types
M |  |
| `Macro` | 2.2 Load an Objective-C header file
| `make-null-ptr` | 1.3 Classes and functions about C types
N |  |
| `null-ptr?` | 1.3 Classes and functions about C types
O |  |
| `object-apply` | 2.3 Functions about Objective-C objects
P |  |
| `ptr` | 1.3 Classes and functions about C types
| `ptr` | 1.3 Classes and functions about C types
R |  |
| `ref` | 1.3 Classes and functions about C types
| `ref` | 1.3 Classes and functions about C types
| `ref` | 1.3 Classes and functions about C types
| `register-finalizer!` | 1.3 Classes and functions about C types
S |  |
| `scm-cast` | 1.3 Classes and functions about C types
U |  |
| `unregister-finalizer!` | 1.3 Classes and functions about C types

Jump to: | ( @ C D F M N O P R S U

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# B. Class Index

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

Jump to: | C

| Index Entry | Section
C |  |
| `c-char` | 1.3 Classes and functions about C types
| `c-double` | 1.3 Classes and functions about C types
| `c-float` | 1.3 Classes and functions about C types
| `c-int` | 1.3 Classes and functions about C types
| `c-long` | 1.3 Classes and functions about C types
| `c-longlong` | 1.3 Classes and functions about C types
| `c-short` | 1.3 Classes and functions about C types
| `c-uchar` | 1.3 Classes and functions about C types
| `c-uint` | 1.3 Classes and functions about C types
| `c-ulong` | 1.3 Classes and functions about C types
| `c-ulonglong` | 1.3 Classes and functions about C types
| `c-ushort` | 1.3 Classes and functions about C types
| `c-value-meta` | 1.3 Classes and functions about C types

Jump to: | C

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# C. Variable Index

[Top] | [Contents] | [Index] | [ ? ]

# Table of Contents

[Top] | [Contents] | [Index] | [ ? ]

# About This Document

This document was generated by KOGURO, Naoki on December, 26 2006 using texi2html 1.76.

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
--- | --- | --- | ---
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | beginning of this chapter or previous chapter | 1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next chapter | 2
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | index |
[ ? ] | About | about (help) |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

- 1. Section One
  - 1.1 Subsection One-One
    - ...
  - 1.2 Subsection One-Two
    - 1.2.1 Subsubsection One-Two-One
    - 1.2.2 Subsubsection One-Two-Two
    - 1.2.3 Subsubsection One-Two-Three <== Current Position
    - 1.2.4 Subsubsection One-Two-Four
  - 1.3 Subsection One-Three
    - ...
  - 1.4 Subsection One-Four

This document was generated by KOGURO, Naoki on December, 26 2006 using texi2html 1.76.