Tutorial

Spud Script Quick Start

Spud Script uses a single class to create a script an run, which can be found in SScript.hpp. To create a script, create a new SScript object and call loadScript() with the only argument being the code you want it to contain.

SScript script;            
script.loadScript("int a; a = 2 * 4;");

Then to execute the code, call execute()

script.execute();

execute() will call any code that is not in a function, anything declared outside a function is in the global scope and can be used in any function after the script is run once. The code above declares an integer and assigns it a value of 8. If you want to get this value in C++, provided a is in the scope, you can call getScriptValue().

int a = *script.getScriptValue<int>("a");

The template is the return type. If the script variable is not of the type that was specified, a cast will be attempted. If the cast fails, a std::runtime_error will be thrown.

If we want to create an object in C++, we can expose it to the global scope in script with the following code:

int exposed = 25;
script.exposeVariable<int>(&exposed, "exposed");

The template for exposeVariable() is the C++ type of the object and the parameters are the address of the object and the second parameter is the name in script of the object. This will expose the actual C++ object, so if it goes out of scope the script variable will point to a bad piece of memory. Any changes made to an object that is exposed in script will be applied to the original C++ object. If we wanted to use this in script, we could simply do something like:

int double_exposed = exposed * 2;

Types

A few default types are exposed to Spud Script by default. This include int, float, double, etc.. Strings are a bit special. They are stored as char arrays, so any C++ operation with them should be done with char*. To create a string in script, the following can be done:

string s = "A string!";

To expose a new type to C++, the macro EXPOSE_SCRIPT_TYPE can be used. This declares a boolean so it can be used outside of a function in a .cpp file to execute when the program first runs. To expose members of an already exposed class, the EXPOSE_SCRIPT_MEMBER macro is used.

struct cppClass {

    int member = 25;

}

EXPOSE_SCRIPT_TYPE(cppClass)
EXPOSE_SCRIPT_MEMBER(cppClass, member, int)

int main(int argc, const char* argv[]) { 
 ...

EXPOSE_SCRIPT_MEMBER takes the exposed type as the first argument, the C++ identifier of the member and the member type.

Functions

Functions in Spud Script are almost the only deviation from C and C++ syntactically. Functions are declared with the func keyword. A return type is not specified.

func test(int a, int b) {

    // function body

    // A function can have a return value in one branch, all branches or none at all
    return value;

}

C++ functions can also be exposed to script with a few macros. Both declare new bools so they can be used outside of a function in a .cpp file.

void cppFunction(int a) {...}

EXPOSE_FUNC(script, cppFunction, void, int)

The arguments to EXPOSE_FUNC are the script that you want to expose the function to, the function itself (currently must be static, member functions are coming), the return type and the function arguments, separated by spaces. A call to EXPOSE_FUNC for a function with more arguments and an int return type would be:

EXPOSE_FUNC(script, cppFunction1, int, int float)

Functions with no arguments can be exposed in two ways, both will achieve the same result:

EXPOSE_FUNC(script, cppFunction2, int, )
EXPOSE_FUNC_NO_ARGS(script, cppFunction2, int)

There is an exception to the function macros. If a string is used as an argument or as the return type, char* is replaced with string. A call to EXPOSE_FUNC_NO_ARGS with a string as the return type would look like this for example:

char* cppFunction3() {...}
EXPOSE_FUNC_NO_ARGS(script, cppFunction3, string)

Syntax

Spud Script is almost identical syntactically to C and C++. There are a few exceptions:

• If, else, for loops and while loops must all ALWAYS have brackets to declare a block.
• ++ and -- do not currently exist. Instead use something like i = i + 1;

Example

There is a full example program and accompanying example script in the example folder. This demonstrates exposing functions of various types, exposing a class and a member, loading a script from a file, creating an object and exposing it to script, executing a script and getting a global object into C++ from script