up | next

Using the Saquen library

Overview of the communication model
Using the compile time library
Using the run time library
Customization
Namespace footprint

Overview of the communication model

The basic unit of scripting is a clump. Each clump has its own global (and persistent) variables and its own set of functions which can be run. At compile time, each clump is individually compiled and saved to disk. Clumps at runtime represent seperate instances of a ModelClump.

The method of communication with a clump is very simple. The communication is seperated into messages. Each message consists of a string representing the entrypoint that is targetted and a vector of strings representing whatever custom data you wish to be transmitted to the script.

Each clump can have any number of functions. Some of these functions can be set up as entrypoints. An entrypoint function can be thought of as 'main()' in a normal c program. The only difference is that more than one of these can be created. The name of the entrypoint is simply the name of the function.

Scripts have two methods of responding to your program. First, they can return values from entrypoints (not implemented). Second, scripts can call a custom api that you can define.

Saquen uses function-objects (aka functors or visitors) to allow you to specify a custom api for the scripts. After registering your functors, the library will link any scripting calls with those names to your customized functions.

Using the compile time library

Basic procedure

  1. Create a 'CompileClump' object.
  2. Run the compile() member function. There will be an exception if a compile error is detected.
  3. Save the compiled script to disk with the save() member function.

class CompileClump in detail:

size_t CompileClump::census(void) const;
This function returns the size in bytes that will be outputted to a file (or other stream, see 'Customization->Saving and Loading' for more details). This is to facilitate file indexing if desired. census() will return 0 if no file was compiled. (This function has not been implemented)

void CompileClump::compile(const char* source, size_t sourceLength);
void CompileClump::compile(const std::string& source);
These functions are interchangeable. Each takes a string as input and attempts to compile it into a byte code for the runtime. This will throw an exception of type CompileError if there was an aberration detected in the source string. Note that semantic checking and error messages are not yet implemented.

void CompileClump::save(OutStream& runFile) const;
The OutStream type is std::ofstream by default.

Note that as of this writing, assignment and copy construction have not been implemented.

class CompileError in detail:

Note that there are methods in CompileError not covered here that are used internally.

const std::string& CompileError::what(void) const;
This function returns a string describing what the problem with the input was. The message does not contain any specific information about the other particulars of the problem.

int32 where(void) const;
This function returns the line number where the error occurred.

const std::string& CompileError::who(void) const;
This function returns any identifiers associated with the problem. For instance, if the problem was an undeclared identifier, then this function would return that identifier.

Using the run time library

Basic Procedure

  1. Load a previously compiled clump from disk into a ModelClump
  2. Create a Clump and set its model to that ModelClump
  3. Call the addMessage() member of Clump to specify which entrypoint and what data to send it
  4. Call processMessage() in Clump to execute the script.

class ModelClump in detail:

ModelClumps can be copied and assigned. But these operations do not change which Clumps are bound to them. For mor information about this, see class Clump

ModelClump::ModelClump(InStream& input);
This allows byte code to be loaded into the model on construction. This is the same as creating the ModelClump and calling load() later.

void ModelClump::load(InStream& input);
Load the model from a stream. The data in the stream should have been emitted by a CompileClump class. Note that the InStream type defaults to std::ifstream. If you wish to change this, see Customization->Saving and Loading. A ModelClump should load data from disk before being used to create any Clump.

Customization

Making your own api

Saving and loading

Keeping data with scripts

Namespace Footprint

The saquen library was designed to have a very small namespace footprint. All identifiers except those listed here are defined within the namespace 'saquen'. Therefore, be sure to use the proper syntax when using them. Avoid all of the symbols listed here as they are generally #defined and therefore much badness could result.

saquen -- the name of the general namespace

Bison Defined:

Defined macro guards:

up | next