"SfR Fresh" - the SfR Freeware/Shareware Archive

Member "q-7.11/modules/swig/README-SWIG" of archive q-7.11.tar.gz:

    1 
    2 SWIG runtime support for the Q programming language
    3 ==== ======= ======= === === = =========== ========
    4 
    5 This module implements the necessary runtime support for SWIG-generated Q
    6 modules. It provides the SWIGPtr type which encapsulates opaque C/C++ data
    7 objects in a way that allows them to be passed around safely between different
    8 SWIG-generated wrapper functions, and implements automatic garbage collection
    9 of such objects (including the ability to call destructors of C++ class
   10 instances). See swig.q for a list of operations provided by this module. A few
   11 simple examples can be found in the example subdirectory.
   12 
   13 Note that until the SWIG-Q module becomes part of the official SWIG
   14 distribution, to use SWIG with Q you'll need a SWIG version which has been
   15 patched up to add support for the Q language. For the time being, a suitable
   16 SWIG package can be found on the Q homepage, http://q-lang.sf.net.
   17 
   18 USAGE
   19 =====
   20 
   21 Please refer to the SWIG documentation for a closer description of how SWIG
   22 works. You'll also need to know how to compile a Q module, see Appendix C of
   23 the Q language manual for details.
   24 
   25 Basically, to create a Q wrapper module for a given C/C++ library, you'll have
   26 to create a simple interface (.i) file which includes the appropriate header
   27 files and/or defines the operations to be wrapped. For instance, here is a
   28 little C code we want to wrap:
   29 
   30 	/* File: example.c */
   31 
   32 	/* A global variable */
   33 	double Foo = 3.0;
   34 
   35 	/* Compute the greatest common divisor of positive integers */
   36 	int gcd(int x, int y)
   37 	{
   38 	  int g;
   39 	  g = y;
   40 	  while (x > 0) {
   41 	    g = x;
   42 	    x = y % x;
   43 	    y = g;
   44 	  }
   45 	  return g;
   46 	}
   47 
   48 Here is the corresponding interface file:
   49 
   50 	/* File: example.i */
   51 
   52 	%module example
   53 
   54 	extern int gcd(int x, int y);
   55 	extern double Foo;
   56 
   57 To generate the module, the interface file is passed through SWIG. Interfaces
   58 for various target languages can be generated from the same interface file.
   59 The -q option specifies that we want to build a module for the Q programming
   60 language:
   61 
   62 	$ swig -q example.i
   63 
   64 (In the case that a C++ module is to be wrapped, you'll have to add another
   65 -c++ option. The swig program supports a number of other options, try swig
   66 -help for a list of these.)
   67 
   68 SWIG will create both the example.q stub script and the example_wrap.c file
   69 which contains the wrapper function definitions. You can take a look at
   70 example.q to find out which functions have been wrapped and how to invoke
   71 them. The example_wrap.c file still has to be compiled along with the original
   72 example.c file to produce the shared object of the module. This can be done
   73 with the Q module compiler qcc as follows:
   74 
   75 	$ qcc example.c example_wrap.c
   76 
   77 (You have to make sure that qcc's output has the same name as the module name
   78 given in the interface file; if necessary, you can use qcc's -o option to
   79 accomplish this. Moreover, when compiling a C++ module, you'll also have to
   80 add the necessary options to link with the standard C++ library. E.g., using
   81 qcc with gcc on Linux: --link -lstdc++)
   82 
   83 Now you can invoke the module as follows:
   84 
   85 	$ q example
   86 	Q interpreter version 6.0 (i686-pc-linux-gnu)
   87 	Copyright (c) 1991-2004 by Albert Graef
   88 	This software is distributed under the terms of the GNU General Public
   89 	License version 2 or later; type `copying' for details.
   90 
   91 	==> gcd 42 105
   92 	21
   93 
   94 	==> _Foo_get
   95 	3.0
   96 
   97 	==> _Foo_set 3.1415926
   98 	()
   99 
  100 	==> _Foo_get
  101 	3.1415926
  102 
  103 Note that SWIG wraps global variables as a pair of Q functions which allow you
  104 to set and get the value of the C variable. Data members in C++ classes are
  105 handled in an analogous fashion. Also note that capitalized function
  106 identifiers will be stropped with a leading underscore, to be compatible with
  107 Q's function naming rules.
  108 
  109 More advanced examples for the SWIG-Q interface can be found in the SWIG
  110 package available on the Q homepage.
  111 
  112 Enjoy! :)
  113 
  114 Oct 19 2004
  115 Albert Graef
  116 ag@muwiinfa.geschichte.uni-mainz.de, Dr.Graef@t-online.de
  117 http://www.musikwissenschaft.uni-mainz.de/~ag