diff options
Diffstat (limited to 'Examples/python/variables')
| -rw-r--r-- | Examples/python/variables/Makefile | 20 | ||||
| -rw-r--r-- | Examples/python/variables/example.c | 91 | ||||
| -rw-r--r-- | Examples/python/variables/example.h | 6 | ||||
| -rw-r--r-- | Examples/python/variables/example.i | 51 | ||||
| -rw-r--r-- | Examples/python/variables/index.html | 100 | ||||
| -rw-r--r-- | Examples/python/variables/runme.py | 75 |
6 files changed, 343 insertions, 0 deletions
diff --git a/Examples/python/variables/Makefile b/Examples/python/variables/Makefile new file mode 100644 index 0000000..0f4a1e0 --- /dev/null +++ b/Examples/python/variables/Makefile @@ -0,0 +1,20 @@ +TOP = ../.. +SWIG = $(TOP)/../preinst-swig +SRCS = example.c +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:: + $(MAKE) -f $(TOP)/Makefile python_clean + rm -f $(TARGET).py + +check: all + $(MAKE) -f $(TOP)/Makefile python_run diff --git a/Examples/python/variables/example.c b/Examples/python/variables/example.c new file mode 100644 index 0000000..aa4ffe9 --- /dev/null +++ b/Examples/python/variables/example.c @@ -0,0 +1,91 @@ +/* File : example.c */ + +/* I'm a file containing some C global variables */ + +/* Deal with Microsoft's attempt at deprecating C standard runtime functions */ +#if !defined(SWIG_NO_CRT_SECURE_NO_DEPRECATE) && defined(_MSC_VER) +# define _CRT_SECURE_NO_DEPRECATE +#endif + +#include <stdio.h> +#include <stdlib.h> +#include "example.h" + +int ivar = 0; +short svar = 0; +long lvar = 0; +unsigned int uivar = 0; +unsigned short usvar = 0; +unsigned long ulvar = 0; +signed char scvar = 0; +unsigned char ucvar = 0; +char cvar = 0; +float fvar = 0; +double dvar = 0; +char *strvar = 0; +const char cstrvar[] = "Goodbye"; +int *iptrvar = 0; +char name[256] = "Dave"; +char path[256] = "/home/beazley"; + + +/* Global variables involving a structure */ +Point *ptptr = 0; +Point pt = { 10, 20 }; + +/* A variable that we will make read-only in the interface */ +int status = 1; + +/* A debugging function to print out their values */ + +void print_vars() { + printf("ivar = %d\n", ivar); + printf("svar = %d\n", svar); + printf("lvar = %ld\n", lvar); + printf("uivar = %u\n", uivar); + printf("usvar = %u\n", usvar); + printf("ulvar = %lu\n", ulvar); + printf("scvar = %d\n", scvar); + printf("ucvar = %u\n", ucvar); + printf("fvar = %g\n", fvar); + printf("dvar = %g\n", dvar); + printf("cvar = %c\n", cvar); + printf("strvar = %s\n", strvar ? strvar : "(null)"); + printf("cstrvar = %s\n", cstrvar ? cstrvar : "(null)"); + printf("iptrvar = %p\n", iptrvar); + printf("name = %s\n", name); + printf("ptptr = %p (%d, %d)\n", ptptr, ptptr ? ptptr->x : 0, ptptr ? ptptr->y : 0); + printf("pt = (%d, %d)\n", pt.x, pt.y); + printf("status = %d\n", status); +} + +/* A function to create an integer (to test iptrvar) */ + +int *new_int(int value) { + int *ip = (int *) malloc(sizeof(int)); + *ip = value; + return ip; +} + +/* A function to create a point */ + +Point *new_Point(int x, int y) { + Point *p = (Point *) malloc(sizeof(Point)); + p->x = x; + p->y = y; + return p; +} + +char * Point_print(Point *p) { + static char buffer[256]; + if (p) { + sprintf(buffer,"(%d,%d)", p->x,p->y); + } else { + sprintf(buffer,"null"); + } + return buffer; +} + +void pt_print() { + printf("(%d, %d)\n", pt.x, pt.y); +} diff --git a/Examples/python/variables/example.h b/Examples/python/variables/example.h new file mode 100644 index 0000000..0f7e895 --- /dev/null +++ b/Examples/python/variables/example.h @@ -0,0 +1,6 @@ +/* File: example.h */ + +typedef struct { + int x,y; +} Point; + diff --git a/Examples/python/variables/example.i b/Examples/python/variables/example.i new file mode 100644 index 0000000..9d0101c --- /dev/null +++ b/Examples/python/variables/example.i @@ -0,0 +1,51 @@ +/* File : example.i */ +%module example +%{ +#include "example.h" +%} + +#pragma SWIG nowarn=SWIGWARN_TYPEMAP_SWIGTYPELEAK + +/* Some global variable declarations */ +%inline %{ +extern int ivar; +extern short svar; +extern long lvar; +extern unsigned int uivar; +extern unsigned short usvar; +extern unsigned long ulvar; +extern signed char scvar; +extern unsigned char ucvar; +extern char cvar; +extern float fvar; +extern double dvar; +extern char *strvar; +extern const char cstrvar[]; +extern int *iptrvar; +extern char name[256]; + +extern Point *ptptr; +extern Point pt; +%} + + +/* Some read-only variables */ + +%immutable; + +%inline %{ +extern int status; +extern char path[256]; +%} + +%mutable; + +/* Some helper functions to make it easier to test */ +%inline %{ +extern void print_vars(); +extern int *new_int(int value); +extern Point *new_Point(int x, int y); +extern char *Point_print(Point *p); +extern void pt_print(); +%} + diff --git a/Examples/python/variables/index.html b/Examples/python/variables/index.html new file mode 100644 index 0000000..2940d8a --- /dev/null +++ b/Examples/python/variables/index.html @@ -0,0 +1,100 @@ +<html> +<head> +<title>SWIG:Examples:python:variables</title> +</head> + +<body bgcolor="#ffffff"> + +<tt>SWIG/Examples/python/variables/</tt> +<hr> + +<H2>Wrapping C Global Variables</H2> + +<p> +When a C global variable appears in an interface file, SWIG tries to +wrap it using a technique known as "variable linking." The idea is +pretty simple---we try to create a Python variable that magically +retrieves or updates the value of the underlying C variable when it is +accessed. Click <a href="example.i">here</a> to see a SWIG interface with some variable +declarations in it. + +<h2>Manipulating Variables from Python</h2> + +Before going any further, it is important to understand some important +differences between C and Python variables. In C, a variable is +simply a name that refers to a specific location in memory. For +example, when you declare a global variable '<tt>double a</tt>' you +know that somewhere in memory, 8 bytes have been set aside to hold a +<tt>double</tt> and that <tt>a</tt> is bound to this location for the +life of the program. In Python, variable creation is nothing more +than a naming operation. For example, when you say '<tt>a = 3</tt>', +'a' becomes a name that refers to some object '3'. Later on, if you say +'<tt>a = 7.5</tt>, the name 'a' is bound to an entirely different object +containing the value '7.5' (the contents of the original object are not +changed). The end result of this is that a variable in Python can refer +to a virtually unlimited number of different objects (memory locations) +over the lifetime of a program. + +<p> +Because of Python's somewhat unusual variable assignment semantics, it is not +possible to directly link a C global variable into an equivalent Python variable. +Instead, all C global variables are accessed as attributes of a special object +called 'cvar'. For example, if you had a global variable + +<blockquote> +<pre> +double foo; +</pre> +</blockquote> + +it will be accessed in the Python module as <tt>cvar.foo</tt>. Click +<a href="example.py">here</a> to see a script that updates and prints +out the values of the variables using this technique. + +<h2>Key points</h2> + +<ul> +<li>When a global variable has the type "<tt>char *</tt>", SWIG manages it as a character +string. However, whenever the value of such a variable is set from Python, the old +value is destroyed using <tt>free()</tt> or <tt>delete</tt> (the choice of which depends +on whether or not SWIG was run with the -c++ option). +<li><tt>signed char</tt> and <tt>unsigned char</tt> are handled as small 8-bit integers. +<li>String array variables such as '<tt>char name[256]</tt>' are managed as Python strings, but +when setting the value, the result is truncated to the maximum length of the array. Furthermore, the string is assumed to be null-terminated. +<li>When structures and classes are used as global variables, they are mapped into pointers. +Getting the "value" returns a pointer to the global variable. Setting the value of a structure results in a memory copy from a pointer to the global. +</ul> + +<h2>Creating read-only variables</h2> + +The <tt>%immutable</tt> and <tt>%mutable</tt> directives can be used to +specify a collection of read-only variables. For example: + +<blockquote> +<pre> +%immutable; +int status; +double blah; +... +%mutable; +</pre> +</blockquote> + +The <tt>%immutable</tt> directive remains in effect until it is explicitly disabled +using the <tt>%mutable</tt> directive. + +<h2>Comments</h2> +<ul> +<li>Management of global variables is one of the most problematic aspects +of C/C++ wrapping because the scripting interface and resulting memory management +is much trickier than simply creating a wrapper function. +<p> +<li>Because of the potential for a namespace conflict, you should not use +the <tt>from module import *</tt> statement for a SWIG module with global +variables. Doing so will cause a collision on the 'cvar' object should +more than one module be loaded in this manner. +</ul> + +</body> +</html> +<hr> diff --git a/Examples/python/variables/runme.py b/Examples/python/variables/runme.py new file mode 100644 index 0000000..b635b98 --- /dev/null +++ b/Examples/python/variables/runme.py @@ -0,0 +1,75 @@ +# file: runme.py + +import example + +# Try to set the values of some global variables + +example.cvar.ivar = 42 +example.cvar.svar = -31000 +example.cvar.lvar = 65537 +example.cvar.uivar = 123456 +example.cvar.usvar = 61000 +example.cvar.ulvar = 654321 +example.cvar.scvar = -13 +example.cvar.ucvar = 251 +example.cvar.cvar = "S" +example.cvar.fvar = 3.14159 +example.cvar.dvar = 2.1828 +example.cvar.strvar = "Hello World" +example.cvar.iptrvar= example.new_int(37) +example.cvar.ptptr = example.new_Point(37,42) +example.cvar.name = "Bill" + +# Now print out the values of the variables + +print "Variables (values printed from Python)" + +print "ivar =", example.cvar.ivar +print "svar =", example.cvar.svar +print "lvar =", example.cvar.lvar +print "uivar =", example.cvar.uivar +print "usvar =", example.cvar.usvar +print "ulvar =", example.cvar.ulvar +print "scvar =", example.cvar.scvar +print "ucvar =", example.cvar.ucvar +print "fvar =", example.cvar.fvar +print "dvar =", example.cvar.dvar +print "cvar =", example.cvar.cvar +print "strvar =", example.cvar.strvar +print "cstrvar =", example.cvar.cstrvar +print "iptrvar =", example.cvar.iptrvar +print "name =", example.cvar.name +print "ptptr =", example.cvar.ptptr, example.Point_print(example.cvar.ptptr) +print "pt =", example.cvar.pt, example.Point_print(example.cvar.pt) + +print "\nVariables (values printed from C)" + +example.print_vars() + +print "\nNow I'm going to try and modify some read only variables"; + +print " Tring to set 'path'"; +try: + example.cvar.path = "Whoa!" + print "Hey, what's going on?!?! This shouldn't work" +except: + print "Good." + +print " Trying to set 'status'"; +try: + example.cvar.status = 0 + print "Hey, what's going on?!?! This shouldn't work" +except: + print "Good." + + +print "\nI'm going to try and update a structure variable.\n" + +example.cvar.pt = example.cvar.ptptr + +print "The new value is" +example.pt_print() +print "You should see the value", example.Point_print(example.cvar.ptptr) + + + |