From: Sylvain Joyeux <sylvain.joyeux@...>
Date: 2008-02-20T18:11:23+09:00
Subject: [ANN] Typelib: a C/C++ type/value manipulation library, and	dynamic function calls

Typelib 1.0rc1 is out !
Author: Sylvain Joyeux <sylvain.joyeux@m4x.org>
Project page: http://sourceforge.net/projects/typelib
Documentation:
    C++ library:   http://typelib.sourceforge.net/html/
    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 !