summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/sol2/docs
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/sol2/docs')
-rw-r--r--3rdparty/sol2/docs/source/api/containers.rst2
-rw-r--r--3rdparty/sol2/docs/source/api/function.rst8
-rw-r--r--3rdparty/sol2/docs/source/api/resolve.rst28
-rw-r--r--3rdparty/sol2/docs/source/codecvt.rst2
-rw-r--r--3rdparty/sol2/docs/source/conf.py2
-rw-r--r--3rdparty/sol2/docs/source/errors.rst8
-rw-r--r--3rdparty/sol2/docs/source/exceptions.rst36
-rw-r--r--3rdparty/sol2/docs/source/mentions.rst5
-rw-r--r--3rdparty/sol2/docs/source/performance.rst1
-rw-r--r--3rdparty/sol2/docs/source/safety.rst4
-rw-r--r--3rdparty/sol2/docs/source/usertypes.rst5
11 files changed, 78 insertions, 23 deletions
diff --git a/3rdparty/sol2/docs/source/api/containers.rst b/3rdparty/sol2/docs/source/api/containers.rst
index 81bbdc40584..8e084a908fd 100644
--- a/3rdparty/sol2/docs/source/api/containers.rst
+++ b/3rdparty/sol2/docs/source/api/containers.rst
@@ -100,4 +100,4 @@ If you have a type that has ``begin`` or ``end`` member functions but don't prov
namespace sol {
template <>
struct is_container<not_container> : std::false_type {};
- }
+ } \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/function.rst b/3rdparty/sol2/docs/source/api/function.rst
index 93adedabe49..1056bd2fe95 100644
--- a/3rdparty/sol2/docs/source/api/function.rst
+++ b/3rdparty/sol2/docs/source/api/function.rst
@@ -82,13 +82,17 @@ This makes it much easier to work with multiple return values. Using ``std::tie`
Calls the function. The second ``operator()`` lets you specify the templated return types using the ``my_func(sol::types<int, std::string>, ...)`` syntax. Function assumes there are no runtime errors, and thusly will call the ``atpanic`` function if an error does occur.
+
+.. _function-argument-handling:
+
+functions and argument passing
+------------------------------
+
.. note::
All arguments are forwarded. Unlike :doc:`get/set/operator[] on sol::state<state>` or :doc:`sol::table<table>`, value semantics are not used here. It is forwarding reference semantics, which do not copy/move unless it is specifically done by the receiving functions / specifically done by the user.
-.. _function-argument-handling:
-
.. note::
This also means that you should pass and receive arguments in certain ways to maximize efficiency. For example, ``sol::table``, ``sol::object``, ``sol::userdata`` and friends are fairly cheap to copy, and should simply by taken as values. This includes primitive types like ``int`` and ``double``. However, C++ types -- if you do not want copies -- should be taken as ``const type&`` or ``type&``, to save on copies if it's important. Note that taking references from Lua also means you can modify the data inside of Lua directly, so be careful. Lua by default deals with things mostly by reference (save for primitive types).
diff --git a/3rdparty/sol2/docs/source/api/resolve.rst b/3rdparty/sol2/docs/source/api/resolve.rst
index d8811d43f5c..193e2fae80f 100644
--- a/3rdparty/sol2/docs/source/api/resolve.rst
+++ b/3rdparty/sol2/docs/source/api/resolve.rst
@@ -7,9 +7,9 @@ utility to pick overloaded C++ function calls
:caption: function: resolve C++ overload
template <typename... Args, typename F>
- auto resolve( F f );
+ constexpr auto resolve( F f );
-``resolve`` is a function that is meant to help users pick a single function out of a group of overloaded functions in C++. You can use it to pick overloads by specifying the signature as the first template argument. Given a collection of overloaded functions:
+``resolve`` is a function that is meant to help users pick a single function out of a group of overloaded functions in C++. It works for *both member and free functions* You can use it to pick overloads by specifying the signature as the first template argument. Given a collection of overloaded functions:
.. code-block:: cpp
:linenos:
@@ -18,6 +18,12 @@ utility to pick overloaded C++ function calls
int overloaded(int x, int y);
int overloaded(int x, int y, int z);
+ struct thing {
+ int overloaded(int x);
+ int overloaded(int x, int y);
+ int overloaded(int x, int y, int z);
+ };
+
You can disambiguate them using ``resolve``:
.. code-block:: cpp
@@ -26,6 +32,7 @@ You can disambiguate them using ``resolve``:
auto one_argument_func = resolve<int(int)>( overloaded );
auto two_argument_func = resolve<int(int, int)>( overloaded );
auto three_argument_func = resolve<int(int, int, int)>( overloaded );
+ auto member_three_argument_func = resolve<int(int, int, int)>( &thing::overloaded );
This resolution becomes useful when setting functions on a :doc:`table<table>` or :doc:`state_view<state>`:
@@ -37,3 +44,20 @@ This resolution becomes useful when setting functions on a :doc:`table<table>` o
lua.set_function("a", resolve<int(int)>( overloaded ) );
lua.set_function("b", resolve<int(int, int)>( overloaded ));
lua.set_function("c", resolve<int(int, int, int)>( overloaded ));
+
+
+It can also be used with :doc:`sol::c_call<c_call>`:
+
+.. code-block:: cpp
+ :linenos:
+
+ sol::state lua;
+
+ auto f = sol::c_call<
+ decltype(sol::resolve<int(int, int)>(&overloaded)),
+ sol::resolve<int(int, int)>(&overloaded)
+ >;
+ lua.set_function("f", f);
+
+ lua.script("f(1, 2)");
+
diff --git a/3rdparty/sol2/docs/source/codecvt.rst b/3rdparty/sol2/docs/source/codecvt.rst
index ff901edea1e..750f6936bd3 100644
--- a/3rdparty/sol2/docs/source/codecvt.rst
+++ b/3rdparty/sol2/docs/source/codecvt.rst
@@ -3,6 +3,6 @@ std::(w/u16/u32)string support
because this is surprisingly hard using standard C++
----------------------------------------------------
-Individuals using Visual Studio 2015, or on Windows with the VC++ and MinGW compilers (possibly Clang++ on Windows as well) have ``<codecvt>`` headers, and thusly Sol will attempt to include it. Individuals on GC 4.9.x, Clang 3.5.x, Clang 3.6.x do not seem to have ``<codecvt>`` shipped with the standard library that comes with installation of these compilers. If you want ``std::wstring``, ``std::u16string``, ``std::u32string`` automatic handling then you need to make sure you have those headers and then define ``SOL_CODECVT_SUPPORT``.
+Individuals using Visual Studio 2015, or on Windows with the VC++ and MinGW compilers (possibly Clang++ on Windows as well) have ``<codecvt>`` headers, and thusly Sol will attempt to include it. Individuals on GC 4.9.x, Clang 3.5.x, Clang 3.6.x do not seem to have ``<codecvt>`` shipped with the standard library that comes with installation of these compilers. If you want ``std::wstring``, ``std::u16string``, ``std::u32string`` automatic handling then you need to make sure you have those headers and then define ``SOL_CODECVT_SUPPORT`` on unsupported compilers.
ThePhD did not want this to have to be a thing, but slow implementations and such force their hand. When GCC 7.x comes out, ThePhD will consider removing the effect of defining this macro and leaving <codecvt> support in at all times.
diff --git a/3rdparty/sol2/docs/source/conf.py b/3rdparty/sol2/docs/source/conf.py
index 9b78b5d59b6..e69c2f79f84 100644
--- a/3rdparty/sol2/docs/source/conf.py
+++ b/3rdparty/sol2/docs/source/conf.py
@@ -61,7 +61,7 @@ author = 'ThePhD'
# The short X.Y version.
version = '2.15'
# The full version, including alpha/beta/rc tags.
-release = '2.15.0'
+release = '2.15.1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/3rdparty/sol2/docs/source/errors.rst b/3rdparty/sol2/docs/source/errors.rst
index f017daad328..5088c09e48e 100644
--- a/3rdparty/sol2/docs/source/errors.rst
+++ b/3rdparty/sol2/docs/source/errors.rst
@@ -10,8 +10,9 @@ Catch and CRASH!
By default, Sol will add a ``default_at_panic`` handler. 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 :doc:`exceptions in Sol here<exceptions>`.
-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.
+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 :ref:`here<typical-panic-function>`.
Destructors and Safety
@@ -25,6 +26,11 @@ Protected Functions and Access
By default, :doc:`sol::function<api/function>` assumes the code ran just fine and there are no problems. :ref:`sol::state(_view)::script(_file)<state-script-function>` also assumes that code ran just fine. Use :doc:`sol::protected_function<api/protected_function>` to have function access where you can check if things worked out. Use :doc:`sol::optional<api/optional>` to get a value safely from Lua. Use :ref:`sol::state(_view)::do_string/do_file/load/load_file<state-do-code>` 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 :doc:`sol::protected_function<api/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.
+
Raw Functions
-------------
diff --git a/3rdparty/sol2/docs/source/exceptions.rst b/3rdparty/sol2/docs/source/exceptions.rst
index 13be8b9a667..0e6584a20ef 100644
--- a/3rdparty/sol2/docs/source/exceptions.rst
+++ b/3rdparty/sol2/docs/source/exceptions.rst
@@ -11,23 +11,27 @@ To make this not be the case, you can set a panic function directly with ``lua_a
.. code-block:: cpp
:caption: regular panic function
+ :name: typical-panic-function
#include <sol.hpp>
#include <iostream>
- int my_panic_function( lua_State* L ) {
- // error message is at the top of the stack
- const char* message = lua_tostring(L, -1);
- // message can be null, so don't crash
- // us with nullptr-constructed-string if it is
- std::string err = message ? message : "An unexpected error occurred and forced the lua state to call atpanic";
- // Weee
- std::cerr << err << std::endl;
+ inline void my_panic(sol::optional<std::string> maybe_msg) {
+ std::cerr << "Lua is in a panic state and will now abort() the application" << std::endl;
+ if (maybe_msg) {
+ const std::string& msg = maybe_msg.value();
+ std::cerr << "\terror message: " << msg << std::endl;
+ }
// When this function exits, Lua will exhibit default behavior and abort()
}
int main () {
- sol::state lua(my_panic_function);
+ sol::state lua(sol::c_call<decltype(&my_panic), &my_panic>);
+ // or, if you already have a lua_State* L
+ // lua_atpanic( L, sol::c_call<decltype(&my_panic)>, &my_panic> );
+ // or, with state/state_view:
+ // sol::state_view lua(L);
+ // lua.set_panic( sol::c_call<decltype(&my_panic)>, &my_panic> );
}
@@ -41,11 +45,21 @@ If there is a place where a throw statement is called or a try/catch is used and
LuaJIT and exceptions
---------------------
-It is important to note that a popular 5.1 distribution of Lua, LuaJIT, has some serious `caveats regarding exceptions`_. LuaJIT's exception promises are flaky at best on x64 (64-bit) platforms, and entirely terrible on non-x64 (32-bit, ARM, etc.) platorms. The trampolines we have in place for all functions bound through conventional means in Sol will catch exceptions and turn them into Lua errors so that LuaJIT remainds unperturbed, but if you link up a C function directly yourself and throw, chances are you might have screwed the pooch.
+It is important to note that a popular 5.1 distribution of Lua, LuaJIT, has some serious `caveats regarding exceptions`_. LuaJIT's exception promises are flaky at best on x64 (64-bit) platforms, and entirely terrible on non-x64 (32-bit, ARM, etc.) platforms. The trampolines we have in place for all functions bound through conventional means in Sol will catch exceptions and turn them into Lua errors so that LuaJIT remainds unperturbed, but if you link up a C function directly yourself and throw, chances are you might have screwed the pooch.
Testing in `this closed issue`_ that it doesn't play nice on 64-bit Linux in many cases either, especially when it hits an error internal to the interpreter (and does not go through Sol). We do have tests, however, that compile for our continuous integration check-ins that check this functionality across several compilers and platforms to keep you protected and given hard, strong guarantees for what happens if you throw in a function bound by Sol. If you stray outside the realm of Sol's protection, however... Good luck.
+Lua and LuaJIT C++ Exception Full Interoperability
+--------------------------------------------------
+
+You can ``#define SOL_EXCEPTIONS_SAFE_PROPAGATION`` before including Sol or define ``SOL_EXCEPTIONS_SAFE_PROPAGATION`` on the command line if you know your implmentation of Lua has proper unwinding semantics that can be thrown through the version of the Lua API you have built / are using.
+
+This will prevent sol from catching ``(...)`` errors in platforms and compilers that have full C++ exception interoperability. This means that Lua errors can be caught with ``catch (...)`` in the C++ end of your code after it goes through Lua, and exceptions can pass through the Lua API and Stack safely.
+
+Currently, the only known platform to do this is the listed "Full" `platforms for LuaJIT`_ and Lua compiled as C++. This define is not turned on automatically, even if Sol detects LuaJIT: *it is your job to define it if you know that your platform supports it*!
+
.. _issue: https://github.com/ThePhD/sol2/issues/
.. _at_panic: http://www.Lua.org/manual/5.3/manual.html#4.6
.. _caveats regarding exceptions: http://luajit.org/extensions.html#exceptions
-.. _this closed issue: https://github.com/ThePhD/sol2/issues/28 \ No newline at end of file
+.. _platforms for LuaJIT: http://luajit.org/extensions.html#exceptions
+.. _this closed issue: https://github.com/ThePhD/sol2/issues/28
diff --git a/3rdparty/sol2/docs/source/mentions.rst b/3rdparty/sol2/docs/source/mentions.rst
index 72330a8a5a9..7ce2a1f3485 100644
--- a/3rdparty/sol2/docs/source/mentions.rst
+++ b/3rdparty/sol2/docs/source/mentions.rst
@@ -24,7 +24,8 @@ Okay, so the features don't convince you, the documentation doesn't convince you
| |before| | |after| |
+----------+---------+
-
+* The `Multiple Arcade Machine Emulator (MAME)`_ project switched from using LuaBridge to sol2!
+ - `The pull request`_ in which it was introduced to the master branch.
* (CppNow) sol2 was mentioned in a comparison to other scripting languages by ChaiScript developer, Jason Turner (@lefticus), at a conference!
- `Jason Turner's presentation`_
* (CppCast) Showed up in CppCast with Elias Daler!
@@ -57,3 +58,5 @@ Are you using sol2 for something neat? Want it to be featured here or think it's
.. _sol2's initial reddit release: https://www.reddit.com/r/cpp/comments/4a8gy7/sol2_lua_c_binding_framework/
.. _Benchmarking Discussing: https://www.reddit.com/r/cpp/comments/4x82hd/plain_c_versus_lua_libraries_benchmarking_speed/
.. _"sol2 saved my life.": https://twitter.com/EliasDaler/status/739215685264494593
+.. _Multiple Arcade Machine Emulator (MAME): http://www.mamedev.org/index.php
+.. _The pull request: https://github.com/mamedev/mame/pull/1626
diff --git a/3rdparty/sol2/docs/source/performance.rst b/3rdparty/sol2/docs/source/performance.rst
index 534ab7e5a3e..4115e01f5a0 100644
--- a/3rdparty/sol2/docs/source/performance.rst
+++ b/3rdparty/sol2/docs/source/performance.rst
@@ -9,6 +9,7 @@ As shown by the :doc:`benchmarks<benchmarks>`, Sol is very performant with its a
* If you have a bound function call / bound member function that you are going to call in a very tight, performance-heavy loop, considering using :doc:`sol::c_call<api/c_call>`
* Be wary of passing by value / reference, and what it means by reading :ref:`this note<function-argument-handling>`.
* It is currently undocumented that usertypes will "inherit" member function / member variables from bound classes, mostly because the semantics are unclear and it is not the most performant (although it is flexible: you can register base classes after / whenever you want in relation to the derived class, provided that derived class has its bases listed). Specifying all member functions / member variables for the usertype constructor / ``new_usertype`` function call and not relying on base lookup will boost performance of member lookup
+* Use the :doc:`sol::stack_{}<api/stack_reference>` versions of functions in order to achieve maximum performance benefits when doing things like calling a function from Lua and knowing that certain arguments of certain Lua types will be on the stack. This can save you a very small fraction of performance to not copy to the register (but is also more dangerous and usually not terribly worth it).
* Specifying base classes can make getting the usertype out of Sol a bit slower since we have to check and cast; if you know the exact type wherever you're retrieving it, considering not specifying the bases, retrieving the exact type from Sol, and then casting to a base type yourself
* Member variables can sometimes cost an extra lookup to occur within the Lua system (as mentioned :doc:`bottom of the usertype page<api/usertype>`); until we find out a safe way around this, member variables will always incur that extra lookup cost
diff --git a/3rdparty/sol2/docs/source/safety.rst b/3rdparty/sol2/docs/source/safety.rst
index 8e01113f2a1..321c37aaa70 100644
--- a/3rdparty/sol2/docs/source/safety.rst
+++ b/3rdparty/sol2/docs/source/safety.rst
@@ -3,7 +3,7 @@ safety
Sol was designed to be correct and fast, and in the pursuit of both uses the regular ``lua_to{x}`` functions of Lua rather than the checking versions (``lua_check{X}``) functions. The API defaults to paranoidly-safe alternatives if you have a ``#define SOL_CHECK_ARGUMENTS`` before you include Sol, or if you pass the ``SOL_CHECK_ARGUMENTS`` define on the build command for your build system. By default, it is off and remains off unless you define this, even in debug mode. The same goes for ``#define SOL_SAFE_USERTYPE``.
-Note that you can obtain safety with regards to functions you bind by using the :doc:`protect<api/protect>` wrapper around function/variable bindings you set into Lua.
+Note that you can obtain safety with regards to functions you bind by using the :doc:`protect<api/protect>` wrapper around function/variable bindings you set into Lua. Additionally, you can have basic boolean checks when using the API by just converting to a :doc:`sol::optional\<T><api/optional>` when necessary for getting things out of Lua and for function arguments.
``SOL_SAFE_USERTYPE`` triggers the following change:
* If the userdata to a usertype function is nil, will trigger an error instead of letting things go through and letting the system segfault.
@@ -13,7 +13,7 @@ Note that you can obtain safety with regards to functions you bind by using the
* ``sol::stack::call`` and its variants will, if no templated boolean is specified, check all of the arguments for a function call.
* If ``SOL_SAFE_USERTYPE`` is not defined, it gets defined to turn being on.
-Remember that if you want these features, you must explicitly turn them on. Additionally, you can have basic boolean checks when using the API by just converting to a :doc:`sol::optional\<T><api/optional>` when necessary. Tests are compiled with this on to ensure everythign is going as expected.
+Tests are compiled with this on to ensure everything is going as expected. Remember that if you want these features, you must explicitly turn them on.
Finally, some warnings that may help with errors when working with Sol:
diff --git a/3rdparty/sol2/docs/source/usertypes.rst b/3rdparty/sol2/docs/source/usertypes.rst
index 89bf1d36a86..081be5ed6eb 100644
--- a/3rdparty/sol2/docs/source/usertypes.rst
+++ b/3rdparty/sol2/docs/source/usertypes.rst
@@ -23,4 +23,7 @@ The examples folder also has a number of really great examples for you to see. T
* Member methods, properties, variables and functions taking ``self&`` arguments modify data directly
- Work on a copy by taking or returning a copy by value.
* The actual metatable associated with the usertype has a long name and is defined to be opaque by the Sol implementation.
-* Containers get pushed as special usertypes, but can be disabled if problems arising as detailed :doc:`here<api/containers>`. \ No newline at end of file
+* Containers get pushed as special usertypes, but can be disabled if problems arising as detailed :doc:`here<api/containers>`.
+* You can use bitfields but it requires some finesse on your part. We have an example to help you get started `here that uses a few tricks`_.
+
+.. _here that uses a few tricks: https://github.com/ThePhD/sol2/blob/develop/examples/usertype_bitfields.cpp