

Here is the terse, brief, and only documentation of sbl's dynamic module
handling. It works like this: when you load a file using the Use directive,
sbl will do one of two things. If its extension is .sbl, it will load into
your program as code. No surprises there. However, in any other case, it
passes it off to a specialized parser that will load modules from external
libraries.

Any libraries you're planning on using should be compiled as standard dynamic
libraries. Or, just about anything dlopen can understand. The first thing to
do is write the code: all functions must be of the same type: returning int,
no functions. Any attempt at passing values through the functions in structs
or other complex data structures would be tricky, complex, and, in all
probability, nonfunctional.

In functions, you can manipulate the stack in the same way as any sbl
function: the following functions are available to you:

	long popn(void);         Returns one integer off the stack
	void pushn(long);        Pushes an integer onto the stack
	double popf(void);       Returns one float off the stack(double, really)
	void pushf(double);      Pushes a float(double, really) onto the stack
	int pops(char *);        Pops a string and places it int the passed buffer
	int pushs(char *);       Pushes the string in the passed buffer

All strings are standard C null-terminated. All math is long or double.

Once you have written and compiled your library, you then have to write a
description(.sbe) file for it. It consists of a number of lines, in the format

library-name library-function sbl-name

Blank lines are ignored and comments begin with # and must start in the first
column. For each line, sbl looks in the specified library, which must be an
absolute path, recalls the specified library-function, stores a reference to
it and, finally, puts the value of that reference in the string variable
dl_sbl-name.

To call a function from sbl, use the syntax ':dl_name ; launch': it will recall
the proper reference number, convert it to integer, and launch it. You will
probably want to stick it in a function somewhere for clarity.

If you want to see a real example, look at bitflip.sbe for the library
description, bitflip.c for the source, and bitflip.sbl for the wrapper
functions. To compile it, use 'make bitflip.o' and to use the library, use 'Use
Bitflip.sbl' in your programs. The three functions are tile, which tiles a 
string n times, interleave, which interleaves two strings, and fill, which
fills a string with a character.

And, of course, if you have any problems, please email me.

	Jonathan Westhues
	offnet@golden.net
