$ swig -ruby example.i +$ swig -ruby example.i
$ swig -c++ -ruby example.i +$ swig -c++ -ruby example.i
$ ruby -e 'puts $:.join("\n")'
+$ ruby -e 'puts $:.join("\n")'
/usr/local/lib/ruby/site_ruby/1.6 /usr/local/lib/ruby/site_ruby/1.6/i686-linux
/usr/local/lib/ruby/site_ruby /usr/local/lib/ruby/1.6 /usr/local/lib/ruby/1.6/i686-linux .
@@ -226,7 +226,10 @@ looks like the following:
Type the following to build the extension:
$ ruby extconf.rb
$ make
$ make install ++$ ruby extconf.rb +$ make +$ make install
$ swig -ruby example.i -$ gcc -c example.c -$ gcc -c example_wrap.c -I/usr/local/lib/ruby/1.6/i686-linux -$ gcc -shared example.o example_wrap.o -o example.so +$ swig -ruby example.i +$ gcc -c example.c +$ gcc -c example_wrap.c -I/usr/local/lib/ruby/1.6/i686-linux +$ gcc -shared example.o example_wrap.o -o example.so
%module example+
%module example
will result in an extension module using the feature name @@ -319,7 +322,11 @@ finally rebuilding Ruby.
using the C++ compiler. For example:$ swig -c++ -ruby example.i
$ g++ -c example.cxx
$ g++ -c example_wrap.cxx -I/usr/local/lib/ruby/1.6/i686-linux
$ g++ -shared example.o example_wrap.o -o example.so ++$ swig -c++ -ruby example.i +$ g++ -c example.cxx +$ g++ -c example_wrap.cxx -I/usr/local/lib/ruby/1.6/i686-linux +$ g++ -shared example.o example_wrap.o -o example.so
C:\swigtest> ruby extconf.rb
C:\swigtest> nmake
C:\swigtest> nmake install ++C:\swigtest> ruby extconf.rb +C:\swigtest> nmake +C:\swigtest> nmake install
C:\swigtest> ruby run.rb+
Foo = 3.0
+C:\swigtest> ruby run.rb +Foo = 3.0 +
An alternate method of specifying a nested module name is to
-use the -prefix
+use the -prefix
option on the SWIG command line. The prefix that you specify with this
-option will be prepended to the module name specified with the %module
+option will be prepended to the module name specified with the %module
directive in your SWIG interface file. So for example, this declaration
-at the top of your SWIG interface file:
-
+at the top of your SWIG interface file:
%module "foo::bar::spam"
will result in a nested module name of Foo::Bar::Spam, +
will result in a nested module name of Foo::Bar::Spam,
but you can achieve the same
-effect by specifying:
+effect by specifying:
%module spam
and then running SWIG with the -prefix command
-line option:
+
and then running SWIG with the -prefix command +line option:
$ swig -ruby -prefix "foo::bar::" example.i+
+$ swig -ruby -prefix "foo::bar::" example.i +
Starting with SWIG 1.3.20, you can also choose to wrap @@ -477,7 +491,9 @@ everything into the global module by specifying the -globalmodule option on the SWIG command line, i.e.
$ swig -ruby -globalmodule example.i+
+$ swig -ruby -globalmodule example.i +
Note that this does not relieve you of the requirement of @@ -721,7 +737,7 @@ utility methods work normally:
Furthermore, if you have a function like this:
void spam(Parent *f);+
void spam(Parent *f);
then the function spam() accepts Parent* @@ -758,7 +774,9 @@ an optional feature that you can activate with the -minherit command-line option:
$ swig -c++ -ruby -minherit example.i+
+$ swig -c++ -ruby -minherit example.i +
Using our previous example, if your SWIG interface file @@ -1004,45 +1022,37 @@ do that, you need to define a container that contains a swig::GC_VALUE, like:
-
+%module nativevector
-%{
-std::vector< swig::GC_VALUE > NativeVector;
-%}
-
+%{
+std::vector< swig::GC_VALUE > NativeVector;
+%}
-%template(NativeVector) std::vector< swig::GC_VALUE >;
+%template(NativeVector) std::vector< swig::GC_VALUE >;
+
This vector can then contain any Ruby object, making them almost identical to Ruby's own Array class.
-require 'nativevector' +include NativeVector -include NativeVector
+v = NativeVector.new +v << 1 +v << [1,2] +v << 'hello' -
+class A; end -v = NativeVector.new
-v << 1
-v << -[1,2]
-v << -'hello'
-
-class A; end
-
-v << -A.new
-
-puts v
-=> -[1, [1,2], 'hello', #<A:0x245325>]
Obviously, there is a lot more to template wrapping than shown in these examples. More details can be found in the SWIG and C++ @@ -1053,7 +1063,7 @@ chapter.
Some containers in the STL allow you to modify their default behavior by using so called functors or function objects. - Functors are often just a very simple struct with operator() + Functors are often just a very simple struct with operator() redefined or an actual C/C++ function. This allows you, for example, to always keep the sort order of a STL container to your liking.
@@ -1062,58 +1072,51 @@ liking. that support functors using Ruby procs or methods, instead. Currently, -this includes std::set, -set::map, -std::multiset -and std::multimap. +this includes std::set, +set::map, +std::multiset +and std::multimap. -The functors in swig are called swig::UnaryFunction
-and swig::BinaryFunction.
+
The functors in swig are called swig::UnaryFunction +and swig::BinaryFunction. -For C++ predicates (ie. functors that must return bool as a result) swig::UnaryPredicate -and swig::BinaryPredicate +For C++ predicates (ie. functors that must return bool as a result) swig::UnaryPredicate +and swig::BinaryPredicate are provided.
As an example, if given this swig file:
-+%module intset; -%typemap(IntSet) std::set< int, swig::BinaryPredicate ->;
You can then use the set from Ruby with or without a proc object as a predicate:
-+require 'intset' +include Intset -include Intset
-
-# Default sorting behavior defined in C++
-a = IntSet.new
- -a << 1
-a << 2
-a << 3
-a
- -=> - [1,2,3]
-
+# Default sorting behavior defined in C++ +a = IntSet.new +a << 1 +a << 2 +a << 3 +a +=> [1,2,3] # Custom sorting behavior defined by a Ruby proc -b = IntSet.new( proc { -|a,b| a > b } )+b = IntSet.new( proc { |a,b| a > b } ) +b << 1 +b << 2 +b << 3 +b +=> [3,2,1] +
-b << 1
-b << 2
-b << 3
-b
-=> - [3,2,1]
The Ruby STL wrappings support both type of iterators by using -a proxy class in-between. This proxy class is swig::Iterator or -swig::ConstIterator. Derived from them are template +a proxy class in-between. This proxy class is swig::Iterator or +swig::ConstIterator. Derived from them are template classes that need to be initialized with the actual iterator for the container you are wrapping and often times with the beginning and ending points of the iteration range.
@@ -1136,86 +1139,68 @@ ending points of the iteration range.The SWIG STL library already provides typemaps to all the standard containers to do this wrapping automatically for you, but if you have your own STL-like iterator, you will need to write your own -typemap for them. For out typemaps, the special functions make_const_iterator and make_nonconst_iterator are provided.
+typemap for them. For out typemaps, the special functions make_const_iterator and make_nonconst_iterator are provided.These can be used either like:
-+make_const_iterator( iterator, rubyclass ); +make_const_iterator( iterator, iterator_begin, iterator_end, rubyclass ); +
The iterators support a next() and previous() member function to -just change the iterator without returning anything. previous() +
The iterators support a next() and previous() member function to +just change the iterator without returning anything. previous() should obviously only be used for bidirectional iterators. You can also advance the iterator multiple steps by using standard math -operations like +=.
+operations like +=.The -value the iterator points at can be accessed with value() -- this is equivalent to dereferencing it with *i. - For non-const iterators, a value=() function +value the iterator points at can be accessed with value() -- this is equivalent to dereferencing it with *i. + For non-const iterators, a value=() function is also provided which allows you to change the value pointed by the -iterator. This is equivalent to the C++ construct of dereferencing and assignment, like *i = something.
+iterator. This is equivalent to the C++ construct of dereferencing and assignment, like *i = something.Thus, given say a vector class of doubles defined as:
-+%module doublevector -
+%include std_vector.i -%include std_vector.i
- -
- -%template(DoubleVector) std::vector<double>;
Its iterator can then be used from Ruby like:
-+require 'doublevector' +include Doublevector -include Doublevector+
+v = DoubleVector.new +v << 1 +v << 2 +v << 3 -
+# +# an elaborate and less efficient way of doing v.map! { |x| x+2 } +# +i = v.begin +e = v.end +while i != e + val = i.value + val += 2 + i.value = val + i.next +end +i +>> [3, 4, 5 ] +
If you'd rather have STL classes without any iterators, you should define -DSWIG_NO_EXPORT_ITERATOR_METHODS when running swig.
+If you'd rather have STL classes without any iterators, you should define -DSWIG_NO_EXPORT_ITERATOR_METHODS when running swig.
$ swig -ruby -autorename example.i +$ swig -ruby -autorename example.i
Then, in ruby, it can be used like:
-
+Window.new(0,0,360,480) { |w|
+ w.color = Fltk::RED
+ w.border = false
+}
+
+For other methods, you can usually use a dummy parameter with a special in typemap, like:
-+// +// original function was: +// +// void func(int x); -// original function was:
-//
-// void func(int x);
-
-%typemap(in,numinputs=0) int RUBY_YIELD_SELF {
- if ( !rb_block_given_p() )
+%typemap(in,numinputs=0) int RUBY_YIELD_SELF { + if ( !rb_block_given_p() ) -rb_raise("No block given");
- return rb_yield(self);
-}
-
-%extend {
+rb_raise("No block given"); + return rb_yield(self); +} + +%extend { void func(int x, int -RUBY_YIELD_SELF );
-}
For more information on typemaps, see Typemaps.
@@ -1685,118 +1671,118 @@ from SWIG error codes to Ruby exceptions: