[gephex-devel] gephex interface definition language

[Georg Seidel]

Since I used it in my last posting, I think it would be good to describe 
the gephex interface definition language (gidl) that is used by pluc and 
idlc.


0. Introduction
-----------------

gidl is designed to be simple and easy to parse. It is loosely based on
C, C++ and Java but much more restrictive.

Methods and functions are the central part of the gidl. They are 
normally grouped into interfaces, but I will omit that here.


1. Constructors and destructors
--------------------------------

The CF grammar rule for constructors is:

    CDTOR_FUN ->   IDENTIFIER "(" PARAM_LIST ")" ":" "constructor" ";"
                 | IDENTIFIER "(" PARAM_LIST ")" ":" destructor" ";"

(IDENTIFIER is the same as identifiers in C).

The rule for parameters (which is used by methods and functions as
well):

    PARAM_LIST ->  epsilon
                 | PARAM "," PARAM_LIST

(epsilon is the empty production)

    PARAM -> PARAM_PREFIX TYPE IDENTIFIER

    PARAM_PREFIX -> "in" | "out"

    TYPE ->   TYPE_NAME
            | BUILTIN_TYPE
            | "ptr" BUILTIN_TYPE

Where TYPE_NAME is an identifier that starts with a uppercase letter
and BUILTIN_TYPE are types like "int", "int32", "char".


2. Methods and functions
-------------------------

    FUN -> RETURN_TYPE IDENTIFIER "(" PARAM_LIST ")" ":"  FUN_SPEC ";"

    RETURN_TYPE -> TYPE | "void"

    FUN_SPEC -> "const method" | "method" | "function"


3. Examples
------------

So let's see some examples. I will show you some methods, functions, 
ctors and their equivalent in c++. Assume that we are inside of the
declaration of class Foo.


  *  "ptr char get_spec()               : function;"
     will translate to
     "static char* get_spec();"

(the fact that it is a function and not a method is translated to the 
"static" keyword)

  *  "ptr char serialize()              : const method;"
    will translate to
     "char* serialize() const;"

  *  "destroy_instance()                : destructor;"
    will translate to
     "~Foo();"

  *  "new_instance()                    : constructor;"
    will translate to
     "Foo();"

  *  "void str_dup(out ptr char dst, in ptr char src) : function;"
    will translate to
     "static void str_dup(char** dst, const char* src);"

Note how the "out" keyword produced a non const pointer to the result of
translating "ptr char" (which is "char*").
It is not possible to use more than one "ptr" keyword for the same type,
so the "out" keyword is the only way to get this second indirection.


4. Usage inside link specs
---------------------------

When you write a spec for a link (to be used by pluc), you have to
provide the signature of any extra functions your link will have.
This signature is specified in gidl.
Here is an example of a link spec:

<<
link number
{
   author      = "Georg"
   version     = "1.0"
   description = "Number Link (double precision)"
   interface   = "
     double get_value() : const method;
     void   set_value(in double newValue) : method;

     double trim_double(in double min, in double max) : const method;
     int    trim_int(in int min, in int max) : const method;
     bool   trim_bool() : const method;"
}
 >>

The additional methods are appended to the common Link interface when
the glue and wrapper code is created.


5. Details
--------------

For the details please look at the idlc subdir of gephex--main--0.5
(or even better to the 
georg at gephex.org--2004-home/gephex--georg-pluc--0.5 branch which
has not yet been merged into main, the archive location is
"http://arch.gephex.org/georg/2004-home").

The file src/idlparser.ypp contains the bison grammar for the
parser and src/idlscanner.flex contains the flex grammer
for the scanner.


Regards,

Georg