yielding, forward declarations, automagical opt-out, unicode

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.

coroutine guard

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.

Improved Error Handling, "final" keyword handling, Tutorials, better Exception handling and more

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

v2.18.5

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

Interop and Integration

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!

lua_xmove, improved threading, and performance improvements

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!

Android Fixes and Error String Improvements

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.

Filters, Garbage Collection, and Automatic Usertype improvements

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

automatic operators, C++17 support, as_container, LuaJIT beta and more

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+

C++14, Old Compilers, and the Future

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.