e5ac3696bc
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@4858 626c5289-ae23-0410-ae9c-e8d60b6d4f22
618 lines
24 KiB
HTML
618 lines
24 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<!-- Hand-written HTML -->
|
|
<html>
|
|
<head>
|
|
<title>SWIG and Guile</title>
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
|
|
<a name="n1"></a><H1>14 SWIG and Guile</H1>
|
|
<!-- INDEX -->
|
|
<ul>
|
|
<li><a href="#n2">Meaning of "Module"</a>
|
|
<li><a href="#n3">Using the SCM or GH Guile API</a>
|
|
<li><a href="#n4">Linkage</a>
|
|
<ul>
|
|
<li><a href="#n5">Simple Linkage</a>
|
|
<li><a href="#n6">Passive Linkage</a>
|
|
<li><a href="#n7">Native Guile Module Linkage</a>
|
|
<li><a href="#n8">Old Auto-Loading Guile Module Linkage</a>
|
|
<li><a href="#n9">Hobbit4D Linkage</a>
|
|
<li><a href="#n10">General Remarks on Multiple SWIG Modules</a>
|
|
</ul>
|
|
<li><a href="#n11">Underscore Folding</a>
|
|
<li><a href="#n12">Typemaps</a>
|
|
<li><a href="#n13">Smobs</a>
|
|
<ul>
|
|
<li><a href="#n14">GH API</a>
|
|
<li><a href="#n15">SCM API</a>
|
|
<li><a href="#n16">Garbage Collection</a>
|
|
<!--<li><a href="#n17">GOOPS</a>-->
|
|
</ul>
|
|
<li><a href="#n18">Exception Handling</a>
|
|
<li><a href="#n19">Procedure documentation</a>
|
|
<li><a href="#n20">Procedures with setters</a>
|
|
</ul>
|
|
<!-- INDEX -->
|
|
|
|
|
|
|
|
<p>
|
|
This section details guile-specific support in SWIG.
|
|
|
|
<a name="n2"></a><H2>14.1 Meaning of "Module"</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>
|
|
There are three different concepts of "module" involved, defined
|
|
separately for SWIG, Guile, and Libtool. To avoid horrible confusion,
|
|
we explicitly prefix the context, e.g., "guile-module".
|
|
|
|
<a name="n3"></a><H2>14.2 Using the SCM or GH Guile API</H2>
|
|
|
|
<p>The guile module can currently export wrapper files that use the guile GH interface or the
|
|
SCM interface. This is controlled by an argument passed to swig. The "-gh" argument causes swig
|
|
to output GH code, and the "-scm" argument causes swig to output SCM code. Right now the "-gh" argument
|
|
is the default. The "-scm" wrapper generation assumes a guile version >= 1.6 and has several advantages over
|
|
the "-gh" wrapper generation including garbage collection and possibly GOOPS support in the future.
|
|
The "-gh" wrapper generation can be used for older versions of guile. Thus eventually
|
|
the guile GH wrapper code generation will be depreciated (as guile 1.6 and above become more common) and the
|
|
SCM interface will become the default. The SCM and GH interface differ greatly in how they store
|
|
pointers and have completly different run-time code. See below for more info.
|
|
<code>make runtime</code> will now produce two libraries, libguilegh and libguilescm containing the
|
|
runtime code using the two different guile API's.</p>
|
|
|
|
<p>The GH interface to guile is deprecated. Read more about why in the
|
|
<a href="http://www.gnu.org/software/guile/docs/guile-ref/GH-deprecation.html">Guile manual</a>.
|
|
The idea of the GH interface was to provide a high level API that other languages and projects
|
|
could adopt. This was a good idea, but didn't pan out well for general development. But for the
|
|
specific, minimal uses that the SWIG typemaps put the GH interface to use is ideal for
|
|
using a high level API. So even though the GH interface is depreciated, SWIG will continue to use
|
|
the GH interface and provide mappings from the GH interface to whatever API we need.
|
|
We can maintain this mapping where guile failed because SWIG uses a small subset of all the GH functions
|
|
which map easily. All the guile typemaps like typemaps.i and std_vector.i
|
|
will continue to use the GH functions to do things like create lists of values, convert strings to
|
|
integers, etc. Then every language module will define a mapping between the GH interface and
|
|
whatever custom API the language uses. This is currently implemented by the guile module to use
|
|
the SCM guile API rather than the GH guile API.
|
|
For example, here are some of the current mapping file for the SCM API</p>
|
|
|
|
<blockquote><pre>
|
|
|
|
#define gh_append2(a, b) scm_append(scm_listify(a, b, SCM_UNDEFINED))
|
|
#define gh_apply(a, b) scm_apply(a, b, SCM_EOL)
|
|
#define gh_bool2scm SCM_BOOL
|
|
#define gh_boolean_p SCM_BOOLP
|
|
#define gh_car SCM_CAR
|
|
#define gh_cdr SCM_CDR
|
|
#define gh_cons scm_cons
|
|
#define gh_double2scm scm_make_real
|
|
...
|
|
</pre></blockquote>
|
|
|
|
<p>This file is parsed by SWIG at wrapper generation time, so every reference to a gh_ function is replaced
|
|
by a scm_ function in the wrapper file. Thus the gh_ function calls will never be seen in the wrapper;
|
|
the wrapper will look exactly like it was generated
|
|
for the specific API. Currently only the guile language module has created a mapping policy from gh_ to scm_,
|
|
but there is no reason other languages (like mzscheme or chicken) couldn't also use this.
|
|
If that happens, there is A LOT less code duplication in the standard typemaps.</p>
|
|
|
|
<a name="n4"></a><H2>14.3 Linkage</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>
|
|
Guile support is complicated by a lack of user community cohesiveness,
|
|
which manifests in multiple shared-library usage conventions. A set of
|
|
policies implementing a usage convention is called a <b>linkage</b>.
|
|
|
|
<a name="n5"></a><H3>14.3.1 Simple Linkage</H3>
|
|
|
|
|
|
The default linkage is the simplest; nothing special is done. In this
|
|
case the function <code>SWIG_init()</code> is exported. Simple linkage
|
|
can be used in several ways:
|
|
|
|
<ul>
|
|
<li><b>Embedded Guile, no modules.</b> You want to embed a Guile
|
|
interpreter into your program; all bindings made by SWIG shall show up
|
|
in the root module. Then call <code>SWIG_init()</code> in the
|
|
<code>inner_main()</code> function. See the "simple" and "matrix" examples under
|
|
<code>Examples/guile</code>.
|
|
|
|
<li><b>Dynamic module mix-in.</b> You want to create a Guile module
|
|
using <code>define-module</code>, containing both Scheme code and
|
|
bindings made by SWIG; you want to load the SWIG modules as shared
|
|
libraries into Guile.
|
|
<blockquote>
|
|
<pre>
|
|
(define-module (my module))
|
|
(define my-so (dynamic-link "./example.so"))
|
|
(dynamic-call "SWIG_init" my-so) ; make SWIG bindings
|
|
;; Scheme definitions can go here
|
|
</pre>
|
|
</blockquote>
|
|
Newer Guile versions provide a shorthand for <code>dynamic-link</code>
|
|
and <code>dynamic-call</code>:
|
|
<blockquote>
|
|
<pre>
|
|
(load-extension "./example.so" "SWIG_init")
|
|
</pre>
|
|
</blockquote>
|
|
You need to explicitly export those bindings made by SWIG that you
|
|
want to import into other modules:
|
|
<blockquote>
|
|
<pre>
|
|
(export foo bar)
|
|
</pre>
|
|
</blockquote>
|
|
In this example, the procedures <code>foo</code> and <code>bar</code>
|
|
would be exported. Alternatively, you can export all bindings with the
|
|
following module-system hack:
|
|
<blockquote>
|
|
<pre>
|
|
(module-map (lambda (sym var)
|
|
(module-export! (current-module) (list sym)))
|
|
(current-module))
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>SWIG can also generate this Scheme stub (from
|
|
<code>define-module</code> up to <code>export</code>)
|
|
semi-automagically if you pass it the command-line argument
|
|
<code>-scmstub <var>foo.scm</var></code>. Since SWIG doesn't know how
|
|
to load your extension module (with <code>dynamic-link</code> or
|
|
<code>load-extension</code>), you need to supply this
|
|
information by including a directive like this in the interface file:
|
|
<blockquote>
|
|
<pre>
|
|
%scheme %{ (load-extension "./example.so" "SWIG_init") %}
|
|
</pre>
|
|
</blockquote>
|
|
(The <code>%scheme</code> directive allows to insert arbitrary Scheme
|
|
code into the generated file <code><var>foo.scm</var></code>; it is
|
|
placed between the <code>define-module</code> form and the
|
|
<code>export</code> form.)
|
|
</ul>
|
|
|
|
<p>If you want to include several SWIG modules, you would need to rename
|
|
<code>SWIG_init</code> via a preprocessor define to avoid symbol
|
|
clashes. For this case, however, passive linkage is available.
|
|
|
|
<a name="n6"></a><H3>14.3.2 Passive Linkage</H3>
|
|
|
|
|
|
<p>Passive linkage is just like simple linkage, but it generates an
|
|
initialization function whose name is derived from the module and
|
|
package name (see below).
|
|
|
|
<p>You should use passive linkage rather than simple linkage when you
|
|
are using multiple modules.
|
|
|
|
<a name="n7"></a><H3>14.3.3 Native Guile Module Linkage</H3>
|
|
|
|
|
|
<p>SWIG can also generate wrapper code that does all the Guile module
|
|
declarations on its own if you pass it the <code>-Linkage
|
|
module</code> command-line option. This requires Guile 1.5.0 or later.
|
|
|
|
<p>The module name is set with the <code>-package</code> and
|
|
<code>-module</code> command-line options. Suppose you want to define
|
|
a module with name <code>(my lib foo)</code>; then you would have to
|
|
pass the options <code>-package <var>my</var>/<var>lib</var> -module
|
|
<var>foo</var></code>. Note that the last part of the name can also be set
|
|
via the SWIG directive <code>%module</code>.
|
|
|
|
<p>You can use this linkage in several ways:
|
|
|
|
<ul>
|
|
<li><b>Embedded Guile with SWIG modules.</b> You want to embed a Guile
|
|
interpreter into your program; the SWIG bindings shall be put into
|
|
different modules. Simply call the function
|
|
<code>scm_init_<var>my</var>_<var>modules</var>_<var>foo</var>_module</code>
|
|
in the <code>inner_main()</code> function.
|
|
|
|
<li><b>Dynamic Guile modules.</b> You want to load the SWIG modules as
|
|
shared libraries into Guile; all bindings are automatically put in
|
|
newly created Guile modules.
|
|
<blockquote>
|
|
<pre>
|
|
(define my-so (dynamic-link "./foo.so"))
|
|
;; create new module and put bindings there:
|
|
(dynamic-call "scm_init_my_modules_foo_module" my-so)
|
|
</pre>
|
|
</blockquote>
|
|
Newer Guile versions have a shorthand procedure for this:
|
|
<blockquote>
|
|
<pre>
|
|
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
|
|
</pre>
|
|
</blockquote>
|
|
</ul>
|
|
|
|
<a name="n8"></a><H3>14.3.4 Old Auto-Loading Guile Module Linkage</H3>
|
|
|
|
|
|
<p>Guile used to support an autoloading facility for object-code
|
|
modules. This support has been marked deprecated in version 1.4.1 and
|
|
is going to disappear sooner or later. SWIG still supports building
|
|
auto-loading modules if you pass it the <code>-Linkage ltdlmod</code>
|
|
command-line option.
|
|
|
|
<p>Auto-loading worked like this: Suppose a module with name <code>(my
|
|
lib foo)</code> is required and not loaded yet. Guile will then search
|
|
all directories in its search path
|
|
for a Scheme file <code>my/modules/foo.scm</code> or a shared library
|
|
<code><var>my</var>/<var>modules</var>/lib<var>foo</var>.so</code> (or
|
|
<code><var>my</var>/<var>modules</var>/lib<var>foo</var>.la</code>;
|
|
see the GNU libtool documentation). If a
|
|
shared library is found that contains the symbol
|
|
<code>scm_init_<var>my</var>_<var>modules</var>_<var>foo</var>_module</code>,
|
|
the library is loaded, and the function at that symbol is called with
|
|
no arguments in order to initialize the module.
|
|
|
|
<p>When invoked with the <code>-Linkage ltdlmod</code> command-line
|
|
option, SWIG generates an exported module initialization function with
|
|
an apropriate name.
|
|
|
|
|
|
<a name="n9"></a><H3>14.3.5 Hobbit4D Linkage</H3>
|
|
|
|
|
|
<p>
|
|
The only other linkage supported at this time creates shared object
|
|
libraries suitable for use by hobbit's <code>(hobbit4d link)</code>
|
|
guile module. This is called the "hobbit" linkage, and requires also
|
|
using the "-package" command line option to set the part of the module
|
|
name before the last symbol. For example, both command lines:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
swig -guile -package my/lib foo.i
|
|
swig -guile -package my/lib -module foo foo.i
|
|
</pre>
|
|
</blockquote>
|
|
|
|
would create module <code>(my lib foo)</code> (assuming in the first
|
|
case foo.i declares the module to be "foo"). The installed files are
|
|
my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very
|
|
experimental; the (hobbit4d link) conventions are not well understood.
|
|
|
|
|
|
<a name="n10"></a><H3>14.3.6 General Remarks on Multiple SWIG Modules</H3>
|
|
|
|
|
|
If you want to use multiple SWIG modules, they have to share some
|
|
run-time data for the typing system. You have two options:
|
|
|
|
<ul>
|
|
<li>Either generate all but one wrapper module with
|
|
the <code>-c</code> command-line argument. Compile all wrapper files
|
|
with the C compiler switch <code>-DSWIG_GLOBAL</code>.
|
|
|
|
<li>Or generate all wrapper modules with the <code>-c</code>
|
|
command-line argument and compile all wrapper files with the C
|
|
compiler switch <code>-DSWIG_GLOBAL</code>. Then link against the
|
|
runtime library <code>libswigguile</code> or <code>libswigguilescm</code>, which is built by
|
|
<code>make runtime</code>. The needed linker flags are reported by
|
|
SWIG if you invoke it with the <code>-guile -ldflags</code>
|
|
command-line arguments.
|
|
</ul>
|
|
|
|
<a name="n11"></a><H2>14.4 Underscore Folding</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>
|
|
Underscores are converted to dashes in identifiers. Guile support may
|
|
grow an option to inhibit this folding in the future, but no one has
|
|
complained so far.
|
|
|
|
<p>You can use the SWIG directives <code>%name</code> and
|
|
<code>%rename</code> to specify the Guile name of the wrapped
|
|
functions and variables (see CHANGES).
|
|
|
|
<a name="n12"></a><H2>14.5 Typemaps</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>
|
|
The Guile module handles all types via typemaps. This
|
|
information is read from <code>Lib/guile/typemaps.i</code>.
|
|
|
|
Some non-standard typemap substitutions are supported:
|
|
<ul>
|
|
<li><code>$descriptor</code> expands to a type descriptor for use with
|
|
the <code>SWIG_NewPointerObj()</code> and
|
|
<code>SWIG_ConvertPtr</code> functions.
|
|
<li>For pointer types, <code>$*descriptor</code> expands to a
|
|
descriptor for the direct base type (i.e., one pointer is stripped),
|
|
whereas <code>$basedescriptor</code> expands to a
|
|
descriptor for the base type (i.e., all pointers are stripped).
|
|
</ul>
|
|
|
|
<p>A function returning <code>void</code> (more precisely, a function
|
|
whose <code>out</code> typemap returns <code>SCM_UNSPECIFIED</code>) is
|
|
treated as returning no values. In <code>argout</code> typemaps, one
|
|
can use the macro <code>GUILE_APPEND_RESULT</code> in order to append
|
|
a value to the list of function return values.
|
|
|
|
<p>Multiple values can be passed up to Scheme in one of three ways:
|
|
<ul>
|
|
<li><em>Multiple values as lists.</em>
|
|
By default, if more than one value is to
|
|
be returned, a list of the values is created and returned; to switch
|
|
back to this behavior, use
|
|
<blockquote>
|
|
<pre>%values_as_list;</pre>
|
|
</blockquote>
|
|
<li><em>Multiple values as vectors.</em>
|
|
By issueing
|
|
<blockquote>
|
|
<pre>%values_as_vector;</pre>
|
|
</blockquote>
|
|
vectors instead of lists will be used.
|
|
<li><em>Multiple values for multiple-value continuations.</em>
|
|
<strong>This is the most elegant way.</strong> By issueing
|
|
<blockquote>
|
|
<pre>%multiple_values;</pre>
|
|
</blockquote>
|
|
multiple values are passed to the multiple-value
|
|
continuation, as created by <code>call-with-values</code> or the
|
|
convenience macro <code>receive</code>. The latter is available if you
|
|
issue <code>(use-modules (srfi srfi-8))</code>. Assuming that your
|
|
<code>divide</code> function
|
|
wants to return two values, a quotient and a remainder, you can write:
|
|
<blockquote>
|
|
<pre>
|
|
(receive (quotient remainder)
|
|
(divide 35 17)
|
|
<var>body</var>...)
|
|
</pre>
|
|
</blockquote>
|
|
In <code><var>body</var></code>, the first result of
|
|
<code>divide</code> will be bound to the variable
|
|
<code>quotient</code>, and the second result to <code>remainder</code>.
|
|
</ul>
|
|
See also the "multivalue" example.
|
|
|
|
<a name="n13"></a><H2>14.6 Smobs</H2>
|
|
|
|
<p>
|
|
For pointer types, SWIG uses Guile smobs. SWIG smobs print
|
|
like this: <code>#<swig struct xyzzy * 0x1234affe></code> Two of
|
|
them are <code>equal?</code> if and only if they have the same type
|
|
and value.
|
|
|
|
<p>
|
|
To construct a Scheme object from a C pointer, the wrapper code calls
|
|
the function <code>SWIG_NewPointerObj()</code>, passing a pointer to a
|
|
struct representing the pointer type. The type index to store in the
|
|
upper half of the CAR is read from this struct.
|
|
To get the pointer represented by a smob, the wrapper code calls the
|
|
function <code>SWIG_ConvertPtr()</code>, passing a pointer to a struct
|
|
representing the expected pointer type. See also
|
|
<a href="Typemaps.html#n41">Section 8.8 The run-time type checker</a>.
|
|
If the Scheme object passed was not a SWIG smob representing a compatible
|
|
pointer, a <code>wrong-type-arg</code> exception is raised.
|
|
|
|
<a name="n14"></a><H3>14.6.1 GH Smobs</H3>
|
|
|
|
<p>
|
|
In earlier versions of SWIG, C pointers were represented as Scheme
|
|
strings containing a hexadecimal rendering of the pointer value and a
|
|
mangled type name. As Guile allows registering user types, so-called
|
|
"smobs" (small objects), a much cleaner representation has been
|
|
implemented now. The details will be discussed in the following.
|
|
|
|
<p>
|
|
A smob is a cons cell where the lower half of the CAR contains the
|
|
smob type tag, while the upper half of the CAR and the whole CDR are
|
|
available. <code>SWIG_Guile_Init()</code> registers a smob type named
|
|
"swig" with Guile; its type tag is stored in the variable
|
|
<code>swig_tag</code>. The upper half of the CAR store an index into
|
|
a table of all C pointer types seen so far, to which new types seen
|
|
are appended. The CDR stores the pointer value.
|
|
|
|
<a name="n15"></a><H3>14.6.2 SCM Smobs</H3>
|
|
|
|
<p>The SCM interface (using the "-scm" argument to swig) uses common.swg.
|
|
The whole type system, when it is first initialized, creates two smobs named "swig" and "collected_swig".
|
|
The swig smob is used for non-garbage collected smobs, while the collected_swig smob is used as described
|
|
below. Each smob has the same format, which is a double cell created by SCM_NEWSMOB2()
|
|
The first word of data is the pointer to the object and the second word of data is the swig_type_info *
|
|
structure describing this type. This is a lot easier than the GH interface above because we can store
|
|
a pointer to the type info structure right in the type. With the GH interface, there was not enough
|
|
room in the smob to store two whole words of data so we needed to store part of the "swig_type_info address"
|
|
in the smob tag.</p>
|
|
|
|
|
|
<a name="n16"></a><H3>14.6.3 Garbage Collection</H3>
|
|
|
|
<p>Garbage collection is a feature of the new SCM interface, and it is automaticlly included
|
|
if you pass the "-scm" flag to swig. Thus the swig garbage collection support requires guile >1.6.
|
|
Garbage collection works like this. Every swig_type_info structure stores in its clientdata field a pointer
|
|
to the destructor for this type. The destructor is the generated wrapper around the delete function.
|
|
So swig still exports a wrapper for the destructor, it just does not call scm_c_define_gsubr() for
|
|
the wrapped delete function. So the only way to delete an object is from the garbage collector, since the
|
|
delete function is not available to scripts. How swig determins if a type should be garbage collected
|
|
is exactly like described in <a href="Customization.html#n9">
|
|
Section 9.2 Object ownership and %newobject</a> in the SWIG manual. All typemaps use an $owner var, and
|
|
the guile module replaces $owner with 0 or 1 depending on feature:new.</p>
|
|
|
|
<!--<a name="n17"></a><H3>14.6.4 GOOPS</H3>
|
|
<p>GOOPS support is also a feature of the new SCM interface, and the "-goops" argument to swig causes
|
|
the GOOPS class defintions to be added to the scmstub file (the "-scmstub" argument is required if the
|
|
"-goops" argument is given.</p>
|
|
|
|
This is what a sample class export would look like
|
|
<blockquote>
|
|
<pre>
|
|
(define-class <Foo> (<swig>)
|
|
(a #:allocation #:swig-virtual #:slot-ref Foo-a-get #:slot-set! Foo-a-set #:accessor a)
|
|
#:metaclass <swig-metaclass>
|
|
|
|
#:new-function new-Foo)
|
|
(define-method (+ (a <Foo>) (b <Foo>))
|
|
(make <Foo> #:init-smob (Foo-add (slot-ref a 'smob) (slot-ref b 'smob))))
|
|
|
|
(define <Helloo> <Foo>)
|
|
|
|
(define-class <Bar> (<swig>)
|
|
(Foo #:allocation #:swig-virtual-class #:slot-ref Bar-Foo-set #:slot-set! Bar-Foo-get
|
|
#:class <Foo> #:accessor Foo)
|
|
#:metaclass <swig-metaclass>
|
|
|
|
#:new-function new-Bar)
|
|
|
|
(define-method (getInt (b <Bar>))
|
|
(Bar-getInt (slot-ref b 'smob)))
|
|
(define-method (getSqr (b <Bar>) c)
|
|
(make <Helloo> #:init-smob (Bar-getSqr (slot-ref b 'smob) c)))
|
|
</pre>
|
|
</blockquote>
|
|
|
|
And the goops base class definitions will look like
|
|
<pre>
|
|
<blockquote>
|
|
(define-class <swig-metaclass> (<class>)
|
|
(new-function #:init-value #f))
|
|
|
|
(define-method (compute-get-n-set (class <swig-metaclass>) s)
|
|
(case (slot-definition-allocation s)
|
|
((#:swig-virtual)
|
|
(list
|
|
;getter
|
|
(let ((func (get-keyword #:slot-ref (slot-definition-options s) #f)))
|
|
(lambda (x) (func (slot-ref x 'smob))))
|
|
;setter
|
|
(let ((func (get-keyword #:slot-set! (slot-definition-options s) #f)))
|
|
(lambda (x val) (func (slot-ref x 'smob) val)))))
|
|
((#:swig-virtual-class)
|
|
(list
|
|
;getter
|
|
(let ((func (get-keyword #:slot-ref (slot-definition-options s) #f))
|
|
(class (get-keyword #:class (slot-definition-options s) #f)))
|
|
(lambda (x) (make class #:init-smob (func (slot-ref x 'smob)))))
|
|
;setter
|
|
(let ((func (get-keyword #:slot-set! (slot-definition-options s) #f)))
|
|
(lambda (x val) (func (slot-ref x 'smob) (func (slot-ref val 'smob)))))))
|
|
((#:swig-new-function)
|
|
(let ((shared-variable (slot-ref class 'new-function)))
|
|
(list (lambda (x) shared-variable)
|
|
(lambda (x var) (set! shared-variable var)))))
|
|
(else (next-method))))
|
|
|
|
(define-method (initialize (class <swig-metaclass>) initargs)
|
|
(slot-set! class 'new-function (get-keyword #:new-function initargs #f))
|
|
(next-method))
|
|
|
|
(define-class <swig> ()
|
|
(smob #:init-value #f)
|
|
(new-function #:allocation #:swig-new-function)
|
|
#:metaclass <swig-metaclass>)
|
|
|
|
(define-method (initialize (obj <swig>) initargs)
|
|
(case (car initargs)
|
|
((#:init-smob)
|
|
(slot-set! obj 'smob (cadr initargs)))
|
|
(else
|
|
(slot-set! obj 'smob (apply (slot-ref obj 'new-function) initargs)))))
|
|
|
|
</pre>
|
|
</blockquote>-->
|
|
|
|
<a name="n18"></a><H2>14.7 Exception Handling</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>
|
|
SWIG code calls <code>scm_error</code> on exception, using the following
|
|
mapping:
|
|
|
|
<pre>
|
|
MAP(SWIG_MemoryError, "swig-memory-error");
|
|
MAP(SWIG_IOError, "swig-io-error");
|
|
MAP(SWIG_RuntimeError, "swig-runtime-error");
|
|
MAP(SWIG_IndexError, "swig-index-error");
|
|
MAP(SWIG_TypeError, "swig-type-error");
|
|
MAP(SWIG_DivisionByZero, "swig-division-by-zero");
|
|
MAP(SWIG_OverflowError, "swig-overflow-error");
|
|
MAP(SWIG_SyntaxError, "swig-syntax-error");
|
|
MAP(SWIG_ValueError, "swig-value-error");
|
|
MAP(SWIG_SystemError, "swig-system-error");
|
|
</pre>
|
|
|
|
<p>
|
|
The default when not specified here is to use "swig-error".
|
|
See Lib/exception.i for details.
|
|
|
|
<a name="n19"></a><H2>14.8 Procedure documentation</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>If invoked with the command-line option <code>-procdoc
|
|
<var>file</var></code>, SWIG creates documentation strings for the
|
|
generated wrapper functions, describing the procedure signature and
|
|
return value, and writes them to <var>file</var>. You need Guile 1.4
|
|
or later to make use of the documentation files.
|
|
|
|
<p>SWIG can generate documentation strings in three formats, which are
|
|
selected via the command-line option <code>-procdocformat
|
|
<var>format</var></code>:
|
|
<ul>
|
|
<li><code>guile-1.4</code> (default): Generates a format suitable for Guile 1.4.
|
|
<li><code>plain</code>: Generates a format suitable for Guile 1.4.1 and
|
|
later.
|
|
<li><code>texinfo</code>: Generates texinfo source, which must be run
|
|
through texinfo in order to get a format suitable for Guile 1.4.1 and
|
|
later.
|
|
</ul>
|
|
|
|
<p>You need to register the generated documentation file with Guile
|
|
like this:
|
|
<pre>
|
|
(use-modules (ice-9 documentation))
|
|
(set! documentation-files
|
|
(cons "<var>file</var>" documentation-files))
|
|
</pre>
|
|
|
|
<p>Documentation strings can be configured using the Guile-specific
|
|
typemaps <code>indoc</code>, <code>outdoc</code>,
|
|
<code>argoutdoc</code>, <code>varindoc</code>, and
|
|
<code>varoutdoc</code>. See <code>Lib/guile/typemaps.i</code> for
|
|
details.
|
|
|
|
<a name="n20"></a><H2>14.9 Procedures with setters</H2>
|
|
|
|
|
|
</a>
|
|
|
|
<p>For global variables, SWIG creates a single wrapper procedure
|
|
<code>(<var>variable</var> :optional value)</code>, which is used for
|
|
both getting and setting the value. For struct members, SWIG creates
|
|
two wrapper procedures <code>(<var>struct</var>-<var>member</var>-get
|
|
pointer)</code> and <code>(<var>struct-member</var>-set pointer value)</code>.
|
|
|
|
<p>If invoked with the command-line option <code>-emit-setters</code>,
|
|
SWIG will additionally create procedures with setters. For global
|
|
variables, the procedure-with-setter <code><var>variable</var></code>
|
|
is created, so you can use <code>(<var>variable</var>)</code> to get
|
|
the value and <code>(set! (<var>variable</var>)
|
|
<var>value</var>)</code> to set it. For struct members, the
|
|
procedure-with-setter <code><var>struct</var>-<var>member</var></code>
|
|
is created, so you can use <code>(<var>struct</var>-<var>member</var>
|
|
<var>pointer</var>)</code> to get the value and <code>(set!
|
|
(<var>struct</var>-<var>member</var> <var>pointer</var>)
|
|
<var>value</var>)</code> to set it.
|
|
|
|
</body>
|
|
</html>
|