It Seemed Like A Good Idea, At The Time

This is the third post in a series or four. It comes after Introduction and Basic Usage.

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

load <library> message void 1 string

(load <library> message void 1 char* is also acceptable)

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

call message Hello


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

call message "Hello, world!"

And quotation marks can be escaped with a backslash:

call message "\"Hello, world!\", he said."

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.

> call get_pointer 37
0x2364DADB
> call get_value 0x2364DADB
37

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 type command registers a new type with SoLoad.  It has pretty much the same syntax as the argument part of loading a function.

type aType 2 int string

new

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

> new aType 37 "Hello, World!"
0x253DB25A

value

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

> value aType 0x253DB25A
37 "Hello, World!"

delete

The delete command frees the struct at the given address.

delete aType 0x253DB25A

deltype

The deltype 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.

deltype aType

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).