interfaces. Intgen works by scanning
.h files with special comments in
them. Intgen builds stubs that implement XLISP SUBR's. When the SUBR is
called, arguments are type-checked and passed to the C routine declared in
.h file. Results are converted into the appropriate XLISP type and
returned to the calling XLISP function. Intgen lets you add C functions
into the XLISP environment with very little effort.
The interface generator will take as command-line input:
.cfile to generate (do not include the
.cextension; e.g. write
reads sndfns.cl to get the command-line input. Only one level of indirection is allowed.
The output is:
.cfile with one SUBR defined for each designated routine in a
.hfile that declares each new C routine. E.g. if the
.cfile is named
xlexten.c, this file will be named
.hfile that extends the SUBR table used by Xlisp. E.g. if the
.cfile is named
xlexten.c, then this file is named
.lspfile with lisp initialization expressions copied from the
.hfiles. This file is only generated if at least one initialization expression is encountered.
For example, the command line
intgen seint ~setypes.h access.h
generates the file
seint.c, using declarations in
access.h. Normally, the
.h files are included by the
generated file using
#include commands. A
~ before a file
means do not include the
.h file. (This may be useful if you extend
xlisp.h, which will be included anyway). Also generated will be
Any number of
.h files may be named on the command line to Intgen,
and Intgen will make a single
.c file with interface routines for all
.h files. On the other hand, it is not necessary to put all
of the extensions to Xlisp into a single interface file. For example, you
can run Intgen once to build interfaces to window manager routines, and
again to build interfaces to a new data type. Both interfaces can be linked
To use the generated files, you must compile the
.c files and link
them with all of the standard Xlisp object files. In addition, you must
edit the file
localdefs.h to contain an
#include for each
*defs.h file, and edit the file
localptrs.h to include each
*ptrs.h file. For example, suppose you run Intgen to build
tableint.c. You would then
localdefs.h to contain the following:
#include "soundintdefs.h" #include "fugueintdefs.h" #include "tableintdefs.h"
localptrs.h to contain:
#include "soundintptrs.h" #include "fugueintptrs.h" #include "tableintptrs.h"
localptrs.h files are in turn included
xlftab.c which is where Xlisp builds a table of SUBRs.
To summarize, building an interface requires just a few simple steps:
.hfiles to tell Intgen which routines to build interfaces to, and to specify the types of the arguments.
localdefs.hto include generated
Each routine to be interfaced with Xlisp must be declared as follows:
type-name routine-name(); /* LISP: (func-name type1 type2 ...) */
The comment may be on the line following the declaration, but the
declaration and the comment must each be on no more than one line.
LISP: at the beginning of the comment mark routines
to put in the interface. The comment also gives the
type and number of arguments. The function, when accessed from lisp will
be known as func-name, which need not bear any relationship to
routine-name. By convention, underscores in the C routine-name
should be converted to dashes in func-name, and func-name should be in
all capitals. None of this is enforced or automated though.
Legal type_names are:
LVAL, but the result is expected to be an atom.
STRING. The result string will be copied into the XLISP heap.
It is easy to extend this list. Any unrecognized type will
be coerced to an
int and then returned as a
FIXNUM, and a warning will be
*” after char must be followed by routine-name with
no intervening space.
Parameter types may be any of the following:
char *, the string is not copied.
value_type. (Not applicable to Fugue.)
event_type. (Not applicable to Fugue.)
LVALwhich is a lisp atom.
FILE*, indicating C routine expects
LVAL *, or
FILE **. This is basically a mechanism for returning more than one value, not a mechanism for clobbering XLisp values. In this spirit, the interface copies the value (an
FILE *) to a local variable and passes the address of that variable to the C routine. On return, a list of resulting “
*” parameters is constructed and bound to the global XLisp symbol
*RSLT*. (Strings are copied.) If the C routine is void, then the result list is also returned by the corresponding XLisp function.
Note 1: this does not support C routines like strcpy that modify strings,
because the C routine gets a pointer to the string in the XLisp heap.
However, you can always add an intermediate routine that allocates
space and then calls
strcpy, or whatever.
Note 2: it follows that a new XLisp
STRING will be created for each
Note 3: putting results on a (global!) symbol seems a bit unstructured, but note that one could write a multiple-value binding macro that hides this ugliness from the user if desired. In practice, I find that pulling the extra result values from
*RSLT* when needed is perfectly acceptable.
For parameters that are result values only, the character “
be substituted for “
*”. In this case, the parameter is not to be passed in the XLisp calling site.
However, the address of an initialized
local variable of the given type is passed to the corresponding
C function, and the resulting value is passed back through
ordinary result parameter as described above.
The local variables are initialized to zero or
If a comment of the form:
/* LISP: type-name (routine-name-2 type-1 type-2 ...) */
appears on a line by itself and there was a
#define on the previous
line, then the preceding
#define is treated as a C routine, e.g.
#define leftshift(val, count) ((val) << (count)) /* LISP: int (LOGSHIFT INT INT) */
will implement the LeLisp function
The type-name following “
LISP:” should have no spaces, e.g. use
Include files often define constants that we would like to have around in the Lisp world, but which are easier to initialize just by loading a text file. Therefore, a comment of the form:
/* LISP-SRC: (any lisp expression) */
will cause Intgen to open a file name
.lsp and append
(any lisp expression)
.lsp, where name is the interface name passed on the command line. If none of the include files examined have comments of
this form, then no name
.lsp file is generated.
Note: the LISP-SRC comment must be on a new line.
This file was used for testing Intgen. It uses a trick (ok, it's a hack) to interface to a standard library macro (tolower). Since tolower is already defined, the macro ToLower is defined just to give Intgen a name to call. Two other routines, strlen and tough, are interfaced as well.
/* igtest.h -- test interface for intgen */ #define ToLower(c) tolower(c) /* LISP: int (TOLOWER FIXNUM) */ int strlen(); /* LISP: (STRLEN STRING) */ void tough(); /* LISP: (TOUGH FIXNUM* FLONUM* STRING ANY FIXNUM) */
Intgen has some compiler switches to enable/disable the use of certain types, including
EVENT types used by Dannenberg's score editing work, the
SOUND type used by Fugue, and
SEXT types added for Dale Amon.
Enabling all of these is not likely to cause problems,
and the chances of an accidental use of these types getting through
the compiler and linker seems very small.