From sol2 (Lua) Bindings​

sol2 binds C++ to Lua with a few calls on a sol::state: new_usertype for a class, set_function or a table assignment for a function or a value, a protected_function to call back. JaiScript covers the same ground with a fluent dynamic_binder per class and plain engine calls, and a sol2 host converts mostly line for line.

The larger change is in the script. JaiScript is not a table language: arrays and maps are values that copy on assignment, indexes start at 0, / between integers truncates, and 0 is false (Lua habits). The binding API is documented in Embedding Quickstart and dynamic_binder.

The concept map​

Headers: <jaiscript/jaiscript.hpp> for the engine, values and binders, and <jaiscript/stdlib/stdlib.hpp> for the standard library.

State and scripts​

Functions​

Usertypes​

Values​

Calls into script and errors​

A host converted​

The GLOOM host that From ChaiScript converts also has a Lua adapter on sol2. Its bindings follow the tables above (the usertype below shows every kind); a script int is an int64_t (jai::script_int), so the host's 64-bit random state crosses whole, as it does through a Lua 5.4 integer. Loading the game and calling into it:

lua["package"]["path"] = dir + "/?.lua";
sol::protected_function_result result = lua.safe_script_file(dir + "/main.lua", sol::script_pass_on_error);
if (!result.valid()) { sol::error err = result; throw std::runtime_error(err.what()); }

sol::protected_function frame = lua["gloom_frame"];
sol::protected_function_result out = frame(dt, key, fps, ms_sim, ms_draw);
if (!out.valid()) { sol::error err = out; throw std::runtime_error(err.what()); }
std::string text = out.get<std::string>();

eng->add_include_path(dir);
eng->execute("import \"main.jai\";");

jai::script_value frame = eng->get_variable("gloom_frame");
jai::checked_result<jai::script_value> out = frame.as_function()({
    eng->make_value(dt), eng->make_value(key), eng->make_value(fps),
    eng->make_value(ms_sim), eng->make_value(ms_draw)});
if (!out) { throw std::runtime_error(eng->format_error(out)); }
std::string text = out.value().as_string();

The engine is ready for the next call after a failed one, as a Lua state is after a protected call. A host that would rather throw converts the function once with jai::convert_script_function, like sol2's conversion to a std::function.

A usertype in full​

The Entity and Monster classes of From ChaiScript (two constructors, an overloaded method, a getter and setter pair, a read-only property, an operator, a base class), bound with sol2:

lua.new_usertype<Entity>("Entity",
    "name", &Entity::name,
    "describe", &Entity::describe);

lua.new_usertype<Monster>("Monster",
    sol::constructors<Monster(), Monster(std::string, int64_t)>(),
    sol::base_classes, sol::bases<Entity>(),
    "damage", sol::overload(
        static_cast<void (Monster::*)(int64_t)>(&Monster::damage),
        static_cast<void (Monster::*)(int64_t, double)>(&Monster::damage)),
    "alive", &Monster::alive,
    "hp", sol::property(&Monster::health, &Monster::setHealth),
    "maxHp", sol::readonly_property([](const Monster&) { return int64_t{100}; }),
    sol::meta_function::equal_to, &Monster::operator==);

lua.set_function("label", sol::overload(
    [](int64_t n) { return std::string("int ") + std::to_string(n); },
    [](const std::string& s) { return std::string("string ") + s; }));

The JaiScript binder for the two classes is the one on that page, entry for entry, and label is two add_function calls under one name. The same session in each language:

local m = Monster.new("ogre", 30)
m:damage(5)
m:damage(10, 1.5)
m.hp = m.hp - 100
print(m.name .. " hp=" .. m.hp .. " alive=" .. tostring(m:alive()) .. " max=" .. m.maxHp .. " " .. m:describe())
print(label(3) .. " / " .. label("x") .. " / " .. tostring(Monster.new("a", 1) == Monster.new("a", 1)))

var m = Monster("ogre", 30);
m.damage(5);
m.damage(10, 1.5);
m.hp -= 100;
print(m.name, " hp=", m.hp, " alive=", m.alive(), " max=", m.maxHp, " ", m.describe());
print(label(3), " / ", label("x"), " / ", Monster("a", 1) == Monster("a", 1));

ogre hp=0 alive=false max=100 monster ogre
int 3 / string x / true

sol::constructors makes a value userdata, which a C++ function taking std::shared_ptr<T> cannot share, so a sol2 host binds such a type with sol::factories returning std::make_shared. In JaiScript the constructor list serves both: Monster(...) is a value, new Monster(...) is a shared_ptr handle.

Lua habits that get a different answer​

JaiScript's semantics are C++'s, so most Lua habits that change are the ones a JavaScript programmer meets too: see From JavaScript and Value Semantics & References. The spellings:

Arrays and maps are values​

In Lua, b = a makes a second name for one table. In JaiScript, assignment copies an array or a map, as passing one by value does; a reference declaration (auto&), a reference parameter or a shared_ptr shares one:

array<int> a = [1, 2, 3];
array<int> b = a;                  // a copy, where Lua's b = a shares the table
b[0] = 99;
map<string, int> stats = {"hp": 10};
auto copy = stats;
copy["hp"] = 0;
auto& alias = stats;               // a reference names the same map
alias["hp"] += 5;
print(a[0], " ", b[0], " ", stats["hp"], " ", copy["hp"]);

1 99 15 0

Indexes start at 0​

The first element is [0] and the last is [size() - 1]. Reading past the end is an error (Array index 3 out of bounds for array of size 3), where Lua returns nil.

Division follows the operand types​

Lua's / always produces a float (7 / 2 is 3.5) and // floors. In JaiScript, / between two integers truncates toward zero, as in C++ (7 / 2 is 3, -7 / 2 is -3), and a float operand makes it float division (7.0 / 2 is 3.5). % takes the sign of the left operand (-7 % 2 is -1), where Lua's takes the sign of the right (1).

0 and the empty string are false​

Lua treats every value but nil and false as true. JaiScript tests a value the C++ way: 0, the empty string and null are false, so if (count) skips a zero count.

Names are declared, and checked before anything runs​

A Lua assignment to an unknown name creates a global, and a misspelled read is nil. JaiScript declares every name; a program-scope declaration is the global, and the checker rejects an undeclared name, a wrong argument count or a mismatched typed value before the first statement runs (Strict checking). Names the host registers before the script loads are visible to the checker.

Integers do not wrap​

Lua 5.4 integers wrap around (math.maxinteger + 1 == math.mininteger). A JaiScript int is the same 64 bits, but an operation that overflows it raises a catchable error, Integer overflow in '+' (Checked overflow); math::wrap_add and its siblings wrap on purpose.

Coroutines​

Coroutines covers the script side of what Lua does with coroutine.wrap, and From Lua Coroutines the conversion.