How useful.  To save me a handful of quotes, I lose the ability to programmatically generate my arguments.

As I was loath to reimplement the entire library just to regain that ability, I looked for another solution.  Thankfully, I found one.

As far as I can tell, this circumvents the macro's quoting features entirely to allow me to pass in a dynamically generated symbol.  While it won't work with functions which modify the environment, it worked well in my case, and allowed me to move on to more interesting code.

                          

In the last two posts, I discussed the reason for SoLoad, and how to use it. The basic usage guide skipped a few of the more complex features in the interest of simplicity. The guide only showed how to use numeric types, and not pointers, strings, or user-defined types. Also, it didn't mention the use of loadable definition files. This post will discuss those features.

Strings

Strings in SoLoad are fairly simple to use. Any sequence of characters, separated by spaces, will be read as a string if its type says so.  To add spaces to a string, simply use quotes.  To add quotes to a string, use a backslash to escape them, and to add a backslash, use two backslashes.  Strings in SoLoad look pretty much like standard C strings.

Say that we have a hypothetical "message" function, which we want to load from a library and use.  It takes a string (char*) as an argument, and puts it in a message box.  It has no return value.

Loading this function is simple.  It looks like

(

is also acceptable)

Calling it is just that simple, too.  For a single word output, you can just say

and get "Hello" as a message. Quotes are needed if we want to use spaces in the string:

And quotation marks can be escaped with a backslash:

Pointers

Using pointers in SoLoad is very simple.  If all you need to do is to call functions that return pointers, and pass those values to other functions, you can just do that.

If you want to be able to create new pointers or get their values, however, there are a few new commands to master.

type

The

command registers a new type with SoLoad.  It has pretty much the same syntax as the argument part of loading a function.

new

The

command creates an instance of a type in memory, and returns a pointer to it.

value

The

command returns the values contained in a struct at the specified address.

delete

The

command frees the struct at the given address.

deltype

The del

command deletes a type that was already registered with SoLoad.  WARNING: Doing this will probably make SoLoad unable to delete remaining instances of this type.

Def Files

All of the commands for opening a library and loading functions work well enough for one-shot uses, but they can get a little tedious when loading an entire library.  Also, I think that bindings developed for SoLoad should easily be usable by any program that uses SoLoad.  I intend to provide this functionality through loadable definitions files. These files are simply text files that list various bits of information necessary to load a library and its functions.  They are incapable of deleting data, they can only open libraries, load functions, and define types.  They look like this:

name sdl
paths /usr/lib/libSDL.so /usr/lib/SDL.so /usr/local/lib/libSDL.so
function SDL_Init int 1 uint32
function SDL_Quit void 0
function SDL_SetVideoMode pointer 4 int int int uint32
function SDL_WM_ToggleFullScreen int 1 pointer
type struct_one 2 int int
type struct_two 2 int string

The "name" statement declares a short name for the library.

The "paths" statement lists paths that the library might be found at.  They will be tried one at a time in order until one is opened successfully.

The "function" statement loads a function from the library.  "function ..." is equivalent to "load <short-name> ..."

The "type" statement does the exact same thing as the "type" statement does in interactive mode.

And that concludes the intermediate level usage tutorial for SoLoad.  It should now be possible for you to load and use any kind of function that SoLoad supports.  You should also be able to interact with structures, pointers, and strings.  In the next (and probably final) post in this series, I will detail the process of creating an FFI library for a dialect of Scheme (just as soon as I get around to writing the library myself).

                          

After much editing down, I ended up with this tutorial, which is much easier to read.

The SoLoad Foreign Function Server is a program that allows interpreters and scripting languages to call C functions.  The only requirements for use are those necessary to start a process and communicate with it.

Previously, I explained the need for and the purpose of SoLoad.  In this post, I will explain how it is used in a command-line session.

Starting

SoLoad has, at the time of this writing, two methods of communication with the outside world.  It can talk over the standard input/output streams, and via TCP.  To start SoLoad and control it over stdin, use the command

Similarly, to use it over TCP, just say

Once you have connected to the port via telnet, there should be no further differences between the different communications methods.

Opening a Library

To open a library, use the

command.  The

command takes one or two arguments.  The first is the path to the library, and the second is an optional short name for the library.  If provided, this short name can be used interchangeably with the library identifier that is returned by the command.

For the purposes of this example, we will try to open the

shared library.  I assume that the path to it is "/lib/libm.so.6" . If it is different on your system, the command will need to be modified accordingly.

So, to open the libm library, the command goes

This opens the library and assigns it a short name of "libm".

Loading a Function

Loading a function from a library is done with the

command.  The load command takes as its arguments: a library identifier, the name of the function to be loaded, the return type, the number of arguments to the function, and the types of all the arguments.  For our purposes, the command will look like

If, however, we had opted not to provide a short name for the library when opening it, the call would probably look something more like

Calling a Function

To call a function, use the

command takes a function identifier, and a number of arguments.  For us, it will look like

and will return the result of the call.

Exiting

To exit, simply type

.  Everything should automatically be unloaded, and SoLoad will close.

Cleanup (Optional)

The following functions don't usually need to be used.  They are provided simply because doing so adds barely any complexity to the program, and allows use in situations where libraries must be continually loaded and unloaded without exiting, and without filling up all available memory with old library references.

Again, SoLoad will automatically do this cleanup when it exits, so you are free to just quit now if you wish.

To unload a function, use the

command.  It takes a function identifier as its only argument.  It would look like

Similarly, to close a library, simply say

The library is closed, and functions loaded from it are no longer valid. (Note: Closing a library does not automatically unload all of its functions, but those functions will still be unloaded at exit)

A More Complex Example

The following is a transcript of a simple interaction with the SDL library.  SoLoad will be used to open SDL, create a window, and then quit.

> soload stdin
> open /usr/lib/libSDL.so sdl
0x9fd7058
> load sdl SDL_Init int 1 uint32
0x9fd7be8
> load sdl SDL_SetVideoMode pointer 4 int int int uint32
0x9fd7bc8
> load sdl SDL_Quit void 0
0x9fd7d88
> call SDL_Init 0
0
> call SDL_SetVideoMode 640 480 16 0
0xa004998
> call SDL_Quit
@�
> exit
exit

Stay tuned for the next post in the series, in which I will discuss intermediate level usage (structs and strings).

                          

So this here is my attempt to share what I've learned over the past few days with regards to syntax-rules macros.  Bear in mind that at the time of writing this, I have known how to use syntax-rules since yesterday, but my knowledge seems to be complete enough to write a working module system, so here's my attempt to pass on what I've learned.

First things first.  You use define-syntax to create a top level binding, and let-syntax bears the same relationship to define-syntax as you'd expect.

That much is pretty clear from reading R5RS, now we need to figure out how to write the syntax transformer.  There are a few ways to do this, but the best way for beginners is to use syntax-rules, which avoids inadvertent variable capture and other such nasties automatically, and uses a rather elegant pattern matching language.

We'll start by trying to write a simple macro, while. This will just be a standard looping construct that keeps executing over and over until its condition becomes false.  We want its usage to look something like this:

So first, we need the define-syntax form.

Next, we need to write the syntax transformer itself.  This is where syntax-rules comes into play.  Syntax-rules uses pattern matching and text substitution to allow you to make some pretty advanced macros.  It looks like:

I will explain keywords later.  For now, just leave that bit blank.  What we're interested in are those ((<pattern>) <template>) pairs.  Each <pattern> is just that, a pattern of code that will be matched.  In our case, we want to match the pattern:

Where the '...' signifies that body may contain one or more forms. Luckily for us, this is exactly the syntax that syntax-rules wants to see, so we can just plug it in, giving us:

So far so good.  Now we just have to fill in the other half, with a suitable <template>

Before we can write the <template>, though, we have to decide what we want the code to end up looking like.  Since this isn't a guide to scheme code in general, I'll just go ahead and say that we want the output to look like:

Got that?  Okay, now we've just got to put this in our syntax-rules macro as a template.  By another startling coincidence, this is exactly what the template code is expected to look like.  We just plug in that code, and our final result is:

Just plug that into your scheme interpreter, and our while loop from earlier should execute perfectly.

Now let's try to write something a little more complicated.  We want to write a for loop similar to the one that Python has.  This should be a pretty easy task, since it's basically just syntactic sugar for scheme's map function.

Our goal is to be able to write a piece of code taking the form:

And have it expand to:

Our first try would probably look something like this:

This works, but there's one issue with it.  All of the following are valid and work exactly the same:

This is not so much of a problem in the case of a for loop, but what if you wanted to add another rule later, so that

will also work? The solution to this problem is in that <keywords> argument that we glossed over earlier.  Change the keywords list to include 'in' (and, for good measure, 'as'), and it will allow those symbols, and only those symbols, in places where they are mentioned.  This change leaves us with:

Or, for simplicity (thanks to Dan Prager for pointing this out)

And if we load this code into our scheme interpreter of choice, we should have two fully functional little bits of new syntax.

Hopefully this guide will help shed some light on the arcane subject that is the Scheme macro system, and hopefully I will never have to learn enough about syntax-case to write a tutorial on it.