XS-MLVP
/
swig
mirror of https://github.com/swig/swig
5
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Ruby examples added. 

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@853 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Masaki Fukushima 2000-09-18 13:26:04 +00:00
parent e867ed25a8
commit b8f01da38b
42 changed files with 1804 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
Examples/GIFPlot/Ruby/shadow/Makefile Normal file
View File

@ -0,0 +1,23 @@
TOP = ../../..
SWIG = $(TOP)/../swig
SWIGOPT = -I../../Interface
SRCS =
TARGET = gifplot
INTERFACE = gifplot.i
LIBS = -L../.. -lgifplot
INCLUDE = -I../../Include
all::
$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
INCLUDE='$(INCLUDE)' LIBS='$(LIBS)' SWIGOPT='$(SWIGOPT)' \
TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' ruby
static::
$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
INCLUDE='$(INCLUDE)' LIBS='$(LIBS)' SWIGOPT='$(SWIGOPT)' \
TARGET='myruby' INTERFACE='$(INTERFACE)' ruby_static
clean::
rm -f *_wrap* *.o *~ *.so myruby .~* core *.gif
check: all

5
Examples/GIFPlot/Ruby/shadow/README Normal file
View File

@ -0,0 +1,5 @@
This example illustrates Ruby shadow classes. Take a look at
the file GIFPlot/Interface/gifplot.i
Actually Ruby module of SWIG needs no shadow class. But this example
is named "shadow" in order to be consistent with other languages.

BIN
Examples/GIFPlot/Ruby/shadow/cmap Normal file
View File

Binary file not shown.

66
Examples/GIFPlot/Ruby/shadow/runme.rb Normal file
View File

@ -0,0 +1,66 @@
# Plot a 3D function
require 'gifplot'
include Math
# Here is the function to plot
def func(x,y)
return 5*cos(2*sqrt(x*x+y*y))*exp(-0.3*sqrt(x*x+y*y))
end
# Here are some plotting parameters
XMIN = -5.0
XMAX = 5.0
YMIN = -5.0
YMAX = 5.0
ZMIN = -5.0
ZMAX = 5.0
# Grid resolution
NXPOINTS = 60
NYPOINTS = 60
cmap = Gifplot::ColorMap.new("cmap")
frame = Gifplot::FrameBuffer.new(500,500)
frame.clear(Gifplot::BLACK)
P3 = Gifplot::Plot3D.new(frame,XMIN,YMIN,ZMIN,XMAX,YMAX,ZMAX)
P3.lookat(2*[XMAX-XMIN,YMAX-YMIN,ZMAX-ZMIN].max)
P3.autoperspective(40)
P3.rotu(60)
P3.rotr(30)
P3.rotd(10)
def drawsolid()
P3.clear(Gifplot::BLACK)
P3.start()
dx = 1.0*(XMAX-XMIN)/NXPOINTS
dy = 1.0*(YMAX-YMIN)/NYPOINTS
cscale = 240.0/(ZMAX-ZMIN)
x = XMIN
for i in 0...NXPOINTS
y = YMIN
for j in 0...NYPOINTS
z1 = func(x,y)
z2 = func(x+dx,y)
z3 = func(x+dx,y+dy)
z4 = func(x,y+dy)
c1 = cscale*(z1-ZMIN)
c2 = cscale*(z2-ZMIN)
c3 = cscale*(z3-ZMIN)
c4 = cscale*(z4-ZMIN)
c = (c1+c2+c3+c4)/4
c = 0 if (c < 0)
c = 239 if c > 239
P3.solidquad(x,y,z1,x+dx,y,z2,x+dx,y+dy,z3,x,y+dy,z4,c+16)
y = y + dy
end
x = x + dx
end
end
puts "Making a nice 3D plot..."
drawsolid()
frame.writeGIF(cmap,"image.gif")
puts "Wrote image.gif"

19
Examples/ruby/class/Makefile Normal file
View File

@ -0,0 +1,19 @@
TOP = ../..
SWIG = $(TOP)/../swig
CXXSRCS = example.cxx
TARGET = example
INTERFACE = example.i
LIBS = -lm
all::
$(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \
TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' ruby_cpp
static::
$(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \
TARGET='myruby' INTERFACE='$(INTERFACE)' ruby_cpp_static
clean::
rm -f *_wrap* *.o *~ *.so myruby .~* core
check: all

28
Examples/ruby/class/example.cxx Normal file
View File

@ -0,0 +1,28 @@
/* File : example.c */
#include "example.h"
#include <math.h>
/* Move the shape to a new location */
void Shape::move(double dx, double dy) {
x += dx;
y += dy;
}
int Shape::nshapes = 0;
double Circle::area() {
return M_PI*radius*radius;
}
double Circle::perimeter() {
return 2*M_PI*radius;
}
double Square::area() {
return width*width;
}
double Square::perimeter() {
return 4*width;
}

39
Examples/ruby/class/example.h Normal file
View File

@ -0,0 +1,39 @@
/* File : example.h */
class Shape {
public:
Shape() {
nshapes++;
}
virtual ~Shape() {
nshapes--;
};
double x, y;
void move(double dx, double dy);
virtual double area() = 0;
virtual double perimeter() = 0;
static int nshapes;
};
class Circle : public Shape {
private:
double radius;
public:
Circle(double r) : radius(r) { };
virtual double area();
virtual double perimeter();
};
class Square : public Shape {
private:
double width;
public:
Square(double w) : width(w) { };
virtual double area();
virtual double perimeter();
};

10
Examples/ruby/class/example.i Normal file
View File

@ -0,0 +1,10 @@
/* File : example.i */
%module example
%{
#include "example.h"
%}
/* Let's just grab the original header file here */
%include "example.h"

221
Examples/ruby/class/index.html Normal file
View File

@ -0,0 +1,221 @@
<html>
<head>
<title>SWIG:Examples:ruby:class</title>
</head>
<body bgcolor="#ffffff">
<tt>SWIG/Examples/ruby/class/</tt>
<hr>
<H2>Wrapping a simple C++ class</H2>
<tt>$Header$</tt><br>
<p>
This example illustrates C++ class wrapping performed by SWIG.
C++ classes are simply transformed into Ruby classes that provide methods to
access class members.
<h2>The C++ Code</h2>
Suppose you have some C++ classes described by the following (and admittedly lame)
header file:
<blockquote>
<pre>
/* File : example.h */
class Shape {
public:
Shape() {
nshapes++;
}
virtual ~Shape() {
nshapes--;
};
double x, y;
void move(double dx, double dy);
virtual double area() = 0;
virtual double perimeter() = 0;
static int nshapes;
};
class Circle : public Shape {
private:
double radius;
public:
Circle(double r) : radius(r) { };
virtual double area();
virtual double perimeter();
};
class Square : public Shape {
private:
double width;
public:
Square(double w) : width(w) { };
virtual double area();
virtual double perimeter();
};
</pre>
</blockquote>
<h2>The SWIG interface</h2>
A simple SWIG interface for this can be built by simply grabbing the header file
like this:
<blockquote>
<pre>
/* File : example.i */
%module example
%{
#include "example.h"
%}
/* Let's just grab the original header file here */
%include "example.h"
</pre>
</blockquote>
Note: when creating a C++ extension, you must run SWIG with the <tt>-c++</tt> option like this:
<blockquote>
<pre>
% swig -c++ -ruby example.i
</pre>
</blockquote>
<h2>A sample Ruby script</h2>
Click <a href="runme.rb">here</a> to see a script that calls the C++ functions from Ruby.
<h2>Key points</h2>
<ul>
<li>To create a new object, you call a constructor like this:
<blockquote>
<pre>
c = Example::Circle.new(10)
</pre>
</blockquote>
<p>
<li>To access member data, a pair of accessor methods are used.
For example:
<blockquote>
<pre>
c.x = 15 # Set member data
x = c.x # Get member data
</pre>
</blockquote>
<p>
<li>To invoke a member function, you simply do this
<blockquote>
<pre>
print "The area is ", c.area, "\n"
</pre>
</blockquote>
<p>
<li>When a instance of Ruby level wrapper class is garbage collected by
Ruby interpreter, the corresponding C++ destructor is automatically invoked.
(Note: destructors are currently not inherited. This might change later.
Until then, use <tt>-make_default</tt>).
<p>
<li>Static member variables are wrapped as Ruby class accessor methods.
For example:
<blockquote>
<pre>
n = Shape.nshapes # Get a static data member
Shapes.nshapes = 13 # Set a static data member
</pre>
</blockquote>
</ul>
<h2>General Comments</h2>
<ul>
<li>Ruby module of SWIG differs from other language modules in wrapping C++
interfaces. They provides lower-level interfaces and optional higher-level
interfaces know as shadow classes. Ruby module needs no such redundancy
due to Ruby's sophisticated extension API.
<p>
<li>SWIG *does* know how to properly perform upcasting of objects in
an inheritance hierarchy except for multiple inheritance.
<p>
<li>A wide variety of C++ features are not currently supported by SWIG. Here is the
short and incomplete list:
<p>
<ul>
<li>Overloaded methods and functions. SWIG wrappers don't know how to resolve name
conflicts so you must give an alternative name to any overloaded method name using the
%name directive like this:
<blockquote>
<pre>
void foo(int a);
%name(foo2) void foo(double a, double b);
</pre>
</blockquote>
<p>
<li>Overloaded operators. Not supported at all. The only workaround for this is
to write a helper function. For example:
<blockquote>
<pre>
%inline %{
Vector *vector_add(Vector *a, Vector *b) {
... whatever ...
}
%}
</pre>
</blockquote>
<p>
<li>Namespaces. Not supported at all. Won't be supported until SWIG2.0 (if at all).
<p>
<li>Templates. Not supported at all. SWIG throws out anything that looks like a template.
You can work around the problem by aliasing a template class behind a typedef however.
For example:
<blockquote>
<pre>
%{
typedef vector<int> IntVector;
%}
class IntVector {
public:
... methods ...
};
</pre>
</blockquote>
</ul>
<p>
<li>There is no guarantee that an extremely complex C++ application will be able to compile
as a Ruby extension. Sorry.
<p>
<li>Dave's snide remark: Like a large bottle of strong Tequilla, it's better to
use C++ in moderation.
</ul>
<hr>
</body>
</html>

49
Examples/ruby/class/runme.rb Normal file
View File

@ -0,0 +1,49 @@
# file: runme.rb
# This file illustrates the C++ interface created by SWIG.
# All of our C++ classes get converted into Ruby classes.
require 'example'
# ----- Object creation -----
print "Creating some objects:\n"
c = Example::Circle.new(10)
print " Created circle #{c}\n"
s = Example::Square.new(10)
print " Created square #{s}\n"
# ----- Access a static member -----
print "\nA total of #{Example::Shape.nshapes} shapes were created\n"
# ----- Member data access -----
# Set the location of the object
# Notice how we can do this using functions specific to
# the 'Circle' class.
c.x = 20
c.y = 30
# Now use the same functions in the base class
s.x = -10
s.y = 5
print "\nHere is their current position:\n"
print " Circle = (", c.x, ",", c.y, ")\n"
print " Square = (", s.x, ",", s.y, ")\n"
# ----- Call some methods -----
print "\nHere are some properties of the shapes:\n"
for o in [c, s]
print " #{o}\n"
print " area = ", o.area, "\n"
print " perimeter = ", o.perimeter, "\n"
end
# Notice how the Shape#area() and Shape#perimeter() functions really
# invoke the appropriate virtual method on each object.
print "\n", Example::Shape.nshapes," shapes remain\n"
print "Goodbye\n"

2
Examples/ruby/constants/example.i
View File

@ -6,7 +6,9 @@
#define ICONST 42 #define ICONST 42
#define FCONST 2.1828 #define FCONST 2.1828
#define CCONST 'x' #define CCONST 'x'
#define CCONST2 '\n'
#define SCONST "Hello World" #define SCONST "Hello World"
#define SCONST2 "\"Hello World\""
/* This should work just fine */ /* This should work just fine */
#define EXPR ICONST + 3*(FCONST) #define EXPR ICONST + 3*(FCONST)

16
Examples/ruby/constants/run.rb
View File

@ -2,13 +2,15 @@
require 'example' require 'example'
print "ICONST = ", Example::ICONST, " (should be 42)\n" print "ICONST = ", Example::ICONST, " (should be 42)\n"
print "FCONST = ", Example::FCONST, " (should be 2.1828)\n" print "FCONST = ", Example::FCONST, " (should be 2.1828)\n"
print "CCONST = ", Example::CCONST, " (should be 'x')\n" print "CCONST = ", Example::CCONST, " (should be 'x')\n"
print "SCONST = ", Example::SCONST, " (should be 'Hello World')\n" print "CCONST2 = ", Example::CCONST2, " (this should be on a new line)\n"
print "EXPR = ", Example::EXPR, " (should be 48.5484)\n" print "SCONST = ", Example::SCONST, " (should be 'Hello World')\n"
print "iconst = ", Example::Iconst, " (should be 37)\n" print "SCONST2 = ", Example::SCONST2, " (should be '\"Hello World\"')\n"
print "fconst = ", Example::Fconst, " (should be 3.14)\n" print "EXPR = ", Example::EXPR, " (should be 48.5484)\n"
print "iconst = ", Example::Iconst, " (should be 37)\n"
print "fconst = ", Example::Fconst, " (should be 3.14)\n"
begin begin
print "EXTERN = ", Example::EXTERN, " (Arg! This shouldn't print anything)\n" print "EXTERN = ", Example::EXTERN, " (Arg! This shouldn't print anything)\n"

18
Examples/ruby/funcptr/Makefile Normal file
View File

@ -0,0 +1,18 @@
TOP = ../..
SWIG = $(TOP)/../swig
SRCS = example.c
TARGET = example
INTERFACE = example.i
all::
$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' ruby
static::
$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
TARGET='myruby' INTERFACE='$(INTERFACE)' ruby_static
clean::
rm -f *_wrap* *.o *~ *.so myruby .~* core
check: all

17
Examples/ruby/funcptr/example.c Normal file
View File

@ -0,0 +1,17 @@
/* File : example.c */
int do_op(int a, int b, int (*op)(int,int)) {
return (*op)(a,b);
}
int add(int a, int b) {
return a+b;
}
int sub(int a, int b) {
return a-b;
}
int mul(int a, int b) {
return a*b;
}

7
Examples/ruby/funcptr/example.h Normal file
View File

@ -0,0 +1,7 @@
/* file: example.h */
extern int do_op(int,int, int (*op)(int,int));
extern int add(int,int);
extern int sub(int,int);
extern int mul(int,int);

15
Examples/ruby/funcptr/example.i Normal file
View File

@ -0,0 +1,15 @@
/* File : example.i */
%module example
%{
#include "example.h"
%}
/* Wrap a function taking a pointer to a function */
extern int do_op(int a, int b, int (*op)(int, int));
/* Now install a bunch of "ops" as constants */
%constant(int (*)(int,int)) ADD = add;
%constant(int (*)(int,int)) SUB = sub;
%constant(int (*)(int,int)) MUL = mul;

92
Examples/ruby/funcptr/index.html Normal file
View File

@ -0,0 +1,92 @@
<html>
<head>
<title>SWIG:Examples:ruby:funcptr</title>
</head>
<body bgcolor="#ffffff">
<tt>SWIG/Examples/ruby/funcptr/</tt>
<hr>
<H2>Pointers to Functions</H2>
<tt>$Header$</tt><br>
<p>
Okay, just what in the heck does SWIG do with a declaration like this?
<blockquote>
<pre>
int do_op(int a, int b, int (*op)(int, int));
</pre>
</blockquote>
Well, it creates a wrapper as usual. Of course, that does raise some
questions about the third argument (the pointer to a function).
<p>
In this case, SWIG will wrap the function pointer as it does for all other
pointers. However, in order to actually call this function from a script,
you will need to pass some kind of C function pointer object. In C,
this is easy, you just supply a function name as an argument like this:
<blockquote>
<pre>
/* Some callback function */
int add(int a, int b) {
return a+b;
}
...
int r = do_op(x,y,add);
</pre>
</blockquote>
To make this work with SWIG, you will need to do a little extra work. Specifically,
you need to create some function pointer objects using the %constant directive like this:
<blockquote>
<pre>
%constant(int (*)(int,int)) ADD = add;
</pre>
</blockquote>
Now, in a script, you would do this:
<blockquote>
<pre>
r = do_op(x,y, ADD)
</pre>
</blockquote>
<h2>An Example</h2>
Here are some files that illustrate this with a simple example:
<ul>
<li><a href="example.c">example.c</a>
<li><a href="example.h">example.h</a>
<li><a href="example.i">example.i</a> (SWIG interface)
<li><a href="runme.rb">runme.rb</a> (Sample script)
</ul>
<h2>Notes</h2>
<ul>
<li>The value of a function pointer must correspond to a function written in C or C++.
It is not possible to pass an arbitrary Ruby proc object in as a substitute for a C
function pointer.
<p>
<li>A ruby proc can be used as a C/C++ callback if you write some
clever typemaps and are very careful about how you create your extension.
This is an advanced topic not covered here.
</ul>
<hr>
</body>
</html>

21
Examples/ruby/funcptr/runme.rb Normal file
View File

@ -0,0 +1,21 @@
# file: runme.rb
require 'example'
a = 37
b = 42
# Now call our C function with a bunch of callbacks
print "Trying some C callback functions\n"
print " a = #{a}\n"
print " b = #{b}\n"
print " ADD(a,b) = ", Example::do_op(a,b,Example::ADD),"\n"
print " SUB(a,b) = ", Example::do_op(a,b,Example::SUB),"\n"
print " MUL(a,b) = ", Example::do_op(a,b,Example::MUL),"\n"
print "Here is what the C callback function objects look like in Ruby\n"
print " ADD = #{Example::ADD}\n"
print " SUB = #{Example::SUB}\n"
print " MUL = #{Example::MUL}\n"

6
Examples/ruby/index.html
View File

@ -16,6 +16,12 @@ The following examples illustrate the use of SWIG with Ruby.
be used to wrap a C function, a global variable, and a constant. be used to wrap a C function, a global variable, and a constant.
<li><a href="constants/index.html">constants</a>. This shows how preprocessor macros and <li><a href="constants/index.html">constants</a>. This shows how preprocessor macros and
certain C declarations are turned into constants. certain C declarations are turned into constants.
<li><a href="variables/index.html">variables</a>. An example showing how to access C global variables from Ruby.
<li><a href="value/index.html">value</a>. How to pass and return structures by value.
<li><a href="class/index.html">class</a>. Wrapping a simple C++ class.
<li><a href="reference/index.html">reference</a>. C++ references.
<li><a href="pointer/index.html">pointer</a>. Simple pointer handling.
<li><a href="funcptr/index.html">funcptr</a>. Pointers to functions.
</ul> </ul>
<h2>Compilation Issues</h2> <h2>Compilation Issues</h2>

18
Examples/ruby/pointer/Makefile Normal file
View File

@ -0,0 +1,18 @@
TOP = ../..
SWIG = $(TOP)/../swig
SRCS = example.c
TARGET = example
INTERFACE = example.i
all::
$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' ruby
static::
$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
TARGET='myruby' INTERFACE='$(INTERFACE)' ruby_static
clean::
rm -f *_wrap* *.o *~ *.so myruby .~* core
check: all

16
Examples/ruby/pointer/example.c Normal file
View File

@ -0,0 +1,16 @@
/* File : example.c */
void add(int *x, int *y, int *result) {
*result = *x + *y;
}
void sub(int *x, int *y, int *result) {
*result = *x - *y;
}
int divide(int n, int d, int *r) {
int q;
q = n/d;
*r = n - q*d;
return q;
}

23
Examples/ruby/pointer/example.i Normal file
View File

@ -0,0 +1,23 @@
/* File : example.i */
%module example
/* This example illustrates a couple of different techniques
for manipulating C pointers */
/* First we'll use the pointer library */
extern void add(int *x, int *y, int *result);
%include pointer.i
/* Next we'll use some typemaps */
%include typemaps.i
extern void sub(int *INPUT, int *INPUT, int *OUTPUT);
/* Next we'll use typemaps and the %apply directive */
%apply int *OUTPUT { int *r };
extern int divide(int n, int d, int *r);

173
Examples/ruby/pointer/index.html Normal file
View File

@ -0,0 +1,173 @@
<html>
<head>
<title>SWIG:Examples:ruby:pointer</title>
</head>
<body bgcolor="#ffffff">
<tt>SWIG/Examples/ruby/pointer/</tt>
<hr>
<H2>Simple Pointer Handling</H2>
<tt>$Header$</tt><br>
<p>
This example illustrates a couple of techniques for handling
simple pointers in SWIG. The prototypical example is a C function
that operates on pointers such as this:
<blockquote>
<pre>
void add(int *x, int *y, int *r) {
*r = *x + *y;
}
</pre>
</blockquote>
By default, SWIG wraps this function exactly as specified and creates
an interface that expects pointer objects for arguments. The only
problem is how does one go about creating these objects from a script?
<h2>Possible Solutions</h2>
<ul>
<li>Write some helper functions to explicitly create objects. For
example:
<blockquote>
<pre>
int *new_int(int ivalue) {
int *i = (int *) malloc(sizeof(ivalue));
*i = ivalue;
return i;
}
int get_int(int *i) {
return *i;
}
void delete_int(int *i) {
free(i);
}
</pre>
</blockquote>
Now, in a script you would do this:
<blockquote>
<pre>
a = new_int(37)
b = new_int(42)
c = new_int(0)
add(a,b,c)
r = get_int(c)
print "Result = #{r}\n"
delete_int(a)
delete_int(b)
delete_int(c)
</pre>
</blockquote>
<p>
<li>Use the SWIG pointer library. For example, in the interface file
you would do this:
<blockquote>
<pre>
%include "pointer.i"
</pre>
</blockquote>
and in a script you would do this:
<blockquote>
<pre>
a = ptrcreate("int",37)
b = ptrcreate("int",42)
c = ptrcreate("int")
add(a,b,c)
r = ptrvalue(c)
print "Result = #{r}\n"
ptrfree(a)
ptrfree(b)
ptrfree(c)
</pre>
</blockquote>
The advantage to using the pointer library is that it unifies some of the helper
functions behind a common set of names. For example, the same set of functions work
with int, double, float, and other fundamental types.
<p>
<li>Use the SWIG typemap library. This library allows you to completely
change the way arguments are processed by SWIG. For example:
<blockquote>
<pre>
%include "typemaps.i"
void add(int *INPUT, int *INPUT, int *OUTPUT);
</pre>
</blockquote>
And in a script:
<blockquote>
<pre>
r = add(37,42)
print "Result = #{r}\n"
</pre>
</blockquote>
Needless to say, this is substantially easier.
<p>
<li>A final alternative is to use the typemaps library in combination
with the %apply directive. This allows you to change the names of parameters
that behave as input or output parameters. For example:
<blockquote>
<pre>
%include "typemaps.i"
%apply int *INPUT {int *x, int *y};
%apply int *OUTPUT {int *r};
void add(int *x, int *y, int *r);
void sub(int *x, int *y, int *r);
void mul(int *x, int *y, int *r);
... etc ...
</pre>
</blockquote>
</ul>
<h2>Example</h2>
The following example illustrates the use of these features for pointer
extraction.
<ul>
<li> <a href="example.c">example.c</a> (C Source)
<li> <a href="example.i">example.i</a> (Swig interface)
<li> <a href="runme.rb">runme.rb</a> (Ruby Script)
</ul>
<h2>Notes</h2>
<ul>
<li>Since pointers are used for so many different things (arrays, output values,
etc...) the complexity of pointer handling can be as complicated as you want to
make it.
<p>
<li>More documentation on the typemaps.i and pointer.i library files can be
found in the SWIG user manual. The files also contain documentation.
<p>
<li>The pointer.i library is designed primarily for convenience. If you
are concerned about performance, you probably want to use a different
approach.
</ul>
<hr>
</body>
</html>

42
Examples/ruby/pointer/runme.rb Normal file
View File

@ -0,0 +1,42 @@
# file: runme.rb
require 'example'
# First create some objects using the pointer library.
print "Testing the pointer library\n"
a = Example::ptrcreate("int", 37)
b = Example::ptrcreate("int", 42)
c = Example::ptrcreate("int");
print " a = #{a}\n"
print " b = #{b}\n"
print " c = #{c}\n"
# Call the add() function with some pointers
Example::add(a, b, c)
# Now get the result
r = Example::ptrvalue(c)
print " 37 + 42 = #{r}\n"
# Clean up the pointers
Example::ptrfree(a)
Example::ptrfree(b)
Example::ptrfree(c)
# Now try the typemap library
# This should be much easier. Now how it is no longer
# necessary to manufacture pointers.
print "Trying the typemap library\n"
r = Example::sub(37, 42)
print " 37 - 42 = #{r}\n"
# Now try the version with multiple return values
print "Testing multiple return values\n"
q, r = Example::divide(42, 37)
print " 42/37 = #{q} remainder #{r}\n"

19
Examples/ruby/reference/Makefile Normal file
View File

@ -0,0 +1,19 @@
TOP = ../..
SWIG = $(TOP)/../swig
CXXSRCS = example.cxx
TARGET = example
INTERFACE = example.i
LIBS = -lm
all::
$(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \
TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' ruby_cpp
static::
$(MAKE) -f $(TOP)/Makefile CXXSRCS='$(CXXSRCS)' SWIG='$(SWIG)' \
TARGET='myruby' INTERFACE='$(INTERFACE)' ruby_cpp_static
clean::
rm -f *_wrap* *.o *~ *.so myruby .~* core
check: all

41
Examples/ruby/reference/example.cxx Normal file
View File

@ -0,0 +1,41 @@
/* File : example.cxx */
#include "example.h"
#include <stdio.h>
#include <stdlib.h>
Vector operator+(const Vector &a, const Vector &b) {
Vector r;
r.x = a.x + b.x;
r.y = a.y + b.y;
r.z = a.z + b.z;
return r;
}
char *Vector::print() {
static char temp[512];
sprintf(temp,"Vector %x (%g,%g,%g)", this, x,y,z);
return temp;
}
VectorArray::VectorArray(int size) {
items = new Vector[size];
maxsize = size;
}
VectorArray::~VectorArray() {
delete [] items;
}
Vector &VectorArray::operator[](int index) {
if ((index < 0) || (index >= maxsize)) {
printf("Panic! Array index out of bounds.\n");
exit(1);
}
return items[index];
}
int VectorArray::size() {
return maxsize;
}

26
Examples/ruby/reference/example.h Normal file
View File

@ -0,0 +1,26 @@
/* File : example.h */
class Vector {
private:
double x,y,z;
public:
Vector() : x(0), y(0), z(0) { };
Vector(double x, double y, double z) : x(x), y(y), z(z) { };
friend Vector operator+(const Vector &a, const Vector &b);
char *print();
};
class VectorArray {
private:
Vector *items;
int maxsize;
public:
VectorArray(int maxsize);
~VectorArray();
Vector &operator[](int);
int size();
};

46
Examples/ruby/reference/example.i Normal file
View File

@ -0,0 +1,46 @@
/* File : example.i */
/* This file has a few "typical" uses of C++ references. */
%module example
%{
#include "example.h"
%}
class Vector {
public:
Vector(double x, double y, double z);
~Vector();
char *print();
};
/* This helper function calls an overloaded operator */
%inline %{
Vector addv(Vector &a, Vector &b) {
return a+b;
}
%}
/* Wrapper around an array of vectors class */
class VectorArray {
public:
VectorArray(int maxsize);
~VectorArray();
int size();
/* This wrapper provides an alternative to the [] operator */
%addmethods {
Vector &get(int index) {
return (*self)[index];
}
void set(int index, Vector &a) {
(*self)[index] = a;
}
}
};

149
Examples/ruby/reference/index.html Normal file
View File

@ -0,0 +1,149 @@
<html>
<head>
<title>SWIG:Examples:ruby:reference</title>
</head>
<body bgcolor="#ffffff">
<tt>SWIG/Examples/ruby/reference/</tt>
<hr>
<H2>C++ Reference Handling</H2>
<tt>$Header$</tt><br>
<p>
This example tests SWIG's handling of C++ references. Since C++
references are closely related to pointers (as both refer to a
location in memory), SWIG simply collapses all references into
pointers when creating wrappers.
<h2>Some examples</h2>
References are most commonly used as function parameter. For example,
you might have an operator like this:
<blockquote>
<pre>
Vector operator+(const Vector &a, const Vector &b) {
Vector result;
result.x = a.x + b.x;
result.y = a.y + b.y;
result.z = a.z + b.z;
return result;
}
</pre>
</blockquote>
or a function:
<blockquote>
<pre>
Vector addv(const Vector &a, const Vector &b) {
Vector result;
result.x = a.x + b.x;
result.y = a.y + b.y;
result.z = a.z + b.z;
return result;
}
</pre>
</blockquote>
In these cases, SWIG transforms everything into a pointer and creates a wrapper
that looks like this:
<blockquote>
<pre>
Vector wrap_addv(Vector *a, Vector *b) {
return addv(*a,*b);
}
</pre>
</blockquote>
Occasionally, a reference is used as a return value of a function
when the return result is to be used as an lvalue in an expression.
The prototypical example is an operator like this:
<blockquote>
<pre>
Vector &operator[](int index);
</pre>
</blockquote>
or a method:
<blockquote>
<pre>
Vector &get(int index);
</pre>
</blockquote>
For functions returning references, a wrapper like this is created:
<blockquote>
<pre>
Vector *wrap_Object_get(Object *self, int index) {
Vector &result = self->get(index);
return &result;
}
</pre>
</blockquote>
The following <a href="example.h">header file</a> contains some class
definitions with some operators and use of references.
<h2>SWIG Interface</h2>
SWIG does NOT support overloaded operators so it can not directly build
an interface to the classes in the above file. However, a number of workarounds
can be made. For example, an overloaded operator can be stuck behind a function
call such as the <tt>addv()</tt> function above. Array access can be handled
with a pair of set/get functions like this:
<blockquote>
<pre>
class VectorArray {
public:
...
%addmethods {
Vector &get(int index) {
return (*self)[index];
}
void set(int index, Vector &a) {
(*self)[index] = a;
}
}
...
}
</pre>
</blockquote>
Click <a href="example.i">here</a> to see a SWIG interface file with these additions.
<h2>Sample Ruby script</h2>
Click <a href="runme.rb">here</a> to see a script that manipulates some C++ references.
<h2>Notes:</h2>
<ul>
<li>C++ references primarily provide notational convenience for C++
source code. However, Ruby only supports the 'x.a'
notation so it doesn't much matter.
<p>
<li>When a program returns a reference, a pointer is returned.
Unlike return by value, memory is not allocated to hold the
return result.
<p>
<li>SWIG has particular trouble handling various combinations of references
and pointers. This is side effect of an old parsing scheme and
type representation that will be replaced in future versions.
</ul>
<hr>
</body>
</html>

60
Examples/ruby/reference/runme.rb Normal file
View File

@ -0,0 +1,60 @@
# file: runme.rb
# This file illustrates the manipulation of C++ references in Ruby.
require 'example'
# ----- Object creation -----
print "Creating some objects:\n"
a = Example::Vector.new(3,4,5)
b = Example::Vector.new(10,11,12)
print " Created ", a.print, "\n"
print " Created ", b.print, "\n"
# ----- Call an overloaded operator -----
# This calls the wrapper we placed around
#
# operator+(const Vector &a, const Vector &)
#
# It returns a new allocated object.
print "Adding a+b\n"
c = Example::addv(a, b)
print " a+b = ", c.print, "\n"
# ----- Create a vector array -----
print "Creating an array of vectors\n"
va = Example::VectorArray.new(10)
print " va = #{va}\n"
# ----- Set some values in the array -----
# These operators copy the value of a and b to the vector array
va.set(0, a)
va.set(1, b)
va.set(2, Example::addv(a,b))
c = Example::addv(a,b)
va.set(3, c)
=begin commented out due to GC issue
# Get some values from the array
print "Getting some array values\n"
for i in 0...5
print " va(#{i}) = ", va.get(i).print, "\n"
end
# Watch under resource meter to check on this
print "Making sure we don't leak memory.\n"
for i in 0...1000000
c = va.get(i % 10)
end
=end

18
Examples/ruby/value/Makefile Normal file
View File

@ -0,0 +1,18 @@
TOP = ../..
SWIG = $(TOP)/../swig
SRCS = example.c
TARGET = example
INTERFACE = example.i
all::
$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' ruby
static::
$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
TARGET='myruby' INTERFACE='$(INTERFACE)' ruby_static
clean::
rm -f *_wrap* *.o *~ *.so myruby .~* core
check: all

15
Examples/ruby/value/example.c Normal file
View File

@ -0,0 +1,15 @@
/* File : example.c */
#include "example.h"
double dot_product(Vector a, Vector b) {
return (a.x*b.x + a.y*b.y + a.z*b.z);
}
Vector vector_add(Vector a, Vector b) {
Vector r;
r.x = a.x + b.x;
r.y = a.y + b.y;
r.z = a.z + b.z;
return r;
}

5
Examples/ruby/value/example.h Normal file
View File

@ -0,0 +1,5 @@
/* File : example.h */
typedef struct {
double x, y, z;
} Vector;

30
Examples/ruby/value/example.i Normal file
View File

@ -0,0 +1,30 @@
// Tests SWIG's handling of pass-by-value for complex datatypes
%module example
%{
#include "example.h"
%}
/* Some functions that manipulate Vectors by value */
extern double dot_product(Vector a, Vector b);
extern Vector vector_add(Vector a, Vector b);
/* Include this because the vector_add() function will leak memory */
void free(void *);
/* Some helper functions for our interface */
%inline %{
Vector *new_Vector(double x, double y, double z) {
Vector *v = (Vector *) malloc(sizeof(Vector));
v->x = x;
v->y = y;
v->z = z;
return v;
}
void vector_print(Vector *v) {
printf("Vector %x = (%g, %g, %g)\n", v, v->x, v->y, v->z);
}
%}

116
Examples/ruby/value/index.html Normal file
View File

@ -0,0 +1,116 @@
<html>
<head>
<title>SWIG:Examples:ruby:value</title>
</head>
<body bgcolor="#ffffff">
<tt>SWIG/Examples/ruby/value/</tt>
<hr>
<H2>Passing and Returning Structures by Value</H2>
<tt>$Header$</tt><br>
<p>
Occasionally, a C program will manipulate structures by value such as shown in the
following code:
<blockquote>
<pre>
/* File : example.c */
typedef struct Vector {
double x, y, z;
} Vector;
double dot_product(Vector a, Vector b) {
return (a.x*b.x + a.y*b.y + a.z*b.z);
}
Vector vector_add(Vector a, Vector b) {
Vector r;
r.x = a.x + b.x;
r.y = a.y + b.y;
r.z = a.z + b.z;
return r;
}
</pre>
</blockquote>
Since SWIG only knows how to manage pointers to structures (not their internal
representation), the following translations are made when wrappers are
created:
<blockquote>
<pre>
double wrap_dot_product(Vector *a, Vector *b) {
return dot_product(*a,*b);
}
Vector *wrap_vector_add(Vector *a, Vector *b) {
Vector *r = (Vector *) malloc(sizeof(Vector));
*r = vector_add(*a,*b);
return r;
}
</pre>
</blockquote>
The functions are then called using pointers from the scripting language interface.
It should also be noted that any function that returns a structure by value results
in an implicit memory allocation. This will be a memory leak unless you take steps
to free the result (see below).
<h2>The SWIG interface</h2>
Click <a href="example.i">here</a> to see a SWIG interface file that
wraps these two functions. In this file, there are a few essential features:
<ul>
<li>A wrapper for the <tt>free()</tt> function is created so that we
can clean up the return result created by <tt>vector_add()</tt>
function.
<p>
<li>The %inline directive is used to create a few helper functions for creating new Vector
objects and to print out the value (for debugging purposes).
</ul>
<h2>A Ruby Script</h2>
Click <a href="runme.rb">here</a> to see a script that uses these functions from Ruby.
<h2>Notes</h2>
<ul>
<li>When the '<tt>-c++</tt>' option is used, the resulting wrapper code for the return value
changes to the following:
<blockquote>
<pre>
Vector *wrap_vector_add(Vector *a, Vector *b) {
Vector *r = new Vector(vector_add(*a,*b));
return r;
}
</pre>
</blockquote>
<p>
<li>If you define C structure (or C++ class with '<tt>-c++</tt>' option)
in the interface file, the SWIG generated wrappers can automaticallyclean
up the result of return-by-reference by GC.
<p>
<li>Passing parameters by value like this really isn't the best C programming style.
If possible, you might change your application to use pointers.
<p>
<li>Similar translations are made when C++ references are used.
</ul>
<hr>
</body>
</html>

32
Examples/ruby/value/runme.rb Normal file
View File

@ -0,0 +1,32 @@
# file: runme.rb
require 'example'
# Create a couple of a vectors
v = Example::new_Vector(1, 2, 3)
w = Example::new_Vector(10, 11, 12)
print "I just created the following vectors\n"
Example::vector_print(v)
Example::vector_print(w)
# Now call some of our functions
print "\nNow I'm going to compute the dot product\n"
d = Example::dot_product(v,w)
print "dot product = #{d} (should be 68)\n"
# Add the vectors together
print "\nNow I'm going to add the vectors together\n"
r = Example::vector_add(v,w)
Example::vector_print(r)
print "The value should be (11, 13, 15)\n"
# Now I'd better clean up the return result r
print "\nNow I'm going to clean up the return result\n"
Example::free(r)
print "Good\n"

18
Examples/ruby/variables/Makefile Normal file
View File

@ -0,0 +1,18 @@
TOP = ../..
SWIG = $(TOP)/../swig
SRCS = example.c
TARGET = example
INTERFACE = example.i
all::
$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
TARGET='$(TARGET)' INTERFACE='$(INTERFACE)' ruby
static::
$(MAKE) -f $(TOP)/Makefile SRCS='$(SRCS)' SWIG='$(SWIG)' \
TARGET='myruby' INTERFACE='$(INTERFACE)' ruby_static
clean::
rm -f *_wrap* *.o *~ *.so myruby .~* core
check: all

86
Examples/ruby/variables/example.c Normal file
View File

@ -0,0 +1,86 @@
/* File : example.c */
/* I'm a file containing some C global variables */
#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 = 0;
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 = %x\n", iptrvar);
printf("name = %s\n", name);
printf("ptptr = %x (%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);
}

6
Examples/ruby/variables/example.h Normal file
View File

@ -0,0 +1,6 @@
/* File: example.h */
typedef struct {
int x,y;
} Point;

44
Examples/ruby/variables/example.i Normal file
View File

@ -0,0 +1,44 @@
/* File : example.i */
%module example
%{
#include "example.h"
%}
/* Some global variable declarations */
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 */
%readonly
extern int status;
extern char path[256];
%readwrite
/* Some helper functions to make it easier to test */
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();

96
Examples/ruby/variables/index.html Normal file
View File

@ -0,0 +1,96 @@
<html>
<head>
<title>SWIG:Examples:ruby:variables</title>
</head>
<body bgcolor="#ffffff">
<tt>SWIG/Examples/ruby/variables/</tt>
<hr>
<H2>Wrapping C Global Variables</H2>
<tt>$Header$</tt><br>
<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 Ruby variable (actually module method) 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 Ruby</h2>
Before going any further, it is important to understand some important
differences between C and Ruby 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 Ruby, 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 Ruby can refer
to a virtually unlimited number of different objects (memory locations)
over the lifetime of a program.
<p>
Because of Ruby's somewhat unusual variable assignment semantics, it is not
possible to directly link a C global variable into an equivalent Ruby variable.
Instead, all C global variables are accessed as attributes of the module.
For example, if you had a global variable
<blockquote>
<pre>
double foo;
</pre>
</blockquote>
it will be accessed in the Ruby module as <tt>Example.foo</tt>. Click
<a href="runme.rb">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 Ruby, the old
value is destroyed using <tt>free()</tt>.
<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 Ruby 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>%readonly</tt> and <tt>%readwrite</tt> directives can be used to
specify a collection of read-only variables. For example:
<blockquote>
<pre>
%readonly
int status;
double blah;
...
%readwrite
</pre>
</blockquote>
The <tt>%readonly</tt> directive remains in effect until it is explicitly disabled
using the <tt>%readwrite</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.
</ul>
</body>
</html>
<hr>

78
Examples/ruby/variables/runme.rb Normal file
View File

@ -0,0 +1,78 @@
# file: runme.rb
require 'example'
# Try to set the values of some global variables
Example.ivar = 42
Example.svar = -31000
Example.lvar = 65537
Example.uivar = 123456
Example.usvar = 61000
Example.ulvar = 654321
Example.scvar = -13
Example.ucvar = 251
Example.cvar = "S"
Example.fvar = 3.14159
Example.dvar = 2.1828
Example.strvar = "Hello World"
Example.cstrvar = "Goodbye"
Example.iptrvar= Example.new_int(37)
Example.ptptr = Example.new_Point(37,42)
Example.name = "Bill"
# Now print out the values of the variables
puts "Variables (values printed from Ruby)"
print "ivar = ", Example.ivar, "\n"
print "svar = ", Example.svar, "\n"
print "lvar = ", Example.lvar, "\n"
print "uivar = ", Example.uivar, "\n"
print "usvar = ", Example.usvar, "\n"
print "ulvar = ", Example.ulvar, "\n"
print "scvar = ", Example.scvar, "\n"
print "ucvar = ", Example.ucvar, "\n"
print "fvar = ", Example.fvar, "\n"
print "dvar = ", Example.dvar, "\n"
print "cvar = ", Example.cvar, "\n"
print "strvar = ", Example.strvar, "\n"
print "cstrvar = ", Example.cstrvar, "\n"
print "iptrvar = ", Example.iptrvar, "\n"
print "name = ", Example.name, "\n"
print "ptptr = ", Example.ptptr, " ", Example.Point_print(Example.ptptr), "\n"
print "pt = ", Example.pt, " ", Example.Point_print(Example.pt), "\n"
puts "\nVariables (values printed from C)"
Example.print_vars()
puts "\nNow I'm going to try and modify some read only variables";
puts " Tring to set 'path'";
begin
Example.path = "Whoa!"
puts "Hey, what's going on?!?! This shouldn't work"
rescue
puts "Good."
end
puts " Trying to set 'status'";
begin
Example.status = 0
puts "Hey, what's going on?!?! This shouldn't work"
rescue
puts "Good."
end
print "\nI'm going to try and update a structure variable.\n\n"
Example.pt = Example.ptptr
puts "The new value is"
Example.pt_print()
print "You should see the value ", Example.Point_print(Example.ptptr), "\n"