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:
- 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]
- Text (string) based interface. You must be able to pass arguments
in text format for your script. [gpmi_scripts]
- You must be able to inject script lines. Mostly it means calling
subroutines of the script. [gpmi_scripts]
- 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.