diff --git a/Examples/README b/Examples/README
index cf20bc925..a3fae68f0 100644
--- a/Examples/README
+++ b/Examples/README
@@ -5,6 +5,10 @@ directories contain a very simple example. The "GIFPlot" contains a
more complicated example that illustrates some of SWIG's more advanced
capabilities.
+The file 'index.html' is the top of a hyperlinked document that
+contains information about all of the examples along with various
+notes related to each example.
+
The Examples directory is currently quite incomplete because it
is being reorganized. A more complete set of examples can be found
in the SWIG1.1p5 distribution (most of which should work with
diff --git a/Examples/index.html b/Examples/index.html
new file mode 100644
index 000000000..c0e1c2507
--- /dev/null
+++ b/Examples/index.html
@@ -0,0 +1,57 @@
+
+
+SWIG Examples
+
+
+
+SWIG Examples
+
+$Header$
+
+
+Welcome to the browsable SWIG Examples directory. This directory contains a
+collection of examples that illustrate various SWIG features for a variety
+of target languages. First, it is important to cover a few preliminaries:
+
+
+- All of the examples depend on the file Examples/Makefile
+found within the SWIG distribution. This file is created by
+'configure' and usually requires no modifications. However, if you
+have an usual installation of packages or experience compilation
+problems, you may need to make a few modifications.
+
+
+
- The examples directory is a work in progress and will probably remain
+somewhat incomplete. At this time, the Examples directory is somewhat sparse
+since it is being rewritten and reoganized.
+
+
+
-
+The SWIG user manual also contains a large variety of examples.
+
+
+
+Fundamentals
+
+Follow one of these links to see some simple examples for a specific target
+language:
+
+
+
+Real Life
+
+The the GIFPlot directory contains examples that illustrate the use of SWIG with
+a moderately complex C library for creating GIF images. Many of these
+examples illustrate more advanced SWIG features.
+
+
+
+
+
diff --git a/Examples/python/constants/Makefile b/Examples/python/constants/Makefile
new file mode 100644
index 000000000..d7dbbc99f
--- /dev/null
+++ b/Examples/python/constants/Makefile
@@ -0,0 +1,18 @@
+TOP = ../..
+SWIG = $(TOP)/../swig
+SRCS =
+TARGET = example
+INTERFACE = example.i
+
+all::
+ $(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
+ TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' python
+
+static::
+ $(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
+ TARGET='mypython' INTERFACE='$(INTERFACE)' python_static
+
+clean::
+ rm -f *_wrap* *.o *~ *.so mypython *.pyc .~* core
+
+
diff --git a/Examples/python/constants/example.i b/Examples/python/constants/example.i
new file mode 100644
index 000000000..9b04ebc1d
--- /dev/null
+++ b/Examples/python/constants/example.i
@@ -0,0 +1,24 @@
+/* File : example.i */
+%module example
+
+/* A few preprocessor macros */
+
+#define ICONST 42
+#define FCONST 2.1828
+#define CCONST 'x'
+#define SCONST "Hello World"
+
+/* This should work just fine */
+#define EXPR ICONST + 3*(FCONST)
+
+/* This shouldn't do anything */
+#define EXTERN extern
+
+/* Neither should this (BAR isn't defined) */
+#define FOO (ICONST + BAR)
+
+/* The following statements also produce constants */
+const int iconst = 37;
+const double fconst = 3.14;
+
+
diff --git a/Examples/python/constants/example.py b/Examples/python/constants/example.py
new file mode 100644
index 000000000..f58f2366b
--- /dev/null
+++ b/Examples/python/constants/example.py
@@ -0,0 +1,25 @@
+# file: example.py
+
+import example
+
+print "ICONST =", example.ICONST, "(should be 42)"
+print "FCONST =", example.FCONST, "(should be 2.1828)"
+print "CCONST =", example.CCONST, "(should be 'x')"
+print "SCONST =", example.SCONST, "(should be 'Hello World')"
+print "EXPR =", example.EXPR, "(should be 48.5484)"
+print "iconst =", example.iconst, "(should be 37)"
+print "fconst =", example.fconst, "(should be 3.14)"
+
+try:
+ print "EXTERN = ", example.EXTERN, "(Arg! This shouldn't print anything)"
+except AttributeError:
+ print "EXTERN isn't defined (good)"
+
+try:
+ print "FOO = ", example.FOO, "(Arg! This shouldn't print anything)"
+except AttributeError:
+ print "FOO isn't defined (good)"
+
+
+
+
diff --git a/Examples/python/constants/index.html b/Examples/python/constants/index.html
new file mode 100644
index 000000000..45d30155f
--- /dev/null
+++ b/Examples/python/constants/index.html
@@ -0,0 +1,69 @@
+
+
+SWIG:Examples:python:constants
+
+
+
+
+SWIG/Examples/python/constants/
+
+
+Wrapping C Constants
+
+$Header$
+
+
+When SWIG encounters C preprocessor macros and C declarations that look like constants,
+it creates Python variables with an identical value. Click here
+to see a SWIG interface with some constant declarations in it.
+
+
Accessing Constants from Python
+
+Click here to see a script that prints out the values
+of the constants contained in the above file.
+
+Key points
+
+
+- The values of preprocessor macros are converted into Python constants.
+
- Types are inferred by syntax (e.g., "3" is an integer and "3.5" is a float).
+
- Character constants such as 'x' are converted into Python strings.
+
- C string literals such as "Hello World" are converted into Python strings.
+
- Macros that are not fully defined are simply ignored. For example:
+
+
+#define EXTERN extern
+
+
+is ignored because SWIG has no idea what type of variable this would be.
+
+
+
- Expressions are allowed provided that all of their components are defined. Otherwise, the constant is ignored.
+
+
- Certain C declarations involving 'const' are also turned into Python constants.
+
- The Python variables that SWIG creates are not protected from modification. For example,
+even if you had this:
+
+
+#define FOO 73
+
+
+a user could come along in a script and type
+
+
+example.FOO = 13
+
+
+Unfortunately, there's no easy way to prevent this.
+
+
+
- The constants that appear in a SWIG interface file do not have to appear in any sort
+of matching C source file since the creation of a constant does not require linkage
+to a stored value (i.e., a value held in a C global variable or memory location).
+
+
+
+
+
+
+
diff --git a/Examples/python/index.html b/Examples/python/index.html
new file mode 100644
index 000000000..a36cb8c2e
--- /dev/null
+++ b/Examples/python/index.html
@@ -0,0 +1,96 @@
+
+
+SWIG:Examples:python
+
+
+
+SWIG Python Examples
+
+$Header$
+
+
+The following examples illustrate the use of SWIG with Python.
+
+
+- simple. A minimal example showing how SWIG can
+be used to wrap a C function, a global variable, and a constant.
+
- constants. This shows how preprocessor macros and
+certain C declarations are turned into constants.
+
+
+Compilation Issues
+
+
+- To create a Python extension, SWIG is run with the following options:
+
+
+
+% swig -python interface.i
+
+
+
+ - The compilation of examples is done using the file Example/Makefile. This
+makefile performs a manual module compilation which is platform specific. Typically,
+the steps look like this (Linux):
+
+
+
+% swig -python interface.i
+% gcc -fpic -c interface_wrap.c -I/usr/local/include/python1.5
+% gcc -shared interface_wrap.o $(OBJS) -o interfacemodule.so
+% python
+Python 1.5.2 (#3, Oct 9 1999, 22:09:34) [GCC 2.95.1 19990816 (release)] on linux2
+Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
+>>> import interface
+>>> interface.blah(...)
+...
+
+
+
+ - The politically "correct" way to compile a Python extension is to follow the steps
+described at www.python.org
+or in the most excellent (and shamelessly plugged) Python Essential Reference:
+
+
+
+- Create a file called Setup that looks like the following where $(SRCS) is filled
+in with any other source files you need to build the extension:
+
+
+
+*shared*
+interface interface_wrap.c $(SRCS)
+
+
+ - Copy the file Makefile.pre.in from the Python distribution. Usually it's located
+in the directory /usr/local/lib/python1.5/config on a Unix machine.
+
+
+
- Type the following to build the extension:
+
+
+
+% make -f Makefile.pre.in boot
+% make
+
+
+ - And that's it. If you are preparing an extension for distribution, you may want
+to look at the distutils.
+
+
+
+Compatibility
+
+The examples have been extensively tested on the following platforms:
+
+
+
+Your mileage may vary. If you experience a problem, please let us know by
+sending a message to swig-dev@cs.uchicago.edu.
+
+
+
+
diff --git a/Examples/python/simple/README b/Examples/python/simple/README
deleted file mode 100644
index a5b95cfde..000000000
--- a/Examples/python/simple/README
+++ /dev/null
@@ -1 +0,0 @@
-Simple example from the users manual
diff --git a/Examples/python/simple/example.c b/Examples/python/simple/example.c
index 792884b41..1c2af789c 100644
--- a/Examples/python/simple/example.c
+++ b/Examples/python/simple/example.c
@@ -1,21 +1,18 @@
-/* Simple example from documentation */
/* File : example.c */
-#include
+/* A global variable */
+double Foo = 3.0;
-double My_variable = 3.0;
-
-int fact(int n) {
- if (n <= 1) return 1;
- else return n*fact(n-1);
+/* 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;
}
-int mod(int n, int m) {
- return (n % m);
-}
-char *get_time() {
- long ltime;
- time(<ime);
- return ctime(<ime);
-}
diff --git a/Examples/python/simple/example.i b/Examples/python/simple/example.i
index 987a7cd55..6702abb1e 100644
--- a/Examples/python/simple/example.i
+++ b/Examples/python/simple/example.i
@@ -1,8 +1,5 @@
/* File : example.i */
%module example
-extern double My_variable;
-extern int fact(int);
-extern int mod(int n, int m);
-extern char *get_time();
-
+extern int gcd(int x, int y);
+extern double Foo;
diff --git a/Examples/python/simple/example.py b/Examples/python/simple/example.py
index 36cf6f218..381f7ce58 100644
--- a/Examples/python/simple/example.py
+++ b/Examples/python/simple/example.py
@@ -1,24 +1,24 @@
-#!/home/sci/local/bin/python
-#
-# Python test script. This also illustrates the use of get/set
-# for C variables.
-
-from example import *
-print get_time()
-print "My Variable = ", cvar.My_variable
-for i in range(0,14):
- n = fact(i)
- print i, "factorial is ", n
-
-for i in range(1,250):
- for j in range(1,250):
- n = mod(i,j)
- cvar.My_variable = cvar.My_variable + n
-
-print "My_variable = ", cvar.My_variable
+# file: example.py
+import example
+# Call our gcd() function
+x = 42
+y = 105
+g = example.gcd(x,y)
+print "The gcd of %d and %d is %d" % (x,y,g)
+
+# Manipulate the Foo global variable
+
+# Output its current value
+print "Foo = ", example.cvar.Foo
+
+# Change its value
+example.cvar.Foo = 3.1415926
+
+# See if the change took effect
+print "Foo = ", example.cvar.Foo
diff --git a/Examples/python/simple/index.html b/Examples/python/simple/index.html
new file mode 100644
index 000000000..9638708cc
--- /dev/null
+++ b/Examples/python/simple/index.html
@@ -0,0 +1,99 @@
+
+
+SWIG:Examples:python:simple
+
+
+
+
+
+SWIG/Examples/python/simple/
+
+
+Simple Python Example
+
+$Header$
+
+
+This example illustrates how you can hook Python to a very simple C program containing
+a function and a global variable.
+
+
The C Code
+
+Suppose you have the following C code:
+
+
+
+/* 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;
+}
+
+
+
+The SWIG interface
+
+Here is a simple SWIG interface file:
+
+
+
+/* File: example.i */
+%module example
+
+extern int gcd(int x, int y);
+extern double Foo;
+
+
+
+Compilation
+
+
+- swig -python example.i
+
+
- Compile example_wrap.c and example.c
+to create the extension examplemodule.so.
+
+
+Using the extension
+
+Click here to see a script that calls our C functions from Python.
+
+Key points
+
+
+- Use the import statement to load your extension module from Python. For example:
+
+
+import example
+
+
+
+ - C functions work just like Python functions. For example:
+
+
+g = example.gcd(42,105)
+
+
+
+ - C global variables are accessed through a special variable called 'cvar'. For example:
+
+
+a = example.cvar.Foo
+
+
+
+
+
+
+
diff --git a/Examples/tcl/constants/Makefile b/Examples/tcl/constants/Makefile
new file mode 100644
index 000000000..2d2b95df6
--- /dev/null
+++ b/Examples/tcl/constants/Makefile
@@ -0,0 +1,19 @@
+TOP = ../..
+SWIG = $(TOP)/../swig
+SRCS =
+TARGET = my_tclsh
+DLTARGET = example
+INTERFACE = example.i
+
+all::
+ $(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
+ TARGET='$(DLTARGET)' INTERFACE='$(INTERFACE)' tcl
+
+static::
+ $(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
+ TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' tclsh
+
+clean::
+ rm -f *_wrap* *.o my_tclsh *~ .~* core *.so *.sl
+
+
diff --git a/Examples/tcl/constants/example.i b/Examples/tcl/constants/example.i
new file mode 100644
index 000000000..9b04ebc1d
--- /dev/null
+++ b/Examples/tcl/constants/example.i
@@ -0,0 +1,24 @@
+/* File : example.i */
+%module example
+
+/* A few preprocessor macros */
+
+#define ICONST 42
+#define FCONST 2.1828
+#define CCONST 'x'
+#define SCONST "Hello World"
+
+/* This should work just fine */
+#define EXPR ICONST + 3*(FCONST)
+
+/* This shouldn't do anything */
+#define EXTERN extern
+
+/* Neither should this (BAR isn't defined) */
+#define FOO (ICONST + BAR)
+
+/* The following statements also produce constants */
+const int iconst = 37;
+const double fconst = 3.14;
+
+
diff --git a/Examples/tcl/constants/example.tcl b/Examples/tcl/constants/example.tcl
new file mode 100644
index 000000000..da159fae0
--- /dev/null
+++ b/Examples/tcl/constants/example.tcl
@@ -0,0 +1,25 @@
+# file: example.tcl
+
+catch { load ./example.so example}
+catch { load ./example.dll example} ;# Windows
+
+puts "ICONST = $ICONST (should be 42)"
+puts "FCONST = $FCONST (should be 2.1828)"
+puts "CCONST = $CCONST (should be 'x')"
+puts "SCONST = $SCONST (should be 'Hello World')"
+puts "EXPR = $EXPR (should be 48.5484)"
+puts "iconst = $iconst (should be 37)"
+puts "fconst = $fconst (should be 3.14)"
+
+if { [catch {
+ puts "EXTERN = $EXTERN (Arg! This shouldn't print anything)"
+}]} {
+ puts "EXTERN isn't defined (good)"
+}
+
+if { [catch {
+ puts "FOO = $FOO (Arg! This shouldn't print anything)"
+}]} {
+ puts "FOO isn't defined (good)"
+}
+
diff --git a/Examples/tcl/constants/index.html b/Examples/tcl/constants/index.html
new file mode 100644
index 000000000..b88f5f810
--- /dev/null
+++ b/Examples/tcl/constants/index.html
@@ -0,0 +1,63 @@
+
+
+SWIG:Examples:tcl:constants
+
+
+
+
+SWIG/Examples/tcl/constants/
+
+
+Wrapping C Constants
+
+$Header$
+
+
+When SWIG encounters C preprocessor macros and C declarations that look like constants,
+it creates Tcl variables with an identical value. Click here
+to see a SWIG interface with some constant declarations in it.
+
+
Accessing Constants from Tcl
+
+Click here to see a script that prints out the values
+of the constants contained in the above file.
+
+Key points
+
+
+- The values of preprocessor macros are converted into Tcl read-only variables.
+
- Types are inferred by syntax (e.g., "3" is an integer and "3.5" is a float).
+
- Character constants such as 'x' are converted into strings.
+
- C string literals such as "Hello World" are converted into strings.
+
- Macros that are not fully defined are simply ignored. For example:
+
+
+#define EXTERN extern
+
+
+is ignored because SWIG has no idea what type of variable this would be.
+
+
+
- Expressions are allowed provided that all of their components are defined. Otherwise, the constant is ignored.
+
+
- Certain C declarations involving 'const' are also turned into Tcl constants.
+
- The constants that appear in a SWIG interface file do not have to appear in any sort
+of matching C source file since the creation of a constant does not require linkage
+to a stored value (i.e., a value held in a C global variable or memory location).
+
- Since constants are turned into Tcl variables, you have to use the global
+statement when accessing from a procedure. For example:
+
+
+
+proc foo {} {
+ global ICONST # Some C constant
+ puts $ICONST
+}
+
+
+
+
+
+
+
+
diff --git a/Examples/tcl/index.html b/Examples/tcl/index.html
new file mode 100644
index 000000000..4c19356ad
--- /dev/null
+++ b/Examples/tcl/index.html
@@ -0,0 +1,62 @@
+
+
+SWIG:Examples:tcl
+
+
+
+SWIG Tcl Examples
+
+$Header$
+
+
+The following examples illustrate the use of SWIG with Tcl.
+
+
+- simple. A minimal example showing how SWIG can
+be used to wrap a C function and a global variable.
+
- constants. This shows how preprocessor macros and
+certain C declarations are turned into constants.
+
+
+Compilation Issues
+
+
+- To create a Tcl extension, SWIG is run with the following options:
+
+
+
+% swig -tcl interface.i
+
+
+
+ - The compilation of examples is done using the file Example/Makefile. This
+makefile performs a manual module compilation which is platform specific. Typically,
+the steps look like this (Linux):
+
+
+
+unix % swig -tcl interface.i
+unix % gcc -fpic -c interface_wrap.c -I/usr/local/include
+unix % gcc -shared interface_wrap.o $(OBJS) -o interface.so
+unix % tclsh8.3
+% load ./interface.so
+% blah ...
+
+
+
+
+Compatibility
+
+The examples have been extensively tested on the following platforms:
+
+
+
+Your mileage may vary. If you experience a problem, please let us know by
+sending a message to swig-dev@cs.uchicago.edu.
+
+
+
+
diff --git a/Examples/tcl/simple/README b/Examples/tcl/simple/README
deleted file mode 100644
index 031b17bc5..000000000
--- a/Examples/tcl/simple/README
+++ /dev/null
@@ -1,10 +0,0 @@
-This is a simple Tcl example. Type 'make' to
-compile a dynamically loadable extension.
-
-'make tcl8' creates a dynamically loadable Tcl 8.x
-extension.
-
-'make static' creates a statically linked 'tclsh' executable.
-
-'make static8' create a statically linked 'tclsh8.0' executable.
-
diff --git a/Examples/tcl/simple/example.c b/Examples/tcl/simple/example.c
index f132e908b..1c2af789c 100644
--- a/Examples/tcl/simple/example.c
+++ b/Examples/tcl/simple/example.c
@@ -1,25 +1,18 @@
-/* Simple example from documentation */
/* File : example.c */
-#ifdef SWIG
-%module example
-#endif
+/* A global variable */
+double Foo = 3.0;
-#include
-
-double My_variable = 3.0;
-
-int fact(int n) {
- if (n <= 1) return 1;
- else return n*fact(n-1);
+/* 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;
}
-int mod(int n, int m) {
- return (n % m);
-}
-char *get_time() {
- long ltime;
- time(<ime);
- return ctime(<ime);
-}
diff --git a/Examples/tcl/simple/example.i b/Examples/tcl/simple/example.i
index 57ee4c440..6702abb1e 100644
--- a/Examples/tcl/simple/example.i
+++ b/Examples/tcl/simple/example.i
@@ -1,13 +1,5 @@
/* File : example.i */
%module example
-%{
-/* Put headers and other declarations here */
-%}
-
-extern double My_variable;
-extern int fact(int);
-extern int mod(int n, int m);
-extern char *get_time();
-
-
+extern int gcd(int x, int y);
+extern double Foo;
diff --git a/Examples/tcl/simple/example.tcl b/Examples/tcl/simple/example.tcl
index 3a6683aa7..af3b29510 100644
--- a/Examples/tcl/simple/example.tcl
+++ b/Examples/tcl/simple/example.tcl
@@ -1,26 +1,23 @@
-#
-# Tcl script for testing simple example
-
+# file: example.tcl
# Try to load as a dynamic module. If not, we'll just assume
-# that it was statically linked in.
catch { load ./example.so example}
catch { load ./example.dll example} ;# Windows
-puts [get_time]
-set tcl_precision 17
-puts "My Variable = $My_variable"
-for {set i 0} {$i < 14} {incr i 1} {
- set n [fact $i];
- puts "$i factorial is $n"
-}
+# Call our gcd() function
+set x 42
+set y 105
+set g [gcd $x $y]
+puts "The gcd of $x and $y is $g"
-for {set i 1} {$i < 250} {incr i 1} {
- for {set j 1} {$j < 250} {incr j 1} {
- set n [mod $i $j]
- set My_variable [expr {$My_variable + $n}]
- }
-}
+# Manipulate the Foo global variable
-puts "My_variable = $My_variable"
+# Output its current value
+puts "Foo = $Foo"
+
+# Change its value
+set Foo 3.1415926
+
+# See if the change took effect
+puts "Foo = $Foo"
diff --git a/Examples/tcl/simple/index.html b/Examples/tcl/simple/index.html
new file mode 100644
index 000000000..f547994d6
--- /dev/null
+++ b/Examples/tcl/simple/index.html
@@ -0,0 +1,99 @@
+
+
+SWIG:Examples:tcl:simple
+
+
+
+
+SWIG/Examples/tcl/simple/
+
+
+Simple Tcl Example
+
+$Header$
+
+
+This example illustrates how you can hook Tcl to a very simple C program containing
+a function and a global variable.
+
+
The C Code
+
+Suppose you have the following C code:
+
+
+
+/* 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;
+}
+
+
+
+The SWIG interface
+
+Here is a simple SWIG interface file:
+
+
+
+/* File: example.i */
+%module example
+
+extern int gcd(int x, int y);
+extern double Foo;
+
+
+
+Compilation
+
+
+- swig -tcl example.i
+
+
- Compile example_wrap.c and example.c
+to create the extension example.so.
+
+
+Using the extension
+
+Click here to see a script that calls our C functions from Tcl.
+
+Key points
+
+
+- Use the load statement to load your extension module into Tcl. For example:
+
+
+load ./example.so
+
+
+
+ - C functions work just like Tcl functions. For example:
+
+
+set g [gcd 42 105]
+
+
+
+ - C global variables are accessed as Tcl variables. For example:
+
+
+set a $Foo
+set Foo $newvalue
+
+
+
+
+
+
+