GPMI - writing a script interpreter module

1. Introduction

One of the use of gpmi is to integrate script interpreters in an application in a modular way. This assumes we actually have script interpreters that work with gpmi. Well, this is what this document is about. You will read detailed information about how to implement a gpmi module for your favorite script language in gpmi.

2. Script modules, general modules

Script modules are just special cases of general gpmi modules. Since there are many common things in the module implementation of different script languages, gpmi has a special package, called gpmi_scripts to avoid code duplications.

First you will need to decide if your script language is similar enough to the model that gpmi_scripts works with. If so, you should read on this file, if not, you are all alone :)

3. Requirements

Let's see what a script language should know to be used with gpmi_scripts package to form a new gpmi module:
  1. Embeddable; it's a must, you need to have a library that you can link to a program. If you have an executable, like /usr/bin/awk, that won't be enough. [gpmi]
  2. Text (string) based interface. You must be able to pass arguments in text format for your script. [gpmi_scripts]
  3. You must be able to inject script lines. Mostly it means calling subroutines of the script. [gpmi_scripts]
  4. Defining external commands is also very important to be able to use packages. [gpmi]
If your favorite script language fails any of the above, you have to check the given point's [] part. If it is [gpmi], that means the option is needed to be gpmi-compatible and you can't make your scripting language to be a real module of gpmi without serious workarounds. If it's [gpmi_scripts], you can't use the default script package and your script-module will be special, you need to spend more time on implementing it.

4. Implementation

Start a new module by cloning the tcl or the php module. After editing the makefiles as necessary, you will work mainly with 2 .c and a .h file.

Edit main.c. Most important part of the file is the GPMI_Script_Info structure that provides an interface between gpmi_scripts package and your module. These are callback routines, the package will call your routines to do low level things using this table.

Other functions in this file are default gpmi-module functions. Most of them calls gpmi_scripts directly, you won't have to change them, but gpmi_mod_Debug needs some editing to suite your language.

Now edit tcl.c (or php.c), of course, after renaming it. In this file you find all the language-dependent parts. I won't list them here, most of the small routines are very clear after reading the comments.

DynamicPackageCommand is a routine that should get requests from the script interpreter for external routine calls. It should get the parameters in argc/argv[] format; if you don't get that way, you probably will need to write a small wrapper. The routine uses gpmi_scripts to look up the command in the command hash table and calls the command's c routine.

When you finished with this file, edit the .h file too, export all the function headers.

5. Distributing your module and licensing

Gpmi itself is LGPL, so you can choose your module's license freely. However, if you choose your license to be GPL for example, because the linking, the host application will have to be GPL-compatible. This is a reasonable choice, just don't forget to notice your users, since they may have checked gpmi's license that would allow them to have a closed source host application.

If you could write a working module for a new script language, please send it back to us. We would like to include your module in gpmi's next release. Thank you.