Typelib 1.0rc1 is out !
Author: Sylvain J. [email protected]
Project page: typelib download | SourceForge.net
Documentation:
C++ library: typeLib: Typelib: a C++ type and value introspection library
Ruby bindings: http://typelib.sourceforge.net/html/ruby
Typelib is a C++ library which allows introspection on data types
and data values. Its value model is based on the C type model. The
library allows to load definition from various type description files
(including plain C), build types programmatically, create and manipulate
values defined using these types.
The Ruby bindings to the C++ Typelib library allow to represent and
easily manipulate C types and in-memory values from within Ruby. Based
on that capability, the bindings offer a nice way to dynamically
interface with C shared libraries. The dynamic function calls are using
the dyncall library, to get rid of the many Ruby/DL bugs and
limitations, and most importantly its lack of maintainership. The
dyncall source code is provided in the Typelib source packages.
== Example
Let‘s assume that a C dynamic library called libtest.so contains a
function with the following prototype: int test_function(SimpleStruct*).
The SimpleStruct type is defined in a test_header.h file which looks
like this:
typedef struct SimpleStruct {
int a;
double d;
} SimpleStruct;
Using Typelib, a Ruby script can interface with this library this way:
require ‘typelib’
include Typelib
Load all types defined in the C file my_header.h
registry = Registry.import(‘test_header.h’)
Get a Library object for the target shared library, and get
a function handle in this library. +registry+ is used as the
type registry to access functions in this library
lib = Library.open(“libtest.so”, registry)
This searches the test_function in libtest.so. Note that MyStruct
must be
already defined in +registry+ (this is the case here). See the
documentation of Typelib::Function for the various ways to define
ruby/C
function bindings.
test_function = lib.find(‘test_function’).
returns(‘int’).
with_arguments(‘MyStruct*’)
Get the Ruby description of the MyStruct type
my_struct = registry.get(‘MyStruct’)
Create an uninitialized MyStruct parameter
arg = my_struct.new
arg.a = 10
arg.b = 20.35498
and call the function, getting the integer return value
result = test_function[struct]
It is also possible to use named parameters
struct = my_struct.new :a => 10, :b => 20
… or to even create the structure argument on the fly
result = test_function[ :a => 10, :b => 20 ]
In fact, the value of this MyStruct argument is not used by
test_function:
This argument is used as a buffer for output values. This can be
set up
in Typelib with:
test_function = registry.find(‘test_function’).
returns(‘int’).
returns(‘MyStruct*’)
result, struct = test_function[]
If the value was both used by +test_function+ and modified by it,
we
would have used the following:
test_function = registry.find(‘test_function’).
returns(‘int’).
modifies(‘MyStruct*’)
result, arg = test_function[arg]
… which can be useful if you want Typelib to build the object
on-the-fly
result, struct = test_function[:a => 10, :b => 20]
Then, getting the returned values is as simple as
puts struct.a
puts struct.b
Enjoy !
