
SWIG runtime support for the Q programming language
==== ======= ======= === === = =========== ========

This module implements the necessary runtime support for SWIG-generated Q
modules. It provides the SWIGPtr type which encapsulates opaque C/C++ data
objects in a way that allows them to be passed around safely between different
SWIG-generated wrapper functions, and implements automatic garbage collection
of such objects (including the ability to call destructors of C++ class
instances). See swig.q for a list of operations provided by this module. A few
simple examples can be found in the example subdirectory.

Note that until the SWIG-Q module becomes part of the official SWIG
distribution, to use SWIG with Q you'll need a SWIG version which has been
patched up to add support for the Q language. For the time being, a suitable
SWIG package can be found on the Q homepage, http://q-lang.sf.net.

USAGE
=====

Please refer to the SWIG documentation for a closer description of how SWIG
works. You'll also need to know how to compile a Q module, see Appendix C of
the Q language manual for details.

Basically, to create a Q wrapper module for a given C/C++ library, you'll have
to create a simple interface (.i) file which includes the appropriate header
files and/or defines the operations to be wrapped. For instance, here is a
little C code we want to wrap:

	/* File: example.c */

	/* A global variable */
	double Foo = 3.0;

	/* Compute the greatest common divisor of positive integers */
	int gcd(int x, int y)
	{
	  int g;
	  g = y;
	  while (x > 0) {
	    g = x;
	    x = y % x;
	    y = g;
	  }
	  return g;
	}

Here is the corresponding interface file:

	/* File: example.i */

	%module example

	extern int gcd(int x, int y);
	extern double Foo;

To generate the module, the interface file is passed through SWIG. Interfaces
for various target languages can be generated from the same interface file.
The -q option specifies that we want to build a module for the Q programming
language:

	$ swig -q example.i

(In the case that a C++ module is to be wrapped, you'll have to add another
-c++ option. The swig program supports a number of other options, try swig
-help for a list of these.)

SWIG will create both the example.q stub script and the example_wrap.c file
which contains the wrapper function definitions. You can take a look at
example.q to find out which functions have been wrapped and how to invoke
them. The example_wrap.c file still has to be compiled along with the original
example.c file to produce the shared object of the module. This can be done
with the Q module compiler qcc as follows:

	$ qcc example.c example_wrap.c

(You have to make sure that qcc's output has the same name as the module name
given in the interface file; if necessary, you can use qcc's -o option to
accomplish this. Moreover, when compiling a C++ module, you'll also have to
add the necessary options to link with the standard C++ library. E.g., using
qcc with gcc on Linux: --link -lstdc++)

Now you can invoke the module as follows:

	$ q example
	Q interpreter version 6.0 (i686-pc-linux-gnu)
	Copyright (c) 1991-2004 by Albert Graef
	This software is distributed under the terms of the GNU General Public
	License version 2 or later; type `copying' for details.

	==> gcd 42 105
	21

	==> _Foo_get
	3.0

	==> _Foo_set 3.1415926
	()

	==> _Foo_get
	3.1415926

Note that SWIG wraps global variables as a pair of Q functions which allow you
to set and get the value of the C variable. Data members in C++ classes are
handled in an analogous fashion. Also note that capitalized function
identifiers will be stropped with a leading underscore, to be compatible with
Q's function naming rules.

More advanced examples for the SWIG-Q interface can be found in the SWIG
package available on the Q homepage.

Enjoy! :)

Oct 19 2004
Albert Graef
ag@muwiinfa.geschichte.uni-mainz.de, Dr.Graef@t-online.de
http://www.musikwissenschaft.uni-mainz.de/~ag
