The first step in composing a breve plugin is to write wrapper functions around your existing code. The wrapper functions simply act as a bridge between the internal breve function calling code, and standard C function calls. When a function is called from within steve, the wrapper function is called. The wrapper function, in turn, calls the necessary C code and coordinates input and output between the C code and the breve call.

The wrapper function passes input and output data between breve and C using a structure called brEval. The brEval struct is a C data structure which is used internally to hold the values of expressions in steve. The structure is used to hold any and all types of steve expressions. So ints, lists, objects and the rest of the steve types are all held in brEval structs. The type field of the struct specifies the type of the expression. The values union of the struct contains the actual value of the expression. Information on how to use these fields is listed below.

Wrapper functions have the following prototype:

int function(brEval arguments[], brEval *result, void *instance);

Arguments are passed in as the arguments array of brEval objects. The function output is returned by setting the contents of the brEval object pointed to by result. instance is an internal pointer to the calling instance—this can be ignored.

        // for a function returning an integer
        result->set( 10 );

        // for a function returning a string
        char *myString = "look at me, I'm returning a string!";
        result->set( myString );

        // our calculation creates a double, but we wish to return an AT_INT type to breve:
        result->set( (int)pow( x, y ) );

        // we want to return an AT_STRING type, but the value is NULL:
        result->set( (char*)NULL );

        // now we want to return an AT_LIST type, but the value is NULL:
        result->set( (brEvalListHead*)NULL );

char *downloadURL(char *url, int timeout);

int breveDownloadURL(brEval *arguments, brEval *result, void *instance) {
        char *url, *urlData;
        int timeout;

        url = BRBRRING(&arguments[0]);
        timeout = BRINT(&arguments[1]);

        urlData = downloadURL(url, timeout);

        result->set( urlData );
                
        return EC_OK;
}

Your entry point function will be called when the plugin is loaded. Its job is to tell the breve engine what new steve functions to add, their names, and the arguments they will take.

The prototype for an entry-point function is:

void entryPointFunctionName(void *data);

The name may be anything you'd like, but it must be a unique symbol.

This entry-point function will be filled with one or more calls to the function brNewBreveCall. The calling convention for this function is:

brNewBreveCall(data, "functionName", cFunctionPointer, returnType, arg1, arg2, ..., 0);

For example, if you have a function which takes two vector inputs and produces an int output, your brNewBreveCall might look like this:

brNewBreveCall(data, "mySteveFunctionName", myCFunctionName, AT_INT, AT_VECTOR, AT_VECTOR, 0);

In order to write plugins for breve, you'll first need to familiarize yourself with a feature of steve which is generally hidden from users—the C-style function call.

C-style function calls in breve work just as they do in C: they take a number of arguments and may return a value. In breve, a C-style function call is used to access code which is built into the breve engine (as opposed to code written in steve). In fact, the built-in class hierarchy provided with breve uses C-style function calls extensively to interface with the breve engine.

From the user's perspective, all computation in breve happens within objects. So when we write a plugin, we'll also give it an object interface. Here's a simple example in which the plugin simply provides some data (like a float or an int) back to the caller.

Object : mySimplePluginObject {
        + to get-input-from-plugin:
                return getPluginInput().
}

By packaging this functionality inside an object, breve users look at it as they do any other object, without needing any information about how the plugin works underneath.

The more important reason to use objects, however, is so that the plugin can be used by more than one agent simultaneously. Imagine, for example, a plugin which simulates neural networks. It's easy to imagine that a breve simulation might want to use several of these neural networks at the same time. Because the neural networking code requires a "persistent state", we would need a way to store many distinct states simultaneously.

Inside our breve object, we'll hold a pointer to C-memory representing these distinct states. Whenever a neural network function is needed, we'll pass that pointer back to the plugin so that it can operate on the correct state. Here's an example:

Object : myNeuralNetwork {
        + variables:
                networkPointer (pointer).

        + to init:
                networkPointer = newNeuralNetwork().

        + to iterate:
                neuralNetworkIterate(networkPointer).

        + to get-output:
                return neuralNetworkOutput(networkPointer).

        + to set-input to value (double):
                neuralNetworkSet(networkPointer, value).
}