mirror of https://github.com/swig/swig
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:
parent
e867ed25a8
commit
b8f01da38b
|
@ -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
|
|
@ -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.
|
Binary file not shown.
|
@ -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"
|
||||
|
|
@ -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
|
|
@ -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;
|
||||
}
|
|
@ -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();
|
||||
};
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
/* File : example.i */
|
||||
%module example
|
||||
|
||||
%{
|
||||
#include "example.h"
|
||||
%}
|
||||
|
||||
/* Let's just grab the original header file here */
|
||||
%include "example.h"
|
||||
|
|
@ -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>
|
|
@ -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"
|
|
@ -6,7 +6,9 @@
|
|||
#define ICONST 42
|
||||
#define FCONST 2.1828
|
||||
#define CCONST 'x'
|
||||
#define CCONST2 '\n'
|
||||
#define SCONST "Hello World"
|
||||
#define SCONST2 "\"Hello World\""
|
||||
|
||||
/* This should work just fine */
|
||||
#define EXPR ICONST + 3*(FCONST)
|
||||
|
|
|
@ -2,13 +2,15 @@
|
|||
|
||||
require 'example'
|
||||
|
||||
print "ICONST = ", Example::ICONST, " (should be 42)\n"
|
||||
print "FCONST = ", Example::FCONST, " (should be 2.1828)\n"
|
||||
print "CCONST = ", Example::CCONST, " (should be 'x')\n"
|
||||
print "SCONST = ", Example::SCONST, " (should be 'Hello World')\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"
|
||||
print "ICONST = ", Example::ICONST, " (should be 42)\n"
|
||||
print "FCONST = ", Example::FCONST, " (should be 2.1828)\n"
|
||||
print "CCONST = ", Example::CCONST, " (should be 'x')\n"
|
||||
print "CCONST2 = ", Example::CCONST2, " (this should be on a new line)\n"
|
||||
print "SCONST = ", Example::SCONST, " (should be 'Hello World')\n"
|
||||
print "SCONST2 = ", Example::SCONST2, " (should be '\"Hello World\"')\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
|
||||
print "EXTERN = ", Example::EXTERN, " (Arg! This shouldn't print anything)\n"
|
||||
|
|
|
@ -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
|
|
@ -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;
|
||||
}
|
|
@ -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);
|
||||
|
|
@ -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;
|
||||
|
||||
|
|
@ -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>
|
||||
|
||||
|
||||
|
||||
|
|
@ -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"
|
||||
|
|
@ -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.
|
||||
<li><a href="constants/index.html">constants</a>. This shows how preprocessor macros and
|
||||
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>
|
||||
|
||||
<h2>Compilation Issues</h2>
|
||||
|
|
|
@ -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
|
|
@ -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;
|
||||
}
|
|
@ -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);
|
||||
|
||||
|
||||
|
||||
|
|
@ -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>
|
|
@ -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"
|
||||
|
||||
|
||||
|
|
@ -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
|
|
@ -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;
|
||||
}
|
||||
|
|
@ -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();
|
||||
};
|
||||
|
||||
|
||||
|
||||
|
|
@ -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;
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
|
||||
|
||||
|
|
@ -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>
|
|
@ -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
|
|
@ -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
|
|
@ -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;
|
||||
}
|
|
@ -0,0 +1,5 @@
|
|||
/* File : example.h */
|
||||
|
||||
typedef struct {
|
||||
double x, y, z;
|
||||
} Vector;
|
|
@ -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);
|
||||
}
|
||||
%}
|
||||
|
|
@ -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>
|
|
@ -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"
|
|
@ -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
|
|
@ -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);
|
||||
}
|
|
@ -0,0 +1,6 @@
|
|||
/* File: example.h */
|
||||
|
||||
typedef struct {
|
||||
int x,y;
|
||||
} Point;
|
||||
|
|
@ -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();
|
||||
|
||||
|
||||
|
||||
|
|
@ -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>
|
|
@ -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"
|
||||
|
||||
|
||||
|
Loading…
Reference in New Issue