README for Emdros SWIG-Ruby
Created: 2/11-2003 (February 11, 2003)
Last update: 7/17-2004

Introduction
============

This document explains how to use the SWIG Ruby bindings for Emdros.

This document is still sketchy.


Test program
============

There is a test program, test.rb, which shows how to use the EmdrosRuby
module.  Use it for inspiration.


Installation
============

From RPM (Linux only)
---------------------

Currently, RPMs are not provided for download.  You can build them
yourself, though.  You will need a basic knowledge of how to use
rpmbuild and how to edit spec files.

To make the spec files, you can issue a "make spec2" command after
running ./configure in the top-level directory of the sources.  This
produces two spec files, one for MySQL and one for PostgreSQL, which
have support for SWIG RPMs.  You will need to edit the spec file if
you don't want support for the other languages (Java, Ruby, etc.).

The RPMs produced will install the EmdrosRuby.so module in the same
directory as the other Emdros libraries, by default
/usr/local/lib/emdros.

After installation, in order to use the EmdrosRuby module, you should
make a symbolic link to the EmdrosRuby.so library in the Ruby library
directory, e.g., /usr/lib/ruby/1.6/i386-linux.

E.g.,

% ln -s /usr/local/lib/emdros/EmdrosRuby.so /usr/lib/ruby/1.6/i386-linux/

You must normally be root in order to do this.

In order to find out which directory is the Ruby .so directory, you
can run this small shell-script:

----------- shell-script begins -----------
#!/bin/bash
for d in `ruby -e 'puts $:.join("\n")'`; do
  if test -f $d/ruby.h; then
    echo $d;
    break;
  fi
done
----------- shell-script ends -------------

This shell script can also be found in the SWIG/ruby source directory
as

dir.sh

or in the documentation directory if installed via RPM, e.g., 

/usr/share/doc/emdros-mysql-swig-ruby-1.1.10




From sources (Linux only)
-------------------------

Before running "make" in the top-level directory, you must configure
Emdros to compile with Ruby support.  Use the

  --with-swig-language-ruby

option to ./configure in the top-level directory.


The EmdrosRuby module is automatically installed by the 

   make install-ruby-lib   # in SWIG/ruby directory

process.  Issue this command in the SWIG/ruby source directory after
any "make install" process.

There is a complementary

   make uninstall-ruby-lib

process which undoes this.

When running the "make install" process, the EmdrosRuby.so library is
placed in the same directory as the other Emdros libraries, e.g.,
/usr/local/lib/emdros.  

When running the "make install-ruby-lib" process, a symbolic link is
made to the EmdrosRuby.so library in the Ruby library directory, e.g.,
/usr/lib/ruby/1.6/i386-linux.



Using
=====

General
-------

C++ classes are wrapped so they are Ruby classes with the same name.


Constants
---------

C++ (enumeration) constants that start with a lower case have been
renamed so that they start with an upper-case name.  They have also
been prefixed with the EmdrosRuby module name, e.g.:

EmdrosRuby::KOKConsole

not kOKConsole.


Creating objects
----------------

To create an object, use the "new" method on the object.  For example:

som = EmdrosRuby::SetOfMonads.new

env = EmdrosRuby::EmdrosEnv.new(EmdrosRuby::KOKConsole, EmdrosRuby::KCSISO_8859_1, "localhost", "emdf", "changeme", "emdf")


Return values
-------------

If a function or method has a call-by-reference parameter, e.g., bool&
or long&, then the return type is not a simple Ruby object but an
array of Ruby objects.  The first object in the array will be the
return value from the method or function.  The second object will be
the value of the first call-by-reference parameter.  The third object
will be the value of the second call-by-reference parameter, and so
on.

For example:


  // C++ signature is:
  // bool executeString(const std::string& input, bool& bResult, 
  //                     bool bPrintResult, bool bReportError);
  bResult = false
  result_array = env.executeString("CREATE DATABASE EMdF5 GO", bResult, true, true)
  print "Query returned: No database error: ", result_array[0], " Compiler OK: ", result_array[1], "\n"

Here, bResult was supposed to have been returned call-by-reference.
We must pass a value, so we give it a false bResult variable, but it
is not used.  Instead, the value is returned as result_array[1].  The
return value is returned as result_array[0].

Note that const std::string& is not considered a call-by-reference
parameter, but a call-by-value parameter.  std::string& is likewise
not a call-by-reference, but a call-by-value parameter.

