c-wrapper reference manual

This is a reference manual of c-wrapper.

 --- The Detailed Node Listing ---

c-wrapper

objc-wrapper

1. c-wrapper

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

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"))

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.

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.

2. objc-wrapper

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

2.1 Load a framework library

Function: c-load-framework framework

Load a framework library framework.

(c-load-framework "Foundation")

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

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.

A. Function and Syntax Index

B. Class Index

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

C. Variable Index

Table of Contents

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:

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.