index.html | searchcode

/trunk/Examples/ruby/class/index.html

#
HTML | 199 lines | 156 code | 43 blank | 0 comment | 0 complexity | abdc42434a37bff22a4fa2eb8ce6b395 MD5 | raw file
  1<html>
  2<head>
  3<title>SWIG:Examples:ruby:class</title>
  4</head>
  5
  6<body bgcolor="#ffffff">
  7
  8
  9<tt>SWIG/Examples/ruby/class/</tt>
 10<hr>
 11
 12<H2>Wrapping a simple C++ class</H2>
 13
 14<p>
 15This example illustrates C++ class wrapping performed by SWIG.
 16C++ classes are simply transformed into Ruby classes that provide methods to
 17access class members.
 18
 19<h2>The C++ Code</h2>
 20
 21Suppose you have some C++ classes described by the following (and admittedly lame) 
 22header file:
 23
 24<blockquote>
 25<pre>
 26/* File : example.h */
 27
 28class Shape {
 29public:
 30  Shape() {
 31    nshapes++;
 32  }
 33  virtual ~Shape() {
 34    nshapes--;
 35  };
 36  double  x, y;   
 37  void    move(double dx, double dy);
 38  virtual double area() = 0;
 39  virtual double perimeter() = 0;
 40  static  int nshapes;
 41};
 42
 43class Circle : public Shape {
 44private:
 45  double radius;
 46public:
 47  Circle(double r) : radius(r) { };
 48  virtual double area();
 49  virtual double perimeter();
 50};
 51
 52class Square : public Shape {
 53private:
 54  double width;
 55public:
 56  Square(double w) : width(w) { };
 57  virtual double area();
 58  virtual double perimeter();
 59};
 60</pre>
 61</blockquote>
 62
 63<h2>The SWIG interface</h2>
 64
 65A simple SWIG interface for this can be built by simply grabbing the header file
 66like this:
 67
 68<blockquote>
 69<pre>
 70/* File : example.i */
 71%module example
 72
 73%{
 74#include "example.h"
 75%}
 76
 77/* Let's just grab the original header file here */
 78%include "example.h"
 79</pre>
 80</blockquote>
 81
 82Note: when creating a C++ extension, you must run SWIG with the <tt>-c++</tt> option like this:
 83<blockquote>
 84<pre>
 85% swig -c++ -ruby example.i
 86</pre>
 87</blockquote>
 88
 89<h2>A sample Ruby script</h2>
 90
 91Click <a href="runme.rb">here</a> to see a script that calls the C++ functions from Ruby.
 92
 93<h2>Key points</h2>
 94
 95<ul>
 96<li>To create a new object, you call a constructor like this:
 97
 98<blockquote>
 99<pre>
100c = Example::Circle.new(10)
101</pre>
102</blockquote>
103
104<p>
105<li>To access member data, a pair of accessor methods are used.
106For example:
107
108<blockquote>
109<pre>
110c.x = 15    # Set member data
111x = c.x     # Get member data
112</pre>
113</blockquote>
114
115<p>
116<li>To invoke a member function, you simply do this
117
118<blockquote>
119<pre>
120print "The area is ", c.area, "\n"
121</pre>
122</blockquote>
123
124<p>
125<li>When a instance of Ruby level wrapper class is garbage collected by
126Ruby interpreter, the corresponding C++ destructor is automatically invoked.
127(Note: destructors are currently not inherited. This might change later.
128Until then, use <tt>-make_default</tt>).
129
130<p>
131<li>Static member variables are wrapped as Ruby class accessor methods.
132For example:
133
134<blockquote>
135<pre>
136n = Shape.nshapes     # Get a static data member
137Shapes.nshapes = 13   # Set a static data member
138</pre>
139</blockquote>
140
141</ul>
142
143<h2>General Comments</h2>
144
145<ul>
146<li>Ruby module of SWIG differs from other language modules in wrapping C++
147interfaces.  They provides lower-level interfaces and optional higher-level
148interfaces know as proxy classes.  Ruby module needs no such redundancy
149due to Ruby's sophisticated extension API.
150
151<p>
152<li>SWIG *does* know how to properly perform upcasting of objects in
153an inheritance hierarchy except for multiple inheritance.
154
155<p>
156<li>A wide variety of C++ features are not currently supported by SWIG.  Here is the
157short and incomplete list:
158
159<p>
160<ul>
161<li>Overloaded methods and functions.  SWIG wrappers don't know how to resolve name
162conflicts so you must give an alternative name to any overloaded method name using the
163%name directive like this:
164
165<blockquote>
166<pre>
167void foo(int a);  
168%name(foo2) void foo(double a, double b);
169</pre>
170</blockquote>
171
172<p>
173<li>Overloaded operators.  Not supported at all. The only workaround for this is
174to write a helper function. For example:
175
176<blockquote>
177<pre>
178%inline %{
179    Vector *vector_add(Vector *a, Vector *b) {
180          ... whatever ...
181    }
182%}
183</pre>
184</blockquote>
185
186<p>
187<li>Namespaces.  Not supported at all. Won't be supported until SWIG2.0 (if at all).
188
189</ul>
190<p>
191
192<li>Dave's snide remark: Like a large bottle of strong Tequilla, it's better to
193use C++	in moderation.
194
195</ul>
196
197<hr>
198</body>
199</html>