diff --git a/.dockerignore b/.dockerignore index b12c08b8..9998cf75 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,4 +1,4 @@ -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab2e446e..c6de308d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ -## Contributing to Sol +## Contributing to sol -Looking to contribute to Sol? Well, first thing I want to mention is thank you! +Looking to contribute to sol? Well, first thing I want to mention is thank you! Second of all, this is probably where you should look :) ## Reporting Issues diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 8793f37c..f3a6f0e0 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -1,6 +1,6 @@ # 🎉 Donators! ♥ 🎉 -Thank you to all patrons, donators and contributors who help keep sol2 amazing. +Thank you to all patrons, donators and contributors who help keep sol3 amazing. - Robert Salvet - Ορφέας Ζαφείρης - 2x Donations! @@ -12,7 +12,7 @@ Thank you to all patrons, donators and contributors who help keep sol2 amazing. # 🎉 Patrons! ♥ 🎉 -Beyond just a one-time donation, patrons make a continued commitment to help keep sol2 supported and bug-free. Thank you for your patronage! Here are the supporters that wanted to be featured as sol2 contributors. +Beyond just a one-time donation, patrons make a continued commitment to help keep sol3 supported and bug-free. Thank you for your patronage! Here are the supporters that wanted to be featured as sol3 contributors. - Michael Caisse - Joshua Fisher @@ -21,6 +21,6 @@ Beyond just a one-time donation, patrons make a continued commitment to help kee # Company Patrons / Supporters # -Companies who sign up for a long-term support contract or patronage are listed here! They really push forward what's possible with sol2 (and the newer v3)! Please reach out to phdofthehouse@gmail.com if you are interested in a custom solution or a long-term support contract that goes beyond the current release's needs! +Companies who sign up for a long-term support contract or patronage are listed here! They really push forward what's possible with sol3 (and the newer v3)! Please reach out to phdofthehouse@gmail.com if you are interested in a custom solution or a long-term support contract that goes beyond the current release's needs! - Intrepid Control Systems [intrepidcs.com](https://www.intrepidcs.com/) diff --git a/Dockerfile b/Dockerfile index 1d9925d3..34207a39 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,4 @@ -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2017 Rapptz, ThePhD, and contributors diff --git a/README.md b/README.md index 1dedd946..831ad30f 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ [![Support via Patreon](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.herokuapp.com%2FThePhD)](https://patreon.com/thephd) [![Liberapay patrons](https://img.shields.io/liberapay/patrons/ThePhD.svg)](https://liberapay.com/ThePhD/) -Sol is a C++ library binding to Lua. It currently supports all Lua versions 5.1+ (LuaJIT 2.x included). Sol aims to be easy to use and easy to add to a project. +sol is a C++ library binding to Lua. It currently supports all Lua versions 5.1+ (LuaJIT 2.x included). sol aims to be easy to use and easy to add to a project. The library is header-only for easy integration with projects. ## Documentation @@ -116,7 +116,7 @@ C++Now 2019 - Flug Auditorium, Aspen Physics Center, Aspen, Colorado ## Supported Compilers -Sol makes use of C++17 features. GCC 7.x.x and Clang 3.9.x (with `-std=c++1z` and appropriate standard library) +sol 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+) @@ -147,6 +147,6 @@ You will need any flavor of python3 and an available compiler. The testing suite ## License -Sol is distributed with an MIT License. You can see LICENSE.txt for more info. +sol is distributed with an MIT License. You can see LICENSE.txt for more info. If you need a custom solution, feel free to contact me. diff --git a/cmake/Modules/Common/Core.cmake b/cmake/Modules/Common/Core.cmake index 61686a58..d785439d 100644 --- a/cmake/Modules/Common/Core.cmake +++ b/cmake/Modules/Common/Core.cmake @@ -1,4 +1,4 @@ -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors diff --git a/cmake/Modules/FindLua/set_version_vars.cmake b/cmake/Modules/FindLua/set_version_vars.cmake index 314265af..c1592214 100644 --- a/cmake/Modules/FindLua/set_version_vars.cmake +++ b/cmake/Modules/FindLua/set_version_vars.cmake @@ -1,4 +1,4 @@ -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors diff --git a/cmake/Modules/FindLuaBuild/LuaJIT.cmake b/cmake/Modules/FindLuaBuild/LuaJIT.cmake index 920e5806..0d91aaec 100644 --- a/cmake/Modules/FindLuaBuild/LuaJIT.cmake +++ b/cmake/Modules/FindLuaBuild/LuaJIT.cmake @@ -1,4 +1,4 @@ -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors diff --git a/cmake/Modules/FindLuaBuild/LuaVanilla.cmake b/cmake/Modules/FindLuaBuild/LuaVanilla.cmake index 50f84c62..c2f2aa52 100644 --- a/cmake/Modules/FindLuaBuild/LuaVanilla.cmake +++ b/cmake/Modules/FindLuaBuild/LuaVanilla.cmake @@ -1,4 +1,4 @@ -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors diff --git a/docs/Makefile b/docs/Makefile index ac69fbd7..c41f3731 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -94,9 +94,9 @@ qthelp: @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Sol.qhcp" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/sol.qhcp" @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Sol.qhc" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/sol.qhc" .PHONY: applehelp applehelp: @@ -113,8 +113,8 @@ devhelp: @echo @echo "Build finished." @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/Sol" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Sol" + @echo "# mkdir -p $$HOME/.local/share/devhelp/sol" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/sol" @echo "# devhelp" .PHONY: epub diff --git a/docs/make.bat b/docs/make.bat index ab1cb812..e5dbc1ba 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -127,9 +127,9 @@ if "%1" == "qthelp" ( echo. echo.Build finished; now you can run "qcollectiongenerator" with the ^ .qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Sol.qhcp + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\sol.qhcp echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Sol.ghc + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\sol.ghc goto end ) diff --git a/docs/source/api/api-top.rst b/docs/source/api/api-top.rst index 62cde27a..44b963b1 100644 --- a/docs/source/api/api-top.rst +++ b/docs/source/api/api-top.rst @@ -1,16 +1,17 @@ api reference manual ==================== -Browse the various function and classes :doc:`Sol<../index>` utilizes to make your life easier when working with Lua. +Browse the various function and classes :doc:`sol<../index>` utilizes to make your life easier when working with Lua. .. toctree:: - :caption: Sol API + :caption: sol API :name: apitoc :maxdepth: 2 state this_state + lua_value reference stack_reference make_reference diff --git a/docs/source/api/as_args.rst b/docs/source/api/as_args.rst index 9ad93bd8..50a6cc74 100644 --- a/docs/source/api/as_args.rst +++ b/docs/source/api/as_args.rst @@ -19,6 +19,6 @@ as_args :caption: args_from_container.cpp :linenos: -It is basically implemented as a `one-way customization point`_. For more information about customization points, see the :doc:`tutorial on how to customize Sol to work with your types<../tutorial/customization>`. +It is basically implemented as a `one-way customization point`_. For more information about customization points, see the :doc:`tutorial on how to customize sol to work with your types<../tutorial/customization>`. .. _one-way customization point: https://github.com/ThePhD/sol2/blob/develop/sol/as_args.hpp diff --git a/docs/source/api/as_table.rst b/docs/source/api/as_table.rst index 5fa0456a..28c0636f 100644 --- a/docs/source/api/as_table.rst +++ b/docs/source/api/as_table.rst @@ -6,7 +6,11 @@ as_table .. code-block:: cpp template - as_table_t { ... }; + as_table_t { + T& value() &; + const T& value() & const; + T&& value() &&; + }; template as_table_t as_function ( T&& container ); @@ -16,12 +20,14 @@ This function serves the purpose of ensuring that an object is pushed -- if poss .. literalinclude:: ../../../examples/source/docs/as_table_ipairs.cpp :linenos: -Note that any caveats with Lua tables apply the moment it is serialized, and the data cannot be gotten out back out in C++ as a C++ type. You can deserialize the Lua table into something explicitly using the ``sol::as_table_t`` marker for your get and conversion operations using Sol. At that point, the returned type is deserialized **from** a table, meaning you cannot reference any kind of C++ data directly as you do with regular userdata/usertypes. *All C++ type information is lost upon serialization into Lua.* +Note that any caveats with Lua tables apply the moment it is serialized, and the data cannot be gotten out back out in C++ as a C++ type. You can deserialize the Lua table into something explicitly using the ``sol::as_table_t`` marker for your get and conversion operations using sol. At that point, the returned type is deserialized **from** a table, meaning you cannot reference any kind of C++ data directly as you do with regular userdata/usertypes. *All C++ type information is lost upon serialization into Lua.* If you need this functionality with a member variable, use a :doc:`property on a getter function` that returns the result of ``sol::as_table``. This marker does NOT apply to :doc:`usertypes`. -You can also use this to nest types and retrieve tables within tables as shown by `this example`_. +You can also use this to nest types and retrieve tables within tables as shown by this example. -.. _this example: https://github.com/ThePhD/sol2/blob/develop/examples/containers_as_table.cpp +.. literalinclude:: ../../../examples/source/containers_as_table.cpp + :linenos: + :lines: 1-8,31-60,62-68,70- diff --git a/docs/source/api/c_call.rst b/docs/source/api/c_call.rst index b23c7837..505a8c32 100644 --- a/docs/source/api/c_call.rst +++ b/docs/source/api/c_call.rst @@ -19,7 +19,7 @@ The goal of ``sol::c_call<...>`` is to provide a way to wrap a function and tran This pushes a raw ``lua_CFunction`` into whatever you pass the resulting ``c_call`` function pointer into, whether it be a table or a userdata or whatever else using sol3's API. The resulting ``lua_CFunction`` can also be used directly with the lua API, just like many of sol3's types can be intermingled with Lua's API if you know what you're doing. -It is advisable for the user to consider making a macro to do the necessary ``decltype( &function_name, ), function_name``. Sol does not provide one because many codebases already have `one similar to this`_. +It is advisable for the user to consider making a macro to do the necessary ``decltype( &function_name, ), function_name``. sol does not provide one because many codebases already have `one similar to this`_. Here's an example below of various ways to use ``sol::c_call``: diff --git a/docs/source/api/compatibility.rst b/docs/source/api/compatibility.rst index 6187b046..fed43630 100644 --- a/docs/source/api/compatibility.rst +++ b/docs/source/api/compatibility.rst @@ -5,7 +5,7 @@ compatibility.hpp This is a detail header used to maintain compatability with the 5.2 and 5.3+ APIs. It contains code from the MIT-Licensed `Lua code`_ in some places and also from the `lua-compat`_ repository by KeplerProject. -It is not fully documented as this header's only purpose is for internal use to make sure Sol compiles across all platforms / distributions with no errors or missing Lua functionality. If you think there's some compatibility features we are missing or if you are running into redefinition errors, please make an `issue in the issue tracker`_. +It is not fully documented as this header's only purpose is for internal use to make sure sol compiles across all platforms / distributions with no errors or missing Lua functionality. If you think there's some compatibility features we are missing or if you are running into redefinition errors, please make an `issue in the issue tracker`_. If you have this already in your project or you have your own compatibility layer, then please ``#define SOL_NO_COMPAT 1`` before including ``sol.hpp`` or pass this flag on the command line to turn off the compatibility wrapper. diff --git a/docs/source/api/error.rst b/docs/source/api/error.rst index ab8b1999..05486486 100644 --- a/docs/source/api/error.rst +++ b/docs/source/api/error.rst @@ -16,6 +16,6 @@ error Please do not throw this error type yourself. It belongs to the library and we do some information appending at the front. -If an eror is thrown by Sol, it is going to be of this type. We use this in a single place: the default ``at_panic`` function we bind on construction of a :ref:`sol::state`. If you turn :doc:`off exceptions<../exceptions>`, the chances of you seeing this error are nil unless you specifically use it to pull errors out of things such as :doc:`sol::protected_function`. +If an eror is thrown by sol, it is going to be of this type. We use this in a single place: the default ``at_panic`` function we bind on construction of a :ref:`sol::state`. If you turn :doc:`off exceptions<../exceptions>`, the chances of you seeing this error are nil unless you specifically use it to pull errors out of things such as :doc:`sol::protected_function`. -As it derives from ``std::runtime_error``, which derives from ``std::exception``, you can catch it with a ``catch (const std::exception& )`` clause in your try/catch blocks. You can retrieve a string error from Lua (Lua pushes all its errors as string returns) by using this type with any of the get or lookup functions in Sol. +As it derives from ``std::runtime_error``, which derives from ``std::exception``, you can catch it with a ``catch (const std::exception& )`` clause in your try/catch blocks. You can retrieve a string error from Lua (Lua pushes all its errors as string returns) by using this type with any of the get or lookup functions in sol. diff --git a/docs/source/api/function.rst b/docs/source/api/function.rst index 8b77187b..1a4b6d61 100644 --- a/docs/source/api/function.rst +++ b/docs/source/api/function.rst @@ -12,7 +12,7 @@ function class unsafe_function : public reference; typedef unsafe_function function; -Function is a correct-assuming version of :doc:`protected_function`, omitting the need for typechecks and error handling (thus marginally increasing speed in some cases). It is the default function type of Sol. Grab a function directly off the stack using the constructor: +Function is a correct-assuming version of :doc:`protected_function`, omitting the need for typechecks and error handling (thus marginally increasing speed in some cases). It is the default function type of sol. Grab a function directly off the stack using the constructor: .. code-block:: cpp :caption: constructor: unsafe_function diff --git a/docs/source/api/lua_value.rst b/docs/source/api/lua_value.rst new file mode 100644 index 00000000..325546cf --- /dev/null +++ b/docs/source/api/lua_value.rst @@ -0,0 +1,16 @@ +lua_value +========= +*easy creation of Lua values and tables at the cost of some safety and speed* + +.. code-block:: cpp + + struct lua_value; + struct array_value; + + +The goal of these types is to make it easy to describe tables and arrays in C++ code. It works by using a thread local ``lua_State*`` variable inside the class so that one can simply pass values. The thread local variable is initialized by creation of a `sol::state`, but can also `be done manually` with ``sol::set_default_state``. An example of usage is below: + +.. literalinclude:: ../../../examples/source/lua_value.cpp + :caption: lua_value.cpp + :name: lua-value-example + :linenos: diff --git a/docs/source/api/make_reference.rst b/docs/source/api/make_reference.rst index 168912ec..a1273338 100644 --- a/docs/source/api/make_reference.rst +++ b/docs/source/api/make_reference.rst @@ -12,7 +12,7 @@ make_object/make_reference template R make_reference(lua_State* L, Args&&... args); -Makes an ``R`` out of the value. The first overload deduces the type from the passed in argument, the second allows you to specify a template parameter and forward any relevant arguments to ``sol::stack::push``. The type figured out for ``R`` is what is referenced from the stack. This allows you to request arbitrary pop-able types from Sol and have it constructed from ``R(lua_State* L, int stack_index)``. If the template boolean ``should_pop`` is ``true``, the value that was pushed will be popped off the stack. It defaults to popping, but if it encounters a type such as :doc:`sol::stack_reference` (or any of its typically derived types in Sol), it will leave the pushed values on the stack. +Makes an ``R`` out of the value. The first overload deduces the type from the passed in argument, the second allows you to specify a template parameter and forward any relevant arguments to ``sol::stack::push``. The type figured out for ``R`` is what is referenced from the stack. This allows you to request arbitrary pop-able types from sol and have it constructed from ``R(lua_State* L, int stack_index)``. If the template boolean ``should_pop`` is ``true``, the value that was pushed will be popped off the stack. It defaults to popping, but if it encounters a type such as :doc:`sol::stack_reference` (or any of its typically derived types in sol), it will leave the pushed values on the stack. .. code-block:: cpp :caption: function: make_object diff --git a/docs/source/api/metatable_key.rst b/docs/source/api/metatable_key.rst index 4ee55bd6..20f1be05 100644 --- a/docs/source/api/metatable_key.rst +++ b/docs/source/api/metatable_key.rst @@ -8,7 +8,7 @@ metatable_key struct metatable_key_t {}; const metatable_key_t metatable_key; -You can use this in conjunction with :doc:`sol::table` to set/get a metatable. Lua metatables are powerful ways to override default behavior of objects for various kinds of operators, among other things. Here is an entirely complete example, showing getting and working with a :doc:`usertype`'s metatable defined by Sol: +You can use this in conjunction with :doc:`sol::table
` to set/get a metatable. Lua metatables are powerful ways to override default behavior of objects for various kinds of operators, among other things. Here is an entirely complete example, showing getting and working with a :doc:`usertype`'s metatable defined by sol: .. literalinclude:: ../../../examples/source/metatable_key_low_level.cpp :caption: messing with metatables diff --git a/docs/source/api/nested.rst b/docs/source/api/nested.rst index 84852343..5d7fa87c 100644 --- a/docs/source/api/nested.rst +++ b/docs/source/api/nested.rst @@ -6,14 +6,18 @@ nested template struct nested { - T source; + T& value() &; + const T& value() & const; + T&& value() &&; }; ``sol::nested<...>`` is a template class similar to :doc:`sol::as_table`, but with the caveat that every :doc:`container type<../containers>` within the ``sol::nested`` type will be retrieved as a table from lua. This is helpful when you need to receive C++-style vectors, lists, and maps nested within each other: all of them will be deserialized from lua using table properties rather than anything else. -Note that any caveats with Lua tables apply the moment it is serialized, and the data cannot be gotten out back out in C++ as a C++ type. You can deserialize the Lua table into something explicitly using the ``sol::as_table_t`` marker for your get and conversion operations using Sol. At that point, the returned type is deserialized **from** a table, meaning you cannot reference any kind of C++ data directly as you do with regular userdata/usertypes. *All C++ type information is lost upon serialization into Lua.* +Note that any caveats with Lua tables apply the moment it is serialized, and the data cannot be gotten out back out in C++ as a C++ type. You can deserialize the Lua table into something explicitly using the ``sol::as_table_t`` marker for your get and conversion operations using sol. At that point, the returned type is deserialized **from** a table, meaning you cannot reference any kind of C++ data directly as you do with regular userdata/usertypes. *All C++ type information is lost upon serialization into Lua.* -The `example`_ provides a very in-depth look at both ``sol::as_table`` and ``sol::nested``, and how the two are equivalent. +The example provides a very in-depth look at both ``sol::as_table`` and ``sol::nested``, and how the two are equivalent. -.. _example: https://github.com/ThePhD/sol2/blob/develop/examples/containers_as_table.cpp \ No newline at end of file +.. literalinclude:: ../../../examples/source/containers_as_table.cpp + :linenos: + :lines: 1-30,56-61,63-68,70- diff --git a/docs/source/api/object.rst b/docs/source/api/object.rst index f87c4f37..d00f8c1c 100644 --- a/docs/source/api/object.rst +++ b/docs/source/api/object.rst @@ -34,7 +34,7 @@ There are 4 kinds of constructors here. One allows construction of an object fro template decltype(auto) as() const; -Performs a cast of the item this reference refers to into the type ``T`` and returns it. It obeys the same rules as :ref:`sol::stack::get\`. +Performs a cast of the item this reference refers to into the type ``T`` and returns it. It obeys the same rules as :ref:`sol::stack::get\`. .. code-block:: cpp :caption: function: type check @@ -42,7 +42,7 @@ Performs a cast of the item this reference refers to into the type ``T`` and ret template bool is() const; -Performs a type check using the :ref:`sol::stack::check` api, after checking if the reference is valid. +Performs a type check using the :ref:`sol::stack::check` api, after checking if the internally stored reference is valid. non-members @@ -64,7 +64,5 @@ These allow a person to compare an ``sol::object`` against :ref:`nil`, whic // doesn't have anything... } -Use this to check objects. - -.. _any_return example: https://github.com/ThePhD/sol2/blob/develop/examples/any_return.cpp \ No newline at end of file +.. _any_return example: https://github.com/ThePhD/sol2/blob/develop/examples/any_return.cpp diff --git a/docs/source/api/overload.rst b/docs/source/api/overload.rst index 5a7f5375..598bc5c9 100644 --- a/docs/source/api/overload.rst +++ b/docs/source/api/overload.rst @@ -56,7 +56,7 @@ Note that because of this system, you can use :doc:`sol::variadic_args auto protect( T&& value ); -``sol::protect( my_func )`` allows you to protect a function call or member variable call when it is being set to Lua. It can be used with usertypes or when just setting a function into Sol. Below is an example that demonstrates that a call that would normally not error without :doc:`Safety features turned on<../safety>` that instead errors and makes the Lua safety-call wrapper ``pcall`` fail: +``sol::protect( my_func )`` allows you to protect a function call or member variable call when it is being set to Lua. It can be used with usertypes or when just setting a function into sol. Below is an example that demonstrates that a call that would normally not error without :doc:`Safety features turned on<../safety>` that instead errors and makes the Lua safety-call wrapper ``pcall`` fail: .. literalinclude:: ../../../examples/source/protect.cpp :linenos: diff --git a/docs/source/api/protected_function.rst b/docs/source/api/protected_function.rst index eee0855b..ca51f8a7 100644 --- a/docs/source/api/protected_function.rst +++ b/docs/source/api/protected_function.rst @@ -107,7 +107,7 @@ Get and set the Lua entity that is used as the default error handler. The defaul reference error_handler; -The error-handler that is called should a runtime error that Lua can detect occurs. The error handler function needs to take a single string argument (use type std::string if you want to use a C++ function bound to lua as the error handler) and return a single string argument (again, return a std::string or string-alike argument from the C++ function if you're using one as the error handler). If :doc:`exceptions<../exceptions>` are enabled, Sol will attempt to convert the ``.what()`` argument of the exception into a string and then call the error handling function. It is a :doc:`reference`, as it must refer to something that exists in the lua registry or on the Lua stack. This is automatically set to the default error handler when ``protected_function`` is constructed. +The error-handler that is called should a runtime error that Lua can detect occurs. The error handler function needs to take a single string argument (use type std::string if you want to use a C++ function bound to lua as the error handler) and return a single string argument (again, return a std::string or string-alike argument from the C++ function if you're using one as the error handler). If :doc:`exceptions<../exceptions>` are enabled, sol will attempt to convert the ``.what()`` argument of the exception into a string and then call the error handling function. It is a :doc:`reference`, as it must refer to something that exists in the lua registry or on the Lua stack. This is automatically set to the default error handler when ``protected_function`` is constructed. .. note:: diff --git a/docs/source/api/stack.rst b/docs/source/api/stack.rst index fb9ab55b..1a6e0bd8 100644 --- a/docs/source/api/stack.rst +++ b/docs/source/api/stack.rst @@ -7,11 +7,11 @@ stack namespace namespace stack -If you find that the higher level abstractions are not meeting your needs, you may want to delve into the ``stack`` namespace to try and get more out of Sol. ``stack.hpp`` and the ``stack`` namespace define several utilities to work with Lua, including pushing / popping utilities, getters, type checkers, Lua call helpers and more. This namespace is not thoroughly documented as the majority of its interface is mercurial and subject to change between releases to either heavily boost performance or improve the Sol :doc:`api`. +If you find that the higher level abstractions are not meeting your needs, you may want to delve into the ``stack`` namespace to try and get more out of sol. ``stack.hpp`` and the ``stack`` namespace define several utilities to work with Lua, including pushing / popping utilities, getters, type checkers, Lua call helpers and more. This namespace is not thoroughly documented as the majority of its interface is mercurial and subject to change between releases to either heavily boost performance or improve the sol :doc:`api`. Working at this level of the stack can be enhanced by understanding how the `Lua stack works in general`_ and then supplementing it with the objects and items here. -There are, however, a few :ref:`template customization points` that you may use for your purposes and a handful of potentially handy functions. These may help if you're trying to slim down the code you have to write, or if you want to make your types behave differently throughout the Sol stack. Note that overriding the defaults **can** throw out many of the safety guarantees Sol provides: therefore, modify the :ref:`extension points` at your own discretion. +There are, however, a few :ref:`ADL customization points` that you may use for your purposes and a handful of potentially handy functions. These may help if you're trying to slim down the code you have to write, or if you want to make your types behave differently throughout the sol stack. Note that overriding the defaults **can** throw out many of the safety guarantees sol provides: therefore, modify the :ref:`extension points` at your own discretion. structures ---------- @@ -69,7 +69,7 @@ This function is helpful for when you bind to a raw C function but need sol's ab template auto get( lua_State* L, int index, record& tracking ) -Retrieves the value of the object at ``index`` in the stack. The return type varies based on ``T``: with primitive types, it is usually ``T``: for all unrecognized ``T``, it is generally a ``T&`` or whatever the extension point :ref:`stack::getter\` implementation returns. The type ``T`` has top-level ``const`` qualifiers and reference modifiers removed before being forwarded to the extension point :ref:`stack::getter\` struct. ``stack::get`` will default to forwarding all arguments to the :ref:`stack::check_get` function with a handler of ``type_panic`` to strongly alert for errors, if you ask for the :doc:`safety<../safety>`. +Retrieves the value of the object at ``index`` in the stack. The return type varies based on ``T``: with primitive types, it is usually ``T``: for all unrecognized ``T``, it is generally a ``T&`` or whatever the extension point :ref:`sol_lua_get\` implementation returns. The type ``T`` is tried once as it is (with ``const`` and reference qualifiers left alone) and then once more once it has top-level ``const`` qualifiers and reference modifiers removed before being forwarded to the extension point :ref:`sol_lua_get\` function. ``stack::get`` will default to forwarding all arguments to the :ref:`stack::check_get` function with a handler of ``type_panic`` to strongly alert for errors, if you ask for the :doc:`safety<../safety>`. You may also retrieve an :doc:`sol::optional\` from this as well, to have it attempt to not throw errors when performing the get and the type is not correct. @@ -123,7 +123,7 @@ Checks if the object at ``index`` is of type ``T`` and stored as a sol3 usertype template auto check_get( lua_State* L, int index, Handler&& handler, record& tracking ) -Retrieves the value of the object at ``index`` in the stack, but does so safely. It returns an ``optional``, where ``U`` in this case is the return type deduced from ``stack::get``. This allows a person to properly check if the type they're getting is what they actually want, and gracefully handle errors when working with the stack if they so choose to. You can define ``SOL_CHECK_ARGUMENTS`` to turn on additional :doc:`safety<../safety>`, in which ``stack::get`` will default to calling this version of the function with some variant on a handler of ``sol::type_panic_string`` to strongly alert for errors and help you track bugs if you suspect something might be going wrong in your system. +Retrieves the value of the object at ``index`` in the stack, but does so safely. It returns an ``optional``, where ``U`` in this case is the return type deduced from ``stack::get``. This allows a person to properly check if the type they're getting is what they actually want, and gracefully handle errors when working with the stack if they so choose to. You can define ``SOL_ALL_SAFETIES_ON`` to turn on additional :doc:`safety<../safety>`, in which ``stack::get`` will default to calling this version of the function with some variant on a handler of ``sol::type_panic_string`` to strongly alert for errors and help you track bugs if you suspect something might be going wrong in your system. .. code-block:: cpp :caption: function: push @@ -141,7 +141,7 @@ Retrieves the value of the object at ``index`` in the stack, but does so safely. template int multi_push( lua_State* L, Args&&... args ) -Based on how it is called, pushes a variable amount of objects onto the stack. in 99% of cases, returns for 1 object pushed onto the stack. For the case of a ``std::tuple<...>``, it recursively pushes each object contained inside the tuple, from left to right, resulting in a variable number of things pushed onto the stack (this enables multi-valued returns when binding a C++ function to a Lua). Can be called with ``sol::stack::push( L, args... )`` to have arguments different from the type that wants to be pushed, or ``sol::stack::push( L, arg, args... )`` where ``T`` will be inferred from ``arg``. The final form of this function is ``sol::stack::multi_push``, which will call one ``sol::stack::push`` for each argument. The ``T`` that describes what to push is first sanitized by removing top-level ``const`` qualifiers and reference qualifiers before being forwarded to the extension point :ref:`stack::pusher\` struct. +Based on how it is called, pushes a variable amount of objects onto the stack. in 99% of cases, returns for 1 object pushed onto the stack. For the case of a ``std::tuple<...>``, it recursively pushes each object contained inside the tuple, from left to right, resulting in a variable number of things pushed onto the stack (this enables multi-valued returns when binding a C++ function to a Lua). Can be called with ``sol::stack::push( L, args... )`` to have arguments different from the type that wants to be pushed, or ``sol::stack::push( L, arg, args... )`` where ``T`` will be inferred from ``arg``. The final form of this function is ``sol::stack::multi_push``, which will call one ``sol::stack::push`` for each argument. The ``T`` that describes what to push is first sanitized by removing top-level ``const`` qualifiers and reference qualifiers before being forwarded to the extension point :ref:`sol_lua_push\`. .. code-block:: cpp :caption: function: push_reference @@ -216,85 +216,81 @@ This function leaves the retrieved value on the stack. objects (extension points) -------------------------- -You can customize the way Sol handles different structures and classes by following the information provided in the :doc:`adding your own types<../tutorial/customization>`. +You can customize the way sol handles different structures and classes by following the information provided in the :doc:`adding your own types<../tutorial/customization>`. Below is more extensive information for the curious. -The structs below are already overriden for a handful of types. If you try to mess with them for the types ``sol`` has already overriden them for, you're in for a world of thick template error traces and headaches. Overriding them for your own user defined types should be just fine, however. +.. code-block:: cpp + :caption: ADL Extension Point sol_lua_get + :name: sol_lua_get + + MyType sol_lua_get ( sol::types, lua_State* L, int index, sol::stack::record& tracking ) { + // do work + // ... + + return MyType{}; // return value + } + +This extension point is to ``get`` an object (or reference or pointer or whatever) of type ``T``, or something convertible to it. The default internal getter implementation assumes ``T`` is a usertype and pulls out a userdata from Lua before attempting to cast it to the desired ``T``. + +Interally, there are implementations for getting numbers (``std::is_floating``, ``std::is_integral``-matching types), getting ``std::string`` and ``const char*`` plus wide string and unicode variants, getting raw userdata with :doc:`userdata_value` and anything as upvalues with :doc:`upvalue_index`, getting raw `lua_CFunction`_ s, and finally pulling out Lua functions into ``std::function``. It is also defined for anything that derives from :doc:`sol::reference`. It also has a special implementation for the 2 standard library smart pointers (see :doc:`usertype memory`) that can be more specifically extended. .. code-block:: cpp - :caption: struct: getter - :name: getter + :caption: ADL Extension Point sol_lua_push + :name: sol_lua_push - template - struct getter { - static T get (lua_State* L, int index, record& tracking) { - // ... - return // T, or something related to T. - } - }; + int push ( sol::types, lua_State* L, MyType&& value ) { + // can optionally take more than just 1 argument + // to "construct" in-place and similar + // use them however you like! + // ... + return N; // number of things pushed onto the stack + } -This is an SFINAE-friendly struct that is meant to expose static function ``get`` that returns a ``T``, or something convertible to it. The default implementation assumes ``T`` is a usertype and pulls out a userdata from Lua before attempting to cast it to the desired ``T``. There are implementations for getting numbers (``std::is_floating``, ``std::is_integral``-matching types), getting ``std::string`` and ``const char*``, getting raw userdata with :doc:`userdata_value` and anything as upvalues with :doc:`upvalue_index`, getting raw `lua_CFunction`_ s, and finally pulling out Lua functions into ``std::function``. It is also defined for anything that derives from :doc:`sol::reference`. It also has a special implementation for the 2 standard library smart pointers (see :doc:`usertype memory`). + +This extension point is to ``push`` a value into Lua. It returns the number of things pushed onto the stack. The default implementation assumes ``T`` is a usertype and pushes a userdata into Lua with a class-specific, state-wide metatable associated with it. There are implementations for pushing numbers (``std::is_floating``, ``std::is_integral``-matching types), getting ``std::string`` and ``const char*``, getting raw userdata with :doc:`userdata` and raw upvalues with :doc:`upvalue`, getting raw `lua_CFunction`_ s, and finally pulling out Lua functions into ``sol::function``. It is also defined for anything that derives from :doc:`sol::reference`. It also has a special implementation for the 2 standard library smart pointers (see :doc:`usertype memory`). .. code-block:: cpp - :caption: struct: pusher - :name: pusher + :caption: ADL Extension Point sol_lua_check + :name: sol_lua_check - template - struct unqualified_pusher { - template - static int push ( lua_State* L, T&&, ... ) { - // can optionally take more than just 1 argument - // ... - return // number of things pushed onto the stack + template + bool sol_lua_check ( sol::types, lua_State* L, int index, Handler&& handler, sol::stack::record& tracking ) { + // if the object in the Lua stack at index is a T, return true + if ( ... ) { + tracking.use(1); // or however many you use + return true; } - }; + // otherwise, call the handler function, + // with the required 4/5 arguments, then return false + // + handler(L, index, expected, indextype, "message"); + return false; + } -This is an SFINAE-friendly struct that is meant to expose static function ``push`` that returns the number of things pushed onto the stack. The default implementation assumes ``T`` is a usertype and pushes a userdata into Lua with a class-specific, state-wide metatable associated with it. There are implementations for pushing numbers (``std::is_floating``, ``std::is_integral``-matching types), getting ``std::string`` and ``const char*``, getting raw userdata with :doc:`userdata` and raw upvalues with :doc:`upvalue`, getting raw `lua_CFunction`_ s, and finally pulling out Lua functions into ``sol::function``. It is also defined for anything that derives from :doc:`sol::reference`. It also has a special implementation for the 2 standard library smart pointers (see :doc:`usertype memory`). -.. code-block:: cpp - :caption: struct: checker - :name: checker +This extension point is to ``check`` whether or not a type at a given index is what its supposed to be. The default implementation simply checks whether the expected type passed in through the template is equal to the type of the object at the specified index in the Lua stack. The default implementation for types which are considered ``userdata`` go through a myriad of checks to support checking if a type is *actually* of type ``T`` or if its the base class of what it actually stored as a userdata in that index. - template , typename = void> - struct checker { - template - static bool check ( lua_State* L, int index, Handler&& handler, record& tracking ) { - // if the object in the Lua stack at index is a T, return true - if ( ... ) { - tracking.use(1); // or however many you use - return true; - } - // otherwise, call the handler function, - // with the required 4/5 arguments, then return false - // - handler(L, index, expected, indextype, "optional message"); - return false; - } - }; - -This is an SFINAE-friendly struct that is meant to expose static function ``check`` that returns whether or not a type at a given index is what its supposed to be. The default implementation simply checks whether the expected type passed in through the template is equal to the type of the object at the specified index in the Lua stack. The default implementation for types which are considered ``userdata`` go through a myriad of checks to support checking if a type is *actually* of type ``T`` or if its the base class of what it actually stored as a userdata in that index. Down-casting from a base class to a more derived type is, unfortunately, impossible to do. +Note that you may .. _userdata-interop: .. code-block:: cpp - :caption: struct: userdata_checker - :name: userdata_checker + :caption: ADL Extension Point sol_lua_interop_check + :name: sol_lua_interop_check - template - struct userdata_checker { - template - static bool check ( lua_State* L, int index, type indextype, Handler&& handler, record& tracking ) { - // implement custom checking here for a userdata: - // if it doesn't match, return "false" and regular - // sol userdata checks will kick in - return false; - // returning true will skip sol's - // default checks - } - }; + template + bool sol_lua_interop_check(sol::types, lua_State* L, int relindex, sol::type index_type, Handler&& handler, sol::stack::record& tracking) { + // implement custom checking here for a userdata: + // if it doesn't match, return "false" and regular + // sol userdata checks will kick in + return false; + // returning true will skip sol's + // default checks + } -This is an SFINAE-friendly struct that is meant to expose a function ``check=`` that returns ``true`` if a type meets some custom userdata specifiction, and ``false`` if it does not. The default implementation just returns ``false`` to let the original sol3 handlers take care of everything. If you want to implement your own usertype checking; e.g., for messing with ``toLua`` or ``OOLua`` or ``kaguya`` or some other libraries. Note that the library must have a with a :doc:`memory compatible layout` if you **want to specialize this checker method but not the subsequent getter method**. You can specialize it as shown in the `interop examples`_. + +This extension point is to ``check`` a foreign userdata. It should return ``true`` if a type meets some custom userdata specifiction (from, say, another library or an internal framework), and ``false`` if it does not. The default implementation just returns ``false`` to let the original sol3 handlers take care of everything. If you want to implement your own usertype checking; e.g., for messing with ``toLua`` or ``OOLua`` or ``kaguya`` or some other libraries. Note that the library must have a with a :doc:`memory compatible layout` if you **want to specialize this checker method but not the subsequent getter method**. You can specialize it as shown in the `interop examples`_. .. note:: @@ -302,31 +298,30 @@ This is an SFINAE-friendly struct that is meant to expose a function ``check=`` .. code-block:: cpp - :caption: struct: userdata_getter - :name: userdata_getter + :caption: ADL Extension Point sol_lua_interop_get + :name: sol_lua_interop_get - template - struct userdata_getter { - static std::pair get ( lua_State* L, int index, void* unadjusted_pointer, record& tracking ) { - // implement custom getting here for non-sol3 userdatas: - // if it doesn't match, return "false" and regular - // sol userdata checks will kick in - return { false, nullptr }; - } - }; + template + std::pair sol_lua_interop_get(sol::types t, lua_State* L, int relindex, void* unadjusted_pointer, sol::stack::record& tracking) { + // implement custom getting here for non-sol3 userdatas: + // if it doesn't match, return "false" and regular + // sol userdata getters will kick in + return { false, nullptr }; + } -This is an SFINAE-friendly struct that is meant to expose a function ``get`` that returns ``true`` and an adjusted pointer if a type meets some custom userdata specifiction (from, say, another library or an internal framework). The default implementation just returns ``{ false, nullptr }`` to let the original sol3 getter take care of everything. If you want to implement your own usertype getter; e.g., for messing with ``kaguya`` or some other libraries. You can specialize it as shown in the `interop examples`_. - -.. note:: - - You do NOT need to use this method in particular if the :doc:`memory layout` is compatible. (For example, ``toLua`` stores userdata in a sol3-compatible way.) +This extension point is to ``get`` a foreign userdata. It should return both ``true`` and an adjusted pointer if a type meets some custom userdata specifiction (from, say, another library or an internal framework). The default implementation just returns ``{ false, nullptr }`` to let the default sol3 implementation take care of everything. You can use it to interop with other frameworks that are not sol3 but still include their power; e.g., for messing with ``kaguya`` or some other libraries. You can specialize it as shown in the `interop examples`_. .. note:: You must turn it on with ``SOL_ENABLE_INTEROP``, as described in the :ref:`config and safety section`. +.. note:: + + You do NOT need to use this method in particular if the :doc:`memory layout` is compatible. (For example, ``toLua`` stores userdata in a sol3-compatible way.) + + .. _lua_CFunction: http://www.Lua.org/manual/5.3/manual.html#lua_CFunction .. _Lua stack works in general: https://www.lua.org/pil/24.2.html .. _calling C functions works: https://www.lua.org/pil/26.html diff --git a/docs/source/api/table.rst b/docs/source/api/table.rst index bf405eb4..e5a1df9f 100644 --- a/docs/source/api/table.rst +++ b/docs/source/api/table.rst @@ -11,11 +11,15 @@ table typedef table_core table; typedef table_core global_table; -``sol::table`` is an extremely efficient manipulator of state that brings most of the magic of the Sol abstraction. Capable of doing multiple sets at once, multiple gets into a ``std::tuple``, being indexed into using ``[key]`` syntax and setting keys with a similar syntax (see: :doc:`here`), ``sol::table`` is the corner of the interaction between Lua and C++. + class lua_table; + +``sol::table`` is an extremely efficient manipulator of state that brings most of the magic of the sol abstraction. Capable of doing multiple sets at once, multiple gets into a ``std::tuple``, being indexed into using ``[key]`` syntax and setting keys with a similar syntax (see: :doc:`here`), ``sol::table`` is the corner of the interaction between Lua and C++. There are two kinds of tables: the global table and non-global tables: however, both have the exact same interface and all ``sol::global_table`` s are convertible to regular ``sol::table`` s. -Tables are the core of Lua, and they are very much the core of Sol. +Tables are the core of Lua, and they are very much the core of sol. + +``sol::lua_table`` is specifically useful for specifying you want **exactly** a Lua table, and not something that can masquerade like a table (e.g., a userdata with a metatable that has overriden `__index` and `__new_index` fields). members diff --git a/docs/source/api/table_traversal_keys.rst b/docs/source/api/table_traversal_keys.rst new file mode 100644 index 00000000..9ad224c3 --- /dev/null +++ b/docs/source/api/table_traversal_keys.rst @@ -0,0 +1,9 @@ +table traversal keys +==================== +*the definitive way to get and set things easily* + + +Objects ``sol::update_if_empty``, ``sol::create_if_nil``, and ``sol::override_value`` are special keys one can pass into a table traversal to enable creating tables as they go in ``nil``/empty spaces, optionally updating a value at the end of a chain of lookups if it is empty, or overriding the values and tables along a chain as they go. Each special key can be used in lookup and setting functionality on tables. It is primarily to enable easy use and creation of functionality like so: + +.. literalinclude:: ../../../examples/source/table_create_if_nil.cpp + :linenos: diff --git a/docs/source/api/this_environment.rst b/docs/source/api/this_environment.rst index 9973ab36..98394982 100644 --- a/docs/source/api/this_environment.rst +++ b/docs/source/api/this_environment.rst @@ -8,7 +8,7 @@ Sometimes in C++ it's useful to know where a Lua call is coming from and what :d .. code-block:: cpp :linenos: - #define SOL_CHECK_ARGUMENTS + #define SOL_ALL_SAFETIES_ON #include #include diff --git a/docs/source/api/tie.rst b/docs/source/api/tie.rst index 23fd09f0..946f7e6d 100644 --- a/docs/source/api/tie.rst +++ b/docs/source/api/tie.rst @@ -3,7 +3,7 @@ tie *improved version of std::tie* -`std::tie()`_ does not work well with :doc:`sol::function`'s ``sol::function_result`` returns. Use ``sol::tie`` instead. Because they're both named `tie`, you'll need to be explicit when you use Sol's by naming it with the namespace (``sol::tie``), even with a ``using namespace sol;``. Here's an example: +`std::tie()`_ does not work well with :doc:`sol::function`'s ``sol::function_result`` returns. Use ``sol::tie`` instead. Because they're both named `tie`, you'll need to be explicit when you use sol's by naming it with the namespace (``sol::tie``), even with a ``using namespace sol;``. Here's an example: .. literalinclude:: ../../../examples/source/tie.cpp :linenos: diff --git a/docs/source/api/types.rst b/docs/source/api/types.rst index 82ebe470..47ac5b6f 100644 --- a/docs/source/api/types.rst +++ b/docs/source/api/types.rst @@ -2,7 +2,7 @@ types ===== *nil, lua_primitive type traits, and other fundamentals* -The ``types.hpp`` header contains various fundamentals and utilities of Sol. +The ``types.hpp`` header contains various fundamentals and utilities of sol. enumerations @@ -83,7 +83,7 @@ This enumeration contains the status of a load operation from :ref:`state::load( table | boolean | function | userdata | lightuserdata }; -The base types that Lua natively communicates in and understands. Note that "poly" isn't really a true type, it's just a symbol used in Sol for something whose type hasn't been checked (and you should almost never see it). +The base types that Lua natively communicates in and understands. Note that "poly" isn't really a true type, it's just a symbol used in sol for something whose type hasn't been checked (and you should almost never see it). type traits @@ -142,7 +142,7 @@ A tag type that, when used with :doc:`stack::get\>`, does n template struct types; -A type list that, unlike ``std::tuple``, does not actually contain anything. Used to indicate types and groups of types all over Sol. +A type list that, unlike ``std::tuple``, does not actually contain anything. Used to indicate types and groups of types all over sol. functions diff --git a/docs/source/api/unique_usertype_traits.rst b/docs/source/api/unique_usertype_traits.rst index 00794fd4..d67f5eb2 100644 --- a/docs/source/api/unique_usertype_traits.rst +++ b/docs/source/api/unique_usertype_traits.rst @@ -39,7 +39,7 @@ This is a customization point for users who need to *work with special kinds of }; } -This will allow the library to properly handle ``boost::shared_ptr``, with ref-counting and all. The ``type`` is the type that lua and sol will interact with, and will allow you to pull out a non-owning reference / pointer to the data when you just ask for a plain ``T*`` or ``T&`` or ``T`` using the getter functions and properties of Sol. The ``actual_type`` is just the "real type" that controls the semantics (shared, unique, ``CComPtr``, ``ComPtr``, OpenGL handles, DirectX objects, the list goes on). +This will allow the library to properly handle ``boost::shared_ptr``, with ref-counting and all. The ``type`` is the type that lua and sol will interact with, and will allow you to pull out a non-owning reference / pointer to the data when you just ask for a plain ``T*`` or ``T&`` or ``T`` using the getter functions and properties of sol. The ``actual_type`` is just the "real type" that controls the semantics (shared, unique, ``CComPtr``, ``ComPtr``, OpenGL handles, DirectX objects, the list goes on). .. note:: diff --git a/docs/source/api/usertype.rst b/docs/source/api/usertype.rst index 64bfe7c3..b710f8b7 100644 --- a/docs/source/api/usertype.rst +++ b/docs/source/api/usertype.rst @@ -7,9 +7,16 @@ usertype ``T`` refers to the type being turned into a usertype. -While other frameworks extend lua's syntax or create Data Structure Languages (DSLs) to create classes in Lua, :doc:`Sol<../index>` instead offers the ability to generate easy bindings that pile on performance. You can see a `small starter example here`_. These use metatables and userdata in Lua for their implementation. Usertypes are also `runtime extensible`_. +.. code-block:: cpp -There are more advanced use cases for how to create and use a usertype, which are all based on how to use its constructor (see below). + class metatable : public table; + + template + class usertype : public metatable; + +While other frameworks extend lua's syntax or create Data Structure Languages (DSLs) to create classes in Lua, :doc:`sol<../index>` instead offers the ability to generate easy bindings that pile on performance. You can see a `small starter example here`_. These use metatables and userdata in Lua for their implementation. Usertypes are also `runtime extensible`_. + +There are more advanced use cases for how to create and use a usertype, which are all based on how to use its `.set()` function and its initial construction (see below). enumerations ------------ @@ -55,31 +62,55 @@ enumerations next, type, type_info, + call_construct, + storage, + gc_names, + static_index, + static_new_index, }; typedef meta_function meta_method; - Use this enumeration to specify names in a manner friendlier than memorizing the special lua metamethod names for each of these. Each binds to a specific operation indicated by the descriptive name of the enum. You can read more about `the metamethods in the Lua manual`_ and learn about how they work and are supposed to be implemented there. Each of the names here (except for the ones used as shortcuts to other names like ``meta_function::call_function`` and ``meta_function::involution`` and not including ``construct``, which just maps to the name ``new``) link directly to the Lua name for the operation. ``meta_function::pairs`` is only available in Lua 5.2 and above (does not include LuaJIT or Lua 5.1) and ``meta_function::ipairs`` is only available in Lua 5.2 exactly (disregarding compatibiltiy flags). -members +Some are also sol2 specific, for example ``meta_function::type_info``, ``meta_function::call_construct``, ``meta_function::static_index`` and ``meta_function::static_new_index`` are sol2-specific and usable by users. The entries ``meta_function::storage`` and ``meta_function::gc_names`` are sol2-internal but still in the enumeration; **please** do not use them. + +``meta_function::index`` and ``meta_function::new_index`` apply strictly to when an object in Lua is called with a key *it does not already know* (e.g., was not bound by the C++ programmer with ``.set(...)`` or ``.new_usertype<...>(...);``. ``meta_function::static_index`` and `meta_function::static_new_index`` functions get called when the the key is not found and the user is calling the new function from the named metatable itself. + +structs ------- +.. _automagic_enrollments: + .. code-block:: cpp - :caption: function: usertype constructor - :name: usertype-constructor + :caption: automagic_enrollments for special members defined on a class + :linenos: - template - usertype(Args&&... args); + struct automagic_enrollments { + bool default_constructor = true; + bool destructor = true; + bool pairs_operator = true; + bool to_string_operator = true; + bool call_operator = true; + bool less_than_operator = true; + bool less_than_or_equal_to_operator = true; + bool length_operator = true; + bool equal_to_operator = true; + }; + +This structure is used with ``new_usertype`` to specifically ordain certain special member functions to be bound to Lua, whether it is capable of them or not. -The constructor of usertype takes a variable number of arguments. It takes an even number of arguments (except in the case where the very first argument is passed as the :ref:`constructor list type`). Names can either be strings, :ref:`special meta_function enumerations`, or one of the special indicators for initializers. +new_usertype/set +---------------- + +``sol::usertype`` is a specialized version of ``sol::metatable``s, which are a specialized version of ``sol::table``. ``sol::metatable``s attempt to treat the table like either a Lua or a sol2 metatable. ``sol::usertype`` demands that a usertype is a specific metatable for a specific class. Both of them are `sol::reference derived types`, meaning they take in the ``lua_State*``. For example... -usertype constructor options -++++++++++++++++++++++++++++ +new_usertype/set options +++++++++++++++++++++++++ -If you don't specify any constructor options at all and the type is `default_constructible`_, Sol will generate a ``new`` for you. Otherwise, the following are special ways to handle the construction of a usertype: +If the type is `default_constructible`_, sol will generate a ``"new"`` member on the usertype for you. Otherwise, use ``my_table.new_usertype("name", sol::no_constructor);`` to prevent the constructor or pass in a ``sol::automagic_enrollments enrollments; /* modify members here */;`` when calling ``.new_usertype("name", enrollments);``. Otherwise, the following are special ways to handle the construction of a usertype: .. _constructor: @@ -108,7 +139,11 @@ If you don't specify any constructor options at all and the type is `default_con - This is compatible with luabind, kaguya and other Lua library syntaxes and looks similar to C++ syntax, but the general consensus in Programming with Lua and other places is to use a function named ``new`` - Note that with the ``sol::call_constructor`` key, a construct type above must be specified. A free function without it will pass in the metatable describing this object as the first argument without that distinction, which can cause strange runtime errors. * ``{anything}, sol::no_constructor`` - - Specifically tells Sol not to create a ``.new()`` if one is not specified and the type is default-constructible + - Specifically tells sol not to create a ``.new()`` if one is not specified and the type is default-constructible + - When the key ``{anything}`` is called on the table, it will result in an error. The error might be that the type is not-constructible. + - *Use this plus some of the above to allow a factory function for your function type but prevent other types of constructor idioms in Lua* +* ``{anything}, sol::no_constructor`` + - Specifically tells sol not to create a ``.new()`` if one is not specified and the type is default-constructible - When the key ``{anything}`` is called on the table, it will result in an error. The error might be that the type is not-constructible. - *Use this plus some of the above to allow a factory function for your function type but prevent other types of constructor idioms in Lua* @@ -129,8 +164,8 @@ If you don't specify anything at all and the type is `destructible`_, then a des .. _automagical-registration: -usertype automatic meta functions -+++++++++++++++++++++++++++++++++ +usertype automatic (automagic) meta functions ++++++++++++++++++++++++++++++++++++++++++++++ If you don't specify a ``sol::meta_function`` name (or equivalent string metamethod name) and the type ``T`` supports certain operations, sol3 will generate the following operations provided it can find a good default implementation: @@ -194,6 +229,11 @@ Otherwise, the following is used to specify functions to bind on the specific us - Tells a usertype what its base classes are. You need this to have derived-to-base conversions work properly. See :ref:`inheritance` +unregister +---------- + +You can unlink and kill a usertype and its associated functionality by calling ``.unregister()`` on a ``sol::usertype`` or ``sol::metatable`` pointed at a proper sol3 metatable. This will entirely unlink and clean out sol3's internal lookup structures and key information. + runtime functions ----------------- @@ -220,7 +260,7 @@ Functions set on a usertype support overloading. See :doc:`here` for a inheritance ----------- -Sol can adjust pointers from derived classes to base classes at runtime, but it has some caveats based on what you compile with: +sol can adjust pointers from derived classes to base classes at runtime, but it has some caveats based on what you compile with: If your class has no complicated™ virtual inheritance or multiple inheritance, than you can try to sneak away with a performance boost from not specifying any base classes and doing any casting checks. (What does "complicated™" mean? Ask your compiler's documentation, if you're in that deep.) @@ -230,7 +270,7 @@ Register the base classes explicitly. .. note:: - Always specify your bases if you plan to retrieve a base class using the Sol abstraction directly and not casting yourself. + Always specify your bases if you plan to retrieve a base class using the sol abstraction directly and not casting yourself. .. literalinclude:: ../../../examples/source/docs/inheritance.cpp :caption: inheritance.cpp @@ -240,15 +280,15 @@ Register the base classes explicitly. .. note:: - You must list ALL base classes, including (if there were any) the base classes of A, and the base classes of those base classes, etc. if you want Sol/Lua to handle them automagically. + You must list ALL base classes, including (if there were any) the base classes of A, and the base classes of those base classes, etc. if you want sol/Lua to handle them automagically. .. note:: - Sol does not support down-casting from a base class to a derived class at runtime. + sol does not support down-casting from a base class to a derived class at runtime. .. warning:: - Specify all base class member variables and member functions to avoid current implementation caveats regarding automatic base member lookup. Sol currently attempts to link base class methods and variables with their derived classes with an undocumented, unsupported feature, provided you specify ``sol::bases<...>``. Unfortunately, this can come at the cost of performance, depending on how "far" the base is from the derived class in the bases lookup list. If you do not want to suffer the performance degradation while we iron out the kinks in the implementation (and want it to stay performant forever), please specify all the base methods on the derived class in the method listing you write. In the future, we hope that with reflection we will not have to worry about this. + Specify all base class member variables and member functions to avoid current implementation caveats regarding automatic base member lookup. sol currently attempts to link base class methods and variables with their derived classes with an undocumented, unsupported feature, provided you specify ``sol::bases<...>``. Unfortunately, this can come at the cost of performance, depending on how "far" the base is from the derived class in the bases lookup list. If you do not want to suffer the performance degradation while we iron out the kinks in the implementation (and want it to stay performant forever), please specify all the base methods on the derived class in the method listing you write. In the future, we hope that with reflection we will not have to worry about this. .. _automagical: @@ -269,7 +309,7 @@ Usertypes automatically register special functions, whether or not they're bound inheritance + overloading ------------------------- -While overloading is supported regardless of inheritance caveats or not, the current version of Sol has a first-match, first-call style of overloading when it comes to inheritance. Put the functions with the most derived arguments first to get the kind of matching you expect or cast inside of an intermediary C++ function and call the function you desire. +While overloading is supported regardless of inheritance caveats or not, the current version of sol has a first-match, first-call style of overloading when it comes to inheritance. Put the functions with the most derived arguments first to get the kind of matching you expect or cast inside of an intermediary C++ function and call the function you desire. compilation speed ----------------- @@ -283,7 +323,7 @@ performance note .. note:: - Note that performance for member function calls goes down by a fixed overhead if you also bind variables as well as member functions. This is purely a limitation of the Lua implementation and there is, unfortunately, nothing that can be done about it. If you bind only functions and no variables, however, Sol will automatically optimize the Lua runtime and give you the maximum performance possible. *Please consider ease of use and maintenance of code before you make everything into functions.* + Note that performance for member function calls goes down by a fixed overhead if you also bind variables as well as member functions. This is purely a limitation of the Lua implementation and there is, unfortunately, nothing that can be done about it. If you bind only functions and no variables, however, sol will automatically optimize the Lua runtime and give you the maximum performance possible. *Please consider ease of use and maintenance of code before you make everything into functions.* .. _destructible: http://en.cppreference.com/w/cpp/types/is_destructible .. _default_constructible: http://en.cppreference.com/w/cpp/types/is_constructible diff --git a/docs/source/api/usertype_memory.rst b/docs/source/api/usertype_memory.rst index bcfe119f..c6d21c47 100644 --- a/docs/source/api/usertype_memory.rst +++ b/docs/source/api/usertype_memory.rst @@ -4,9 +4,9 @@ usertype memory .. note:: - Sol does not take ownership of raw pointers, returned from functions or set through the ``set`` functions. Return a value, a ``std::unique_ptr``, a ``std::shared_ptr`` of some kind, or hook up the :doc:`unique usertypes traits` to work for some specific handle structure you use (AKA, for ``boost::shared_ptr``). + sol does not take ownership of raw pointers, returned from functions or set through the ``set`` functions. Return a value, a ``std::unique_ptr``, a ``std::shared_ptr`` of some kind, or hook up the :doc:`unique usertypes traits` to work for some specific handle structure you use (AKA, for ``boost::shared_ptr``). -The userdata generated by Sol has a specific layout, depending on how Sol recognizes userdata passed into it. All of the referred to metatable names are generated from the name of the class itself. Note that we use 1 metatable per the 3 styles listed below, plus 1 additional metatable that is used for the actual table that you bind with the name when calling ``table::new/set_(simple_)usertype``. +The userdata generated by sol has a specific layout, depending on how sol recognizes userdata passed into it. All of the referred to metatable names are generated from the name of the class itself. Note that we use 1 metatable per the 3 styles listed below, plus 1 additional metatable that is used for the actual table that you bind with the name when calling ``table::new/set_(simple_)usertype``. In general, we always insert a ``T*`` in the first ``sizeof(T*)`` bytes, so the any framework that pulls out those first bytes expecting a pointer will work. The rest of the data has some different alignments and contents based on what it's used for and how it's used. @@ -41,7 +41,7 @@ Lua will clean up the memory itself but does not know about any destruction sema For ``T*`` ---------- -These are classified as a separate ``T*`` metatable, essentially the "reference" table. Things passed to Sol as a pointer or as a ``std::reference`` are considered to be references, and thusly do not have a ``__gc`` (garbage collection) method by default. All raw pointers are non-owning pointers in C++. If you're working with a C API, provide a wrapper around pointers that are supposed to own data and use the constructor/destructor idioms (e.g., with an internal ``std::unique_ptr``) to keep things clean. +These are classified as a separate ``T*`` metatable, essentially the "reference" table. Things passed to sol as a pointer or as a ``std::reference`` are considered to be references, and thusly do not have a ``__gc`` (garbage collection) method by default. All raw pointers are non-owning pointers in C++. If you're working with a C API, provide a wrapper around pointers that are supposed to own data and use the constructor/destructor idioms (e.g., with an internal ``std::unique_ptr``) to keep things clean. The data layout for data that only refers is as follows:: @@ -60,4 +60,4 @@ The data layout for these kinds of types is as follows:: | T* | void(*)(void*) function_pointer | T | ^-sizeof(T*) bytes-^-sizeof(void(*)(void*)) bytes, deleter-^- sizeof(T) bytes, actal data -^ -Note that we put a special deleter function before the actual data. This is because the custom deleter must know where the offset to the data is and where the special deleter is. In other words, fixed-size-fields come before any variably-sized data (T can be known at compile time, but when serialized into Lua in this manner it becomes a runtime entity). Sol just needs to know about ``T*`` and the userdata (and userdata metatable) to work, everything else is for preserving construction / destruction semantics. \ No newline at end of file +Note that we put a special deleter function before the actual data. This is because the custom deleter must know where the offset to the data is and where the special deleter is. In other words, fixed-size-fields come before any variably-sized data (T can be known at compile time, but when serialized into Lua in this manner it becomes a runtime entity). sol just needs to know about ``T*`` and the userdata (and userdata metatable) to work, everything else is for preserving construction / destruction semantics. \ No newline at end of file diff --git a/docs/source/compilation.rst b/docs/source/compilation.rst index d68b3eef..d7163e25 100644 --- a/docs/source/compilation.rst +++ b/docs/source/compilation.rst @@ -90,7 +90,7 @@ Here are some notes on achieving better compile times without sacrificing too mu 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). +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. diff --git a/docs/source/conf.py b/docs/source/conf.py index 3c0d20f4..bce034bb 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# Sol documentation build configuration file, created by +# sol documentation build configuration file, created by # sphinx-quickstart on Mon Feb 29 21:49:51 2016. # # This file is execfile()d with the current directory set to its @@ -46,7 +46,7 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = 'Sol' +project = 'sol' copyright = '2019, ThePhD' author = 'ThePhD' @@ -226,7 +226,7 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'Sol.tex', 'Sol Documentation', 'ThePhD', 'manual'), + (master_doc, 'sol.tex', 'sol Documentation', 'ThePhD', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -253,7 +253,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [(master_doc, 'sol', 'Sol Documentation', [author], 1)] +man_pages = [(master_doc, 'sol', 'sol Documentation', [author], 1)] # If true, show URL addresses after external links. #man_show_urls = False @@ -264,7 +264,7 @@ man_pages = [(master_doc, 'sol', 'Sol Documentation', [author], 1)] # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'Sol', 'Sol Documentation', author, 'Sol', + (master_doc, 'sol', 'sol Documentation', author, 'sol', 'One line description of project.', 'Miscellaneous'), ] diff --git a/docs/source/containers.rst b/docs/source/containers.rst index 7267d768..ec2045c5 100644 --- a/docs/source/containers.rst +++ b/docs/source/containers.rst @@ -13,7 +13,7 @@ Containers are objects that are meant to be inspected and iterated and whose job - If you need tables, consider using ``sol::as_table`` and ``sol::nested`` - See `this table serialization example`_ for more details * Lua 5.1 has different semantics for ``pairs`` and ``ipairs``: be wary. See :ref:`examples down below` for more details -* You can override container behavior by overriding :ref:`the detection trait` and :ref:`specializing the container_traits template` +* You can override container behavior by overriding :ref:`the detection trait` and :ref:`specializing the usertype_container template` * You can bind typical C-style arrays, but must follow :ref:`the rules` .. _container-c-array: @@ -27,7 +27,7 @@ Containers are objects that are meant to be inspected and iterated and whose job container detection ------------------- -containers are detected by the type trait ``sol::is_container``. If that turns out to be true, sol3 will attempt to push a userdata into Lua for the specified type ``T``, and bestow it with some of the functions and properties listed below. These functions and properties are provided by a template struct ``sol::container_traits``, which has a number of static Lua C functions bound to a safety metatable. If you want to override the behavior for a specific container, you must first specialize ``sol::is_container`` to drive from ``std::true_type``, then override the functions you want to change. Any function you do not override will call the default implementation or equivalent. The default implementation for unrecognized containers is simply errors. +containers are detected by the type trait ``sol::is_container``. If that turns out to be true, sol3 will attempt to push a userdata into Lua for the specified type ``T``, and bestow it with some of the functions and properties listed below. These functions and properties are provided by a template struct ``sol::usertype_container``, which has a number of static Lua C functions bound to a safety metatable. If you want to override the behavior for a specific container, you must first specialize ``sol::is_container`` to drive from ``std::true_type``, then override the functions you want to change. Any function you do not override will call the default implementation or equivalent. The default implementation for unrecognized containers is simply errors. You can also specialize ``sol::is_container`` to turn off container detection, if you find it too eager for a type that just happens to have ``begin`` and ``end`` functions, like so: @@ -56,7 +56,7 @@ This will let the type be pushed as a regular userdata. Pushing a new :doc:`usertype` will prevent a qualifying C++ container type from being treated like a container. To force a type that you've registered/bound as a usertype using ``new_usertype`` or ``new_simple_usertype`` to be treated like a container, use :doc:`sol::as_container`. -.. _container-traits: +.. _usertype-container: container overriding -------------------- @@ -75,7 +75,7 @@ If you need a type whose declaration and definition you do not have control over struct is_container : std::true_type {}; template <> - struct container_traits { + struct usertype_container { ... // see below for implemetation details @@ -83,7 +83,7 @@ If you need a type whose declaration and definition you do not have control over } -The various operations provided by ``container_traits`` are expected to be like so, below. Ability to override them requires familiarity with the Lua stack and how it operates, as well as knowledge of Lua's :ref:`raw C functions`. You can read up on raw C functions by looking at the "Programming in Lua" book. The `online version's information`_ about the stack and how to return information is still relevant, and you can combine that by also using sol's low-level :doc:`stack API` to achieve whatever behavior you need. +The various operations provided by ``usertype_container`` are expected to be like so, below. Ability to override them requires familiarity with the Lua stack and how it operates, as well as knowledge of Lua's :ref:`raw C functions`. You can read up on raw C functions by looking at the "Programming in Lua" book. The `online version's information`_ about the stack and how to return information is still relevant, and you can combine that by also using sol's low-level :doc:`stack API` to achieve whatever behavior you need. .. warning:: @@ -94,29 +94,29 @@ The various operations provided by ``container_traits`` are expected to be li container operations ------------------------- -Below are the many container operations and their override points for ``container_traits``. Please use these to understand how to use any part of the implementation. +Below are the many container operations and their override points for ``usertype_container``. Please use these to understand how to use any part of the implementation. +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| operation | lua syntax | container_traits | stack argument order | notes/caveats | +| operation | lua syntax | usertype_container | stack argument order | notes/caveats | | | | extension point | | | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | set | ``c:set(key, value)`` | ``static int set(lua_State*);`` | 1 self | - if ``value`` is nil, it performs an erase in default implementation | -| | | | 2 key | - if this is a sequence container and it support insertion and ``key``,is an index equal to the size of the container,+ 1, it will insert at,the end of the container (this is a Lua idiom) | -| | | | 3 value | | +| | | | 2 key | - if this is a container that supports insertion and``key`` is an index equal to the (size of the container) + 1, it will insert the value at the end of the container (this is a Lua idiom) | +| | | | 3 value | - default implementation uses ``.insert`` or `operator[]` for c arrays | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| index_set | ``c[key] = value`` | ``static int index_set(lua_State*);`` | 1 self | - default implementation calls "set" | +| index_set | ``c[key] = value`` | ``static int index_set(lua_State*);`` | 1 self | - default implementation defers work to "set" | | | | | 2 key | - if this is a sequence container and it support insertion and ``key`` is an index equal to the size of the container + 1, it will insert at the end of the container (this is a Lua idiom) | | | | | 3 value | | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | at | ``v = c:at(key)`` | ``static int at(lua_State*);`` | 1 self | - can return multiple values | -| | | | 2 index | - default implementation increments iterators linearly for non-random-access | +| | | | 2 index | - default implementation increments iterators linearly for non-random-access; uses ``.find()`` if available | | | | | | - if the type does not have random-access iterators, **do not use this in a for loop** ! | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | get | ``v = c:get(key)`` | ``static int get(lua_State*);`` | 1 self | - can return multiple values | | | | | 2 key | - default implementation increments iterators linearly for non-random-access | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | index_get | ``v = c[key]`` | ``static int index_get(lua_State*);`` | 1 self | - can only return 1 value | -| | | | 2 key | - default implementation just calls "get" | +| | | | 2 key | - default implementation defers work to "get" | | | | | | - if ``key`` is a string and ``key`` is one of the other member functions, it will return that member function rather than perform a lookup / index get | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | find | ``c:find(target)`` | ``static int find(lua_State*);`` | 1 self | - ``target`` is a value for non-lookup containers (fixed containers, sequence containers, non-associative and non-ordered containers) | @@ -125,31 +125,31 @@ Below are the many container operations and their override points for ``containe | erase | ``c:erase(target)`` | ``static int erase(lua_State*);`` | 1 self | - for sequence containers, ``target`` is an index to erase | | | | | 2 target | - for lookup containers, ``target`` is the key type | | | | | | - uses linear incrementation to spot for sequence containers that do not have random access iterators (``std::list``, ``std::forward_list``, and similar) | -| | | | | - invalidates iteration | +| | | | | - can invalidates iteration | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | insert | ``c:insert(target, value)`` | | 1 self | - for sequence containers, ``target`` is an index, otherwise it is the key type | | | | | 2 target | - inserts into a container if possible at the specified location | | | | | 3 key | | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | add | ``c:add(key, value)`` or ``c:add(value)`` | ``static int add(lua_State*);`` | 1 self | - 2nd argument (3rd on stack) is provided for associative containers to add | -| | | | 2 key/value | - ordered containers will insert into the appropriate spot, not necessarily at the end | -| | | | 3 value | | +| | | | 2 key/value | - ordered containers will insert into the appropriate spot, not necessarily at the end (uses ``.insert(...)`` or ``.find(...)`` with assignment | +| | | | 3 value | - can invalidate iteratorion | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | size | ``#c`` | ``static int size(lua_State*);`` | 1 self | - default implementation calls ``.size()`` if present | | | | | | - otherwise, default implementation uses ``std::distance(begin(L, self), end(L, self))`` | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | clear | ``c:clear()`` | ``static int clear(lua_State*);`` | 1 self | - default implementation provides no fallback if there's no ``clear`` operation | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| offset | n/a | ``static int index_adjustment(lua_State*, T&);`` | n/a | - returns an index that adds to the passed-in numeric index for array acces (default implementation is ``return -1`` to simulate 1-based indexing from Lua) | +| offset | n/a | ``static int index_adjustment(lua_State*, T&);`` | n/a | - returns an index that adds to the passed-in numeric index for array access (default implementation is ``return -1`` to simulate 1-based indexing from Lua) | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| begin | n/a | ``static iterator begin(lua_State*, T&);`` | n/a | - called by default implementation | +| begin | n/a | ``static iterator begin(lua_State*, T&);`` | n/a | - called by default implementation in above functions | | | | | | - is not the regular raw function: must return an iterator from second "T&" argument, which is self | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| end | n/a | ``static iterator end(lua_State*, T&);`` | n/a | - called by default implementation | +| end | n/a | ``static iterator end(lua_State*, T&);`` | n/a | - called by default implementation in above functions | | | | | | - is not the regular raw function: must return an iterator from second "T&" argument, which is self | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| next | | ``static int next(lua_State*);`` | 1 self | - implement if advanced user only that understands caveats | -| | | | | - is used as 'iteration function' dispatched with pairs() call | +| next | | ``static int next(lua_State*);`` | 1 self | - implement if advanced user only that understands caveats of writing a ``next`` function for Lua traversal | +| | | | | - is used as the 'iteration function' dispatched with pairs() call | | | | | | | | | | | | | +-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -189,7 +189,7 @@ When you serialize a container into sol3, the default container handler deals wi | | | std::forward_list | | +------------------------+----------------------------------------+-------------------------+-----------------------------------------------------------------------------------------------+ | fixed | lacking ``push_back``/``insert`` | std::array | - regular c-style arrays must be set with ``std::ref( arr )`` or ``&arr`` to be usable | -| | lacking ``erase`` | T[n] (fixed arrays) | | +| | lacking ``erase`` | T[n] (fixed arrays) | - C++ implementation inserts using operator[] | | | | | | +------------------------+----------------------------------------+-------------------------+-----------------------------------------------------------------------------------------------+ | ordered | ``key_type`` typedef | std::set | - ``container[key] = stuff`` operation erases when ``stuff`` is nil, inserts/sets when not | diff --git a/docs/source/errors.rst b/docs/source/errors.rst index 07b4c0c7..29bcb9e2 100644 --- a/docs/source/errors.rst +++ b/docs/source/errors.rst @@ -3,12 +3,12 @@ errors 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. +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 :ref:`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``. +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 :ref:`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``. .. _compilation_errors_warnings: @@ -53,7 +53,7 @@ This should use the 64-bit tools by default, and increase your maximum heap spac 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. +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. @@ -69,9 +69,9 @@ Please make sure to use the ``SOL_EXCEPTIONS_SAFE_PROPAGATION`` define before in Catch and CRASH! ---------------- -By default, Sol will add a ``default_at_panic`` handler to states opened by Sol (see :ref:`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. +By default, sol will add a ``default_at_panic`` handler to states opened by sol (see :ref:`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 :doc:`exceptions in Sol here`. +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`. 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`. 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. diff --git a/docs/source/exceptions.rst b/docs/source/exceptions.rst index 3fb300d5..35a018a3 100644 --- a/docs/source/exceptions.rst +++ b/docs/source/exceptions.rst @@ -3,7 +3,7 @@ exceptions since somebody is going to ask about it... ------------------------------------------ -Yes, you can turn off exceptions in Sol with ``#define SOL_NO_EXCEPTIONS`` before including or by passing the command line argument that defines ``SOL_NO_EXCEPTIONS``. We don't recommend it unless you're playing with a Lua distro that also doesn't play nice with exceptions (like non-x64 versions of :ref:`LuaJIT` ). +Yes, you can turn off exceptions in sol with ``#define SOL_NO_EXCEPTIONS`` before including or by passing the command line argument that defines ``SOL_NO_EXCEPTIONS``. We don't recommend it unless you're playing with a Lua distro that also doesn't play nice with exceptions (like non-x64 versions of :ref:`LuaJIT` ). If you turn this off, the default `at_panic`_ function :doc:`state` set for you will not throw (see :ref:`sol::state's automatic handlers` for more details). Instead, the default Lua behavior of aborting will take place (and give you no chance of escape unless you implement your own at_panic function and decide to try ``longjmp`` out). @@ -15,7 +15,7 @@ To make this not be the case, you can set a panic function directly with ``lua_a :linenos: -Note that ``SOL_NO_EXCEPTIONS`` will also disable :doc:`sol::protected_function`'s ability to catch C++ errors you throw from C++ functions bound to Lua that you are calling through that API. So, only turn off exceptions in Sol if you're sure you're never going to use exceptions ever. Of course, if you are ALREADY not using Exceptions, you don't have to particularly worry about this and now you can use Sol! +Note that ``SOL_NO_EXCEPTIONS`` will also disable :doc:`sol::protected_function`'s ability to catch C++ errors you throw from C++ functions bound to Lua that you are calling through that API. So, only turn off exceptions in sol if you're sure you're never going to use exceptions ever. Of course, if you are ALREADY not using Exceptions, you don't have to particularly worry about this and now you can use sol! If there is a place where a throw statement is called or a try/catch is used and it is not hidden behind a ``#ifndef SOL_NO_EXCEPTIONS`` block, please file an issue at `issue`_ or submit your very own pull request so everyone can benefit! @@ -45,9 +45,9 @@ The other handler is specific to sol3. If you open a ``sol::state``, or open the 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.) 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. +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. +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. .. _exception-interop: @@ -55,7 +55,7 @@ Testing in `this closed issue`_ that it doesn't play nice on 64-bit Linux in man 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. +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. @@ -63,7 +63,7 @@ Currently, the only known platform to do this is the listed "Full" `platforms fo .. warning:: - ``SOL_EXCEPTIONS_SAFE_PROPAGATION`` is not defined automatically when Sol detects LuaJIT. *It is your job to define it if you know that your platform supports it*! + ``SOL_EXCEPTIONS_SAFE_PROPAGATION`` is not defined automatically when 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/ diff --git a/docs/source/features.rst b/docs/source/features.rst index c74517db..59bf8379 100644 --- a/docs/source/features.rst +++ b/docs/source/features.rst @@ -1,13 +1,13 @@ features ======== -*what does Sol (and other libraries) support?* +*what does sol (and other libraries) support?* -The goal of Sol is to provide an incredibly clean API that provides high performance (comparable or better than the C it was written on) and extreme ease of use. That is, users should be able to say: "this works pretty much how I expected it to." +The goal of sol is to provide an incredibly clean API that provides high performance (comparable or better than the C it was written on) and extreme ease of use. That is, users should be able to say: "this works pretty much how I expected it to." For the hard technical components of Lua and its ecosystem we support, here is the full rundown: -what Sol supports +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 :doc:`compatibility` header. @@ -75,7 +75,7 @@ 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. +* 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. @@ -162,13 +162,13 @@ kaguya - * Table variables / member variables are automatically turned into ``obj:x( value )`` to set and ``obj:x()`` to get * Has optional support -* Inspired coroutine support for Sol +* Inspired coroutine support for sol * Library author (satoren) is a nice guy! * C++11/14, or boostified (which makes it C++03 compatible) * Class registration is a bit verbose, but not as offensive as OOLua or lua-intf or others * Constructor setting syntax is snazzy and good -Sol - +sol - * One of the few libraries with optional support! * Basically the fastest in almomst all respects: http://sol2.readthedocs.io/en/latest/benchmarks.html @@ -260,7 +260,7 @@ luwra - * Cannot pull functions without first leaving them on the stack: manual cleanup becomes a thing * Doesn't understand ``std::function`` conversions and the like (but with some extra code can get it to work) * Recently improved by a lot: can chain tables and such, even if performance is a bit sad for that use case -* When you do manage to set function calls with the macros they are fast (can a template solution do just as good? Sol is going to find out!) +* When you do manage to set function calls with the macros they are fast (can a template solution do just as good? sol is going to find out!) * No table variable support - get turned into getter/setter functions, similar to kaguya * Table variables become class statics (surprising) * Tanks in later MSVCs diff --git a/docs/source/functions.rst b/docs/source/functions.rst index 55c111d7..4aa14da6 100644 --- a/docs/source/functions.rst +++ b/docs/source/functions.rst @@ -87,7 +87,7 @@ When you bind a function to Lua, please take any pointer arguments as ``T*``, un function call safety -------------------- -You can have functions here and on usertypes check to definitely make sure that the types passed to C++ functions are what they're supposed to be by adding a ``#define SOL_CHECK_ARGUMENTS`` before including Sol, or passing it on the command line. Otherwise, for speed reasons, these checks are only used where absolutely necessary (like discriminating between :doc:`overloads`). See :doc:`safety<../safety>` for more information. +You can have functions here and on usertypes check to definitely make sure that the types passed to C++ functions are what they're supposed to be by adding a ``#define SOL_ALL_SAFETIES_ON`` before including sol, or passing it on the command line. Otherwise, for speed reasons, these checks are only used where absolutely necessary (like discriminating between :doc:`overloads`). See :doc:`safety<../safety>` for more information. .. _raw-function-note: @@ -95,7 +95,7 @@ You can have functions here and on usertypes check to definitely make sure that raw functions (``lua_CFunction``) --------------------------------- -When you push a function into Lua using Sol using any methods and that function exactly matches the signature ``int( lua_State* );``, it will be treated as a *raw C function* (a ``lua_CFunction``). This means that the usual exception trampoline Sol wraps your other function calls in will not be present. You will be responsible for catching exceptions and handling them before they explode into the C API (and potentially destroy your code). Sol in all other cases adds an exception-handling trampoline that turns exceptions into Lua errors that can be caught by the above-mentioned protected functions and accessors. +When you push a function into Lua using sol using any methods and that function exactly matches the signature ``int( lua_State* );``, it will be treated as a *raw C function* (a ``lua_CFunction``). This means that the usual exception trampoline sol wraps your other function calls in will not be present. You will be responsible for catching exceptions and handling them before they explode into the C API (and potentially destroy your code). sol in all other cases adds an exception-handling trampoline that turns exceptions into Lua errors that can be caught by the above-mentioned protected functions and accessors. Note that stateless lambdas can be converted to a function pointer, so stateless lambdas similar to the form ``[](lua_State*) -> int { ... }`` will also be pushed as raw functions. If you need to get the Lua state that is calling a function, use :doc:`sol::this_state`. diff --git a/docs/source/licenses.rst b/docs/source/licenses.rst index 3860c91f..6f68280a 100644 --- a/docs/source/licenses.rst +++ b/docs/source/licenses.rst @@ -1,9 +1,9 @@ licenses ======== -The following licenses cover all of the code in Sol. Spoiler: they're all `MIT`_ (and ``CC0``) and it's safe to use in commercial code: feel free to copy/paste the below right into your own attributions / licenses file. +The following licenses cover all of the code in sol. Spoiler: they're all `MIT`_ (and ``CC0``) and it's safe to use in commercial code: feel free to copy/paste the below right into your own attributions / licenses file. -Sol - ThePhD/sol2: +sol - ThePhD/sol2: ------------------ .. code-block:: none diff --git a/docs/source/mentions.rst b/docs/source/mentions.rst index 5588b155..de1b8150 100644 --- a/docs/source/mentions.rst +++ b/docs/source/mentions.rst @@ -4,7 +4,7 @@ mentions First off, feel free to `tell me about your uses!`_ -Okay, so the features don't convince you, the documentation doesn't convince you, you want to see what *other* people think about Sol? Well, aside from the well-wishes that come through in the issue tracker, here's a few things floating around about sol3 that I occasionally get pinged about: +Okay, so the features don't convince you, the documentation doesn't convince you, you want to see what *other* people think about sol? Well, aside from the well-wishes that come through in the issue tracker, here's a few things floating around about sol3 that I occasionally get pinged about: `eevee`_ demonstrating the sheer code reduction by using sol3: diff --git a/docs/source/origin.rst b/docs/source/origin.rst index 19105acc..34b8e674 100644 --- a/docs/source/origin.rst +++ b/docs/source/origin.rst @@ -13,7 +13,7 @@ And lo, `Danny Y., Rapptz`_ did stand firm in the sea and cast his hands to the seriously --------- -Sol was originally started by many moon cycles ago to interop with Lua and C++, by `Rapptz`_. It was very successful and many rejoiced at having an easy to use abstraction on top of the Lua API. Rapptz continued to make a number of great projects and has been busy with other things, so upon seeing the repository grow stagnant and tired in the last very long while (over a year), `ThePhD`_ forked it into Sol3 and rebooted the code with the hopes of reaching the Milestone and the documentation you have today. +sol was originally started by many moon cycles ago to interop with Lua and C++, by `Rapptz`_. It was very successful and many rejoiced at having an easy to use abstraction on top of the Lua API. Rapptz continued to make a number of great projects and has been busy with other things, so upon seeing the repository grow stagnant and tired in the last very long while (over a year), `ThePhD`_ forked it into Sol3 and rebooted the code with the hopes of reaching the Milestone and the documentation you have today. To get to the old repo, head over `here`_. @@ -21,7 +21,7 @@ To get to the old repo, head over `here`_. the name -------- -Sol means sun. The moon (Lua) needs a sun, because without it only the bleak night of copy-paste programming and off-by-one errors would prevail. ... Or something. +sol means sun. The moon (Lua) needs a sun, because without it only the bleak night of copy-paste programming and off-by-one errors would prevail. ... Or something. .. _here: https://github.com/Rapptz/sol diff --git a/docs/source/performance.rst b/docs/source/performance.rst index 5e346784..ee1ab16c 100644 --- a/docs/source/performance.rst +++ b/docs/source/performance.rst @@ -1,16 +1,16 @@ getting performance =================== -*things to make Sol as fast as possible* +*things to make sol as fast as possible* -As shown by the :doc:`benchmarks`, Sol is very performant with its abstractions. However, in the case where you need every last drop of performance from Sol, a number of tips and API usage tricks will be documented here. PLEASE benchmark / profile your code before you start invoking these, as some of them trade in readability / clarity for performance. +As shown by the :doc:`benchmarks`, sol is very performant with its abstractions. However, in the case where you need every last drop of performance from sol, a number of tips and API usage tricks will be documented here. PLEASE benchmark / profile your code before you start invoking these, as some of them trade in readability / clarity for performance. * 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` * Be wary of passing by value / reference, and what it means by reading :ref:`this note`. * 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_{}` 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 +* 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`); until we find out a safe way around this, member variables will always incur that extra lookup cost -That's it as far as different performance options are avilable to make Sol run faster. Again, please make sure to invoke these only when you know Sol is the bottleneck. If you find some form of the performance unacceptable to you, also feel free to open an issue at the github. +That's it as far as different performance options are avilable to make sol run faster. Again, please make sure to invoke these only when you know sol is the bottleneck. If you find some form of the performance unacceptable to you, also feel free to open an issue at the github. diff --git a/docs/source/rtti.rst b/docs/source/rtti.rst index 0f0a3a5c..8b0892fb 100644 --- a/docs/source/rtti.rst +++ b/docs/source/rtti.rst @@ -2,6 +2,6 @@ run-time type information (rtti) ================================ *because somebody's going to want to shut this off, too...* -Sol does not use RTTI. +sol does not use RTTI. .. _an issue: https://github.com/ThePhD/sol2/issues diff --git a/docs/source/safety.rst b/docs/source/safety.rst index 6c793875..47645070 100644 --- a/docs/source/safety.rst +++ b/docs/source/safety.rst @@ -1,7 +1,7 @@ config and 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. +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_ALL_SAFETIES_ON`` before you include sol, or if you pass the ``SOL_ALL_SAFETIES_ON`` 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. .. _config: @@ -54,7 +54,7 @@ Safety Config * Don't turn this on unless you have an extremely good reason * *DON'T TURN THIS ON UNLESS YOU HAVE AN EXTREMELY GOOD REASON* -``SOL_CHECK_ARGUMENTS`` triggers the following changes: +``SOL_ALL_SAFETIES_ON`` triggers the following changes: * If ``SOL_SAFE_USERTYPE``, ``SOL_SAFE_REFERENCES``, ``SOL_SAFE_FUNCTION``, ``SOL_SAFE_NUMERICS``, ``SOL_SAFE_GETTER``, and ``SOL_SAFE_FUNCTION_CALLS`` are not defined, they get defined and the effects described above kick in * **Not** turned on by default under any settings: *this MUST be turned on manually* diff --git a/docs/source/tutorial/all-the-things.rst b/docs/source/tutorial/all-the-things.rst index 4633096d..ecd49e22 100644 --- a/docs/source/tutorial/all-the-things.rst +++ b/docs/source/tutorial/all-the-things.rst @@ -11,10 +11,14 @@ These are all the things. Use your browser's search to find things you want. All of the code below is available at the `sol3 tutorial examples`_. +.. note:: + + Make sure to add ``SOL_ALL_SAFETIES_ON`` preprocessor define to your build configuration to turn safety on. + asserts / prerequisites ----------------------- -You'll need to ``#include `` 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 :doc:`getting started tutorial` for more details. +You'll need to ``#include `` 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 :doc:`getting started tutorial` for more details. The implementation for ``assert.hpp`` with ``c_assert`` looks like so: @@ -57,6 +61,13 @@ To run Lua code but have an error handler in case things go wrong: :linenos: :lines: 28-39,47- +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. + + +.. note:: + + If you have the safety definitions on, `.script` will call into the `.safe_script` versions automatically. Otherwise, it will call into the `.unsafe_script` versions. + running lua code (low-level) ---------------------------- @@ -75,6 +86,24 @@ You can use the individual load and function call operator to load, check, and t 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: + +.. literalinclude:: ../../../examples/source/tutorials/quick_n_dirty/arguments_to_scripts.cpp + :linenos: + + +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*! + +.. literalinclude:: ../../../examples/source//dump.cpp + :linenos: + + set and get variables --------------------- @@ -254,14 +283,14 @@ You can emulate namespacing by having a table and giving it the namespace names :lines: 1- -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 :doc:`sol::table's<../api/table>` abstractions. +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 :doc:`sol::table's<../api/table>` abstractions. there is a LOT more ------------------- Some more things you can do/read about: * :doc:`the usertypes page<../usertypes>` lists the huge amount of features for functions - - :doc:`unique usertype traits<../api/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 + - :doc:`unique usertype traits<../api/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 * :doc:`the containers page<../containers>` gives full information about handling everything about container-like usertypes * :doc:`the functions page<../functions>` lists a myriad of features for functions - :doc:`variadic arguments<../api/variadic_args>` in functions with ``sol::variadic_args``. @@ -271,11 +300,12 @@ Some more things you can do/read about: * :doc:`ownership semantics` are described for how Lua deals with its own internal references and (raw) pointers. * :doc:`stack manipulation<../api/stack>` to safely play with the stack. You can also define customization points for ``stack::get``/``stack::check``/``stack::push`` for your type. * :doc:`make_reference/make_object convenience function<../api/make_reference>` to get the same benefits and conveniences as the low-level stack API but put into objects you can specify. - * :doc:`stack references<../api/stack_reference>` to have zero-overhead Sol abstractions while not copying to the Lua registry. + * :doc:`stack references<../api/stack_reference>` to have zero-overhead sol abstractions while not copying to the Lua registry. * :doc:`resolve<../api/resolve>` overloads in case you have overloaded functions; a cleaner casting utility. You must use this to emulate default parameters. +.. _.safe_script: https://github.com/ThePhD/sol2/tree/develop/examples/source/tutorials/quick_n_dirty/running_lua_code_safely.cpp .. _develop custom loaders: https://github.com/ThePhD/sol2/blob/develop/examples/custom_reader.cpp .. _basic example: https://github.com/ThePhD/sol2/blob/develop/examples/usertype.cpp .. _special functions example: https://github.com/ThePhD/sol2/blob/develop/examples/usertype_special_functions.cpp .. _initializers example: https://github.com/ThePhD/sol2/blob/develop/examples/usertype_initializers.cpp -.. _sol3 tutorial examples: https://github.com/ThePhD/sol2/tree/develop/examples/tutorials/quick_n_dirty +.. _sol3 tutorial examples: https://github.com/ThePhD/sol2/tree/develop/examples/source/tutorials/quick_n_dirty diff --git a/docs/source/tutorial/customization.rst b/docs/source/tutorial/customization.rst index f9aac2e8..272f6dc8 100644 --- a/docs/source/tutorial/customization.rst +++ b/docs/source/tutorial/customization.rst @@ -1,7 +1,7 @@ adding your own types ===================== -Sometimes, overriding Sol to make it handle certain ``struct``'s and ``class``'es as something other than just userdata is desirable. The way to do this is to take advantage of the 4 customization points for Sol. These are ``sol::lua_size``, ``sol::stack::unqualified_pusher``, ``sol::stack::getter``, ``sol::stack::checker``. +Sometimes, overriding sol to make it handle certain ``struct``'s and ``class``'es as something other than just userdata is desirable. The way to do this is to take advantage of the 4 customization points for sol. These are ``sol_lua_check``, ``sol_lua_get``, ``sol_lua_push``, and ``sol_lua_check_get``. These are template class/structs, so you'll override them using a technique C++ calls *class/struct specialization*. Below is an example of a struct that gets broken apart into 2 pieces when going in the C++ --> Lua direction, and then pulled back into a struct when going in the Lua --> C++: @@ -25,8 +25,8 @@ You can make something pushable into Lua, but not get-able in the same way if yo .. note:: - It is important to note here that the ``getter``, ``pusher`` and ``checker`` differentiate between a type ``T`` and a pointer to a type ``T*``. This means that if you want to work purely with, say, a ``T*`` handle that does not have the same semantics as just ``T``, you may need to specify checkers/getters/pushers for both ``T*`` and ``T``. The checkers for ``T*`` forward to the checkers for ``T``, but the getter for ``T*`` does not forward to the getter for ``T`` (e.g., because of ``int*`` not being quite the same as ``int``). + It is important to note here that the ``gett``, ``push`` and ``check`` differentiate between a type ``T`` and a pointer to a type ``T*``. This means that if you want to work purely with, say, a ``T*`` handle that does not have the same semantics as just ``T``, you may need to specify checkers/getters/pushers for both ``T*`` and ``T``. The checkers for ``T*`` forward to the checkers for ``T``, but the getter for ``T*`` does not forward to the getter for ``T`` (e.g., because of ``int*`` not being quite the same as ``int``). -In general, this is fine since most getters/checkers only use 1 stack point. But, if you're doing more complex nested classes, it would be useful to use ``tracking.last`` to understand how many stack indices the last getter/checker operation did and increment it by ``index + tracking.last`` after using a ``stack::check<..>( L, index, tracking)`` call. +In general, this is fine since most getters/checkers only use 1 stack point. But, if you're doing more complex nested classes, it would be useful to use ``tracking.last`` to understand how many stack indices the last gett/check operation did and increment it by ``index + tracking.last`` after using a ``stack::check<..>( L, index, tracking)`` call. -You can read more about the structs themselves :ref:`over on the API page for stack`, and if there's something that goes wrong or you have anymore questions, please feel free to drop a line on the Github Issues page or send an e-mail! +You can read more about the extension points themselves :ref:`over on the API page for stack`, and if there's something that goes wrong or you have anymore questions, please feel free to drop a line on the Github Issues page or send an e-mail! diff --git a/docs/source/tutorial/cxx-in-lua.rst b/docs/source/tutorial/cxx-in-lua.rst index 9ebdf7d6..bf1b3129 100644 --- a/docs/source/tutorial/cxx-in-lua.rst +++ b/docs/source/tutorial/cxx-in-lua.rst @@ -1,7 +1,7 @@ C++ in Lua ========== -Using user defined types ("usertype"s, or just "udt"s) is simple with Sol. If you don't call any member variables or functions, then you don't even have to 'register' the usertype at all: just pass it through. But if you want variables and functions on your usertype inside of Lua, you need to register it. We're going to give a short example here that includes a bunch of information on how to work with things. +Using user defined types ("usertype"s, or just "udt"s) is simple with sol. If you don't call any member variables or functions, then you don't even have to 'register' the usertype at all: just pass it through. But if you want variables and functions on your usertype inside of Lua, you need to register it. We're going to give a short example here that includes a bunch of information on how to work with things. Take this ``player`` struct in C++ in a header file: @@ -133,7 +133,7 @@ To do this, you bind things using the ``new_usertype`` and ``set_usertype`` meth That script should run fine now, and you can observe and play around with the values. Even more stuff :doc:`you can do<../api/usertype>` is described elsewhere, like initializer functions (private constructors / destructors support), "static" functions callable with ``name.my_function( ... )``, and overloaded member functions. You can even bind global variables (even by reference with ``std::ref``) with ``sol::var``. There's a lot to try out! -This is a powerful way to allow reuse of C++ code from Lua beyond just registering functions, and should get you on your way to having more complex classes and data structures! In the case that you need more customization than just usertypes, however, you can customize Sol to behave more fit to your desires by using the desired :doc:`customization and extension structures`. +This is a powerful way to allow reuse of C++ code from Lua beyond just registering functions, and should get you on your way to having more complex classes and data structures! In the case that you need more customization than just usertypes, however, you can customize sol to behave more fit to your desires by using the desired :doc:`customization and extension structures`. You can check out this code and more complicated code at the `examples directory`_ by looking at the ``usertype_``-prefixed examples. diff --git a/docs/source/tutorial/existing.rst b/docs/source/tutorial/existing.rst index 17e70eda..a78d0466 100644 --- a/docs/source/tutorial/existing.rst +++ b/docs/source/tutorial/existing.rst @@ -9,7 +9,7 @@ If you're already using lua and you just want to use ``sol`` in some places, you :name: state-view-snippet int something_in_my_system (lua_State* L) { - // start using Sol with a pre-existing system + // start using sol with a pre-existing system sol::state_view lua(L); // non-owning lua.script("print('bark bark bark!')"); @@ -21,13 +21,13 @@ If you're already using lua and you just want to use ``sol`` in some places, you return 0; // or whatever you require of working with a raw function } -:doc:`sol::state_view<../api/state>` is exactly like ``sol::state``, but it doesn't manage the lifetime of a ``lua_State*``. Therefore, you get all the goodies that come with a ``sol::state`` without any of the ownership implications. Sol has no initialization components that need to deliberately remain alive for the duration of the program. It's entirely self-containing and uses lua's garbage collectors and various implementation techniques to require no state C++-side. After you do that, all of the power of `Sol` is available to you, and then some! +:doc:`sol::state_view<../api/state>` is exactly like ``sol::state``, but it doesn't manage the lifetime of a ``lua_State*``. Therefore, you get all the goodies that come with a ``sol::state`` without any of the ownership implications. sol has no initialization components that need to deliberately remain alive for the duration of the program. It's entirely self-containing and uses lua's garbage collectors and various implementation techniques to require no state C++-side. After you do that, all of the power of `sol` is available to you, and then some! ``sol::state_view`` is also helpful when you want to `create a DLL that loads some Lua module`_ via requires. You may also want to call ``require`` and supply a string of a script file or something that returns an object that you set equal to something in C++. For that, you can use the :ref:`require functionality`. -Remember that Sol can be as lightweight as you want it: almost all of Sol's Lua types take the ``lua_State*`` argument and then a second ``int index`` stack index argument, meaning you can use :doc:`tables<../api/table>`, :doc:`lua functions<../api/function>`, :doc:`coroutines<../api/coroutine>`, and other reference-derived objects that expose the proper constructor for your use. You can also set :doc:`usertypes<../api/usertype>` and other things you need without changing your entire architecture in one go. +Remember that sol can be as lightweight as you want it: almost all of sol's Lua types take the ``lua_State*`` argument and then a second ``int index`` stack index argument, meaning you can use :doc:`tables<../api/table>`, :doc:`lua functions<../api/function>`, :doc:`coroutines<../api/coroutine>`, and other reference-derived objects that expose the proper constructor for your use. You can also set :doc:`usertypes<../api/usertype>` and other things you need without changing your entire architecture in one go. You can even customize it to `work with an external Lua wrapper/framework/library`_. diff --git a/docs/source/tutorial/functions.rst b/docs/source/tutorial/functions.rst index c6c0e31a..90258001 100644 --- a/docs/source/tutorial/functions.rst +++ b/docs/source/tutorial/functions.rst @@ -1,12 +1,12 @@ functions and You ================= -Sol can register all kinds of functions. Many are shown in the :doc:`quick 'n' dirty`, but here we will discuss many of the additional ways you can register functions into a sol-wrapped Lua system. +sol can register all kinds of functions. Many are shown in the :doc:`quick 'n' dirty`, but here we will discuss many of the additional ways you can register functions into a sol-wrapped Lua system. Setting a new function ---------------------- -Given a C++ function, you can drop it into Sol in several equivalent ways, working similar to how :ref:`setting variables` works: +Given a C++ function, you can drop it into sol in several equivalent ways, working similar to how :ref:`setting variables` works: .. code-block:: cpp :linenos: @@ -338,4 +338,4 @@ It can be used like so, inconjunction with ``sol::this_state``: } -This covers almost everything you need to know about Functions and how they interact with Sol. For some advanced tricks and neat things, check out :doc:`sol::this_state<../api/this_state>` and :doc:`sol::variadic_args<../api/variadic_args>`. The next stop in this tutorial is about :doc:`C++ types (usertypes) in Lua`! If you need a bit more information about functions in the C++ side and how to best utilize arguments from C++, see :ref:`this note`. +This covers almost everything you need to know about Functions and how they interact with sol. For some advanced tricks and neat things, check out :doc:`sol::this_state<../api/this_state>` and :doc:`sol::variadic_args<../api/variadic_args>`. The next stop in this tutorial is about :doc:`C++ types (usertypes) in Lua`! If you need a bit more information about functions in the C++ side and how to best utilize arguments from C++, see :ref:`this note`. diff --git a/docs/source/tutorial/getting-started.rst b/docs/source/tutorial/getting-started.rst index 1cf8079d..2873d02f 100644 --- a/docs/source/tutorial/getting-started.rst +++ b/docs/source/tutorial/getting-started.rst @@ -1,7 +1,7 @@ getting started =============== -Let's get you going with Sol! To start, you'll need to use a lua distribution of some sort. Sol doesn't provide that: it only wraps the API that comes with it, so you can pick whatever distribution you like for your application. There are lots, but the two popular ones are `vanilla Lua`_ and speedy `LuaJIT`_ . We recommend vanilla Lua if you're getting started, LuaJIT if you need speed and can handle some caveats: the interface for Sol doesn't change no matter what Lua version you're using. +Let's get you going with sol! To start, you'll need to use a lua distribution of some sort. sol doesn't provide that: it only wraps the API that comes with it, so you can pick whatever distribution you like for your application. There are lots, but the two popular ones are `vanilla Lua`_ and speedy `LuaJIT`_ . We recommend vanilla Lua if you're getting started, LuaJIT if you need speed and can handle some caveats: the interface for sol doesn't change no matter what Lua version you're using. If you need help getting or building Lua, check out the `Lua page on getting started`_. Note that for Visual Studio, one can simply download the sources, include all the Lua library files in that project, and then build for debug/release, x86/x64/ARM rather easily and with minimal interference. Just make sure to adjust the Project Property page to build as a static library (or a DLL with the proper define set in the ``Preprocessor`` step). @@ -59,7 +59,7 @@ The second line opens a single lua-provided library, "base". There are several o return 0; } -If you're interested in integrating Sol with a project that already uses some other library or Lua in the codebase, check out the :doc:`existing example` to see how to work with Sol when you add it to a project (the existing example covers ``require`` as well)! +If you're interested in integrating sol with a project that already uses some other library or Lua in the codebase, check out the :doc:`existing example` to see how to work with sol when you add it to a project (the existing example covers ``require`` as well)! .. note:: diff --git a/docs/source/tutorial/ownership.rst b/docs/source/tutorial/ownership.rst index a70112ba..8f6f13e0 100644 --- a/docs/source/tutorial/ownership.rst +++ b/docs/source/tutorial/ownership.rst @@ -34,7 +34,7 @@ You can take a reference to something that exists in Lua by pulling out a :doc:` lua["say"](keep_alive); -Sol will not take ownership of raw pointers: raw pointers do not own anything. Sol will not delete raw pointers, because they do not (and are not supposed to) own anything: +sol will not take ownership of raw pointers: raw pointers do not own anything. sol will not delete raw pointers, because they do not (and are not supposed to) own anything: .. code-block:: cpp @@ -96,7 +96,7 @@ If you have something you know is going to last and you just want to give it to }; -Sol can detect ``nullptr``, so if you happen to return it there won't be any dangling because a ``sol::nil`` will be pushed. +sol can detect ``nullptr``, so if you happen to return it there won't be any dangling because a ``sol::nil`` will be pushed. .. code-block:: cpp diff --git a/docs/source/tutorial/tutorial-top.rst b/docs/source/tutorial/tutorial-top.rst index 677b31f1..ee152b61 100644 --- a/docs/source/tutorial/tutorial-top.rst +++ b/docs/source/tutorial/tutorial-top.rst @@ -5,7 +5,7 @@ Take some time to learn the framework with these tutorials. But, if you need to .. toctree:: - :caption: Sol Tutorial + :caption: sol Tutorial :name: tutorialtoc :maxdepth: 2 diff --git a/docs/source/usertypes.rst b/docs/source/usertypes.rst index ef84e46c..5afc8084 100644 --- a/docs/source/usertypes.rst +++ b/docs/source/usertypes.rst @@ -58,8 +58,8 @@ Here are some other general advice and tips for understanding and dealing with u - Work on a copy by taking arguments or returning by value. - Do not use r-value references: they do not mean anything in Lua code. - Move-only types can only be taken by reference: sol3 cannot know if/when to move a value (except when serializing with perfect forwarding *into* Lua, but not calling a C++ function from Lua) -* The actual metatable associated with the usertype has a long name and is defined to be opaque by the Sol implementation. -* The actual metatable inner workings is opaque and defined by the Sol implementation, and there are no internal docs because optimizations on the operations are applied based on heuristics we discover from performance testing the system. +* The actual metatable associated with the usertype has a long name and is defined to be opaque by the sol implementation. +* The actual metatable inner workings is opaque and defined by the sol implementation, and there are no internal docs because optimizations on the operations are applied based on heuristics we discover from performance testing the system. .. _here, that uses a few tricks: https://github.com/ThePhD/sol2/blob/develop/examples/usertype_bitfields.cpp .. _Lua: https://github.com/ThePhD/sol2/blob/develop/examples/usertype_advanced.cpp#L81 diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt index 2ac93f1e..2c285dee 100644 --- a/examples/CMakeLists.txt +++ b/examples/CMakeLists.txt @@ -1,4 +1,4 @@ -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors @@ -20,7 +20,7 @@ # IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# # # sol2 Examples +# # # sol3 Examples if (SOL2_DYNAMIC_LOADING_EXAMPLES OR SOL2_DYNAMIC_LOADING_EXAMPLES_SINGLE OR SOL2_DYNAMIC_LOADING_EXAMPLES_SINGLE_GENERATED) # # require_from_dll example diff --git a/examples/interop/LuaBridge/CMakeLists.txt b/examples/interop/LuaBridge/CMakeLists.txt index 4e644cbe..6417f76b 100644 --- a/examples/interop/LuaBridge/CMakeLists.txt +++ b/examples/interop/LuaBridge/CMakeLists.txt @@ -1,4 +1,4 @@ -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors @@ -20,7 +20,7 @@ # IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# # # sol2 interop Examples - luabridge +# # # sol3 interop Examples - luabridge find_package(LuaBridgeBuild) diff --git a/examples/interop/LuaBridge/source/LuaBridge.cpp b/examples/interop/LuaBridge/source/LuaBridge.cpp index 72d9ccc7..81a9199b 100644 --- a/examples/interop/LuaBridge/source/LuaBridge.cpp +++ b/examples/interop/LuaBridge/source/LuaBridge.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #define SOL_ENABLE_INTEROP 1 // MUST be defined to use interop features #include diff --git a/examples/interop/kaguya/CMakeLists.txt b/examples/interop/kaguya/CMakeLists.txt index 9e1bc8e9..0b010612 100644 --- a/examples/interop/kaguya/CMakeLists.txt +++ b/examples/interop/kaguya/CMakeLists.txt @@ -1,4 +1,4 @@ -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors @@ -20,7 +20,7 @@ # IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# # # sol2 interop Examples - kaguya +# # # sol3 interop Examples - kaguya find_package(KaguyaBuild) diff --git a/examples/interop/kaguya/source/kaguya.cpp b/examples/interop/kaguya/source/kaguya.cpp index 564f38ec..ce81ff81 100644 --- a/examples/interop/kaguya/source/kaguya.cpp +++ b/examples/interop/kaguya/source/kaguya.cpp @@ -1,6 +1,6 @@ #include -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #define SOL_ENABLE_INTEROP 1 // MUST be defined to use interop features #include diff --git a/examples/interop/luwra/CMakeLists.txt b/examples/interop/luwra/CMakeLists.txt index ef6c4501..27538121 100644 --- a/examples/interop/luwra/CMakeLists.txt +++ b/examples/interop/luwra/CMakeLists.txt @@ -1,4 +1,4 @@ -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors @@ -20,7 +20,7 @@ # IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# # # sol2 interop Examples - luwra +# # # sol3 interop Examples - luwra find_package(LuwraBuild) diff --git a/examples/interop/luwra/source/luwra.cpp b/examples/interop/luwra/source/luwra.cpp index 6710194c..2a12f6ca 100644 --- a/examples/interop/luwra/source/luwra.cpp +++ b/examples/interop/luwra/source/luwra.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #define SOL_ENABLE_INTEROP 1 // MUST be defined to use interop features #include @@ -55,7 +55,7 @@ inline bool sol_lua_interop_check(sol::types, lua_State* L, int relindex, sol template inline std::pair sol_lua_interop_get(sol::types t, lua_State* L, int relindex, void* unadjusted_pointer, sol::stack::record& tracking) { // you may not need to specialize this method every time: - // some libraries are compatible with sol2's layout + // some libraries are compatible with sol3's layout int index = lua_absindex(L, relindex); if (!sol_lua_interop_check(t, L, index, sol::type::userdata, sol::no_panic, tracking)) { return { false, nullptr }; diff --git a/examples/interop/tolua/CMakeLists.txt b/examples/interop/tolua/CMakeLists.txt index fc3ce957..75f94cc9 100644 --- a/examples/interop/tolua/CMakeLists.txt +++ b/examples/interop/tolua/CMakeLists.txt @@ -1,4 +1,4 @@ -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors @@ -20,7 +20,7 @@ # IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# # # sol2 interop Examples - tolua +# # # sol3 interop Examples - tolua find_package(ToLuappBuild REQUIRED) diff --git a/examples/interop/tolua/source/tolua.cpp b/examples/interop/tolua/source/tolua.cpp index 0c31eee1..d413e270 100644 --- a/examples/interop/tolua/source/tolua.cpp +++ b/examples/interop/tolua/source/tolua.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #define SOL_ENABLE_INTEROP 1 // MUST be defined to use interop features #include diff --git a/examples/require_dll_example/CMakeLists.txt b/examples/require_dll_example/CMakeLists.txt index 39544d49..a2aea847 100644 --- a/examples/require_dll_example/CMakeLists.txt +++ b/examples/require_dll_example/CMakeLists.txt @@ -1,4 +1,4 @@ -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors @@ -20,7 +20,7 @@ # IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# # # sol2 Examples - require_from_dll +# # # sol3 Examples - require_from_dll # # Reusable function to call for single target # # Also hides variables from directory/global scope diff --git a/examples/require_dll_example/source/my_object.cpp b/examples/require_dll_example/source/my_object.cpp index a733afd4..d966c2b7 100644 --- a/examples/require_dll_example/source/my_object.cpp +++ b/examples/require_dll_example/source/my_object.cpp @@ -1,6 +1,6 @@ #include -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include namespace my_object { diff --git a/examples/require_dll_example/source/require_from_dll.cpp b/examples/require_dll_example/source/require_from_dll.cpp index 33f71a8f..874d187a 100644 --- a/examples/require_dll_example/source/require_from_dll.cpp +++ b/examples/require_dll_example/source/require_from_dll.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/any_return.cpp b/examples/source/any_return.cpp index 04e98f5c..33ff7d8a 100644 --- a/examples/source/any_return.cpp +++ b/examples/source/any_return.cpp @@ -1,10 +1,10 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include #include "assert.hpp" -// Uses some of the fancier bits of sol2, including the "transparent argument", +// Uses some of the fancier bits of sol3, including the "transparent argument", // sol::this_state, which gets the current state and does not increment // function arguments sol::object fancy_func(sol::object a, sol::object b, sol::this_state s) { diff --git a/examples/source/args_from_container.cpp b/examples/source/args_from_container.cpp index 43db2b9f..0e310d89 100644 --- a/examples/source/args_from_container.cpp +++ b/examples/source/args_from_container.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/as_returns.cpp b/examples/source/as_returns.cpp index e24bbc9f..1c2e759b 100644 --- a/examples/source/as_returns.cpp +++ b/examples/source/as_returns.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/basic.cpp b/examples/source/basic.cpp index 577cfbc4..78d1d77c 100644 --- a/examples/source/basic.cpp +++ b/examples/source/basic.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/c_array.cpp b/examples/source/c_array.cpp index 62c9af71..084c04d6 100644 --- a/examples/source/c_array.cpp +++ b/examples/source/c_array.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/c_call.cpp b/examples/source/c_call.cpp index 87f17bb5..47587052 100644 --- a/examples/source/c_call.cpp +++ b/examples/source/c_call.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/calling_lua_functions.cpp b/examples/source/calling_lua_functions.cpp index c848fb3a..66680384 100644 --- a/examples/source/calling_lua_functions.cpp +++ b/examples/source/calling_lua_functions.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/config.cpp b/examples/source/config.cpp index 0c254a1f..883696b4 100644 --- a/examples/source/config.cpp +++ b/examples/source/config.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/container_usertype_as_container.cpp b/examples/source/container_usertype_as_container.cpp index a9aa7dc5..20cbfbf3 100644 --- a/examples/source/container_usertype_as_container.cpp +++ b/examples/source/container_usertype_as_container.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/container_with_pairs.cpp b/examples/source/container_with_pairs.cpp index 0becee33..7651a68f 100644 --- a/examples/source/container_with_pairs.cpp +++ b/examples/source/container_with_pairs.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/containers.cpp b/examples/source/containers.cpp index 800631d3..01bf420e 100644 --- a/examples/source/containers.cpp +++ b/examples/source/containers.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/containers_as_table.cpp b/examples/source/containers_as_table.cpp index c8d8fb5d..5a0ce020 100644 --- a/examples/source/containers_as_table.cpp +++ b/examples/source/containers_as_table.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/coroutine.cpp b/examples/source/coroutine.cpp index 7c87ed46..045bbe83 100644 --- a/examples/source/coroutine.cpp +++ b/examples/source/coroutine.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/coroutine_state.cpp b/examples/source/coroutine_state.cpp index eb6f69f9..bcece881 100644 --- a/examples/source/coroutine_state.cpp +++ b/examples/source/coroutine_state.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/custom_reader.cpp b/examples/source/custom_reader.cpp index 252d3f7b..3e0d4302 100644 --- a/examples/source/custom_reader.cpp +++ b/examples/source/custom_reader.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/customization_convert_on_get.cpp b/examples/source/customization_convert_on_get.cpp index 77df4fc7..da2b5da5 100644 --- a/examples/source/customization_convert_on_get.cpp +++ b/examples/source/customization_convert_on_get.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include @@ -11,7 +11,7 @@ struct number_shim { template bool sol_lua_check(sol::types, lua_State* L, int index, Handler&& handler, sol::stack::record& tracking) { - // check_usertype is a backdoor for directly checking sol2 usertypes + // check_usertype is a backdoor for directly checking sol3 usertypes if (!sol::stack::check_usertype(L, index) && !sol::stack::check(L, index)) { handler(L, index, sol::type_of(L, index), sol::type::userdata, "expected a number_shim or a number"); diff --git a/examples/source/customization_global_transparent_argument.cpp b/examples/source/customization_global_transparent_argument.cpp index 2ab95073..a7e93c33 100644 --- a/examples/source/customization_global_transparent_argument.cpp +++ b/examples/source/customization_global_transparent_argument.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include // Something that can't be collided with diff --git a/examples/source/customization_multiple.cpp b/examples/source/customization_multiple.cpp index 796349e9..2d5ae0f5 100644 --- a/examples/source/customization_multiple.cpp +++ b/examples/source/customization_multiple.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/docs/as_function.cpp b/examples/source/docs/as_function.cpp index ea0ebe83..ef9ac613 100644 --- a/examples/source/docs/as_function.cpp +++ b/examples/source/docs/as_function.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include int main () { diff --git a/examples/source/docs/as_function_usertype_member_variable.cpp b/examples/source/docs/as_function_usertype_member_variable.cpp index 456a3909..3907b131 100644 --- a/examples/source/docs/as_function_usertype_member_variable.cpp +++ b/examples/source/docs/as_function_usertype_member_variable.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include int main () { diff --git a/examples/source/docs/as_table_ipairs.cpp b/examples/source/docs/as_table_ipairs.cpp index 8a393f8d..43978ce4 100644 --- a/examples/source/docs/as_table_ipairs.cpp +++ b/examples/source/docs/as_table_ipairs.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/docs/inheritance.cpp b/examples/source/docs/inheritance.cpp index e09a7ed2..b1c87f06 100644 --- a/examples/source/docs/inheritance.cpp +++ b/examples/source/docs/inheritance.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include struct A { diff --git a/examples/source/docs/my_panic.cpp b/examples/source/docs/my_panic.cpp index 16471c7e..3e696974 100644 --- a/examples/source/docs/my_panic.cpp +++ b/examples/source/docs/my_panic.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/docs/preparing_environments.cpp b/examples/source/docs/preparing_environments.cpp index 1b377deb..f3820f7e 100644 --- a/examples/source/docs/preparing_environments.cpp +++ b/examples/source/docs/preparing_environments.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include int main (int, char*[]) { diff --git a/examples/source/docs/references_in_lambdas.cpp b/examples/source/docs/references_in_lambdas.cpp index 4bf0c6ea..f681d2a7 100644 --- a/examples/source/docs/references_in_lambdas.cpp +++ b/examples/source/docs/references_in_lambdas.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/docs/runtime_extension.cpp b/examples/source/docs/runtime_extension.cpp index e747f9b6..9d36d0d4 100644 --- a/examples/source/docs/runtime_extension.cpp +++ b/examples/source/docs/runtime_extension.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/docs/simple_functions.cpp b/examples/source/docs/simple_functions.cpp index 17a1ed8b..c49c8539 100644 --- a/examples/source/docs/simple_functions.cpp +++ b/examples/source/docs/simple_functions.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/docs/simple_structs.cpp b/examples/source/docs/simple_structs.cpp index e98f2bb1..9b0fc272 100644 --- a/examples/source/docs/simple_structs.cpp +++ b/examples/source/docs/simple_structs.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/docs/state_script_safe.cpp b/examples/source/docs/state_script_safe.cpp index 372450ce..22defee3 100644 --- a/examples/source/docs/state_script_safe.cpp +++ b/examples/source/docs/state_script_safe.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/docs/state_transfer.cpp b/examples/source/docs/state_transfer.cpp index 332f17ca..1728810e 100644 --- a/examples/source/docs/state_transfer.cpp +++ b/examples/source/docs/state_transfer.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include diff --git a/examples/source/dump.cpp b/examples/source/dump.cpp new file mode 100644 index 00000000..16d94b7c --- /dev/null +++ b/examples/source/dump.cpp @@ -0,0 +1,42 @@ +#define SOL_ALL_SAFETIES_ON 1 +#include + +#include +#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; + 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; +} \ No newline at end of file diff --git a/examples/source/dynamic_object.cpp b/examples/source/dynamic_object.cpp index 2c2cd684..3d04da6d 100644 --- a/examples/source/dynamic_object.cpp +++ b/examples/source/dynamic_object.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/environment_snooping.cpp b/examples/source/environment_snooping.cpp index f6c272c7..1c3fdf10 100644 --- a/examples/source/environment_snooping.cpp +++ b/examples/source/environment_snooping.cpp @@ -1,10 +1,10 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" #include -// Simple sol2 version of the below +// Simple sol3 version of the below void simple(sol::this_state ts, sol::this_environment te) { sol::state_view lua = ts; if (te) { diff --git a/examples/source/environment_state.cpp b/examples/source/environment_state.cpp index 9f4bf3be..c8768795 100644 --- a/examples/source/environment_state.cpp +++ b/examples/source/environment_state.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/environment_state_2.cpp b/examples/source/environment_state_2.cpp index cbd8261d..57ec2fee 100644 --- a/examples/source/environment_state_2.cpp +++ b/examples/source/environment_state_2.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/environments.cpp b/examples/source/environments.cpp index f484a1fc..0087dea3 100644 --- a/examples/source/environments.cpp +++ b/examples/source/environments.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/environments_on_functions.cpp b/examples/source/environments_on_functions.cpp index 4f1cd5b1..baa0e77b 100644 --- a/examples/source/environments_on_functions.cpp +++ b/examples/source/environments_on_functions.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/error_handler.cpp b/examples/source/error_handler.cpp index 3fd333a6..6564676c 100644 --- a/examples/source/error_handler.cpp +++ b/examples/source/error_handler.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/exception_handler.cpp b/examples/source/exception_handler.cpp index 0601fa22..5fdb4dd4 100644 --- a/examples/source/exception_handler.cpp +++ b/examples/source/exception_handler.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/functions.cpp b/examples/source/functions.cpp index 96c00369..007dff3c 100644 --- a/examples/source/functions.cpp +++ b/examples/source/functions.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/functions_empty_arguments.cpp b/examples/source/functions_empty_arguments.cpp index a2f393db..6d93e9b7 100644 --- a/examples/source/functions_empty_arguments.cpp +++ b/examples/source/functions_empty_arguments.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/index_and_newindex_usertype.cpp b/examples/source/index_and_newindex_usertype.cpp index fece136b..bc87e1d6 100644 --- a/examples/source/index_and_newindex_usertype.cpp +++ b/examples/source/index_and_newindex_usertype.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/indirect_function_calls.cpp b/examples/source/indirect_function_calls.cpp index 8196aeab..da9e13ca 100644 --- a/examples/source/indirect_function_calls.cpp +++ b/examples/source/indirect_function_calls.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" @@ -33,7 +33,7 @@ sol::variadic_results call_it(sol::object function_name, sol::variadic_args args return results; } -int main() { +int main(int, char* []) { std::cout << "=== indirect function calls ===" << std::endl; sol::state lua; diff --git a/examples/source/lua_value.cpp b/examples/source/lua_value.cpp new file mode 100644 index 00000000..97ce227d --- /dev/null +++ b/examples/source/lua_value.cpp @@ -0,0 +1,103 @@ +#define SOL_ALL_SAFETIES_ON 1 +#include + +#include "assert.hpp" +#include +#include + +struct int_entry { + int value; + + int_entry() : value(0) { + } + + int_entry(int v) : value(v) { + } + + std::string to_string () const { + return "int_entry(" + std::to_string(value) + ")"; + } + + bool operator==(const int_entry& e) const { + return value == e.value; + } +}; + +int main(int, char* []) { + + std::cout << "=== sol::lua_value/sol::array_value ===" << std::endl; + + sol::state lua; + lua.open_libraries(sol::lib::base, sol::lib::io); + + sol::lua_value lv_int(lua, 56); + sol::lua_value lv_int_table(lua, { 1, 2, 3, 4, 5 }); + sol::lua_value lv_map(lua, { { "bark bark", "meow hiss!" }, { 3, 4 }, { ":D", 6 } }); + sol::lua_value lv_mixed_table(lua, sol::array_value{ 1, int_entry(2), 3, int_entry(4), 5 }); + sol::lua_value lv_mixed_nested_table(lua, sol::array_value{ 1, int_entry(2), 3, int_entry(4), sol::array_value{ 5, 6, int_entry(7), "8" } }); + + const auto& code = R"( + function real_print_recursive (e, level) + local et = type(e) + if et == 'table' then + io.write("{ ") + local iters = 0 + for k, v in pairs(e) do + if iters ~= 0 then + io.write(", ") + end + real_print_recursive(k, level + 1) + io.write(": ") + real_print_recursive(v, level + 1) + iters = iters + 1 + end + io.write(" }") + elseif et == 'string' then + io.write('"') + io.write(e) + io.write('"') + else + io.write(tostring(e)) + end + if level == 0 then + io.write("\n") + end + end + + function print_recursive (e) + real_print_recursive(e, 0) + end + )"; + + sol::optional maybe_error = lua.safe_script(code, sol::script_pass_on_error); + if (maybe_error) { + std::cerr << maybe_error->what() << std::endl; + return 1; + } + sol::function print_recursive = lua["print_recursive"]; + + // show it printed out + std::cout << "lv_int: " << std::endl; + print_recursive(lv_int); + std::cout << std::endl; + + std::cout << "lv_int_table: " << std::endl; + print_recursive(lv_int_table); + std::cout << std::endl; + + std::cout << "lv_map: " << std::endl; + print_recursive(lv_map); + std::cout << std::endl; + + std::cout << "lv_mixed_table: " << std::endl; + print_recursive(lv_mixed_table); + std::cout << std::endl; + + std::cout << "lv_mixed_nested_table: " << std::endl; + print_recursive(lv_mixed_nested_table); + std::cout << std::endl; + + std::cout << std::endl; + + return 0; +} \ No newline at end of file diff --git a/examples/source/metatable_customization.cpp b/examples/source/metatable_customization.cpp index 01bd518e..c259598f 100644 --- a/examples/source/metatable_customization.cpp +++ b/examples/source/metatable_customization.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include @@ -55,7 +55,7 @@ void register_thing_type(sol::state& lua) { // so we call out lua_CFunction that we serialized earlier auto it = thing_variable_associations.find(*maybe_svkey); if (it != thing_variable_associations.cend()) { - // note that calls generated by sol2 + // note that calls generated by sol3 // for member variables expect the stack ordering to be // 2(, 3, ..., n) -- value(s) // 1 -- source @@ -87,7 +87,7 @@ void register_thing_type(sol::state& lua) { // so we call out lua_CFunction that we serialized earlier auto it = thing_variable_associations.find(*maybe_svkey); if (it != thing_variable_associations.cend()) { - // note that calls generated by sol2 + // note that calls generated by sol3 // for member variables expect the stack ordering to be // 2(, 3, ..., n) -- value(s) // 1 -- source diff --git a/examples/source/metatable_key_low_level.cpp b/examples/source/metatable_key_low_level.cpp index 341e016e..8e79ab44 100644 --- a/examples/source/metatable_key_low_level.cpp +++ b/examples/source/metatable_key_low_level.cpp @@ -1,9 +1,9 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" -int main () { +int main(int, char* []) { struct bark { int operator()(int x) { diff --git a/examples/source/multi_results.cpp b/examples/source/multi_results.cpp index 2aec0819..6487f72a 100644 --- a/examples/source/multi_results.cpp +++ b/examples/source/multi_results.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/optional_with_iteration.cpp b/examples/source/optional_with_iteration.cpp index 1bbcb792..abf6885c 100644 --- a/examples/source/optional_with_iteration.cpp +++ b/examples/source/optional_with_iteration.cpp @@ -1,11 +1,11 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include #include #include -int main(int, char**) { +int main(int, char* []) { std::cout << "=== optional with iteration ===" << std::endl; struct thing { diff --git a/examples/source/overloading.cpp b/examples/source/overloading.cpp index 4c18a049..696e153f 100644 --- a/examples/source/overloading.cpp +++ b/examples/source/overloading.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/overloading_with_fallback.cpp b/examples/source/overloading_with_fallback.cpp index e4f0092d..c14ed461 100644 --- a/examples/source/overloading_with_fallback.cpp +++ b/examples/source/overloading_with_fallback.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/overloading_with_members.cpp b/examples/source/overloading_with_members.cpp index 9fb3c2c1..92f1260d 100644 --- a/examples/source/overloading_with_members.cpp +++ b/examples/source/overloading_with_members.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/overridable_function_members.cpp b/examples/source/overridable_function_members.cpp index 011b5530..3fe17f1c 100644 --- a/examples/source/overridable_function_members.cpp +++ b/examples/source/overridable_function_members.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/pairs.cpp b/examples/source/pairs.cpp index c406cedd..215161b1 100644 --- a/examples/source/pairs.cpp +++ b/examples/source/pairs.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/pairs_with_raw_functions.cpp b/examples/source/pairs_with_raw_functions.cpp index 56146b91..cfb5af52 100644 --- a/examples/source/pairs_with_raw_functions.cpp +++ b/examples/source/pairs_with_raw_functions.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/player_script.lua b/examples/source/player_script.lua index 432983e0..c53a8d10 100644 --- a/examples/source/player_script.lua +++ b/examples/source/player_script.lua @@ -26,4 +26,4 @@ print(p1.bullets) -- would error: is a readonly variable, cannot write -- p1.bullets = 20 -p1:boost() \ No newline at end of file +p1:boost() diff --git a/examples/source/property.cpp b/examples/source/property.cpp index 1c795dc1..cd8525b6 100644 --- a/examples/source/property.cpp +++ b/examples/source/property.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/protect.cpp b/examples/source/protect.cpp index 6a3eeb7f..4d044c6f 100644 --- a/examples/source/protect.cpp +++ b/examples/source/protect.cpp @@ -1,9 +1,10 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" -int main () { +int main(int, char*[]) { + struct protect_me { int gen(int x) { return x; diff --git a/examples/source/protected_functions.cpp b/examples/source/protected_functions.cpp index 420ee9fb..7e217fc6 100644 --- a/examples/source/protected_functions.cpp +++ b/examples/source/protected_functions.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/read_only.cpp b/examples/source/read_only.cpp index ecbe11b3..27af9b2c 100644 --- a/examples/source/read_only.cpp +++ b/examples/source/read_only.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include @@ -13,7 +13,8 @@ int deny(lua_State* L) { return luaL_error(L, "HAH! Deniiiiied!"); } -int main() { +int main(int, char*[]) { + sol::state lua; lua.open_libraries(sol::lib::base); diff --git a/examples/source/require.cpp b/examples/source/require.cpp index 640212ab..0b485ad7 100644 --- a/examples/source/require.cpp +++ b/examples/source/require.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/require_override_behavior.cpp b/examples/source/require_override_behavior.cpp index 9a839043..2af8dd02 100644 --- a/examples/source/require_override_behavior.cpp +++ b/examples/source/require_override_behavior.cpp @@ -1,6 +1,6 @@ // Thanks to OrfeasZ for their answer to // an issue for this example! -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" @@ -12,7 +12,7 @@ // -- this is called a "raw C function", // and matches the type for lua_CFunction int LoadFileRequire(lua_State* L) { - // use sol2 stack API to pull + // use sol3 stack API to pull // "first argument" std::string path = sol::stack::get(L, 1); @@ -35,8 +35,8 @@ int LoadFileRequire(lua_State* L) { } int main() { - std::cout << "=== require override behavior ===" << std::endl; - + std::cout << "=== require override behavior ===" << std::endl; + sol::state lua; // need base for print, // need package for package/searchers/require @@ -64,7 +64,7 @@ int main() { c_assert(!b_result.valid()); } catch (const std::exception& ex) { - // Whenever sol2 throws an exception from panic, + // Whenever sol3 throws an exception from panic, // catch std::cout << "Something went wrong, as expected:\n" << ex.what() << std::endl; // and CRASH / exit the application diff --git a/examples/source/runtime_additions.cpp b/examples/source/runtime_additions.cpp index eccc1323..720eb588 100644 --- a/examples/source/runtime_additions.cpp +++ b/examples/source/runtime_additions.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/script_error_handling.cpp b/examples/source/script_error_handling.cpp index b7cb2cad..2c23af4f 100644 --- a/examples/source/script_error_handling.cpp +++ b/examples/source/script_error_handling.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/self_from_lua.cpp b/examples/source/self_from_lua.cpp index 294261a4..f3af69d5 100644 --- a/examples/source/self_from_lua.cpp +++ b/examples/source/self_from_lua.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/shared_ptr.cpp b/examples/source/shared_ptr.cpp index 7b8610cb..8f1cce6b 100644 --- a/examples/source/shared_ptr.cpp +++ b/examples/source/shared_ptr.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/shared_ptr_modify_in_place.cpp b/examples/source/shared_ptr_modify_in_place.cpp index 37673bfb..b116705a 100644 --- a/examples/source/shared_ptr_modify_in_place.cpp +++ b/examples/source/shared_ptr_modify_in_place.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/singleton.cpp b/examples/source/singleton.cpp index eda5753d..81ea2a3e 100644 --- a/examples/source/singleton.cpp +++ b/examples/source/singleton.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/stack_aligned_function.cpp b/examples/source/stack_aligned_function.cpp index a0bde213..b2a258ad 100644 --- a/examples/source/stack_aligned_function.cpp +++ b/examples/source/stack_aligned_function.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/stack_aligned_stack_handler_function.cpp b/examples/source/stack_aligned_stack_handler_function.cpp index b0f5ed42..13f1b94a 100644 --- a/examples/source/stack_aligned_stack_handler_function.cpp +++ b/examples/source/stack_aligned_stack_handler_function.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/static_variables.cpp b/examples/source/static_variables.cpp index 46701cf9..686eb0dd 100644 --- a/examples/source/static_variables.cpp +++ b/examples/source/static_variables.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/table_create_if_nil.cpp b/examples/source/table_create_if_nil.cpp new file mode 100644 index 00000000..04ddcd73 --- /dev/null +++ b/examples/source/table_create_if_nil.cpp @@ -0,0 +1,39 @@ +#define SOL_ALL_SAFETIES_ON 1 +#include + +#include "assert.hpp" + +void create_namespace_sf(sol::state& lua) { + // this would explode + // lua["sf"]["value"] = 256; + lua[sol::create_if_nil]["sf"]["value"] = 256; +} + +int main(int, char*[]) { + + std::cout << "=== sol::lua_value/sol::array_value ===" << std::endl; + + sol::state lua; + lua.open_libraries(sol::lib::base); + + const auto& code = R"( + print(sf) + print(sf.value) + assert(sf.value == 256) + )"; + + auto result = lua.safe_script(code, sol::script_pass_on_error); + // did not work + c_assert(!result.valid()); + + // create values + create_namespace_sf(lua); + + auto result2 = lua.safe_script(code, sol::script_pass_on_error); + // it worked properly + c_assert(result2.valid()); + + std::cout << std::endl; + + return 0; +} diff --git a/examples/source/table_proxy.cpp b/examples/source/table_proxy.cpp index 9d4222f3..899143ab 100644 --- a/examples/source/table_proxy.cpp +++ b/examples/source/table_proxy.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/tables.cpp b/examples/source/tables.cpp index 5627577a..5aab030c 100644 --- a/examples/source/tables.cpp +++ b/examples/source/tables.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/this_state.cpp b/examples/source/this_state.cpp index ed3731f9..9dd91f06 100644 --- a/examples/source/this_state.cpp +++ b/examples/source/this_state.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/tie.cpp b/examples/source/tie.cpp index 9069b5e2..c61701bc 100644 --- a/examples/source/tie.cpp +++ b/examples/source/tie.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/tutorials/erase_demo.cpp b/examples/source/tutorials/erase_demo.cpp index c303ee7b..bf22f27d 100644 --- a/examples/source/tutorials/erase_demo.cpp +++ b/examples/source/tutorials/erase_demo.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include int main() { diff --git a/examples/source/tutorials/lazy_demo.cpp b/examples/source/tutorials/lazy_demo.cpp index 3645046b..5936dcce 100644 --- a/examples/source/tutorials/lazy_demo.cpp +++ b/examples/source/tutorials/lazy_demo.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/arguments_to_scripts.cpp b/examples/source/tutorials/quick_n_dirty/arguments_to_scripts.cpp new file mode 100644 index 00000000..c96ded45 --- /dev/null +++ b/examples/source/tutorials/quick_n_dirty/arguments_to_scripts.cpp @@ -0,0 +1,28 @@ +#define SOL_ALL_SAFETIES_ON 1 +#include + +#include +#include + +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 << "failde to load string-based script in the program" << err.what() << std::endl; + } + + // prints "your arguments here" + fx("your", "arguments", "here"); + + return 0; +} diff --git a/examples/source/tutorials/quick_n_dirty/functions_all.cpp b/examples/source/tutorials/quick_n_dirty/functions_all.cpp index 5185c894..822958f4 100644 --- a/examples/source/tutorials/quick_n_dirty/functions_all.cpp +++ b/examples/source/tutorials/quick_n_dirty/functions_all.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/functions_easy.cpp b/examples/source/tutorials/quick_n_dirty/functions_easy.cpp index 366f25df..748cc8ed 100644 --- a/examples/source/tutorials/quick_n_dirty/functions_easy.cpp +++ b/examples/source/tutorials/quick_n_dirty/functions_easy.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/make_tables.cpp b/examples/source/tutorials/quick_n_dirty/make_tables.cpp index 14ee88cb..2c8b9468 100644 --- a/examples/source/tutorials/quick_n_dirty/make_tables.cpp +++ b/examples/source/tutorials/quick_n_dirty/make_tables.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/multiple_returns_from_lua.cpp b/examples/source/tutorials/quick_n_dirty/multiple_returns_from_lua.cpp index 97648926..2d0d016a 100644 --- a/examples/source/tutorials/quick_n_dirty/multiple_returns_from_lua.cpp +++ b/examples/source/tutorials/quick_n_dirty/multiple_returns_from_lua.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/multiple_returns_to_lua.cpp b/examples/source/tutorials/quick_n_dirty/multiple_returns_to_lua.cpp index 0861ee5f..0a0745f3 100644 --- a/examples/source/tutorials/quick_n_dirty/multiple_returns_to_lua.cpp +++ b/examples/source/tutorials/quick_n_dirty/multiple_returns_to_lua.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/namespacing.cpp b/examples/source/tutorials/quick_n_dirty/namespacing.cpp index 95229bd1..5a6f5538 100644 --- a/examples/source/tutorials/quick_n_dirty/namespacing.cpp +++ b/examples/source/tutorials/quick_n_dirty/namespacing.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/opening_a_state.cpp b/examples/source/tutorials/quick_n_dirty/opening_a_state.cpp index 071d8ab9..390d4324 100644 --- a/examples/source/tutorials/quick_n_dirty/opening_a_state.cpp +++ b/examples/source/tutorials/quick_n_dirty/opening_a_state.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/opening_state_on_raw_lua.cpp b/examples/source/tutorials/quick_n_dirty/opening_state_on_raw_lua.cpp index b97b5b1f..42d74daf 100644 --- a/examples/source/tutorials/quick_n_dirty/opening_state_on_raw_lua.cpp +++ b/examples/source/tutorials/quick_n_dirty/opening_state_on_raw_lua.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/running_lua_code.cpp b/examples/source/tutorials/quick_n_dirty/running_lua_code.cpp index 068fca06..2ee39cb9 100644 --- a/examples/source/tutorials/quick_n_dirty/running_lua_code.cpp +++ b/examples/source/tutorials/quick_n_dirty/running_lua_code.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/running_lua_code_low_level.cpp b/examples/source/tutorials/quick_n_dirty/running_lua_code_low_level.cpp index f341b29f..350c779a 100644 --- a/examples/source/tutorials/quick_n_dirty/running_lua_code_low_level.cpp +++ b/examples/source/tutorials/quick_n_dirty/running_lua_code_low_level.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/running_lua_code_safely.cpp b/examples/source/tutorials/quick_n_dirty/running_lua_code_safely.cpp new file mode 100644 index 00000000..3248fd2f --- /dev/null +++ b/examples/source/tutorials/quick_n_dirty/running_lua_code_safely.cpp @@ -0,0 +1,65 @@ +#define SOL_ALL_SAFETIES_ON 1 +#include + +#include +#include +#include + +int main(int, char*[]) { + std::cout << "=== running lua code (safely) ===" << std::endl; + + { + std::ofstream out("a_lua_script.lua"); + out << "print('hi from a lua script file')"; + } + + sol::state lua; + lua.open_libraries(sol::lib::base); + + // load and execute from string + auto result = lua.safe_script("a = 'test'", sol::script_pass_on_error); + if (!result.valid()) { + sol::error err = result; + std::cerr << "The code has failed to run!\n" << err.what() << "\nPanicking and exiting..." << std::endl; + return 1; + } + + // load and execute from file + auto script_from_file_result = lua.safe_script_file("a_lua_script.lua", sol::script_pass_on_error); + if (!script_from_file_result.valid()) { + sol::error err = script_from_file_result; + std::cerr << "The code from the file has failed to run!\n" << err.what() << "\nPanicking and exiting..." << std::endl; + return 1; + } + + // run a script, get the result + sol::optional maybe_value = lua.safe_script("return 54", sol::script_pass_on_error); + c_assert(maybe_value.has_value()); + c_assert(*maybe_value == 54); + + auto bad_code_result = lua.safe_script("123 herp.derp", sol::script_pass_on_error); + c_assert(!bad_code_result.valid()); + + // you can also specify a handler function, and it'll + // properly work here + auto bad_code_result2 = 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_result2.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); + + std::cout << std::endl; + + { + std::remove("a_lua_script.lua"); + } + + return 0; +} diff --git a/examples/source/tutorials/quick_n_dirty/self_call.cpp b/examples/source/tutorials/quick_n_dirty/self_call.cpp index 9fd3c349..b839e0ba 100644 --- a/examples/source/tutorials/quick_n_dirty/self_call.cpp +++ b/examples/source/tutorials/quick_n_dirty/self_call.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp b/examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp index 5ac7e3db..b207ff27 100644 --- a/examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp +++ b/examples/source/tutorials/quick_n_dirty/set_and_get_variables.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/set_and_get_variables_exists.cpp b/examples/source/tutorials/quick_n_dirty/set_and_get_variables_exists.cpp index 043c2640..3b751664 100644 --- a/examples/source/tutorials/quick_n_dirty/set_and_get_variables_exists.cpp +++ b/examples/source/tutorials/quick_n_dirty/set_and_get_variables_exists.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/tables_and_nesting.cpp b/examples/source/tutorials/quick_n_dirty/tables_and_nesting.cpp index ea04f1d6..47b66ff4 100644 --- a/examples/source/tutorials/quick_n_dirty/tables_and_nesting.cpp +++ b/examples/source/tutorials/quick_n_dirty/tables_and_nesting.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/userdata.cpp b/examples/source/tutorials/quick_n_dirty/userdata.cpp index 9794b9cb..8db4981b 100644 --- a/examples/source/tutorials/quick_n_dirty/userdata.cpp +++ b/examples/source/tutorials/quick_n_dirty/userdata.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/userdata_memory_reference.cpp b/examples/source/tutorials/quick_n_dirty/userdata_memory_reference.cpp index b2a33a83..648cec02 100644 --- a/examples/source/tutorials/quick_n_dirty/userdata_memory_reference.cpp +++ b/examples/source/tutorials/quick_n_dirty/userdata_memory_reference.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/quick_n_dirty/usertypes.cpp b/examples/source/tutorials/quick_n_dirty/usertypes.cpp index 1b81ed4b..7a820e1a 100644 --- a/examples/source/tutorials/quick_n_dirty/usertypes.cpp +++ b/examples/source/tutorials/quick_n_dirty/usertypes.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/variables_demo.cpp b/examples/source/tutorials/variables_demo.cpp index 9023fdd0..143d8449 100644 --- a/examples/source/tutorials/variables_demo.cpp +++ b/examples/source/tutorials/variables_demo.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/tutorials/write_variables_demo.cpp b/examples/source/tutorials/write_variables_demo.cpp index 307f9fc1..6f77ee86 100644 --- a/examples/source/tutorials/write_variables_demo.cpp +++ b/examples/source/tutorials/write_variables_demo.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include @@ -21,7 +21,7 @@ int main() { lua["bark"], "the key is 50 and this string is its value!"); // Run a plain ol' string of lua code - // Note you can interact with things set through Sol in C++ with lua! + // Note you can interact with things set through sol in C++ with lua! // Using a "Raw String Literal" to have multi-line goodness: // http://en.cppreference.com/w/cpp/language/string_literal lua.script(R"( diff --git a/examples/source/unique_ptr.cpp b/examples/source/unique_ptr.cpp index aa87c2eb..78249074 100644 --- a/examples/source/unique_ptr.cpp +++ b/examples/source/unique_ptr.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/usertype.cpp b/examples/source/usertype.cpp index 56674b04..75c6e89b 100644 --- a/examples/source/usertype.cpp +++ b/examples/source/usertype.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/usertype_advanced.cpp b/examples/source/usertype_advanced.cpp index 314b63c7..e9e6cf84 100644 --- a/examples/source/usertype_advanced.cpp +++ b/examples/source/usertype_advanced.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/usertype_automatic_operators.cpp b/examples/source/usertype_automatic_operators.cpp index ae330a86..6e996cb4 100644 --- a/examples/source/usertype_automatic_operators.cpp +++ b/examples/source/usertype_automatic_operators.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/usertype_basics.cpp b/examples/source/usertype_basics.cpp index 901ec793..c3254108 100644 --- a/examples/source/usertype_basics.cpp +++ b/examples/source/usertype_basics.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/usertype_bitfields.cpp b/examples/source/usertype_bitfields.cpp index 8eb3c969..7d8e0ab9 100644 --- a/examples/source/usertype_bitfields.cpp +++ b/examples/source/usertype_bitfields.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/usertype_call_from_c++.cpp b/examples/source/usertype_call_from_c++.cpp index 5639bd29..f65282c8 100644 --- a/examples/source/usertype_call_from_c++.cpp +++ b/examples/source/usertype_call_from_c++.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/usertype_dynamic_get_set.cpp b/examples/source/usertype_dynamic_get_set.cpp index c0d6d1ad..61003ea4 100644 --- a/examples/source/usertype_dynamic_get_set.cpp +++ b/examples/source/usertype_dynamic_get_set.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/usertype_initializers.cpp b/examples/source/usertype_initializers.cpp index 821e361c..1a135833 100644 --- a/examples/source/usertype_initializers.cpp +++ b/examples/source/usertype_initializers.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/usertype_special_functions.cpp b/examples/source/usertype_special_functions.cpp index 9d9b0b54..f600445c 100644 --- a/examples/source/usertype_special_functions.cpp +++ b/examples/source/usertype_special_functions.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/usertype_var.cpp b/examples/source/usertype_var.cpp index 1cebad3f..9a3c4658 100644 --- a/examples/source/usertype_var.cpp +++ b/examples/source/usertype_var.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include "assert.hpp" diff --git a/examples/source/variables.cpp b/examples/source/variables.cpp index ef173c75..2c796880 100644 --- a/examples/source/variables.cpp +++ b/examples/source/variables.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/variadic_args.cpp b/examples/source/variadic_args.cpp index 65ac16d5..2d9e5577 100644 --- a/examples/source/variadic_args.cpp +++ b/examples/source/variadic_args.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/variadic_args_shifted.cpp b/examples/source/variadic_args_shifted.cpp index 67563e08..c08d7116 100644 --- a/examples/source/variadic_args_shifted.cpp +++ b/examples/source/variadic_args_shifted.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/variadic_args_storage.cpp b/examples/source/variadic_args_storage.cpp index be958c1e..fb1a94be 100644 --- a/examples/source/variadic_args_storage.cpp +++ b/examples/source/variadic_args_storage.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/examples/source/wip/lua_inheritance.cpp b/examples/source/wip/lua_inheritance.cpp index 2ddffef6..5aa32e20 100644 --- a/examples/source/wip/lua_inheritance.cpp +++ b/examples/source/wip/lua_inheritance.cpp @@ -1,4 +1,4 @@ -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #include #include diff --git a/include/sol/compatibility.hpp b/include/sol/compatibility.hpp index 3d4e3215..7e904afd 100644 --- a/include/sol/compatibility.hpp +++ b/include/sol/compatibility.hpp @@ -26,7 +26,7 @@ // The various pieces of the compatibility layer // comes from https://github.com/keplerproject/lua-compat-5.3 -// but has been modified in many places for use with Sol and luajit, +// but has been modified in many places for use with sol and luajit, // though the core abstractions remain the same #include "feature_test.hpp" diff --git a/include/sol/config.hpp b/include/sol/config.hpp index 0986b6a1..975c50e0 100644 --- a/include/sol/config.hpp +++ b/include/sol/config.hpp @@ -64,8 +64,15 @@ #endif // vc++ || clang++/g++ -// If this is defined, turn on all the safety checks automatically +// Compatibility Define #if defined(SOL_CHECK_ARGUMENTS) && SOL_CHECK_ARGUMENTS + #if defined(SOL_ALL_SAFETIES_ON) + #define SOL_ALL_SAFETIES_ON 1 + #endif // turn all the safeties on +#endif // Compatibility define + +// If this is defined, turn on all the safety checks automatically +#if defined(SOL_ALL_SAFETIES_ON) && SOL_ALL_SAFETIES_ON // Checks low-level getter function // (and thusly, affects nearly entire framework) @@ -191,7 +198,7 @@ // Interop allows userdata from external systems // with external memory layout and metatable names // to be registered. It costs something to perform -// the interop_checker / differentiation for sol2 usertypes versus +// the interop_checker / differentiation for sol3 usertypes versus // external ones however, so this is off by default #if !defined(SOL_ENABLE_INTEROP) // off by default here @@ -230,7 +237,7 @@ // This macro ensures that we check the stack // on every push of a value. -// This is only for sol2: if you want safety in your customization +// This is only for sol3: if you want safety in your customization // points, you need to build it into each and every customization point you use, // by using luaL_checkstack or lua_checkstack // this is off by default, diff --git a/include/sol/error_handler.hpp b/include/sol/error_handler.hpp index 5de5e662..49831b0d 100644 --- a/include/sol/error_handler.hpp +++ b/include/sol/error_handler.hpp @@ -35,7 +35,7 @@ namespace sol { constexpr const char* not_enough_stack_space_integral = "not enough space left on Lua stack for an integral number"; constexpr const char* not_enough_stack_space_string = "not enough space left on Lua stack for a string"; constexpr const char* not_enough_stack_space_meta_function_name = "not enough space left on Lua stack for the name of a meta_function"; - constexpr const char* not_enough_stack_space_userdata = "not enough space left on Lua stack to create a sol2 userdata"; + constexpr const char* not_enough_stack_space_userdata = "not enough space left on Lua stack to create a sol3 userdata"; constexpr const char* not_enough_stack_space_generic = "not enough space left on Lua stack to push valuees"; constexpr const char* not_enough_stack_space_environment = "not enough space left on Lua stack to retrieve environment"; constexpr const char* protected_function_error = "caught (...) unknown error during protected_function call"; diff --git a/include/sol/optional_implementation.hpp b/include/sol/optional_implementation.hpp index e5398966..0d9abc0e 100644 --- a/include/sol/optional_implementation.hpp +++ b/include/sol/optional_implementation.hpp @@ -1143,7 +1143,7 @@ namespace sol { /// \exclude constexpr optional(const T& u) : base(in_place, u) { } -#endif // sol2 modification +#endif // sol3 modification /// Converting copy constructor. /// \synopsis template optional(const optional &rhs); diff --git a/include/sol/proxy.hpp b/include/sol/proxy.hpp index 75603c40..9993ca2c 100644 --- a/include/sol/proxy.hpp +++ b/include/sol/proxy.hpp @@ -1,4 +1,4 @@ -// sol2 +// sol3 // The MIT License (MIT) diff --git a/include/sol/stack_core.hpp b/include/sol/stack_core.hpp index 463f0cd8..f4d44091 100644 --- a/include/sol/stack_core.hpp +++ b/include/sol/stack_core.hpp @@ -689,7 +689,7 @@ namespace sol { constexpr const char* not_enough_stack_space_integral = "not enough space left on Lua stack for an integral number"; constexpr const char* not_enough_stack_space_string = "not enough space left on Lua stack for a string"; constexpr const char* not_enough_stack_space_meta_function_name = "not enough space left on Lua stack for the name of a meta_function"; - constexpr const char* not_enough_stack_space_userdata = "not enough space left on Lua stack to create a sol2 userdata"; + constexpr const char* not_enough_stack_space_userdata = "not enough space left on Lua stack to create a sol3 userdata"; constexpr const char* not_enough_stack_space_generic = "not enough space left on Lua stack to push valuees"; constexpr const char* not_enough_stack_space_environment = "not enough space left on Lua stack to retrieve environment"; diff --git a/include/sol/state_handling.hpp b/include/sol/state_handling.hpp index e28da72b..8484e6c0 100644 --- a/include/sol/state_handling.hpp +++ b/include/sol/state_handling.hpp @@ -60,7 +60,7 @@ namespace sol { std::string err(message, messagesize); lua_settop(L, 0); #if defined(SOL_PRINT_ERRORS) && SOL_PRINT_ERRORS - std::cerr << "[sol2] An error occurred and panic has been invoked: "; + std::cerr << "[sol3] An error occurred and panic has been invoked: "; std::cerr << err; std::cerr << std::endl; #endif @@ -85,7 +85,7 @@ namespace sol { msg.assign(traceback.data(), traceback.size()); } #if defined(SOL_PRINT_ERRORS) && SOL_PRINT_ERRORS - //std::cerr << "[sol2] An error occurred and was caught in traceback: "; + //std::cerr << "[sol3] An error occurred and was caught in traceback: "; //std::cerr << msg; //std::cerr << std::endl; #endif // Printing @@ -147,7 +147,7 @@ namespace sol { err.append(serr.data(), serr.size()); } #if defined(SOL_PRINT_ERRORS) && SOL_PRINT_ERRORS - std::cerr << "[sol2] An error occurred and has been passed to an error handler: "; + std::cerr << "[sol3] An error occurred and has been passed to an error handler: "; std::cerr << err; std::cerr << std::endl; #endif diff --git a/include/sol/trampoline.hpp b/include/sol/trampoline.hpp index 025450e2..d0cdad1d 100644 --- a/include/sol/trampoline.hpp +++ b/include/sol/trampoline.hpp @@ -48,7 +48,7 @@ namespace sol { // must push at least 1 object on the stack inline int default_exception_handler(lua_State* L, optional, string_view what) { #if defined(SOL_PRINT_ERRORS) && SOL_PRINT_ERRORS - std::cerr << "[sol2] An exception occurred: "; + std::cerr << "[sol3] An exception occurred: "; std::cerr.write(what.data(), what.size()); std::cerr << std::endl; #endif diff --git a/include/sol/usertype_storage.hpp b/include/sol/usertype_storage.hpp index 2af3b0be..9aa59c10 100644 --- a/include/sol/usertype_storage.hpp +++ b/include/sol/usertype_storage.hpp @@ -928,7 +928,7 @@ namespace sol { namespace u_detail { // we then let typical definitions potentially override these intrinsics // it's the user's fault if they override things or screw them up: - // these names have been reserved and documented since sol2 + // these names have been reserved and documented since sol3 // STEP 0: tell the old usertype (if it exists) // to fuck off diff --git a/list_headers.py b/list_headers.py index 9e6c3c6f..7faf73fc 100644 --- a/list_headers.py +++ b/list_headers.py @@ -3,7 +3,7 @@ import os import re -description = "Lists all primary sol2 header files" +description = "Lists all primary sol3 header files" script_path = os.path.normpath(os.path.dirname(os.path.realpath(__file__))) working_dir = os.getcwd() diff --git a/meson.build b/meson.build index 966eac56..819ab8a5 100644 --- a/meson.build +++ b/meson.build @@ -1,4 +1,4 @@ -project('sol2', 'cpp') +project('sol3', 'cpp') # Find lua dependency if get_option('lua_cpp') @@ -41,7 +41,7 @@ if get_option('single') cmd = run_command(python, 'list_headers.py') if cmd.returncode() != 0 - error('Could not list sol2 header files.') + error('Could not list sol3 header files.') endif # Create our custom target to generate the single header file. diff --git a/meson_options.txt b/meson_options.txt index dc6ddd9c..2f157f69 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -1,2 +1,2 @@ -option('single', type: 'boolean', value: false, description: 'Generate the sol2 single header and expose the corresponding build targets') +option('single', type: 'boolean', value: false, description: 'Generate the sol3 single header and expose the corresponding build targets') option('lua_cpp', type: 'boolean', value: false, description: 'Compile lua as C++ code') \ No newline at end of file diff --git a/scripts/build.linux.sh b/scripts/build.linux.sh index 808b9b7f..90d88760 100644 --- a/scripts/build.linux.sh +++ b/scripts/build.linux.sh @@ -1,6 +1,6 @@ #!/usr/bin/env zsh -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors diff --git a/scripts/preparation.linux.sh b/scripts/preparation.linux.sh index 9b94608f..4e1033a5 100644 --- a/scripts/preparation.linux.sh +++ b/scripts/preparation.linux.sh @@ -1,6 +1,6 @@ #!/usr/bin/env zsh -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors diff --git a/scripts/preparation.osx.sh b/scripts/preparation.osx.sh index 10c08a1b..51af9dda 100644 --- a/scripts/preparation.osx.sh +++ b/scripts/preparation.osx.sh @@ -1,6 +1,6 @@ #!/usr/bin/env zsh -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors diff --git a/scripts/push.linux.sh b/scripts/push.linux.sh index 08ea716f..198ec9a8 100644 --- a/scripts/push.linux.sh +++ b/scripts/push.linux.sh @@ -1,6 +1,6 @@ #!/usr/bin/env zsh -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors diff --git a/scripts/run.linux.sh b/scripts/run.linux.sh index 2ef7a743..f725a2c7 100644 --- a/scripts/run.linux.sh +++ b/scripts/run.linux.sh @@ -1,6 +1,6 @@ #!/usr/bin/env zsh -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors diff --git a/scripts/run.osx.sh b/scripts/run.osx.sh index 743fbe9c..ba40b555 100644 --- a/scripts/run.osx.sh +++ b/scripts/run.osx.sh @@ -1,6 +1,6 @@ #!/usr/bin/env zsh -# # # # sol2 +# # # # sol3 # The MIT License (MIT) # # Copyright (c) 2013-2019 Rapptz, ThePhD, and contributors diff --git a/single/CMakeLists.txt b/single/CMakeLists.txt index 6fdf9b8c..c5bd0bfb 100644 --- a/single/CMakeLists.txt +++ b/single/CMakeLists.txt @@ -28,8 +28,8 @@ cmake_minimum_required(VERSION 3.5.0) file(GLOB SOL2_SINGLE_HEADER_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/include/**/*.hpp) source_group(sol2_single FILES ${SOL2_SINGLE_HEADER_SOURCES}) -# # # sol2 Library, single -# # Add a target for sol2's library to be included by external users +# # # sol3 Library, single +# # Add a target for sol3's library to be included by external users # # single version add_library(sol2_single INTERFACE) add_library(sol2::sol2_single ALIAS sol2_single) @@ -41,7 +41,7 @@ target_include_directories(sol2_single INTERFACE $ $) -# # # sol2 single generation header +# # # sol3 single generation header # generate the single header if we can find the python3 interpreter if (SOL2_GENERATE_SINGLE) find_package(PythonInterp 3) @@ -62,7 +62,7 @@ if (SOL2_GENERATE_SINGLE) "${CMAKE_CURRENT_BINARY_DIR}/include/sol/sol.hpp" "${CMAKE_CURRENT_BINARY_DIR}/include/sol/forward.hpp" "${sol2_generated_header_sources}") - # # # sol2 generated single header library + # # # sol3 generated single header library add_library(sol2_single_generated INTERFACE) add_library(sol2::sol2_single_generated ALIAS sol2_single_generated) set_target_properties(sol2_single_generated diff --git a/single/include/sol/forward.hpp b/single/include/sol/forward.hpp index d6d7e591..6c6c2a3c 100644 --- a/single/include/sol/forward.hpp +++ b/single/include/sol/forward.hpp @@ -99,7 +99,7 @@ #endif // vc++ || clang++/g++ -#if defined(SOL_CHECK_ARGUMENTS) && SOL_CHECK_ARGUMENTS +#if defined(SOL_ALL_SAFETIES_ON) && SOL_ALL_SAFETIES_ON // Checks low-level getter function // (and thusly, affects nearly entire framework) diff --git a/single/include/sol/sol.hpp b/single/include/sol/sol.hpp index bb71e83b..6059ea6c 100644 --- a/single/include/sol/sol.hpp +++ b/single/include/sol/sol.hpp @@ -7584,7 +7584,7 @@ namespace sol { // must push at least 1 object on the stack inline int default_exception_handler(lua_State* L, optional, string_view what) { #if defined(SOL_PRINT_ERRORS) && SOL_PRINT_ERRORS - std::cerr << "[sol2] An exception occurred: "; + std::cerr << "[sol3] An exception occurred: "; std::cerr.write(what.data(), what.size()); std::cerr << std::endl; #endif @@ -8216,7 +8216,7 @@ namespace sol { constexpr const char* not_enough_stack_space_integral = "not enough space left on Lua stack for an integral number"; constexpr const char* not_enough_stack_space_string = "not enough space left on Lua stack for a string"; constexpr const char* not_enough_stack_space_meta_function_name = "not enough space left on Lua stack for the name of a meta_function"; - constexpr const char* not_enough_stack_space_userdata = "not enough space left on Lua stack to create a sol2 userdata"; + constexpr const char* not_enough_stack_space_userdata = "not enough space left on Lua stack to create a sol3 userdata"; constexpr const char* not_enough_stack_space_generic = "not enough space left on Lua stack to push valuees"; constexpr const char* not_enough_stack_space_environment = "not enough space left on Lua stack to retrieve environment"; constexpr const char* protected_function_error = "caught (...) unknown error during protected_function call"; @@ -9834,7 +9834,7 @@ namespace sol { constexpr const char* not_enough_stack_space_integral = "not enough space left on Lua stack for an integral number"; constexpr const char* not_enough_stack_space_string = "not enough space left on Lua stack for a string"; constexpr const char* not_enough_stack_space_meta_function_name = "not enough space left on Lua stack for the name of a meta_function"; - constexpr const char* not_enough_stack_space_userdata = "not enough space left on Lua stack to create a sol2 userdata"; + constexpr const char* not_enough_stack_space_userdata = "not enough space left on Lua stack to create a sol3 userdata"; constexpr const char* not_enough_stack_space_generic = "not enough space left on Lua stack to push valuees"; constexpr const char* not_enough_stack_space_environment = "not enough space left on Lua stack to retrieve environment"; @@ -11818,7 +11818,7 @@ namespace sol { namespace stack { // Because additional lambdas / functions which serve as // capture-all-and-then-invoke bloat binary sizes // by an actually detectable amount - // (one user uses sol2 pretty heavily and 22 MB of binary size + // (one user uses sol3 pretty heavily and 22 MB of binary size // was saved by reducing reliance on lambdas in templates) // This would really be solved by having break N; @@ -21634,7 +21634,7 @@ namespace sol { namespace u_detail { // we then let typical definitions potentially override these intrinsics // it's the user's fault if they override things or screw them up: - // these names have been reserved and documented since sol2 + // these names have been reserved and documented since sol3 // STEP 0: tell the old usertype (if it exists) // to fuck off @@ -23857,7 +23857,7 @@ namespace sol { std::string err(message, messagesize); lua_settop(L, 0); #if defined(SOL_PRINT_ERRORS) && SOL_PRINT_ERRORS - std::cerr << "[sol2] An error occurred and panic has been invoked: "; + std::cerr << "[sol3] An error occurred and panic has been invoked: "; std::cerr << err; std::cerr << std::endl; #endif @@ -23882,7 +23882,7 @@ namespace sol { msg.assign(traceback.data(), traceback.size()); } #if defined(SOL_PRINT_ERRORS) && SOL_PRINT_ERRORS - //std::cerr << "[sol2] An error occurred and was caught in traceback: "; + //std::cerr << "[sol3] An error occurred and was caught in traceback: "; //std::cerr << msg; //std::cerr << std::endl; #endif // Printing @@ -23944,7 +23944,7 @@ namespace sol { err.append(serr.data(), serr.size()); } #if defined(SOL_PRINT_ERRORS) && SOL_PRINT_ERRORS - std::cerr << "[sol2] An error occurred and has been passed to an error handler: "; + std::cerr << "[sol3] An error occurred and has been passed to an error handler: "; std::cerr << err; std::cerr << std::endl; #endif diff --git a/sol2.pc.in b/sol2.pc.in index 4841ed67..96ea41e1 100644 --- a/sol2.pc.in +++ b/sol2.pc.in @@ -1,6 +1,6 @@ includedir=@CMAKE_INSTALL_FULL_INCLUDEDIR@ -Name: Sol2 +Name: sol2 Description: C++ <-> Lua Wrapper Library Version: @sol2_VERSION@ Cflags: -I${includedir} diff --git a/tests/compile_tests/source/sol_defines.hpp b/tests/compile_tests/source/sol_defines.hpp index 039d95ef..2de38b97 100644 --- a/tests/compile_tests/source/sol_defines.hpp +++ b/tests/compile_tests/source/sol_defines.hpp @@ -24,9 +24,9 @@ #ifndef SOL_TESTS_SOL_DEFINES_HPP #define SOL_TESTS_SOL_DEFINES_HPP -#if !defined(SOL_CHECK_ARGUMENTS) -#define SOL_CHECK_ARGUMENTS 1 -#endif // SOL_CHECK_ARGUMENTS +#if !defined(SOL_ALL_SAFETIES_ON) +#define SOL_ALL_SAFETIES_ON 1 +#endif // SOL_ALL_SAFETIES_ON #if !defined(SOL_ENABLE_INTEROP) #define SOL_ENABLE_INTEROP 1 #endif // SOL_ENABLE_INTEROP diff --git a/tests/runtime_tests/source/coroutines.cpp b/tests/runtime_tests/source/coroutines.cpp index 697f5498..db074940 100644 --- a/tests/runtime_tests/source/coroutines.cpp +++ b/tests/runtime_tests/source/coroutines.cpp @@ -541,7 +541,7 @@ end REQUIRE(s5 == 0); } -TEST_CASE("coroutines/yielding", "test that a sol2 bound function can yield when marked yieldable") { +TEST_CASE("coroutines/yielding", "test that a sol3 bound function can yield when marked yieldable") { SECTION("regular functions") { sol::state lua; lua.open_libraries(sol::lib::base, sol::lib::coroutine); diff --git a/tests/runtime_tests/source/functions.cpp b/tests/runtime_tests/source/functions.cpp index b49b01e6..d3fa61a8 100644 --- a/tests/runtime_tests/source/functions.cpp +++ b/tests/runtime_tests/source/functions.cpp @@ -1633,7 +1633,7 @@ TEST_CASE("functions/lua style default arguments", "allow default arguments usin #if !defined(_MSC_VER) || !(defined(_WIN32) && !defined(_WIN64)) -TEST_CASE("functions/noexcept", "allow noexcept functions to be serialized properly into Lua using sol2") { +TEST_CASE("functions/noexcept", "allow noexcept functions to be serialized properly into Lua using sol3") { struct T { static int noexcept_function() noexcept { return 0x61; diff --git a/tests/runtime_tests/source/sol_test.hpp b/tests/runtime_tests/source/sol_test.hpp index 83c09ebf..d9d07dfd 100644 --- a/tests/runtime_tests/source/sol_test.hpp +++ b/tests/runtime_tests/source/sol_test.hpp @@ -24,12 +24,12 @@ #ifndef SOL_TESTS_SOL_TEST_HPP #define SOL_TESTS_SOL_TEST_HPP -#if !defined(SOL_CHECK_ARGUMENTS) - #define SOL_CHECK_ARGUMENTS 1 -#endif // SOL_CHECK_ARGUMENTS +#if !defined(SOL_ALL_SAFETIES_ON) + #define SOL_ALL_SAFETIES_ON 1 +#endif // SOL_ALL_SAFETIES_ON #if !defined(SOL_PRINT_ERRORS) #define SOL_PRINT_ERRORS 1 -#endif // SOL_CHECK_ARGUMENTS +#endif // SOL_ALL_SAFETIES_ON #if !defined(SOL_ENABLE_INTEROP) #define SOL_ENABLE_INTEROP 1 #endif // SOL_ENABLE_INTEROP diff --git a/tests/runtime_tests/source/storage.cpp b/tests/runtime_tests/source/storage.cpp index 51a610b4..44d99d8c 100644 --- a/tests/runtime_tests/source/storage.cpp +++ b/tests/runtime_tests/source/storage.cpp @@ -21,7 +21,7 @@ // IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN // CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -#define SOL_CHECK_ARGUMENTS 1 +#define SOL_ALL_SAFETIES_ON 1 #define SOL_ENABLE_INTEROP 1 #include diff --git a/tests/runtime_tests/source/usertypes.unique.cpp b/tests/runtime_tests/source/usertypes.unique.cpp index 21b0f1ad..e3028ea8 100644 --- a/tests/runtime_tests/source/usertypes.unique.cpp +++ b/tests/runtime_tests/source/usertypes.unique.cpp @@ -159,7 +159,7 @@ TEST_CASE("usertype/unique_usertype-check", "make sure unique usertypes don't ge }()); } -TEST_CASE("usertype/unique void pointers", "can compile shared_ptr types and not trip the compiler or sol2's internals") { +TEST_CASE("usertype/unique void pointers", "can compile shared_ptr types and not trip the compiler or sol3's internals") { sol::state lua; lua.set_function("f", [](std::shared_ptr d) { int* pi = static_cast(d.get());