asserts / prerequisites¶

You’ll need to #include <sol/sol.hpp> somewhere in your code. sol is header-only, so you don’t need to compile anything. However, Lua must be compiled and available. See the getting started tutorial for more details.

The implementation for assert.hpp with c_assert looks like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

#ifndef EXAMPLES_ASSERT_HPP
#define EXAMPLES_ASSERT_HPP

#   define m_assert(condition, message) \
    do { \
        if (! (condition)) { \
            std::cerr << "Assertion `" #condition "` failed in " << __FILE__ \
                      << " line " << __LINE__ << ": " << message << std::endl; \
            std::terminate(); \
        } \
    } while (false)

#   define c_assert(condition) \
    do { \
        if (! (condition)) { \
            std::cerr << "Assertion `" #condition "` failed in " << __FILE__ \
                      << " line " << __LINE__ << std::endl; \
            std::terminate(); \
        } \
    } while (false)
#else
#   define m_assert(condition, message) do { if (false) { (void)(condition); (void)sizeof(message); } } while (false)
#   define c_assert(condition) do { if (false) { (void)(condition); } } while (false)
#endif

#endif // EXAMPLES_ASSERT_HPP

This is the assert used in the quick code below.

opening a state¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <iostream>
#include <assert.hpp>

int main(int, char*[]) {
	std::cout << "=== opening a state ===" << std::endl;

	sol::state lua;
	// open some common libraries
	lua.open_libraries(sol::lib::base, sol::lib::package);
	lua.script("print('bark bark bark!')");

	std::cout << std::endl;

	return 0;
}

using sol3 on a lua_State*¶

For your system/game that already has Lua or uses an in-house or pre-rolled Lua system (LuaBridge, kaguya, Luwra, etc.), but you’d still like sol3 and nice things:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <iostream>

int use_sol2(lua_State* L) {
	sol::state_view lua(L);
	lua.script("print('bark bark bark!')");
	return 0;
}

int main(int, char*[]) {
	std::cout << "=== opening sol::state_view on raw Lua ===" << std::endl;

	lua_State* L = luaL_newstate();
	luaL_openlibs(L);

	lua_pushcclosure(L, &use_sol2, 0);
	lua_setglobal(L, "use_sol2");

	if (luaL_dostring(L, "use_sol2()")) {
		lua_error(L);
		return -1;
	}

	std::cout << std::endl;

	return 0;
}

running lua code¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <fstream>
#include <iostream>
#include <assert.hpp>

int main(int, char*[]) {
	std::cout << "=== running lua code ===" << std::endl;

	sol::state lua;
	lua.open_libraries(sol::lib::base);
	
	// load and execute from string
	lua.script("a = 'test'");
	// load and execute from file
	lua.script_file("a_lua_script.lua");

	// run a script, get the result
	int value = lua.script("return 54");
	c_assert(value == 54);

To run Lua code but have an error handler in case things go wrong:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

	auto bad_code_result = lua.script("123 herp.derp", [](lua_State*, sol::protected_function_result pfr) {
		// pfr will contain things that went wrong, for either loading or executing the script
		// Can throw your own custom error
		// You can also just return it, and let the call-site handle the error if necessary.
		return pfr;
	});
	// it did not work
	c_assert(!bad_code_result.valid());
	
	// the default handler panics or throws, depending on your settings
	// uncomment for explosions:
	//auto bad_code_result_2 = lua.script("bad.code", &sol::script_default_on_error);
	return 0;
}

You can see more use of safety by employing the use of .safe_script, which returns a protected result you can use to properly check for errors and similar.

running lua code (low-level)¶

You can use the individual load and function call operator to load, check, and then subsequently run and check code.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <fstream>
#include <iostream>
#include <cstdio>
#include <assert.hpp>

int main(int, char*[]) {
	std::cout << "=== running lua code (low level) ===" << std::endl;

	sol::state lua;
	lua.open_libraries(sol::lib::base);

	// load file without execute
	sol::load_result script1 = lua.load_file("a_lua_script.lua");
	//execute
	script1();

	// load string without execute
	sol::load_result script2 = lua.load("a = 'test'");
	//execute
	sol::protected_function_result script2result = script2();
	// optionally, check if it worked
	if (script2result.valid()) {
		// yay!
	}
	else {
		// aww
	}

	sol::load_result script3 = lua.load("return 24");
	// execute, get return value
	int value2 = script3();
	c_assert(value2 == 24);

	return 0;
}

You can also develop custom loaders that pull from things that are not strings or files.

passing arguments to scripts¶

Arguments to Lua scripts can be passed by first loading the file or script blob, and then calling it using sol’s abstractions. Then, in the script, access the variables with a … on the left hand side of an assignment:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <iostream>
#include <assert.hpp>

int main(int, char* []) {
	std::cout << "=== passing arguments to scripts ===" << std::endl;

	sol::state lua;
	lua.open_libraries(sol::lib::base);

	const auto& my_script = R"(
local a,b,c = ...
print(a,b,c)
	)";

	sol::load_result fx = lua.load(my_script);
	if (!fx.valid()) {
		sol::error err = fx;
		std::cerr << "failed to load string-based script into the program" << err.what() << std::endl;
	}
	
	// prints "your arguments here"
	fx("your", "arguments", "here");

	return 0;
}

transferring functions (dumping bytecode)¶

You can dump the bytecode of a function, which allows you to transfer it to another state (or save it, or load it). Note that bytecode is typically specific to the Lua version!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <iostream>
#include "assert.hpp"


int main() {
	std::cout << "=== dump (serialize between states) ===" << std::endl;

	// 2 states, transferring function from 1 to another
	sol::state lua;
	sol::state lua2;

	// we're not going to run the code on the first
	// state, so we only actually need
	// the base lib on the second state
	// (where we will run the serialized bytecode)
	lua2.open_libraries(sol::lib::base);

	// load this code (but do not run)
	sol::load_result lr = lua.load("a = function (v) print(v) return v end");
	// check if it's sucessfully loaded
	c_assert(lr.valid());

	// turn it into a function, then dump the bytecode
	sol::protected_function target = lr.get<sol::protected_function>();
	sol::bytecode target_bc = target.dump();

	// reload the byte code
	// in the SECOND state
	auto result2 = lua2.safe_script(target_bc.as_string_view(), sol::script_pass_on_error);
	// check if it was done properly
	c_assert(result2.valid());

	// check in the second state if it was valid
	sol::protected_function pf = lua2["a"];
	int v = pf(25557);
	c_assert(v == 25557);

	return 0;
}

set and get variables¶

You can set/get everything using table-like syntax.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <assert.hpp>

int main(int, char*[]) {
	sol::state lua;
	lua.open_libraries(sol::lib::base);

	// integer types
	lua.set("number", 24);
	// floating point numbers
	lua["number2"] = 24.5;
	// string types
	lua["important_string"] = "woof woof";
	// is callable, therefore gets stored as a function that can be called
	lua["a_function"] = []() { return 100; };
	// make a table
	lua["some_table"] = lua.create_table_with("value", 24);

Equivalent to loading lua values like so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

	// equivalent to this code
	std::string equivalent_code = R"(
		t = {
			number = 24,
			number2 = 24.5,
			important_string = "woof woof",
			a_function = function () return 100 end,
			some_table = { value = 24 }
		}
	)";

	// check in Lua
	lua.script(equivalent_code);

You can show they are equivalent:

1
2
3
4
5
6
7

	lua.script(R"(
		assert(t.number == number)
		assert(t.number2 == number2)
		assert(t.important_string == important_string)
		assert(t.a_function() == a_function())
		assert(t.some_table.value == some_table.value)
	)");

Retrieve these variables using this syntax:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

	// implicit conversion
	int number = lua["number"];
	c_assert(number == 24);
	// explicit get
	auto number2 = lua.get<double>("number2");
	c_assert(number2 == 24.5);
	// strings too
	std::string important_string = lua["important_string"];
	c_assert(important_string == "woof woof");
	// dig into a table
	int value = lua["some_table"]["value"];
	c_assert(value == 24);
	// get a function
	sol::function a_function = lua["a_function"];
	int value_is_100 = a_function();
	// convertible to std::function
	std::function<int()> a_std_function = a_function;
	int value_is_still_100 = a_std_function();
	c_assert(value_is_100 == 100);
	c_assert(value_is_still_100 == 100);

Retrieve Lua types using object and other sol:: types.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

	sol::object number_obj = lua.get<sol::object>("number");
	// sol::type::number
	sol::type t1 = number_obj.get_type();
	c_assert(t1 == sol::type::number);

	sol::object function_obj = lua["a_function"];
	// sol::type::function
	sol::type t2 = function_obj.get_type();
	c_assert(t2 == sol::type::function);
	bool is_it_really = function_obj.is<std::function<int()>>();
	c_assert(is_it_really);

	// will not contain data
	sol::optional<int> check_for_me = lua["a_function"];
	c_assert(check_for_me == sol::nullopt);

	return 0;
}

You can erase things by setting it to nullptr or sol::lua_nil.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <assert.hpp>

int main(int, char*[]) {
	sol::state lua;
	lua.open_libraries(sol::lib::base);

	lua.script("exists = 250");

	int first_try = lua.get_or("exists", 322);
	c_assert(first_try == 250);

	lua.set("exists", sol::lua_nil);
	int second_try = lua.get_or("exists", 322);
	c_assert(second_try == 322);

	return 0;
}

Note that if its a userdata/usertype for a C++ type, the destructor will run only when the garbage collector deems it appropriate to destroy the memory. If you are relying on the destructor being run when its set to sol::lua_nil, you’re probably committing a mistake.

tables¶

Tables can be manipulated using accessor-syntax. Note that sol::state is a table and all the methods shown here work with sol::state, too.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <assert.hpp>

int main(int, char*[]) {

	sol::state lua;
	lua.open_libraries(sol::lib::base);

	lua.script(R"(
		abc = { [0] = 24 }
		def = { 
			ghi = { 
				bark = 50, 
				woof = abc 
			} 
		}
	)");

	sol::table abc = lua["abc"];
	sol::table def = lua["def"];
	sol::table ghi = lua["def"]["ghi"];

	int bark1 = def["ghi"]["bark"];
	int bark2 = lua["def"]["ghi"]["bark"];
	c_assert(bark1 == 50);
	c_assert(bark2 == 50);

	int abcval1 = abc[0];
	int abcval2 = ghi["woof"][0];
	c_assert(abcval1 == 24);
	c_assert(abcval2 == 24);

If you’re going deep, be safe:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

	sol::optional<int> will_not_error = lua["abc"]["DOESNOTEXIST"]["ghi"];
	c_assert(will_not_error == sol::nullopt);
	
	int also_will_not_error = lua["abc"]["def"]["ghi"]["jklm"].get_or(25);
	c_assert(also_will_not_error == 25);

	// if you don't go safe,
	// will throw (or do at_panic if no exceptions)
	//int aaaahhh = lua["boom"]["the_dynamite"];

	return 0;
}

make tables¶

There are many ways to make a table. Here’s an easy way for simple ones:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <assert.hpp>

int main(int, char* []) {
	sol::state lua;
	lua.open_libraries(sol::lib::base);

	lua["abc_sol2"] = lua.create_table_with(
		0, 24
	);

	sol::table inner_table = lua.create_table_with("bark", 50,
		// can reference other existing stuff too
		"woof", lua["abc_sol2"]
	);
	lua.create_named_table("def_sol2",
		"ghi", inner_table
	);

Equivalent Lua code, and check that they’re equivalent:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

	std::string code = R"(
		abc = { [0] = 24 }
		def = {
			ghi = {
				bark = 50,
				woof = abc
			}
		}
	)";

	lua.script(code);
	lua.script(R"(
		assert(abc_sol2[0] == abc[0])
		assert(def_sol2.ghi.bark == def.ghi.bark)
	)");

	return 0;
}

You can put anything you want in tables as values or keys, including strings, numbers, functions, other tables.

Note that this idea that things can be nested is important and will help later when you get into namespacing.

functions¶

They’re easy to use, from Lua and from C++:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <assert.hpp>

int main(int, char*[]) {
	sol::state lua;
	lua.open_libraries(sol::lib::base);

	lua.script("function f (a, b, c, d) return 1 end");
	lua.script("function g (a, b) return a + b end");

	// sol::function is often easier: 
	// takes a variable number/types of arguments...
	sol::function fx = lua["f"];
	// fixed signature std::function<...>
	// can be used to tie a sol::function down
	std::function<int(int, double, int, std::string)> stdfx = fx;

	int is_one = stdfx(1, 34.5, 3, "bark");
	c_assert(is_one == 1);
	int is_also_one = fx(1, "boop", 3, "bark");
	c_assert(is_also_one == 1);

	// call through operator[]
	int is_three = lua["g"](1, 2);
	c_assert(is_three == 3);
	double is_4_8 = lua["g"](2.4, 2.4);
	c_assert(is_4_8 == 4.8);

	return 0;
}

If you need to protect against errors and parser problems and you’re not ready to deal with Lua’s longjmp problems (if you compiled with C), use sol::protected_function.

You can bind member variables as functions too, as well as all KINDS of function-like things:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <assert.hpp>
#include <iostream>

void some_function() {
	std::cout << "some function!" << std::endl;
}

void some_other_function() {
	std::cout << "some other function!" << std::endl;
}

struct some_class {
	int variable = 30;

	double member_function() {
		return 24.5;
	}
};

int main(int, char*[]) {
	std::cout << "=== functions (all) ===" << std::endl;
	
	sol::state lua;
	lua.open_libraries(sol::lib::base);

	// put an instance of "some_class" into lua
	// (we'll go into more detail about this later
	// just know here that it works and is
	// put into lua as a userdata
	lua.set("sc", some_class());

	// binds a plain function
	lua["f1"] = some_function;
	lua.set_function("f2", &some_other_function);

	// binds just the member function
	lua["m1"] = &some_class::member_function;

	// binds the class to the type
	lua.set_function("m2", &some_class::member_function, some_class{});

	// binds just the member variable as a function
	lua["v1"] = &some_class::variable;

	// binds class with member variable as function
	lua.set_function("v2", &some_class::variable, some_class{});

The lua code to call these things is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

	lua.script(R"(
	f1() -- some function!
	f2() -- some other function!
	
	-- need class instance if you don't bind it with the function
	print(m1(sc)) -- 24.5
	-- does not need class instance: was bound to lua with one 
	print(m2()) -- 24.5
	
	-- need class instance if you 
	-- don't bind it with the function
	print(v1(sc)) -- 30
	-- does not need class instance: 
	-- it was bound with one 
	print(v2()) -- 30

	-- can set, still 
	-- requires instance
	v1(sc, 212)
	-- can set, does not need 
	-- class instance: was bound with one 
	v2(254)

	print(v1(sc)) -- 212
	print(v2()) -- 254
	)");

	std::cout << std::endl;

	return 0;
}

You can use sol::readonly( &some_class::variable ) to make a variable readonly and error if someone tries to write to it.

self call¶

You can pass the self argument through C++ to emulate ‘member function’ calls in Lua.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <iostream>

int main() {
	std::cout << "=== self_call ===" << std::endl;

	sol::state lua;
	lua.open_libraries(sol::lib::base, sol::lib::package, sol::lib::table);

	// a small script using 'self' syntax
	lua.script(R"(
	some_table = { some_val = 100 }

	function some_table:add_to_some_val(value)
	    self.some_val = self.some_val + value
	end

	function print_some_val()
	    print("some_table.some_val = " .. some_table.some_val)
	end
	)");

	// do some printing
	lua["print_some_val"]();
	// 100

	sol::table self = lua["some_table"];
	self["add_to_some_val"](self, 10);
	lua["print_some_val"]();

	std::cout << std::endl;

	return 0;
}

multiple returns from lua¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <assert.hpp>

int main(int, char* []) {
	sol::state lua;

	lua.script("function f (a, b, c) return a, b, c end");

	std::tuple<int, int, int> result;
	result = lua["f"](100, 200, 300);
	// result == { 100, 200, 300 }
	int a;
	int b;
	std::string c;
	sol::tie(a, b, c) = lua["f"](100, 200, "bark");
	c_assert(a == 100);
	c_assert(b == 200);
	c_assert(c == "bark");

	return 0;
}

multiple returns to lua¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <assert.hpp>

int main(int, char* []) {
	sol::state lua;
	lua.open_libraries(sol::lib::base);

	lua["f"] = [](int a, int b, sol::object c) {
		// sol::object can be anything here: just pass it through
		return std::make_tuple(a, b, c);
	};

	std::tuple<int, int, int> result = lua["f"](100, 200, 300);
	const std::tuple<int, int, int> expected(100, 200, 300);
	c_assert(result == expected);

	std::tuple<int, int, std::string> result2;
	result2 = lua["f"](100, 200, "BARK BARK BARK!");
	const std::tuple<int, int, std::string> expected2(100, 200, "BARK BARK BARK!");
	c_assert(result2 == expected2);

	int a, b;
	std::string c;
	sol::tie(a, b, c) = lua["f"](100, 200, "bark");
	c_assert(a == 100);
	c_assert(b == 200);
	c_assert(c == "bark");

	lua.script(R"(
		a, b, c = f(150, 250, "woofbark")
		assert(a == 150)
		assert(b == 250)
		assert(c == "woofbark")
	)");

	return 0;
}

C++ classes from C++¶

Everything that is not a:

• primitive type: bool, char/short/int/long/long long, float/double
• string type: std::string, const char*
• function type: function pointers, lua_CFunction, std::function, sol::function/sol::protected_function, sol::coroutine, member variable, member function
• designated sol type: sol::table, sol::thread, sol::error, sol::object
• transparent argument type: sol::variadic_arg, sol::this_state, sol::this_environment
• usertype<T> class: sol::usertype

Is set as a userdata + usertype.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <assert.hpp>
#include <iostream>

struct Doge {
	int tailwag = 50;

	Doge() {
	}

	Doge(int wags)
	: tailwag(wags) {
	}

	~Doge() {
		std::cout << "Dog at " << this << " is being destroyed..." << std::endl;
	}
};

int main(int, char* []) {
	std::cout << "=== userdata ===" << std::endl;

	sol::state lua;

	Doge dog{ 30 };

	// fresh one put into Lua
	lua["dog"] = Doge{};
	// Copy into lua: destroyed by Lua VM during garbage collection
	lua["dog_copy"] = dog;
	// OR: move semantics - will call move constructor if present instead
	// Again, owned by Lua
	lua["dog_move"] = std::move(dog);
	lua["dog_unique_ptr"] = std::make_unique<Doge>(25);
	lua["dog_shared_ptr"] = std::make_shared<Doge>(31);

	// Identical to above
	Doge dog2{ 30 };
	lua.set("dog2", Doge{});
	lua.set("dog2_copy", dog2);
	lua.set("dog2_move", std::move(dog2));
	lua.set("dog2_unique_ptr", std::unique_ptr<Doge>(new Doge(25)));
	lua.set("dog2_shared_ptr", std::shared_ptr<Doge>(new Doge(31)));

	// Note all of them can be retrieved the same way:
	Doge& lua_dog = lua["dog"];
	Doge& lua_dog_copy = lua["dog_copy"];
	Doge& lua_dog_move = lua["dog_move"];
	Doge& lua_dog_unique_ptr = lua["dog_unique_ptr"];
	Doge& lua_dog_shared_ptr = lua["dog_shared_ptr"];
	c_assert(lua_dog.tailwag == 50);
	c_assert(lua_dog_copy.tailwag == 30);
	c_assert(lua_dog_move.tailwag == 30);
	c_assert(lua_dog_unique_ptr.tailwag == 25);
	c_assert(lua_dog_shared_ptr.tailwag == 31);
	std::cout << std::endl;

	return 0;
}

std::unique_ptr/std::shared_ptr’s reference counts / deleters will be respected.

If you want it to refer to something, whose memory you know won’t die in C++ while it is used/exists in Lua, do the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <assert.hpp>
#include <iostream>

struct Doge {
	int tailwag = 50;

	Doge() {
	}

	Doge(int wags)
		: tailwag(wags) {
	}

	~Doge() {
		std::cout << "Dog at " << this << " is being destroyed..." << std::endl;
	}
};

int main(int, char* []) {
	std::cout << "=== userdata memory reference ===" << std::endl;

	sol::state lua;
	lua.open_libraries(sol::lib::base);

	Doge dog{}; // Kept alive somehow

	// Later...
	// The following stores a reference, and does not copy/move
	// lifetime is same as dog in C++
	// (access after it is destroyed is bad)
	lua["dog"] = &dog;
	// Same as above: respects std::reference_wrapper
	lua["dog"] = std::ref(dog);
	// These two are identical to above
	lua.set( "dog", &dog );
	lua.set( "dog", std::ref( dog ) );


	Doge& dog_ref = lua["dog"]; // References Lua memory
	Doge* dog_pointer = lua["dog"]; // References Lua memory
	Doge dog_copy = lua["dog"]; // Copies, will not affect lua

You can retrieve the userdata in the same way as everything else. Importantly, note that you can change the data of usertype variables and it will affect things in lua if you get a pointer or a reference:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

	lua.new_usertype<Doge>("Doge",
		"tailwag", &Doge::tailwag
	);

	dog_copy.tailwag = 525;
	// Still 50
	lua.script("assert(dog.tailwag == 50)");

	dog_ref.tailwag = 100;
	// Now 100
	lua.script("assert(dog.tailwag == 100)");

	dog_pointer->tailwag = 345;
	// Now 345
	lua.script("assert(dog.tailwag == 345)");

	std::cout << std::endl;

	return 0;
}

C++ classes put into Lua¶

See this section here. Also check out a basic example, special functions example and initializers example! There are many more examples that show off the usage of classes in C++, so please peruse them all carefully as it can be as simple or as complex as your needs are.

namespacing¶

You can emulate namespacing by having a table and giving it the namespace names you want before registering enums or usertypes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

#define SOL_ALL_SAFETIES_ON 1
#include <sol/sol.hpp>

#include <iostream>
#include <assert.hpp>

int main() {
	std::cout << "=== namespacing ===" << std::endl;

	struct my_class {
		int b = 24;

		int f() const {
			return 24;
		}

		void g() {
			++b;
		}
	};

	sol::state lua;
	lua.open_libraries();

	// "bark" namespacing in Lua
	// namespacing is just putting things in a table
	// forces creation if it does not exist
	auto bark = lua["bark"].get_or_create<sol::table>();
	// equivalent-ish:
	//sol::table bark = lua["bark"].force(); // forces table creation
	// equivalent, and more flexible:
	//sol::table bark = lua["bark"].get_or_create<sol::table>(sol::new_table());
	// equivalent, but less efficient/ugly:
	//sol::table bark = lua["bark"] = lua.get_or("bark", lua.create_table());
	bark.new_usertype<my_class>("my_class",
		"f", &my_class::f,
		"g", &my_class::g); // the usual

	// can add functions, as well (just like the global table)
	bark.set_function("print_my_class", [](my_class& self) { std::cout << "my_class { b: " << self.b << " }" << std::endl; });

	// this works
	lua.script("obj = bark.my_class.new()");
	lua.script("obj:g()");

	// calling this function also works
	lua.script("bark.print_my_class(obj)");
	my_class& obj = lua["obj"];
	c_assert(obj.b == 25);

	std::cout << std::endl;

	return 0;
}

This technique can be used to register namespace-like functions and classes. It can be as deep as you want. Just make a table and name it appropriately, in either Lua script or using the equivalent sol code. As long as the table FIRST exists (e.g., make it using a script or with one of sol’s methods or whatever you like), you can put anything you want specifically into that table using sol::table’s abstractions.

there is a LOT more¶

Some more things you can do/read about:

• the usertypes page lists the huge amount of features for functions

  • unique usertype traits allows you to specialize handle/RAII types from other libraries frameworks, like boost and Unreal, to work with sol. Allows custom smart pointers, custom handles and others

• the containers page gives full information about handling everything about container-like usertypes

• the functions page lists a myriad of features for functions

  • variadic arguments in functions with sol::variadic_args.
  • also comes with variadic_results for returning multiple differently-typed arguments
  • this_state to get the current lua_State*, alongside other transparent argument types

• metatable manipulations allow a user to change how indexing, function calls, and other things work on a single type.
• ownership semantics are described for how Lua deals with its own internal references and (raw) pointers.
• stack manipulation to safely play with the stack. You can also define customization points for stack::get/stack::check/stack::push for your type.
• make_reference/make_object convenience function to get the same benefits and conveniences as the low-level stack API but put into objects you can specify.
• stack references to have zero-overhead sol abstractions while not copying to the Lua registry.
• resolve overloads in case you have overloaded functions; a cleaner casting utility. You must use this to emulate default parameters.

how to handle exceptions or other errors¶

Here is some advice and some tricks for common errors about iteration, compile time / linker errors, and other pitfalls, especially when dealing with thrown exceptions, error conditions and the like in sol.

Running Scripts¶

Scripts can have syntax errors, can load from the file system wrong, or have runtime issues. Knowing which one can be troublesome. There are various small building blocks to load and run code, but to check errors you can use the overloaded script/script_file functions on sol::state/sol::state_view, specifically the safe_script variants. These also take an error callback that is called only when something goes wrong, and sol comes with some default error handlers in the form of sol::script_default_on_error and sol::script_pass_on_error.

Compiler Errors / Warnings¶

A myriad of compiler errors can occur when something goes wrong. Here is some basic advice about working with these types:

• If there are a myriad of errors relating to std::index_sequence, type traits, and other std:: members, it is likely you have not turned on your C++14 switch for your compiler. Visual Studio 2015 turns these on by default, but g++ and clang++ do not have them as defaults and you should pass the flag --std=c++1y or --std=c++14, or similar for your compiler.
• If you are pushing a non-primitive type into Lua, you may get strange errors about initializer lists or being unable to initializer a luaL_Reg. This may be due to automatic function and operator registration. Disabling it may help.
• Sometimes, a generated usertype can be very long if you are binding a lot of member functions. You may end up with a myriad of warnings about debug symbols being cut off or about __LINE_VAR exceeding maximum length. You can silence these warnings safely for some compilers.
• Template depth errors may also be a problem on earlier versions of clang++ and g++. Use -ftemplate-depth compiler flag and specify really high number (something like 2048 or even double that amount) to let the compiler work freely.
• When using usertype templates extensively, MSVC may invoke compiler error C1128 , which is solved by using the /bigobj compilation flag.
• If you have a move-only type, that type may need to be made readonly if it is bound as a member variable on a usertype or bound using state_view::set_function. See sol::readonly for more details.
• Assigning a std::string or a std::pair<T1, T2> using operator= after it’s been constructed can result in compiler errors when working with sol::function and its results. See this issue for fixes to this behavior.
• Sometimes, using __stdcall in a 32-bit (x86) environment on VC++ can cause problems binding functions because of a compiler bug. We have a prelimanry fix in, but if it doesn’t work and there are still problems: put the function in a std::function to make the compiler errors and other problems go away. Also see this __stdcall issue report for more details.
• If you are using /std:c++latest on VC++ and get a number of errors for noexcept specifiers on functions, you may need to file an issue or wait for the next release of the VC++ compiler.

Mac OSX Crashes¶

On LuaJIT, your code may crash at seemingly random points when using Mac OSX. Make sure that your build has these flags, as advised by the LuaJIT website:

-pagezero_size 10000 -image_base 100000000

These will allow your code to run properly, without crashing arbitrarily. Please read the LuaJIT documentation on compiling and running with LuaJIT for more information.

“compiler out of heap space”¶

Typical of Visual Studio, the compiler will complain that it is out of heap space because Visual Studio defaults to using the x86 (32-bit) version of itself (it will still compile x86 or x64 or ARM binaries, just the compiler itself is a 32-bit executable). In order to get around heap space requirements, add the following statement in your .vcoxproj files under the <Import .../> statement, as instructed by OrfeasZ in this issue:

<PropertyGroup>
        <PreferredToolArchitecture>x64</PreferredToolArchitecture>
</PropertyGroup>

This should use the 64-bit tools by default, and increase your maximum heap space to whatever a 64-bit windows machine can handle. If you do not have more than 4 GB of RAM, or you still encounter issues, you should look into breaking up your usertype across C++ files. Also, it is imperative to not put all the functions inside single calls to the new_usertype(…) function directly: instead, use my_usertype[“func”] = func; like so:

auto my_usertype = lua.new_usertype<my_class>("my_class");
my_usertype["talkin"] = &about;
my_usertype["this"] = &my_class::that;
my_usertype["and_the"] = sol::property(&my_class::third);

Linker Errors¶

There are lots of reasons for compiler linker errors. A common one is not knowing that you’ve compiled the Lua library as C++: when building with C++, it is important to note that every typical (static or dynamic) library expects the C calling convention to be used and that sol includes the code using extern 'C' where applicable.

However, when the target Lua library is compiled with C++, one must change the calling convention and name mangling scheme by getting rid of the extern 'C' block. This can be achieved by adding #define SOL_USING_CXX_LUA before including sol3, or by adding it to your compilation’s command line. If you build LuaJIT in C++ mode (how you would even, is beyond me), then you need to #define SOL_USING_CXX_LUAJIT as well. Typically, there is never a need to use this last one.

Note that you should not be defining these with standard builds of either Lua or LuaJIT. See the config page for more details.

“caught (…) exception” errors¶

Sometimes, you expect properly written errors and instead receive an error about catching a ... exception instead. This might mean that you either built Lua as C++ or are using a framework like LuaJIT that has full interopability support for exceptions on certain system types (x64 for LuaJIT 2.0.5, x86 and x64 on LuaJIT 2.1.x-beta and later).

Please make sure to use the SOL_EXCEPTIONS_SAFE_PROPAGATION define before including sol3 to make this work out. You can read more at the exception page here.

Catch and CRASH!¶

By default, sol will add a default_at_panic handler to states opened by sol (see sol::state automatic handlers for more details). If exceptions are not turned off, this handler will throw to allow the user a chance to recover. However, in almost all cases, when Lua calls lua_atpanic and hits this function, it means that something irreversibly wrong occured in your code or the Lua code and the VM is in an unpredictable or dead state. Catching an error thrown from the default handler and then proceeding as if things are cleaned up or okay is NOT the best idea. Unexpected bugs in optimized and release mode builds can result, among other serious issues.

It is preferred if you catch an error that you log what happened, terminate the Lua VM as soon as possible, and then crash if your application cannot handle spinning up a new Lua state. Catching can be done, but you should understand the risks of what you’re doing when you do it. For more information about catching exceptions, the potentials, not turning off exceptions and other tricks and caveats, read about exceptions in sol here.

Lua is a C API first and foremost: exceptions bubbling out of it is essentially last-ditch, terminal behavior that the VM does not expect. You can see an example of handling a panic on the exceptions page here. This means that setting up a try { ... } catch (...) {} around an unprotected sol3 function or script call is NOT enough to keep the VM in a clean state. Lua does not understand exceptions and throwing them results in undefined behavior if they bubble through the C API once and then the state is used again. Please catch, and crash.

Furthermore, it would be a great idea for you to use the safety features talked about safety section, especially for those related to functions.

Destructors and Safety¶

Another issue is that Lua is a C API. It uses setjmp and longjmp to jump out of code when an error occurs. This means it will ignore destructors in your code if you use the library or the underlying Lua VM improperly. To solve this issue, build Lua as C++. When a Lua VM error occurs and lua_error is triggered, it raises it as an exception which will provoke proper unwinding semantics.

Building Lua as C++ gets around this issue, and allows lua-thrown errors to properly stack unwind.

Protected Functions and Access¶

By default, sol::function assumes the code ran just fine and there are no problems. sol::state(_view)::script(_file) also assumes that code ran just fine. Use sol::protected_function to have function access where you can check if things worked out. Use sol::optional to get a value safely from Lua. Use sol::state(_view)::do_string/do_file/load/load_file to safely load and get results from a script. The defaults are provided to be simple and fast with thrown exceptions to violently crash the VM in case things go wrong.

Protected Functions Are Not Catch All¶

Sometimes, some scripts load poorly. Even if you protect the function call, the actual file loading or file execution will be bad, in which case sol::protected_function will not save you. Make sure you register your own panic handler so you can catch errors, or follow the advice of the catch + crash behavior above. Remember that you can also bind your own functions and forego sol3’s built-in protections for you own by binding a raw lua_CFunction function

Iteration¶

Tables may have other junk on them that makes iterating through their numeric part difficult when using a bland for-each loop, or when calling sol’s for_each function. Use a numeric look to iterate through a table. Iteration does not iterate in any defined order also: see this note in the table documentation for more explanation.

getting good final product out of sol¶

supported compilers¶

GCC 7.x is now out alongside Visual Studio 2018. This means that sol release v2.20.1 is the current version of the code targeted at the older compilers not listed below. Newer code will be targeted at working with the following compilers and leveraging their features, possibly taking advantage of whatever C++17 features are made available by the compilers and standard libraries bundled by-default with them.

v2.20.1 supports:

• VC++

  • Visual Studio 2018
  • Visual Studio 2015 (Latest updates)

• GCC (includes MinGW)

  • v7.x
  • v6.x
  • v5.x
  • v4.8+

• Clang

  • v4.x
  • v3.9.x
  • v3.8.x
  • v3.7.x
  • v3.6.x
  • Note: this applies to XCode’s Apple Clang as well, but that compiler packs its own deficiencies and problems as well

This does not mean we are immediately abandoning older compilers. We will update this page as relevant bugfixes are backported to the v2.x.x releases. Remember that sol3 is feature-complete: there is nothing more we can add to the library at this time with C++11/C++14 compiler support, so your code will be covered for a long time to come.

Newer features will be targeted at the following compilers:

• VC++

  • Visual Studio vNext
  • Visual Studio 2018

• GCC (includes MinGW)

  • v8.x
  • v7.x

• Clang

  • v7.x
  • v6.x
  • v5.x
  • v4.x
  • v3.9.x

Note that Visual Studio’s 2018 Community Edition is absolutely free now, and installs faster and easier than ever before. It also removes a lot of hacky work arounds and formally supports decltype SFINAE.

MinGW’s GCC version 7.x of the compiler fixes a long-standing derp in the <codecvt> header that swapped the endianness of utf16 and utf32 strings.

Clang 3.4, 3.5 and 3.6 have many bugs we have run into when developing sol3 and that have negatively impacted users for a long time now.

We encourage all users to upgrade immediately. If you need old code for some reason, use sol release v2.20.1: otherwise, always grab sol3’s latest.

feature support¶

track future compiler and feature support in this issue here.

supported Lua version¶

We support:

• Lua 5.3+
• Lua 5.2
• Lua 5.1
• LuaJIT 2.0.x+
• LuaJIT 2.1.x-beta3+

binary sizes¶

For individiauls who use usertypes a lot, they can find their compilation times increase. This is due to C++11 and C++14 not having very good facilities for handling template parameters and variadic template parameters. There are a few things in cutting-edge C++17 and C++Next that sol can use, but the problem is many people cannot work with the latest and greatest: therefore, we have to use older techniques that result in a fair amount of redundant function specializations that can be subject to the pickiness of the compiler’s inlining and other such techniques.

compile speed improvemements¶

Here are some notes on achieving better compile times without sacrificing too much performance:

• When you bind lots of usertypes, put them all in a single translation unit (one C++ file) so that it is not recompiled multiple times over, only to be discarded later by the linker.

  • Remember that the usertype binding ends up being serialized into the Lua state, so you never need them to appear in a header and cause that same compilation overhead for every compiled unit in your project.

• Consider placing groups of bindings in multiple different translation units (multiple C++ source files) so that only part of the bindings are recompiled when you have to change the bindings.

  • Avoid putting your bindings into headers: it will slow down your compilation

• If you are developing a shared library, restrict your overall surface area by specifically and explicitly marking functions as visible and exported and leaving everything else as hidden or invisible by default
• For people who already have a tool that retrieves function signatures and arguments, it might be in your best interest to hook into that tool or generator and dump out the information once using sol3’s lower-level abstractions. An issue describing preliminary steps can be found here.

next steps¶

The next step for sol from a developer standpoint is to formally make the library a C++17 one. This would mean using Fold Expressions and several other things which will reduce compilation time drastically. Unfortunately, that means also boosting compiler requirements. While most wouldn’t care, others are very slow to upgrade: finding the balance is difficult, and often we have to opt for backwards compatibility and fixes for bad / older compilers (of which there are many in the codebase already).

Hopefully, as things progress, we move things forward.

what sol supports¶

• Support for Lua 5.1, 5.2, and 5.3+ and LuaJIT 2.0.4 + 2.1.x-beta3+. We achieve this through our compatibility header.

• Table support: setting values, getting values of multiple (different) types

  • Lazy evaluation for nested/chained queries

    table["a"]["b"]["c"] = 24;

  • Implicit conversion to the types you want

    double b = table["computed_value"];

• yielding support: tag a function as whose return is meant to yield into a coroutine

• Optional support: setting values, getting values of multiple (different) types

  • Lazy evaluation for nested/chained queries

    optional<int> maybe_number = table["a"]["b"]["invalid_key"];

  • Turns on safety when you want it: speed when you don’t

• Support for callables (functions, lambdas, member functions)

  • Pull out any Lua function with sol::function: sol::function fx = table["socket_send"];
  • Can also set callables into operator[] proxies: table["move_dude"] = &engine::move_dude;

  • Safety: use sol::protected_function to catch any kind of error

    • ANY kind: C++ exception or Lua erors are trapped and run through the optional error_handler variable

  • Advanced: overloading of a single function name so you don’t need to do boring typechecks
  • Advanced: efficient handling and well-documented way of dealing with arguments

• User-Defined Type (sol::usertype in the API) support:

  • Set member functions to be called
  • Set member variables
  • Set variables on a class that are based on setter/getter functions using properties
  • Use free-functions that take the Type as a first argument (pointer or reference)
  • Support for “Factory” classes that do not expose constructor or destructor
  • Modifying memory of userdata in C++ directly affects Lua without copying, and

  • Modifying userdata in Lua directly affects C++ references/pointers

    my_class& a = table["a"]; my_class* a_ptr = table["a"];

  • If you want a copy, just use value semantics and get copies:

    my_class a = table["a"];

• Thread/Coroutine support

  • Use, resume, and play with coroutines like regular functions
  • Get and use them even on a separate Lua thread
  • Monitor status and get check errors

• Advanced: Customizable and extensible to your own types if you override getter/pusher/checker template struct definitions.

The Feature Matrix™¶

The below feature table checks for the presence of something. It, however, does not actually account for any kind of laborious syntax.

✔ full support: works as you’d expect (operator[] on tables, etc…)

~ partial support / wonky support: this means its either supported through some other fashion (not with the desired syntax, serious caveats, etc.). Sometimes means dropping down to use the plain C API (at which point, what was the point of the abstraction?).

✗ no support: feature doesn’t work or, if it’s there, it REALLY sucks to use

Implementation notes from using the libraries are below the tables.

category explanations¶

Explanations for a few categories are below (rest are self-explanatory).

• optional: Support for getting an element, or potentially not (and not forcing the default construction of what amounts to a bogus/dead object). Usually comes with std(::experimental)::optional. It’s a fairly new class, so a hand-rolled class internal to the library with similar semantics is also acceptable
• tables: Some sort of abstraction for dealing with tables. Ideal support is mytable["some_key"] = value, and everything that the syntax implies.
• table chaining: In conjunction with tables, having the ability to query deeply into tables mytable["key1"]["key2"]["key3"]. Note that this becomes a tripping point for some libraries: crashing if "key1" doesn’t exist while trying to access "key2" (sol avoids this specifically when you use sol::optional), and sometimes it’s also a heavy performance bottleneck as expressions are not lazy-evaluated by a library.
• arbitrary keys: Letting C++ code use userdata, other tables, integers, etc. as keys for into a table.
• user-defined types (udts): C++ types given form and function in Lua code.
• udts - member functions: C++ member functions on a type, usually callable with my_object:foo(1) or similar in Lua.
• udts - table variables: C++ member variables/properties, manipulated by my_object.var = 24 and in Lua
• function binding: Support for binding all types of functions. Lambdas, member functions, free functions, in different contexts, etc…
• protected function: Use of lua_pcall to call a function, which offers error-handling and trampolining (as well as the ability to opt-in / opt-out of this behavior)
• multi-return: returning multiple values from and to Lua (generally through std::tuple<...> or in some other way)
• variadic/variant argument: being able to accept “anything” from Lua, and even return “anything” to Lua (object abstraction, variadic arguments, etc…)
• inheritance: allowing some degree of subtyping or inheritance on classes / userdata from Lua - this generally means that you can retrieve a base pointer from Lua even if you hand the library a derived pointer
• overloading: the ability to call overloaded functions, matched based on arity or type (foo( 1 ) from lua calls a different function then foo( "bark" )).
• Lua thread: basic wrapping of the lua thread API; ties in with coroutine.
• coroutines: allowing a function to be called multiple times, resuming the execution of a Lua coroutine each time
• yielding C++ functions: allowing a function from C++ to be called multiple times, and yield any results it has back through the C API or into Lua
• environments: an abstraction for getting, setting and manipulating an environment, using table techniques, functions or otherwise. Typically for the purposes of sandboxing