🎨 Refactor tutorial examples

- 🛠 Make sure the tutorials compile across platforms!
- ✍ Redo quite a bit of the documentation

.clang-format

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 # 
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

.dockerignore

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 # 
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

.gitignore

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 # 
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors
@@ -46,6 +46,10 @@ x86/
 # VSCode
 .vscode/
 
+# scratch space
+main.cpp
+scratch/
+
 # CMake
 build/
 build-sol2/
@@ -109,7 +113,6 @@ desktop.ini
 
 # Miscellaneous
 external/
-scratch/
 vendor/
 .idea/
 cmake-build-debug/

.travis.yml

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 # 
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

CMakeLists.txt

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 # 
 # Copyright (c) 2013-2021 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.
 
-# # # # sol3
+# # # # sol2
 # # # Required minimum version statement
 cmake_minimum_required(VERSION 3.15.0)
 
@@ -311,4 +311,11 @@ if (SOL2_IS_TOP_LEVEL AND (SOL2_DO_TESTS OR SOL2_DO_EXAMPLES))
 		message(STATUS "sol2 adding tests...")
 		add_subdirectory(tests "${CMAKE_BINARY_DIR}/tests")
 	endif()
+
+	# # # Scratch Space
+	# # Scratch space for diagnosing bugs and other shenanigans
+	if (SOL2_SCRATCH)
+		message(STATUS "sol2 adding scratch space...")
+		add_subdirectory(scratch)
+	endif()
 endif()

CONTRIBUTORS.md

@@ -1,6 +1,6 @@
 # 🎉 Donators! ♥ 🎉
 
-Thank you to all patrons, donators and contributors who help keep sol3 amazing.
+Thank you to all patrons, donators and contributors who help keep sol2 amazing.
 
 - Robert Salvet
 - Ορφέας Ζαφείρης - 2x Donations!
@@ -12,7 +12,7 @@ Thank you to all patrons, donators and contributors who help keep sol3 amazing.
 
 # 🎉 Patrons! ♥ 🎉
 
-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.
+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.
 
 - Joel Falcou
 - Michael Caisse
@@ -22,6 +22,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 sol3 (and the newer v3)! Please reach out to [email protected] 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 sol2 (and the newer v3)! Please reach out to [email protected] 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/)

Dockerfile

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 # 
 # Copyright (c) 2013-2017 Rapptz, ThePhD, and contributors

README.md

@@ -65,7 +65,7 @@ You can find [donation and sponorship options here](https://github.com/ThePhD/.g
 
 # Features
 
-- [Fastest in the land](http://sol2.readthedocs.io/en/latest/benchmarks.html) (see: sol3 bar in graph).
+- [Fastest in the land](http://sol2.readthedocs.io/en/latest/benchmarks.html) (see: sol2 bar in graph).
 - Supports retrieval and setting of multiple types including: 
   * `std::string`, `std::wstring`, `std::u16string` and `std::u32string` support (and for views).
   * understands and works with containers such as `std::map/unordered_map`, c-style arrays, vectors, non-standard custom containers and more.
@@ -98,7 +98,7 @@ Please make sure you use the `-std=c++2a`, `-std=c++1z`, `-std=c++17` or better
 
 If you would like support for an older compiler (at the cost of some features), use the latest tagged sol2 branch. If you would like support for an even older compiler, feel free to contact me for a Custom Solution.
 
-sol3 is checked by-hand for other platforms as well, including Android-based builds with GCC and iOS-based builds out of XCode with Apple-clang. It should work on both of these platforms, so long as you have the proper standards flags. If something doesn't work or you need special options, you may need to look into the different ways to support the project to have it done for you!
+sol2 is checked by-hand for other platforms as well, including Android-based builds with GCC and iOS-based builds out of XCode with Apple-clang. It should work on both of these platforms, so long as you have the proper standards flags. If something doesn't work or you need special options, you may need to look into the different ways to support the project to have it done for you!
 
 
 
@@ -141,7 +141,7 @@ ThePhD
 C++Now 2018 - Hudson Commons, Aspen Physics Center, Aspen, Colorado  
 [Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2018.05.10%20-%20ThePhD%20-%20Compile%20Fast%2C%20Run%20Faster%2C%20Scale%20Forever.pdf)
 
-"Scripting at the Speed of Thought: Using Lua in C++ with sol3"  
+"Scripting at the Speed of Thought: Using Lua in C++ with sol2"  
 ThePhD
 CppCon 2018 - 404 Keystone, Meydenbauer Center, Aspen, Colorado  
 [Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2018.09.28%20-%20ThePhD%20-%20Scripting%20at%20the%20Speed%20of%20Thought.pdf)

appveyor.yml

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 # 
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

cmake/Modules/Common/Core.cmake

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 #
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

cmake/Modules/FindKaguyaBuild.cmake

@@ -1,5 +1,5 @@
 
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 #
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

cmake/Modules/FindLua/set_version_vars.cmake

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 # 
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

cmake/Modules/FindLuaBridgeBuild.cmake

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 #
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

cmake/Modules/FindLuaBuild.cmake

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 #
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

cmake/Modules/FindLuaBuild/LuaJIT.cmake

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 # 
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

cmake/Modules/FindLuaBuild/LuaVanilla.cmake

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 # 
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

cmake/Modules/FindLuwraBuild.cmake

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 #
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

cmake/Modules/FindSphinx.cmake

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 #
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

cmake/Modules/FindToLuappBuild.cmake

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 #
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

cmake/sol2-config.cmake.in

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 # 
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

documentation/.clang-format

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 # 
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

documentation/CMakeLists.txt

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 # 
 # Copyright (c) 2013-2021 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.
 
-# # # # sol3, documentation generation
+# # # # sol2, documentation generation
 # # # Required minimum version statement
 cmake_minimum_required(VERSION 3.15.0)
 

documentation/Doxyfile.in

@@ -1,4 +1,4 @@
-# # # # sol3
+# # # # sol2
 # The MIT License (MIT)
 # 
 # Copyright (c) 2013-2021 Rapptz, ThePhD, and contributors

documentation/source/api/c_call.rst

@@ -17,7 +17,7 @@ The goal of ``sol::c_call<...>`` is to provide a way to wrap a function and tran
 
 	This can also be placed into the argument list for a :doc:`usertype<usertype>` as well. 
 
-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.
+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 sol2's API. The resulting ``lua_CFunction`` can also be used directly with the lua API, just like many of sol2'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`_.
 

documentation/source/api/policies.rst

@@ -2,7 +2,7 @@ policies
 ========
 *stack modification right before lua call returns*
 
-``sol::policies`` is an advanced, low-level modification feature allowing you to take advantage of sol3's abstractions before applying your own stack-based modifications at the last moment. They cover the same functionality as `luabind's "return reference to" and "dependency"`_ types. A few pre-rolled policies are defined for your use:
+``sol::policies`` is an advanced, low-level modification feature allowing you to take advantage of sol2's abstractions before applying your own stack-based modifications at the last moment. They cover the same functionality as `luabind's "return reference to" and "dependency"`_ types. A few pre-rolled policies are defined for your use:
 
 +------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | policy                             | usage                                                                                              | modification                                                                                                                                                                |

documentation/source/api/proxy.rst

@@ -171,5 +171,5 @@ on function objects and proxies
 
 .. note::
 
-	As of recent versions of sol3 (2.18.2 and above), this is no longer an issue, as even bound classes will have any detectable function call operator automatically bound to the object, to allow this to work without having to use ``.set`` or ``.set_function``. The note here is kept for posterity and information for older versions. There are only some small caveats, see: :ref:`this note here<binding-callable-objects>`.
+	As of recent versions of sol2 (2.18.2 and above), this is no longer an issue, as even bound classes will have any detectable function call operator automatically bound to the object, to allow this to work without having to use ``.set`` or ``.set_function``. The note here is kept for posterity and information for older versions. There are only some small caveats, see: :ref:`this note here<binding-callable-objects>`.
 

documentation/source/api/stack.rst

@@ -58,7 +58,7 @@ members
 	template<bool check_args = stack_detail::default_check_arguments, bool clean_stack = true, typename Fx, typename... FxArgs>
 	inline int call_lua(lua_State* L, int start, Fx&& fx, FxArgs&&... fxargs);
 
-This function is helpful for when you bind to a raw C function but need sol's abstractions to save you the agony of setting up arguments and know how `calling C functions works`_. The ``start`` parameter tells the function where to start pulling arguments from. The parameter ``fx``  is what's supposed to be called. Extra arguments are passed to the function directly. There are intermediate versions of this (``sol::stack::call_into_lua`` and similar) for more advanced users, but they are not documented as they are subject to change to improve performance or adjust the API accordingly in later iterations of sol3. Use the more advanced versions at your own peril.
+This function is helpful for when you bind to a raw C function but need sol's abstractions to save you the agony of setting up arguments and know how `calling C functions works`_. The ``start`` parameter tells the function where to start pulling arguments from. The parameter ``fx``  is what's supposed to be called. Extra arguments are passed to the function directly. There are intermediate versions of this (``sol::stack::call_into_lua`` and similar) for more advanced users, but they are not documented as they are subject to change to improve performance or adjust the API accordingly in later iterations of sol2. Use the more advanced versions at your own peril.
 
 .. code-block:: cpp
 	:caption: function: get
@@ -97,7 +97,7 @@ Checks if the object at ``index`` is of type ``T``. If it is not, it will call t
 	template <typename T>
 	auto get_usertype( lua_State* L, int index, record& tracking )
 
-Directly attempts to rertieve the type ``T`` using sol3's usertype mechanisms. Similar to a regular ``get`` for a user-defined type. Useful when you need to access sol3's usertype getter mechanism while at the same time `providing your own customization`_.
+Directly attempts to rertieve the type ``T`` using sol2's usertype mechanisms. Similar to a regular ``get`` for a user-defined type. Useful when you need to access sol2's usertype getter mechanism while at the same time `providing your own customization`_.
 
 .. code-block:: cpp
 	:caption: function: check_usertype
@@ -112,7 +112,7 @@ Directly attempts to rertieve the type ``T`` using sol3's usertype mechanisms. S
 	template <typename T, typename Handler>
 	bool check_usertype( lua_State* L, int index, Handler&& handler, record& tracking )
 
-Checks if the object at ``index`` is of type ``T`` and stored as a sol3 usertype. Useful when you need to access sol3's usertype checker mechanism while at the same time `providing your own customization`_.
+Checks if the object at ``index`` is of type ``T`` and stored as a sol2 usertype. Useful when you need to access sol2's usertype checker mechanism while at the same time `providing your own customization`_.
 
 .. code-block:: cpp
 	:caption: function: check_get
@@ -160,7 +160,7 @@ Based on how it is called, pushes a variable amount of objects onto the stack. i
 	int multi_push_reference( lua_State* L, Args&&... args )
 
 
-These functinos behave similarly to the ones above, but they check for specific criteria and instead attempt to push a reference rather than forcing a copy if appropriate. Use cautiously as sol3 uses this mainly as a return from usertype functions and variables to preserve chaining/variable semantics from that a class object. Its internals are updated to fit the needs of sol3 and while it generally does the "right thing" and has not needed to be changed for a while, sol3 reserves the right to change its internal detection mechanisms to suit its users needs at any time, generally without breaking backwards compatibility and expectations but not exactly guaranteed.
+These functinos behave similarly to the ones above, but they check for specific criteria and instead attempt to push a reference rather than forcing a copy if appropriate. Use cautiously as sol2 uses this mainly as a return from usertype functions and variables to preserve chaining/variable semantics from that a class object. Its internals are updated to fit the needs of sol2 and while it generally does the "right thing" and has not needed to be changed for a while, sol2 reserves the right to change its internal detection mechanisms to suit its users needs at any time, generally without breaking backwards compatibility and expectations but not exactly guaranteed.
 
 .. code-block:: cpp
 	:caption: function: pop
@@ -290,7 +290,7 @@ Note that you may
 	}
 
 
-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<usertype_memory>` 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 sol2 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<usertype_memory>` 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::
 
@@ -303,14 +303,14 @@ This extension point is to ``check`` a foreign userdata. It should return ``true
 
 	template <typename T>
 	std::pair<bool, T*> sol_lua_interop_get(sol::types<T> t, lua_State* L, int relindex, void* unadjusted_pointer, sol::stack::record& tracking) {			
-		// implement custom getting here for non-sol3 userdatas:
+		// implement custom getting here for non-sol2 userdatas:
 		// if it doesn't match, return "false" and regular 
 		// sol userdata getters will kick in
 		return { false, nullptr };
 	}
 
 
-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`_.
+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 sol2 implementation take care of everything. You can use it to interop with other frameworks that are not sol2 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::
 
@@ -319,7 +319,7 @@ This extension point is to ``get`` a foreign userdata. It should return both ``t
 
 .. note::
 
-	You do NOT need to use this method in particular if the :doc:`memory layout<usertype_memory>` is compatible. (For example, ``toLua`` stores userdata in a sol3-compatible way.)
+	You do NOT need to use this method in particular if the :doc:`memory layout<usertype_memory>` is compatible. (For example, ``toLua`` stores userdata in a sol2-compatible way.)
 
 
 .. _lua_CFunction: http://www.Lua.org/manual/5.3/manual.html#lua_CFunction