HEAVILY improve the entire infrastructure and documentation along wit…

…h all the examples

.dockerignore

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

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

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 [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 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!
 
 - Intrepid Control Systems [intrepidcs.com](https://www.intrepidcs.com/)

Dockerfile

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

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.

cmake/Modules/Common/Core.cmake

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

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

cmake/Modules/FindLuaBuild/LuaJIT.cmake

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

cmake/Modules/FindLuaBuild/LuaVanilla.cmake

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

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

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
 )
 

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

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

docs/source/api/as_table.rst

@@ -6,7 +6,11 @@ as_table
 .. code-block:: cpp
 	
 	template <typename T>
-	as_table_t { ... };
+	as_table_t {
+		T& value() &;
+		const T& value() & const;
+		T&& value() &&;
+	};
 
 	template <typename T>
 	as_table_t<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<property>` that returns the result of ``sol::as_table``.
 
 This marker does NOT apply to :doc:`usertypes<usertype>`.
 
-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-

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``:
 

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.
 

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<set-panic>`. 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<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<set-panic>`. 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<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.

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<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<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

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<state-automatic-handlers>` 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:

docs/source/api/make_reference.rst

@@ -12,7 +12,7 @@ make_object/make_reference
 	template <typename T, typename R = reference, bool should_pop = (R is base of sol::stack_index), typename... Args>
 	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<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<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

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<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<usertype>`'s metatable defined by Sol:
+You can use this in conjunction with :doc:`sol::table<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<usertype>`'s metatable defined by sol:
 
 .. literalinclude:: ../../../examples/source/metatable_key_low_level.cpp
 	:caption: messing with metatables

docs/source/api/nested.rst

@@ -6,14 +6,18 @@ nested
 	
 	template <typename T>
 	struct nested {
-		T source;
+		T& value() &;
+		const T& value() & const;
+		T&& value() &&;
 	};
 
 
 ``sol::nested<...>`` is a template class similar to :doc:`sol::as_table<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<T>`` and ``sol::nested<T>``, and how the two are equivalent.
+The example provides a very in-depth look at both ``sol::as_table<T>`` and ``sol::nested<T>``, and how the two are equivalent.
 
-.. _example: https://github.com/ThePhD/sol2/blob/develop/examples/containers_as_table.cpp
+.. literalinclude:: ../../../examples/source/containers_as_table.cpp
+	:linenos:
+	:lines: 1-30,56-61,63-68,70-

docs/source/api/object.rst

@@ -34,15 +34,15 @@ There are 4 kinds of constructors here. One allows construction of an object fro
 	template<typename T>
 	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\<T><getter>`.
+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\<T><stack-get>`.
 
 .. code-block:: cpp
 	:caption: function: type check
 	
 	template<typename T>
 	bool is() const;
 
-Performs a type check using the :ref:`sol::stack::check<checker>` api, after checking if the reference is valid.
+Performs a type check using the :ref:`sol::stack::check<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<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
+.. _any_return example: https://github.com/ThePhD/sol2/blob/develop/examples/any_return.cpp