Sol3 (sol2 v3.0) - a C++ <-> Lua API wrapper with advanced features and top notch performance - is here, and it's great! Documentation:

Last update: Jan 4, 2023

Overview

sol2

sol2 is a C++ library binding to Lua. It currently supports all Lua versions 5.1+ (LuaJIT 2.0+ and MoonJIT included). sol2 aims to be easy to use and easy to add to a project. The library is header-only for easy integration with projects, and a single header can be used for drag-and-drop start up.

Sneak Peek

#include <sol/sol.hpp>
#include <cassert>

int main() {
    sol::state lua;
    int x = 0;
    lua.set_function("beep", [&x]{ ++x; });
    lua.script("beep()");
    assert(x == 1);
}

#include <sol/sol.hpp>
#include <cassert>

struct vars {
    int boop = 0;
};

int main() {
    sol::state lua;
    lua.new_usertype<vars>("vars", "boop", &vars::boop);
    lua.script("beep = vars.new()\n"
               "beep.boop = 1");
    assert(lua.get<vars>("beep").boop == 1);
}

More examples are given in the examples directory here.

Documentation

Find it here. A run-through kind of tutorial is here! The API documentation goes over most cases (particularly, the "api/usertype" and "api/table_proxy" and "api/function" sections) that should still get you off your feet and going, and there's an examples directory here as well.

"I need X Feature or Fix, Right Now™"

Find the support option that's right for you, here! If you're happy to wait, you can just file a boring issue and we'll get to it Whenever There Is Time™.

I want to donate to help!

You can find donation and sponorship options here and from the little heart button near the top of this repository that will take you to a bevy of links in which you can donate and show support for this project and others!

Features

Fastest in the land (see: sol3 bar in graph).
Supports retrieval and setting of multiple types including:
- std::string, std::wstring, std::u16string and std::u32string support (and for views).
- understands and works with containers such as std::map/unordered_map, c-style arrays, vectors, non-standard custom containers and more.
- user-defined types, with or without registering that type
- std::unique_ptr, std::shared_ptr, and optional support of other pointer types like boost::shared_ptr.
- custom optional<T> that works with references, and support for the inferior std::optional.
- C++17 support for variants and similar new types.
Lambda, function, and member function bindings are supported.
Intermediate type for checking if a variable exists.
Simple API that completely abstracts away the C stack API, including protected_function with the ability to use an error-handling function.
operator[]-style manipulation of tables
C++ type representations in Lua userdata as usertypes with guaranteed cleanup.
Customization points to allow your C++ objects to be pushed and retrieved from Lua as multiple consecutive objects, or anything else you desire!
Overloaded function calls: my_function(1); my_function("Hello") in the same Lua script route to different function calls based on parameters
Support for tables, nested tables, table iteration with table.for_each / begin() and end() iterators.
Zero string overhead for usertype function lookup.

Supported Compilers

sol2 makes use of C++17 features. GCC 7.x.x and Clang 3.9.x (with -std=c++1z and appropriate standard library) or higher should be able to compile without problems. However, the officially supported and CI-tested compilers are:

GCC 7.x.x+ (MinGW 7.x.x+)
Clang 3.9.x+
Visual Studio 2017 Community (Visual C++ 15.0)+

Please make sure you use the -std=c++2a, -std=c++1z, -std=c++17 or better standard flags (some of these flags are the defaults in later versions of GCC, such as 7+ and better).

If you would like support for an older compiler (at the cost of some features), use the latest tagged sol2 branch. If you would like support for an even older compiler, feel free to contact me for a Custom Solution.

sol3 is checked by-hand for other platforms as well, including Android-based builds with GCC and iOS-based builds out of XCode with Apple-clang. It should work on both of these platforms, so long as you have the proper standards flags. If something doesn't work or you need special options, you may need to look into the different ways to support the project to have it done for you!

Creating a single header

You can grab a single header (and the single forward header) out of the library here. For stable version, check the releases tab on GitHub for a provided single header file for maximum ease of use. A script called single.py is provided in the repository if there's some bleeding edge change that hasn't been published on the releases page. You can run this script to create a single file version of the library so you can only include that part of it. Check single.py --help for more info.

If you use CMake, you can also configure and generate a project that will generate the sol2_single_header for you. You can also include the project using CMake. Run CMake for more details. Thanks @Nava2, @alkino, @mrgreywater and others for help with making the CMake build a reality.

Testing

Testing turns on certain CI-only variables in the CMake to test a myriad of configuration options. You can generate the tests by running CMake and configuring SOL2_TESTS, SOL2_TESTS_SINGLE, SOL2_TESTS_EXAMPLES, and SOL2_EXAMPLES to be on. Make sure SOL2_SINGLE is also on.

You will need any flavor of python3 and an available compiler. The testing suite will build its own version of Lua and LuaJIT, so you do not have to provide one (you may provide one with the LUA_LOCAL_DIR variable).

Presentations

"A Sun For the Moon - A Zero-Overhead Lua Abstraction using C++"
ThePhD Lua Workshop 2016 - Mashape, San Francisco, CA
Deck

"Wrapping Lua C in C++ - Efficiently, Nicely, and with a Touch of Magic"
ThePhD Boston C++ Meetup November 2017 - CiC (Milk Street), Boston, MA
Deck

"Biting the CMake Bullet"
ThePhD Boston C++ Meetup February 2018 - CiC (Main Street), Cambridge, MA
Deck

"Compile Fast, Run Faster, Scale Forever: A look into the sol2 Library"
ThePhD C++Now 2018 - Hudson Commons, Aspen Physics Center, Aspen, Colorado
Deck

"Scripting at the Speed of Thought: Using Lua in C++ with sol3"
ThePhD CppCon 2018 - 404 Keystone, Meydenbauer Center, Aspen, Colorado
Deck

"The Plan for Tomorrow: Compile-Time Extension Points in C++" ThePhD C++Now 2019 - Flug Auditorium, Aspen Physics Center, Aspen, Colorado Deck

License

sol2 is distributed with an MIT License. You can see LICENSE.txt for more info.

If you need a custom solution, feel free to reach out.

Comments

Alignment error with member callback

The following example, where we try to execute a std::function member object, creates alignment errors on clang 6.0.0 according to the UndefinedBehaviorSanitizer.

#include <sol.hpp>
#include <functional>
#include <iostream>

struct Test{
  std::function<void()> callback = [](){ std::cout << "Hello world!" << std::endl; };
};

int main() {
  sol::state lua;
  lua.new_usertype<Test>("Test","callback",&Test::callback);
  Test test;
  lua["test"] = &test;
  lua.script("test.callback()");
  return 0;
}

when compiled using clang++ --std=c++14 -fsanitize=undefined ... a cascade of 'misaligned address' runtime errors is generated, beginning with

(a.out:x86_64+0x1000d8c48): runtime error: constructor call on misaligned address 0x7fc01c405518 for type 'sol::function_detail::functor_function<std::__1::function<void ()> >', which requires 16 byte alignment
0x7fc01c405518: note: pointer points here
 00 00 00 00  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  00 00 00 00
              ^

Otherwise the program executes as expected.

Ahhh.Real Monsters Baited.Undefined Behavior

opened by TheLartians 42

sol::variadic_args use in usertype constructor

struct foo 
{
	foo(sol::variadic_args args)
	{
		std::cout << args.size() << std::endl;
	}
};


int main(int argc, char ** argv)
{
	sol::state lua;

	lua.open_libraries();
	lua.new_usertype<foo>("foo", sol::constructors<foo(sol::variadic_args)>());

	lua.script(R"(
	foo.new()
	foo.new(0, 1)
	foo.new(0, 1, 2)
	foo.new(0, 1, 2, 3)
	)");
}

This will be print

why? my compiler is vc2019.

Maybe.Bug...?

opened by 11nk 33

Long compilation times when registering usertype with lots (>50) of member functions.
I have a class which has a lot of member functions. I pass them all in usertype constructor but that probably generates huge template intantiations of some functions. This causes CPP file in VS2015 to compile for 3-4 minutes while consuming 1.5 gigabytes of RAM.

What I need is ability to register functions one by one, not all at once. I realize that this may not be the most efficient way to do this, but compilation times are very important for me, more that runtime performance when registering this stuff.

I propose something like:

usertype<SomeClass> ut("SomeClass"); ut.add_function("someFunc", &SomeClass::someFunc); ...
Refactoring.Usability Feature.Can Do Feature.Shiny
opened by eliasdaler 29
Calling Unknown function on global variable crashes on cleanup
Hey there,

I just grabbed latest to benefit from the "attempt to index a nil value" fix, but ran into an issue on app exit. When having called an unknown function on a global lua var it will crash on exit with iterator debug level 2, orphaned pointer, read access violation.

Example:

class A { public: A() : a(0){} }; solState.new_usertype<A>("A", "a", &A::a);

runs and exits fine:

local test = A.new() test:Unknown()

runs fine but will cause app crash on exit:

test = A.new() -- notice global variable test:Unknown() -- having called it will cause app to crash on exit

Looking into it more the crash happens during GC for the fail_on_error functor.
Maybe.Bug...?
opened by schnitzelK1ng 27
AppVeyor for VS 2017/2015 | Travis for g++ 7/6/5 , clang++ 3.7/3.8/3.9/4.0
All of the old test harnesses should be placed into "Allowed Failures" buckets, including VS 2015. This will let us know what commit exactly breaks a certain compiler level, albeit it would mean tests would take an additional hour to complete in the cloud (mostly because of additional XCode imaging setup).

[x] Travis CI:

[x] g++ 5.3

[x] g++ 5.4

[x] g++ 6.3

[x] g++ 7.1

[x] clang++ 3.6

[x] clang++ 3.7

[x] clang++ 3.8

[x] clang++ 3.9

[x] clang++ 4.0

[x] AppVeyor:

[x] Visual Studio 2015, Latest (allowed failure)

[x] Visual Studio 2017, Latest

All older tests should be bundled up as "allowed failures"
Tests.CI
opened by ThePhD 25
Write a tutorial

The current README is pretty terse, and reading API reference is a not pleasant way to learn any library. I propose to kidnap manual from any competing library (kagaya, selene, lua-intf to name a few), made a few edits to identifiers (and list of supported compilers) and put it into README. You may even combine parts kidnapeed here and there. Later Sol-specific features may be added, but it will be a good start.

I believe that now, when you are released a major stable version, lack of step-by-step tutorial is main barrier to wider Sol2 acceptance.
Documentation

opened by Bulat-Ziganshin 25
LuaJIT 5.1: Exceptions are not rethrown through sol::error
In my code, I'm trying to force some sandboxing, one part of this is setting the require function to nil.

To test this, I create an "library script":

local M = {} function M.foo() return "foo" end return M

I store this into a file in the test dir, m.lua, and then load it via:

local M= require('m') assert(M.foo() == "foo");

On Lua 5.2, this throws a sol::error claiming the require function is nil. This is the expected behaviour, however, luajit exceptions are never caught and it throws an error unrecognized.
opened by Nava2 25

Usertypes with many members become too complex for the compiler

I'm experiencing this issue under MSVC140 (Update 3) on the 64-bit toolchain.

I have a usertype which has 147 property members (sol::property), a call constructor, and two base classes, and during compilation I'm getting the following errors:

2>I:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\include\type_traits(1016): fatal error C1202: recursive type or function dependency context too complex (compiling source file CustomUsertypeClass.cpp)
2>  I:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\include\type_traits(1035): note: see reference to class template instantiation 'std::_Choose_conjunction<true,_Lhs,std::is_constructible<const char (&)[27],const char (&)[27]>,std::is_constructible<sol::property_wrapper<bool (__cdecl CustomUsertypeClass::* )(void) const,void (__cdecl CustomUsertypeClass::* )(bool)>,_Ty>,std::is_constructible<const char (&)[27],const char (&)[27]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[30],const char (&)[30]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[26],const char (&)[26]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[16],const char (&)[16]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[15],const char (&)[15]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[20],const char (&)[20]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[25],const char (&)[25]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[34],const char (&)[34]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[28],const char (&)[28]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[32],const char (&)[32]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[21],const char (&)[21]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[18],const char (&)[18]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[23],const char (&)[23]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[21],const char (&)[21]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[24],const char (&)[24]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[26],const char (&)[26]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (&)[25],const char (&)[25]>,std::is_constructible<_Ty,_Ty>,std::is_constructible<const char (...

This could be associated to #202 but since it's an actual issue I'm posted it here for reference.

Bike.Shed

opened by OrfeasZ 23

Issue compiling sol on OSX (xcode 8.2.1, LLVM 8.0).

I wonder if someone could help me. This is likely something on my end.

Im trying to use sol2 with luajit. Previously using lua worked fine. I add the header like this:

` #define SOL_USING_CXX_LUA

#define SOL_USING_CXX_LUAJIT

#include <sol2/sol.hpp> `

I get an error in compilation: .../include/sol2/sol.hpp:2082:10: Cannot initialize return object of type 'char *' with an rvalue of type 'int'

It seems strerror_r returns an int, not as expected a char *. Should i be using those 2 defines when trying to use luajit?

Thanks!
Bug.Well Shit

opened by pjohalloran 22
Container Usertypes are not iterable

Using the latest release of sol2, Visual Studio 2017 and compiled as C++17 through the appropriate compiler flags

I have a class, X, which satisfies the requirements of Container and holds a different class, Y.

Class X has methods and functions that help manipulate Y's, and i want this class to be exposed to Lua. As such, i've attempted to register it as a usertype, which works, but I can't for the life of me figure out how to get the actual Container part to work. No matter what i try i can't iterate over it from Lua.

I have tried specializing the is_container template to be true, but that does not visibly change anything.

Is this not possible in sol2? Am i missing something?
Documentation Docs.Are Bad

opened by DianaNites 22
Large integer support
This PR adds large integer support for x86 and integer misrepresentation detection for x86/x64. sol2 will still try to use lua_Integer wherever it is safe to do so, only when the value can't possibly fit in lua_Integer, it uses lua_Number as fallback with optional runtime checks to make sure the floating point value still represents the integer accurately.

Would appreciate any feedback or concerns, if there are any.

See #470

[x] large integer changes

[x] tests

[x] working linux:i386 build

[x] passes travis-ci (as good as develop)

[x] reviewed

unrelated to this PR:

The build for the original develop branch is currently broken, I'll update my fork from upstream as soon as it's fixed.

currently both linux:i386 and windows:x86 are failing some tests on upstream/develop (at least with the latest luajit) maybe we could have some i386 builds on travis?

you manually need to set SOL_EXCEPTIONS_SAFE_PROPAGATION under windows x86/luajit2.1b3 (the new versions have proper exception handling under windows x86 with \EHsc)

single.py is failing with python2.7 and only works with python3

it would be nice to have a build config that runs with msvc that you don't need to create yourself

Feature.Shiny Tests.CI
opened by mrgreywater 22
Unwanted function argument copying starting from v3.3.0

In push_reference, where the use_reference_tag is calculated, there is a change made in v3.3.0: meta::neg<std::is_const<T>> -> meta::neg<std::is_const<std::remove_reference_t<T>>>

Due to this change, const T& args meet the reference condition no more, and now they are copied for the call. The first issue here is that some big and heavy objects are copied although we explicitly pass them as const references and don't either want or expect copying to happen. The second issue is inability to pass refcounted objects without making a new reference, which is desired sometimes and was possible before the change.

opened by niello 0
is_value_semantic_for_function doesn't work as expected
As follows from code, passing by reference or by value is determined as:

using use_reference_tag = meta::all< meta::neg<is_value_semantic_for_function<T>> ... >;

But when we pass some argument to sol::function by value (say type is MyType), in push_reference the T is already MyType&. And if we define MyType as passed by value, we actually get nothing, because for MyType& it is not defined. This causes me to define all these just in case:

template <> struct is_value_semantic_for_function<MyType> : std::true_type {}; template <> struct is_value_semantic_for_function<const MyType> : std::true_type {}; template <> struct is_value_semantic_for_function<MyType&> : std::true_type {}; template <> struct is_value_semantic_for_function<const MyType&> : std::true_type {};

And there is the second issue. While we may want to pass [const] MyType and const MyType& by value, we may at the same time want explicit MyType& to be passed by reference. It is typical pattern for C++ signatures. But we can't define that because MyType& specialization is used for MyType args.

The perfect behaviour would be to define specialization for MyType only and to have MyType& as an automatic exception from the rule, bound always by reference. And if someone wants a reference to be passed by value, let them explicitly use const MyType& on C++ side.
opened by niello 0
LuaJIT 2.1.0-beta3 and 64-bit bitwise operations
Hello,

My apologies in advance if this is not a SOL issue but I thought it'd be worth asking. I have encountered the following issue: I am trying to use luaJIT's built-in bit library which, reportedly, handles 64-bit integers. The issue is: When I try to use local bit = require("bit") and do my thing, I get this error:

ERROR! XElua_state.cpp : 352 : CheckAndRunFunction : Assets/script/__init.lua:1: module 'bit' not found: no field package.preload['bit'] no file '.\bit.lua' no file 'C:\Users\User\source\repos\engine\x64\Debug\lua\bit.lua' no file 'C:\Users\User\source\repos\engine\x64\Debug\lua\bit\init.lua' no file '.\bit.dll' no file 'C:\Users\User\source\repos\engine\x64\Debug\bit.dll' no file 'C:\Users\User\source\repos\engine\x64\Debug\loadall.dll'

Opening sol::lib::bit32 makes bit functions work but only for 32-bit numbers.

So...is there any way to make the "correct" luaJIT library visible?
opened by vdweller84 0

Memory leak when returning usertype A from a usertype B member function when usertype B does not have a registered member variable.

I am currently using C++ in Visual Studio 2022. I noticed a weird memory leak in a program I was making and after some debugging, I found it. It is possible that I'm just doing something wrong but from what I can find, It seems that as the title says if you return a usertype A from a function that is a member of usertype B and usertype B does not have any member variables it will not delete the new instance of usertype A properly. Here is some example code to demonstrate the issue:

struct A
{
    int X;
    int Y;
};

struct B
{
    int Z;

    A Get()
    {
   	 return A();
    }
};

struct C
{
    A Get()
    {
   	 return A();
    }
};

int Main()
{
    std::string BScript =
    "local T = B:new()\n"
    "for i = 0, 1000 ^ 2.5 do\n"
    "    local Temp = T:Get()\n"
    "end\n";

    std::string CScript =
   	 "local T = C:new()\n"
   	 "for i = 0, 1000 ^ 2.5 do\n"
   	 "    local Temp = T:Get()\n"
   	 "end\n";

    {    
   	 std::cout << "This will not create a memory leak!" << std::endl;

   	 sol::state State;

   	 State.new_usertype<A>("A", sol::constructors<void()>(),
   		 "X", &A::X,
   		 "Y", &A::Y);

   	 State.new_usertype<B>("B", sol::constructors<void()>(),
   		 "Z", &B::Z,
   		 "Get", &B::Get);

   	 State.script(BScript);

   	 std::cout << "Done! Waiting..." << std::endl;

   	 _sleep(1000);
    }

    {
   	 std::cout << "This will create a memory leak!" << std::endl;

   	 sol::state State;

   	 State.new_usertype<A>("A", sol::constructors<void()>(),
   		 "X", &A::X,
   		 "Y", &A::Y);

   	 State.new_usertype<B>("B", sol::constructors<void()>(),
   		 "Get", &B::Get);

   	 State.script(BScript);   	 
   	 
   	 std::cout << "Done! Waiting..." << std::endl;

   	 _sleep(1000);
    }

    {
   	 std::cout << "This will also create a memory leak!" << std::endl;

   	 sol::state State;

   	 State.new_usertype<A>("A", sol::constructors<void()>(),
   		 "X", &A::X,
   		 "Y", &A::Y);

   	 State.new_usertype<C>("C", sol::constructors<void()>(),
   		 "Get", &C::Get);

   	 State.script(CScript);

   	 std::cout << "Done! Waiting..." << std::endl;

   	 _sleep(1000);
    }

    std::cout << "Program complete" << std::endl;

    while (true);

    return EXIT_SUCCESS;
}

The code contains three structs A, B and C, the functions B::Get and C::Get return a new instance of A.

The first block of code will register the structs A and B and the struct B will be registered with both a function and a variable. It then runs BScript which just calls the B::Get function a lot of times NOT CREATING a memory leak.

The second block of code will register the structs A and B and the struct B will register only its function. It then runs BScript which just calls the B::Get function a lot of times CREATING a memory leak. Presumably, because it doesn't have a registered variable?

The third block of code will register the structs A and C and the struct C will only contain one function which is registered. The purpose of this is to show that what's causing the memory leak isn't forgetting to register all member variables of a struct. It then runs CScript which just calls the C::Get function a lot of times CREATING a memory leak.

So, is this intended behaviour, am I doing something wrong or is this a bug?

opened by Kaj9296 0

Overloaded base function isn't called

struct Test1 {
    void test() {
    }
};
struct Test2 : Test1 {
    void test(int value) {
    }
};

Test2.new():test()
Test2.new():test(2) # error stack index 2, expected number, received no value: not a numeric type that fits exactly an integer (number maybe has significant decimals) (bad argument into 'void(int)')

Is this normal, or there is a bug somewhere?

opened by deadlocklogic 1

Segmentation fault when accessing objects inside a table with wrong type

Below program is crashing after throwing the exception when accessing "test2" with the incorrect type. Incorrectly accessing "test" is throwing as expected and program runs after that. The expected behavior I suggest would be just throw an exception and not crash afterwards.

I've tested this with sol 3.3.0 and Lua 5.3.6 and with sol 3.2.1 with Lua 5.3.5 (this is what compiler explorer is providing). It was working with the same Lua version before updating to sol3 with v2.20.6.

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

auto main() -> int {
    sol::state lua;
    lua["object"] = lua.create_table_with("test2", 10);
    lua["test"] = 10;

    try {
        std::cout << lua["test"].get<int>() << std::endl;
        std::cout << lua["test"].get<std::string>() << std::endl;
    } catch (const std::exception& e) {
        std::cout << "exception caught for test: " << e.what() << std::endl;
    }

    try {
        std::cout << lua["object"]["test2"].get<int>() << std::endl;
        std::cout << lua["object"]["test2"].get<std::string>() << std::endl;
    } catch (const std::exception& e) {
        std::cout << "exception caught for test2: " << e.what() << std::endl;
    }

    return 0;
}

Output:

Program returned: 139
munmap_chunk(): invalid pointer
10
exception caught for test: lua: error: stack index -1, expected string, received number
exception caught for test2: lua: error: attempt to index a string value

You can test it by yourself in compiler explorer: https://godbolt.org/z/ojbzMGsdf (not current sol2 version, but it fails in 3.3.0 as well)

The segfault is happening inside ltable.c at the marked Line:

static Node *mainposition (const Table *t, const TValue *key) {
  switch (ttype(key)) {
    case LUA_TNUMINT:
      return hashint(t, ivalue(key));
    case LUA_TNUMFLT:
      return hashmod(t, l_hashfloat(fltvalue(key)));
    case LUA_TSHRSTR:
      return hashstr(t, tsvalue(key));
    case LUA_TLNGSTR:
      return hashpow2(t, luaS_hashlongstr(tsvalue(key)));
    case LUA_TBOOLEAN:
      return hashboolean(t, bvalue(key));
    case LUA_TLIGHTUSERDATA:
      return hashpointer(t, pvalue(key));
    case LUA_TLCF:
      return hashpointer(t, fvalue(key));
    default:
      lua_assert(!ttisdeadkey(key));
      return hashpointer(t, gcvalue(key)); // <----
  }
}

My current workaround is to check against the type before converting, but I relied on the exceptions on version v2.20.6 and I'm worried that I'm introducing crashes somewhere I'm currently not aware of.

opened by dns13 1

Releases(v3.3.0)

v3.3.0(Jun 25, 2022)
🎉 v3.3.0

This follows the version 3 release, incorporating a few improvements from the still-in-progress v4 and a number of critical fixes for keep-alive during iteration (especially w.r.t. Lua coroutines) and fixes for Lua 5.4. It also cleans up some logical bugs in many different places and improves the header hygiene.

It also gives a chance to update various package managers which were waiting for a newer stable release.

What's Changed

Add CMake option to disable installation by @violinyanev in https://github.com/ThePhD/sol2/pull/1056

Fix typos in configuration macros. by @atom0s in https://github.com/ThePhD/sol2/pull/1058

Add override qualifier to bad_optional_access::what() by @cuavas in https://github.com/ThePhD/sol2/pull/1065

Fixed typos in quick n' dirty tutorial. by @TwinHits in https://github.com/ThePhD/sol2/pull/1077

Ignore unused variables; Ignore -Wshadow and -Wconversion on Clang by @dimitrisudell in https://github.com/ThePhD/sol2/pull/1059

Fix argument usage typo. by @atom0s in https://github.com/ThePhD/sol2/pull/1091

Support constexpr boost::none with recent Boost versions. by @vlichevsky in https://github.com/ThePhD/sol2/pull/1129

Remove duplicate constructor type section from docs by @Riyyi in https://github.com/ThePhD/sol2/pull/1116

Added FFI enabled check by @RinatNamazov in https://github.com/ThePhD/sol2/pull/1194

Fix sol2 cmake include failing as a dependency by @edunad in https://github.com/ThePhD/sol2/pull/1196

Fix aligned memory allocation by @Smertig in https://github.com/ThePhD/sol2/pull/1193

Update is_string_constructible for C++23 P2166R1 by @StephanTLavavej in https://github.com/ThePhD/sol2/pull/1222

Fixed: std::cout not found on msvc by @Klaim in https://github.com/ThePhD/sol2/pull/1295

Add missing parenthesis for std::max by @halx99 in https://github.com/ThePhD/sol2/pull/1292

Fix issues with is_c_str_or_string and is_c_str by @cschreib in https://github.com/ThePhD/sol2/pull/1331

🐛 Fix #1346 by @Immortalety in https://github.com/ThePhD/sol2/pull/1347

✨ Test and fix #1315 by @ShepherdSoasis in https://github.com/ThePhD/sol2/pull/1369

CMake: Build LuaJIT: use copy_if_different by @DerSauron in https://github.com/ThePhD/sol2/pull/1352

Fix compile error when registering new user types with operator() by @matusfedorko in https://github.com/ThePhD/sol2/pull/1277

fix #1354 by @qinix in https://github.com/ThePhD/sol2/pull/1355

New Contributors

@violinyanev made their first contribution in https://github.com/ThePhD/sol2/pull/1056

@atom0s made their first contribution in https://github.com/ThePhD/sol2/pull/1058

@cuavas made their first contribution in https://github.com/ThePhD/sol2/pull/1065

@TwinHits made their first contribution in https://github.com/ThePhD/sol2/pull/1077

@dimitrisudell made their first contribution in https://github.com/ThePhD/sol2/pull/1059

@vlichevsky made their first contribution in https://github.com/ThePhD/sol2/pull/1129

@Riyyi made their first contribution in https://github.com/ThePhD/sol2/pull/1116

@RinatNamazov made their first contribution in https://github.com/ThePhD/sol2/pull/1194

@edunad made their first contribution in https://github.com/ThePhD/sol2/pull/1196

@StephanTLavavej made their first contribution in https://github.com/ThePhD/sol2/pull/1222

@Klaim made their first contribution in https://github.com/ThePhD/sol2/pull/1295

@halx99 made their first contribution in https://github.com/ThePhD/sol2/pull/1292

@cschreib made their first contribution in https://github.com/ThePhD/sol2/pull/1331

@Immortalety made their first contribution in https://github.com/ThePhD/sol2/pull/1347

@ShepherdSoasis made their first contribution in https://github.com/ThePhD/sol2/pull/1369

@DerSauron made their first contribution in https://github.com/ThePhD/sol2/pull/1352

@matusfedorko made their first contribution in https://github.com/ThePhD/sol2/pull/1277

@qinix made their first contribution in https://github.com/ThePhD/sol2/pull/1355

Full Changelog: https://github.com/ThePhD/sol2/compare/v3.2.3...v3.3.0
Source code(tar.gz)
Source code(zip)
config.hpp(2.04 KB)
forward.hpp(37.19 KB)
sol.hpp(978.14 KB)
v3.2.2(Oct 4, 2020)
This release is a patch update. It adds a new feature but because that feature is gated behind a macro definition, the minor nor major versions are changed. New code should be unaffected!

New feature: function pointer retrieval! It is not on by default!

Please note this is unsafe, see the documentation for SOL_GET_FUNCTION_POINTERS_UNSAFE - https://sol2.readthedocs.io/en/latest/safety.html

A UBSan error for null pointer arithmetic was fixed up, resulting in UB-free codegen (It hadn't become a problem yet, but it was probably going to! #1017)

load_result and friends are not copyable. They were never supposed to be, and since I only ever used them transiently it almost never came up until now (#995)

An API for accessing and messing with the garbage collector has been added (#997)

MoonJIT is totally supported. The author was very nice to us! (#967)

Recently, documentation was improved around certain configuration macros (https://sol2.readthedocs.io/en/latest/safety.html):

SOL_CONTAINERS_START

SOL_NO_THREAD_LOCAL

SOL_ID_SIZE

Configuration has been reworked through the library:

The user-facing definitions are, however, the same, and cleaned up a little bit.

You can place a folder and a in some directly that follows the convention <sol/config.hpp> and put your macro definitions in there to make it easier to manage your library-specific defines. This makes it easier to keep all your definitions together.

Build issues on all systems from Mac OSX with Apple Clang to Windows with VC++ should be resolved now! (#1021 #1031 #1034)

Issues with certain constant definitions in the Lua 5.4 release should not happen.

Fixed some bugs in the use of is_lvalue_reference (thanks, #1028 !)

Source code(tar.gz)
Source code(zip)
config.hpp(2.04 KB)
forward.hpp(24.72 KB)
sol.hpp(897.35 KB)
v3.2.1(Jun 6, 2020)

This release is basically what it says on the tin: please stop erroring my users, Visual Studio.

Pretty please. :)
Source code(tar.gz)
Source code(zip)
forward.hpp(13.07 KB)
sol.hpp(874.88 KB)
v3.0.3(Jul 4, 2019)
The tutorials were made better!

C++ in Lua walkthrough was greatly enhanced for quality: https://sol2.readthedocs.io/en/latest/tutorial/cxx-in-lua.html

Ownership is now very clearly explained (or at least better than before): https://sol2.readthedocs.io/en/latest/tutorial/ownership.html

And various other minor documentation improvements

Some variant fixes were deployed and more CMake fiddling was done.

Have fun!~
Source code(tar.gz)
Source code(zip)
forward.hpp(14.77 KB)
sol.hpp(871.93 KB)
v3.0.2(May 29, 2019)
This is the official sol3 release. Get it while it's hot, and read up about it using the blog posts and the documentation:

https://thephd.github.io/sol3-released

https://thephd.github.io/sol3-compile-times-binary-sizes

https://sol2.rtfd.io

Thank you for your love and support over the years!
Source code(tar.gz)
Source code(zip)
forward.hpp(14.71 KB)
sol.hpp(862.93 KB)
v2.20.6(Nov 28, 2018)

This fix backports a handling of the regular std::optional properly.

Thanks to everyone who made this release nice!
Source code(tar.gz)
Source code(zip)
sol.hpp(743.93 KB)
sol_forward.hpp(11.55 KB)
v2.20.5(Nov 10, 2018)

This release is a move of some of the bugfixes and improvements that were contained in sol3 back into sol2, with some modification to not break things!

This closes all known open issues, including those reported privately VIA Discord and E-mail. Thank you for your help in making sol2 great!
Source code(tar.gz)
Source code(zip)
sol.hpp(740.93 KB)
sol_forward.hpp(11.55 KB)
v2.20.4(Aug 4, 2018)

This release adds a number of bug fixes to 2.20 backported from current sol3 development. No major features were added in this change and it solves quite a few problems.
Source code(tar.gz)
Source code(zip)
sol.hpp(740.10 KB)
sol_forward.hpp(11.55 KB)
v2.20.2(May 22, 2018)

With the new logo in place and everything prepared, I'm going to be focusing on developing for sol v3 now.

This last release focuses on getting the semantics for configuration macros right and fixing some older warnings. It also handles some integer madness and does its best to straighten out exceptions.

Newer development is going to specifically use features from C++17 and C++20, in an effort to bring the same performance, with BETTER, compile times and to investigate some of the issues discovered while writing the C++Now talk. This means that the v2.x.x releases will still work with VS 2015, and older toolsets, but the stuff in the branch sol3 will not.

The sol3 branch will not be merged anytime soon, so don't worry about anything breaking unduly!

Thanks for using sol2.
Source code(tar.gz)
Source code(zip)
sol.hpp(723.00 KB)
sol_forward.hpp(11.37 KB)
v2.19.5(Mar 6, 2018)

This release is a small Quality of Implementation fix. sol::reference and sol::object (but not their derived types) accept nil/none as types now when passing from C++-bound Lua functions. This emulates the default behavior of how Lua functions work. It also contains minor fixes for const vs. nonconst size() functions.

This release also allows you to call the same function sol2 uses to set up good default tracebacks and a proper default protected_function error handler.

Docs: sol2.readthedocs.io/en/latest/api/state.html#sol-state-automatic-handlers

Example: https://github.com/ThePhD/sol2/blob/develop/examples/functions_empty_arguments.cpp
Source code(tar.gz)
Source code(zip)
sol.hpp(703.43 KB)
sol_forward.hpp(9.11 KB)
v2.19.4(Mar 2, 2018)

This release provides an opt-out parameter for automagical types, full-on CMake support, and a myriad of other fixes and tweaks (especially to handle Eigen types). Thanks you everyone who reported issues and helped refine the library!

This release also adds a new feature: sol::yielding, to define a function that yields it results back to Lua's control.

Coroutines can now be constructed with an error_handler parameter, and sol2 will call that error handler in the case of failure to execute (much like protected_function). The default handler provides a traceback.

yielding: http://sol2.readthedocs.io/en/latest/api/yielding.html automagical-opt-out: http://sol2.readthedocs.io/en/latest/api/usertype.html#automagical-usertypes codecvt cleaned out: http://sol2.readthedocs.io/en/latest/codecvt.html

A new single header is provided, called "sol_forward": this contains all the forwarded declarations and allows some saving on compile times.
Source code(tar.gz)
Source code(zip)
sol.hpp(701.34 KB)
sol_forward.hpp(9.11 KB)
v2.18.7(Nov 21, 2017)

This release adds a coroutine guard from an issue investigation on gitter and prepares for new_experimental_usertype, and updates the readme and documentation to include a link for financial support, if that's your thing.

Thank you for using sol2.
Source code(tar.gz)
Source code(zip)
sol.hpp(662.99 KB)
v2.18.6(Nov 21, 2017)

This release adds some work arounds for classes that are declared final and thusly can't use sol's callable traits due to that limitation. It also improves the error handling and report for users who get errors with userdata, reporting a mirror of the actual type's name.

This release also adds iterators to function result/protected function result, making them iterable by a terse for loop. An ipairs implementation swapping bug was also fixed in this release. LuaJIT should also no longer absolutely consume errors thrown by C++ on Linux and Windows.

The tutorials and documentation have seen heavy improvements, and some of the tutorial code has now been properly serialized into a place for everyone to get it: https://github.com/ThePhD/sol2/tree/develop/examples/tutorials/quick_n_dirty

http://sol2.readthedocs.io/en/latest/tutorial/all-the-things.html
Source code(tar.gz)
Source code(zip)
sol.hpp(662.04 KB)
v2.18.5(Oct 30, 2017)

This release adds some work arounds for classes that are declared final and thusly can't use sol's callable traits due to that limitation. It also improves the error handling and report for users who get errors with userdata, reporting a mirror of the actual type's name.

This release also changes how expections are handled when we detect that it is possible to propagate errors through the Lua API boundary (e.g., when they're compiled as C++ or you're using LuaJIT compiled for a proper platform). In this case, we won't catch all exceptions: instead, they will be thrown without holding onto them.

Also fixes: pairs/ipairs iteration bug
Source code(tar.gz)
Source code(zip)
sol.hpp(653.04 KB)
v2.18.4(Sep 24, 2017)

This release of sol2 includes the addition of a new userdata checker/getter paradigm that allows non-sol2 usertypes to be integrated with sol2's mechanisms. There are a good chunk of examples from popular external frameworks, showcasing ways to do it. You can add your own custom logic to enable sol2 in your already millions-of-lines codebase and slowly ease out other libraries -- or not, and have the two play together perfectly nicely!

Find your framework here, or just take a peek to see how it's done: https://github.com/ThePhD/sol2/tree/develop/examples/interop Read about it in the stack API: http://sol2.readthedocs.io/en/latest/api/stack.html#objects-extension-points

Thanks to @feltech for bringing this to my attention and helping me work on it.

Have fun, everyone!
Source code(tar.gz)
Source code(zip)
sol.hpp(637.82 KB)
v2.18.3(Sep 22, 2017)
This release adds major additional support for coroutines and threading, improving the documentation and adding examples to demonstrate new uses. It also outlines a few helpful ways to handle multiple threads in a Lua environment and ways that it can affect things.

Threading: http://sol2.readthedocs.io/en/latest/threading.html

New Coroutine Example: https://github.com/ThePhD/sol2/blob/develop/examples/coroutine_state.cpp

This release also includes a new compatibility layer and a shiny new clang formatter and the preparations for more robust cross-platform testing.

Thank you to everyone who contributed to this release!
Source code(tar.gz)
Source code(zip)
sol.hpp(635.41 KB)
v2.18.2(Sep 3, 2017)

This release adds some much-needed clarity to the error messages received. Alongside stack information, more descriptive errors are now serialized into the error strings, increasing the ability to reason about bugs. Android bugs and small typos have also been corrected.

This release also includes a breaking change that will affect a tiny fraction of users using the nitty-gritty of the customization points with full-fledged customization points for their own type. Specifically, the checker now needs a handler that takes 5 arguments, not 4 (the last is an error message). All handlers must be updated to take const char* or similar.
Source code(tar.gz)
Source code(zip)
sol.hpp(604.62 KB)
v2.18.1(Aug 28, 2017)
This is an important bugfix release that fixes some garbage collection errors in simple_usertype and solves a variety of bugs. It also introduces a new modifer on functions and arguments to C/C++ function calls called "filters", similar to luabind's reference_to and policies. sol2 should now be nearly 100% feature-parity with luabind.

Happy porting!

Features:

sol::filters abstraction -- thanks to @mrgreywater and @OrfeasZ for the bikeshedding and help in developing this feature. Implements #472.

__tostring metamethods are now generated from operator<<, to_string(obj), or obj.to_string() calls

Fixes:

Android not putting its math functions in the std:: namespace for some reason: #488

Bogus alignment errors: #487 (also fixed by upgrading VS2017 to its latest version)

Add explanations to heap space errors: #496 (http://sol2.readthedocs.io/en/latest/errors.html#compiler-out-of-heap-space)

Fix issues with indestructible types and virtual destructor types: #492

Garbage collection issues: #489 #490 #491

Garbage collection is now applied to types even if someone does not specify a usertype for it. If the type is non-destructible, it will plant an erroring garbage collection function warning you of undefined behavior if you do not register a usertype in time to handle it

Source code(tar.gz)
Source code(zip)
sol.hpp(600.26 KB)
v2.18.0(Aug 14, 2017)
This is an enormous improvement release that adds several new features, including support for many household name C++17 types (variant and the like). It also includes a small amount of integer handling safety thanks to @mrgreywater and some inspiration for handling and dealing with containers types thanks to @iaz3 .

Notables:

NEW Container support, overhauled and overridable by users (inspired by @s13n): http://sol2.readthedocs.io/en/latest/containers.html

A new example for using require in Lua code with a DLL that is built with sol2: https://github.com/ThePhD/sol2/tree/develop/examples/require_dll_example

A new example for working with containers and messing with traits: https://github.com/ThePhD/sol2/blob/develop/examples/container_usertype_as_container.cpp

Additional automatically-generated usertype operations, including tostring and pairs (pairs metamethod is only available in Lua 5.2+): https://github.com/ThePhD/sol2/blob/develop/examples/usertype_automatic_operators.cpp

Overloading fallbacks for constructors and functions using variadic_args: https://github.com/ThePhD/sol2/blob/develop/examples/overloading_with_fallback.cpp

New number handling for safety, triggered by SOL_CHECK_ARGUMENTS. See this page for more information about safety changes: http://sol2.readthedocs.io/en/latest/safety.html#config

This release also introduces:

necessary thread safety usages when creating multiple states across threads (solving #458)

some new functions to work safely with called code: http://sol2.readthedocs.io/en/latest/api/state.html#state-script-function

additional handling for __stdcall on x86, solving @horatii's issue in #463 permanently (thanks for introducing a good fix on x86, @horatii)

Support for g++ 7.x.x and Visual Studio 2017+

Source code(tar.gz)
Source code(zip)
sol.hpp(580.29 KB)
v2.17.5(Jun 13, 2017)

This release marks one of the last ones that will support GCC 4.x, Clang 3.4/3.5/3.6, and old version of Visual Studio 2015. It contains fixes for MinGW's bad std::wstring/std::u16string handling, and some minor changes to handle compilation issues and new warnings on GCC 7.x. Bugfixes for older compilers will continue into the future for some time.

For more information about what is happening with older compilers, see: http://sol2.readthedocs.io/en/latest/compilation.html#supported-compilers

sol2's future will be focusing on leveraging new C++17 features and types (std::any, std::variant, etc.) when they become widely-available across the Big Three™ compilers. Since sol2 has been feature-complete for a long time, future versions will more or less contain bells and whistles, and most of the code here is fairly bug-free for most uses.

Thank you for supporting sol2, and we hope you continue using it into the far future.
Source code(tar.gz)
Source code(zip)
sol.hpp(495.18 KB)
v2.17.4(May 21, 2017)

This release is a small patchfix to fix the way sol::readonly and std:: containers behave with move-only types. Documentation was updated for sol::readonly and the library was vetted for uses of is_const and is_copy_assignable. Documentation was also updated for Compiler Errors under the Error page in the sol2 documentation: http://sol2.readthedocs.io/en/latest/errors.html#compiler-errors-warnings

Please do upgrade as soon as possible!
Source code(tar.gz)
Source code(zip)
sol.hpp(470.28 KB)
v2.17.3(May 17, 2017)

This release includes some fixes for LuaJIT's beta. Please use LuaJIT-beta3, and not LuaJIT-beta2, as it is redefining some functions present in the compatibility wrapper but does not include its semantic versioning scheme in any of its macros in a usable format.

This also fixes a bug in VS2013 CTP+ that does not perform qualified name lookup properly, even with a template alias.

Finally, this_environment -- a convenience transparent function -- is now in sol2. Note that it does not work too terribly well when combined with someone calling a Lua function directly from C++ using std::function, sol::function, or similar. But, it will capture the environment of a script or function in a script calling your code fairly effectively.

Docs: http://sol2.readthedocs.io/en/latest/api/this_environment.html

Have fun!
Source code(tar.gz)
Source code(zip)
sol.hpp(470.05 KB)
v2.17.1(Apr 25, 2017)

This release adds the ability to get environments from Lua, because I sort of forgot about that when we were implementing setting environments and it never came up until now!

This is a minor release, unless you really need the above feature. Then it's probably major for you! Also some minor fixes, here 'n' there.
Source code(tar.gz)
Source code(zip)
sol.hpp(465.05 KB)
v2.17.0(Apr 16, 2017)
I never expected to make this release, but just a short while after 2.16 there is now a 2.17.0! This release includes Environments, alongside a number of small bugfixes related to globals and static order initialization explosions.

state_view::script: overloads for accepting environments and error handling functions

sol::environment: support for sandboxing code more easily and inheriting parent environments

sol::new_table/sol::create: for creating new tables easier without an empty state_view::create_table call.

Improved Examples: for environments on functions and being safe while calling a script!

Source code(tar.gz)
Source code(zip)
sol.hpp(455.83 KB)
v2.16.0(Mar 26, 2017)

This release adds a new type of constructor syntax to usertypes and also allows them to be extended with methods defined in Lua at runtime or added through the named usertype table using the Lua API in C++. It also fixes numerous bugs and beefs up the testing suite to ensure that users are guaranteed a level of functional programming while using sol2.

This also marks a level of "feature-completeness". Beyond users making new recommendations for features, this code is essentially deployment and production ready, as it has been for several releases, but now even moreso. There are no more planned features until C++21/22, when reflection will allow us to automate usertype creation entirely.

Thanks for helping to make sol2 a wonderful library, and keep posting issues when you come across them!
Source code(tar.gz)
Source code(zip)
sol.hpp(443.42 KB)
v2.15.9(Feb 20, 2017)

This release fixes a number of bugs related to usertypes and how they were used, including #346 - #347, #345 an #344!

It also addressed a critical issue with usertypes and returning a temporary reference if you utilized a customization point in a specific manner. (#348)
Source code(tar.gz)
Source code(zip)
sol.hpp(439.06 KB)
v2.15.8(Feb 19, 2017)

This release fixes many bugs that were filed between now and the last release, improving stability and solving a few very subtle "ouches" that affected a small portion of users rather prominently. Thanks to everyone who reported issues!

It is highly recommended to upgrade to this version immediately, even if none of the bugs affected you directly.
Source code(tar.gz)
Source code(zip)
sol.hpp(437.87 KB)
v2.15.7(Jan 7, 2017)

This release adds some state and thread awareness to the various pushers for sol2, making it easier to work with threads and pass arguments off to coroutines inside of C++.

Fixes: #309 - this issue inspired adding the support as well as figuring out more about threading in general
Source code(tar.gz)
Source code(zip)
sol.hpp(433.43 KB)
v2.15.6(Jan 7, 2017)

This release addresses a number of minor bugs and provides some updated documentation, as well as gives a new definition for handling Lua compiled as C++.

Fixes: #306 - Building Lua as C++ now has a definition to make it easier to work with sol2: http://sol2.readthedocs.io/en/latest/errors.html#linker-errors #304 - LuaJIT condition fixes #305 - default handlers becoming invalid for a given Lua state (still potentially problematic: e.g., see multiple Lua states and the fact that the function is static, provides a bit of a problem) #301 - Thread state deadness was default-defined, now defined to an out-of-the-way value #300 - Apple build failures not a problem, thankfully
Source code(tar.gz)
Source code(zip)
sol.hpp(433.22 KB)
v2.15.4(Dec 5, 2016)
This release addresses a long-standing fix that would drop a reference and leak it when copying. The fix was really simple but it's really important, so upgrade immediately!

Fixes #284

Source code(tar.gz)
Source code(zip)
sol.hpp(426.15 KB)