Quirrel bindings

Guide in bindings

Not full guide but some brief introduction. To get deeper into bindings you need to study samples or read the code of SqRat

Sqrat is a C++ binding library designed for the Quirrel scripting language. Sqrat simplifies the process of exposing C++ functions and classes to Quirrel scripts. It automates type conversion between C++ and Quirrel, making it easier to register functions, methods, and classes without needing to manually handle the Quirrel stack in every case.

Example

Basic Includes

#include <sqrat.h>
#include <sqModules.h>

Create a module

SqModules allows to export Quirrel objects (usually tables and classes) as script modules. Example of module creation:

Sqrat::Table exports(vm); // Create a table to hold the exported functions and classes
exports
  .Func("function_name", function) // Export a C++ function with automatic handling of arguments and return values
  .SquirrelFuncDeclString(add, "add(a: int, b: int): int", "Returns the sum of two integers, optional string")// Export a C++ function that works with the Quirrel stack, fully documented
  .SquirrelFunc("function_name", low_level_function) // Export a C++ function that works with the Quirrel stack
  .SetValue("SOME_ID", value) // Exports is a table, so it can hold any Quirrel value
;
module_manager->addNativeModule("module_name", exports); // Expose the table as a module to the Quirrel scripts

Simple bind of cpp function

You can use Sqrat::Table::Func() or Sqrat::Class::Func() to register a C++ function for use in a Quirrel script. Sqrat automatically handles argument and return value conversions between Quirrel and C++ types.

C++:

Sqrat::Table exports(vm);
exports.Func("pow", &std::pow);  // Register pow function in the script
module_manager->addNativeModule("math_demo", exports);

Usage in Quirrel:

from "math_demo" import pow
// or
let { pow } = require("math_demo")

local result = pow(2, 3)  // Calls the C++ std::pow(2, 3)
print(result)  // Output: 8

Bind function that works with Quirrel stack

For more control, you can manually handle the Quirrel stack by using SquirrelFunc. This allows you to specify custom logic for processing function arguments and returning values. For instance, you may need this for variadic functions, arguments of varying types, or functions with complex logic that can’t be automatically bound.

SQInteger sum_all_args(HSQUIRRELVM v) {
    SQInteger n = sq_gettop(v); // Number of arguments
    SQFloat sum = 0;
    for (SQInteger i = 2; i <= n; ++i) { // Sum all arguments, starting from 2 (#1 is `this`)
        SQFloat val;
        if (SQ_SUCCEEDED(sq_getfloat(v, i, &val))) // For demo purposes, we only handle numbers and ignore other types
            sum += val;
    }
    sq_pushfloat(v, sum); // Push the result
    return 1; // Number of return values (0 for void, 1 for return value, SQ_ERROR for error)
}

exports.SquirrelFunc("sum_all_args", sum_all_args, -2);  // -2: variable arguments, at least 2 (`this` and a number

In script:

local result = sum_all_args(1, 2, 3, 4)  // Calls the C++ function
print(result)  // Output: 10

Full signature of SquirrelFunc:

TableBase &Table::SquirrelFunc(const SQChar *name, SQFUNCTION func, SQInteger nparamscheck, const SQChar *typemask = nullptr, const SQChar *docstring = nullptr, SQInteger nfreevars = 0, const Object *freevars = nullptr)
Parameters
  • name – should be string, func should be function that works with Quirrel

  • nparamscheck – number of arguments of function. If negative - function can have at least this number of arguments but can accept more.

  • typemask – optional typemask (see sq_setparamscheck in API)

  • docstring – optional docstring, nfreevars and freevars - free variables of function.

  • nfreevars – number of free variables

  • freevars – free variables to capture

Remarks

The typemask is a string that represent the expected parameter type. The types are expressed as follows: ‘o’ null, ‘i’ integer, ‘f’ float, ‘n’ integer or float, ‘s’ string, ‘t’ table, ‘a’ array, ‘u’ userdata, ‘c’ closure and nativeclosure, ‘g’ generator, ‘p’ userpointer, ‘v’ thread, ‘x’ instance(class instance), ‘y’ class, ‘b’ bool. and ‘.’ any type. The symbol ‘|’ can be used as ‘or’ to accept multiple types on the same parameter. There isn’t any limit on the number of ‘or’ that can be used. Spaces are ignored so can be inserted between types to increase readability. For instance to check a function that expect a table as ‘this’ a string as first parameter and a number or a userpointer as second parameter, the string would be “tsn|p” (table,string,number or userpointer). If the parameters mask is contains fewer parameters than ‘nparamscheck’, the remaining parameters will not be typechecked.

The preferred method for binding C++ functions that work with the Quirrel stack is to use .SquirrelFuncDeclString. This declarative method allows you to specify the function signature, argument types (including optional/default values), return type, and documentation string all in one place.

Example:

.SquirrelFuncDeclString(
    do_math,
    "pure do_math(a: int, [b: number = 2]): float",
    "Performs math operation. Optional argument 'b' defaults to 2."
)

This approach allows the engine to: - Parse argument types and generate typemasks for type checking - Reflect metadata for documentation and scripting tools - Recognize pure functions for optimization

Why use SquirrelFuncDeclString?

  • Declarative: Full signature, types, defaults, and docstring in a single place.

  • Robust: More accurate binding and automatic validation.

  • Documentation-friendly: Signature and docs are automatically extracted.

Deprecation Notice:

The older .SquirrelFunc macro is now deprecated. It required manually handling arguments from the Quirrel VM stack, which is more error-prone and lacks reflection support. Always prefer `.SquirrelFuncDeclString` for new bindings.

Bind classes, constants and values

Sqrat allows to register C++ classes with member variables and methods that can be accessed from Quirrel scripts.

Toy example:

class Rect {
  public:
    float width, height;
    Rect(float w, float h) : width(w), height(h) {}
    float area() const {
        return width * height;
    }
    float perimeter() const {
        return 2 * (width + height);
    }
};

Sqrat::Class<Rect> rectClass(table.GetVM(), "Rect");
rectClass
  .Ctor()
  .Var("width", &Rect::width)
  .Var("height", &Rect::height)
  .Func("area", &Rect::area)
  .Prop("perimeter", &Rect::perimeter)
;

exports.Bind("Rect", rectClass);  // Bind the class to the table
module_manager->addNativeModule("geometry", exports);

In script:

from "geometry" import Rect
local r = Rect(1, 3)
r.width = 2
print(r.area())  // Output: 6
print(r.perimeter)  // Output: 10

SquirrelCtor() may be used for a constructor with a flexible behavior. It has to implement an actual native instance creation.

Example:

static SQInteger rect_ctor(HSQUIRRELVM v) {
    SQInteger n = sq_gettop(v);
    if (n == 2) { // copy constructor
      if (!Sqrat::check_signature<Rect *>(vm, 2))
        return sq_throwerror(vm, "Invalid type passed to copy ctor");
    }
    else if (n != 1 && n != 3)
      return sqstd_throwerrorf(vm, "Invalid arguments count %d", n);

    Rect *instance = new Rect(0, 0);
    if (n == 1) // no arguments
      ; // already initialized with default 0, 0
    else if (n == 3) { // instance and 2 numbers
      SQFloat w, h;
      sq_getfloat(v, 2, &w); // Should always succeed, because types are specified in type mask (see SquirrelCtor)
      sq_getfloat(v, 3, &h);
      instance->width = w;
      instance->height = h;
    }
    else if (n == 2) { // copy constructor (self instance and another instance)
      Rect *other = Sqrat::Var<Rect *>(vm, 2).value;
      instance->width = other->width;
      instance->height = other->height;
    }
    Sqrat::ClassType<Rect>::SetManagedInstance(vm, 1, instance); // Link with script instance
    return 1;
}

Sqrat::Class<Rect> rectClass(table.GetVM(), "Rect");
rectClass
  .SquirrelCtor(rect_ctor, 0, "x y|n n") // 0 - no argument count check, "x y|n n" - type mask (instance('this') and instance or 2 numbers)
  .Var("width", &Rect::width)
  .Var("height", &Rect::height)
  .Func("area", &Rect::area)
  .Prop("perimeter", &Rect::perimeter)
;

In script:

from "geometry" import Rect
local r1 = Rect(1, 3)
local r2 = Rect(r1)
local r3 = Rect()

Consttable - not documented

Class property (setter) - not documented

Static functions - not documented