Merge pull request #5887 from dburnsii/upgrade_libsol2_v2.20.6

Upgrade libsol2 v2.20.6

features/testbot/nil.feature

@@ -1,18 +1,18 @@
 @routing @testbot @nil
-Feature: Testbot - Check assigning nil values
-    Scenario: Assign nil values to all way strings
+Feature: Testbot - Check assigning empty values
+    Scenario: Assign empty values to all way strings
         Given the profile file
         """
         functions = require('testbot')
 
         function way_function(profile, way, result)
-          result.name = nil
-          result.ref = nil
-          result.destinations = nil
-          result.exits = nil
-          result.pronunciation = nil
-          result.turn_lanes_forward = nil
-          result.turn_lanes_backward = nil
+          result.name = ""
+          result.ref = ""
+          result.destinations = ""
+          result.exits = ""
+          result.pronunciation = ""
+          result.turn_lanes_forward = ""
+          result.turn_lanes_backward = ""
 
           result.forward_speed = 10
           result.backward_speed = 10

include/engine/datafacade_factory.hpp

@@ -70,7 +70,7 @@ template <template <typename A> class FacadeT, typename AlgorithmT> class DataFa
                              "The exclude prefix needs to be a valid data path.");
             std::size_t index =
                 std::stoi(exclude_prefix.substr(index_begin + 1, exclude_prefix.size()));
-            BOOST_ASSERT(index >= 0 && index < facades.size());
+            BOOST_ASSERT(index < facades.size());
             facades[index] = std::make_shared<const Facade>(allocator, metric_name, index);
         }
 

include/extractor/extraction_turn.hpp

@@ -33,16 +33,16 @@ struct ExtractionTurnLeg
     {
     }
 
-    const bool is_restricted;
-    const bool is_motorway;
-    const bool is_link;
-    const int number_of_lanes;
-    const int highway_turn_classification;
-    const int access_turn_classification;
-    const int speed;
-    const RoadPriorityClass::Enum priority_class;
-    const bool is_incoming;
-    const bool is_outgoing;
+    bool is_restricted;
+    bool is_motorway;
+    bool is_link;
+    int number_of_lanes;
+    int highway_turn_classification;
+    int access_turn_classification;
+    int speed;
+    RoadPriorityClass::Enum priority_class;
+    bool is_incoming;
+    bool is_outgoing;
 };
 
 struct ExtractionTurn

include/extractor/scripting_environment_lua.hpp

@@ -12,7 +12,7 @@
 #include <mutex>
 #include <string>
 
-#include <sol2/sol.hpp>
+#include <sol.hpp>
 
 namespace osrm
 {

profiles/lib/measure.lua

@@ -72,7 +72,7 @@ function Measure.get_max_height(raw_value, element)
   if raw_value then
     if height_non_numerical_values[raw_value] then
       if element then
-        return element:get_location_tag('maxheight') or default_maxheight
+        return tonumber(element:get_location_tag('maxheight')) or default_maxheight
       else
         return default_maxheight
       end

src/extractor/scripting_environment_lua.cpp

@@ -88,7 +88,7 @@ struct to_lua_object : public boost::static_visitor<sol::object>
 {
     to_lua_object(sol::state &state) : state(state) {}
     template <typename T> auto operator()(T &v) const { return sol::make_object(state, v); }
-    auto operator()(boost::blank &) const { return sol::nil; }
+    auto operator()(boost::blank &) const { return sol::lua_nil; }
     sol::state &state;
 };
 } // namespace
@@ -236,7 +236,7 @@ void Sol2ScriptingEnvironment::InitContext(LuaScriptingContext &context)
 
     auto get_location_tag = [](auto &context, const auto &location, const char *key) {
         if (context.location_dependent_data.empty())
-            return sol::object(sol::nil);
+            return sol::object(context.state);
 
         const LocationDependentData::point_t point{location.lon(), location.lat()};
         if (!boost::geometry::equals(context.last_location_point, point))
@@ -259,7 +259,7 @@ void Sol2ScriptingEnvironment::InitContext(LuaScriptingContext &context)
         "version",
         &osmium::Way::version,
         "get_nodes",
-        [](const osmium::Way &way) { return sol::as_table(way.nodes()); },
+        [](const osmium::Way &way) { return sol::as_table(&way.nodes()); },
         "get_location_tag",
         [&context, &get_location_tag](const osmium::Way &way, const char *key) {
             // HEURISTIC: use a single node (last) of the way to localize the way
@@ -927,7 +927,7 @@ std::vector<std::string>
 Sol2ScriptingEnvironment::GetStringListFromFunction(const std::string &function_name)
 {
     auto &context = GetSol2Context();
-    BOOST_ASSERT(context.state.lua_state() != nullptr);
+    BOOST_ASSERT(context.state.lua_state());
     std::vector<std::string> strings;
     sol::function function = context.state[function_name];
     if (function.valid())
@@ -943,6 +943,10 @@ Sol2ScriptingEnvironment::GetStringListFromTable(const std::string &table_name)
     auto &context = GetSol2Context();
     BOOST_ASSERT(context.state.lua_state() != nullptr);
     std::vector<std::string> strings;
+    if (!context.profile_table[table_name])
+    {
+        return strings;
+    }
     sol::table table = context.profile_table[table_name];
     if (table.valid())
     {
@@ -961,6 +965,10 @@ Sol2ScriptingEnvironment::GetStringListsFromTable(const std::string &table_name)
 
     auto &context = GetSol2Context();
     BOOST_ASSERT(context.state.lua_state() != nullptr);
+    if (!context.profile_table[table_name])
+    {
+        return string_lists;
+    }
     sol::table table = context.profile_table[table_name];
     if (!table.valid())
     {

third_party/sol2/.clang-format

@@ -0,0 +1,110 @@
+# # # # sol2
+# The MIT License (MIT)
+# 
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+---
+BasedOnStyle: WebKit
+IndentWidth: 5
+TabWidth: 5
+ContinuationIndentWidth: 5
+UseTab: Always
+
+# Namespaces
+NamespaceIndentation: All
+CompactNamespaces: true
+FixNamespaceComments: true
+
+# Overall Alignment
+ColumnLimit: 0
+AlignAfterOpenBracket: DontAlign # uses ContinuationIndentWidth for this instead
+AccessModifierOffset: -5 # do not push public: or private: around
+#AlignConsecutiveAssignments: true # affects more than what's expected: do not use
+#AlignConsecutiveDeclarations: true # affects more than what's expected: do not use
+
+# Type Alignment
+DerivePointerAlignment: false
+PointerAlignment: Left
+AlwaysBreakTemplateDeclarations: true
+AlwaysBreakBeforeMultilineStrings: true
+
+# Comments
+AlignTrailingComments: true
+ReflowComments: true
+
+# Macros
+AlignEscapedNewlines: Left
+#IndentPPDirectives: None
+
+# Functions
+AllowShortFunctionsOnASingleLine: None
+AlwaysBreakAfterReturnType: None
+BreakConstructorInitializers: BeforeComma
+ConstructorInitializerIndentWidth: 0
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+BinPackArguments: true
+BinPackParameters: true
+
+# Classes
+BreakBeforeInheritanceComma: false
+
+# Braces
+Cpp11BracedListStyle: false
+BreakBeforeBraces: Custom
+BraceWrapping:
+  AfterEnum: false
+  AfterStruct: false
+  AfterControlStatement: false
+  AfterClass: false
+  AfterNamespace: false
+  AfterStruct: false
+  AfterUnion: false
+  BeforeElse: true
+  BeforeCatch: true
+  IndentBraces: false
+  SplitEmptyFunction: false
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: true
+
+# Control Statements
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+IndentCaseLabels: false
+
+# Spaces
+SpaceAfterCStyleCast: false
+SpacesInCStyleCastParentheses: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesInAngles: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+MaxEmptyLinesToKeep: 3
+
+# OCD
+SortUsingDeclarations: true
+SortIncludes: false
+
+---
+Language: Cpp
+Standard: Cpp11

third_party/sol2/.dockerignore

@@ -0,0 +1,27 @@
+# # # # sol2
+# The MIT License (MIT)
+# 
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+# Ignore literally everything
+**
+
+# Except the script directory
+!scripts/preparation*

third_party/sol2/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,14 @@
+Read these guidelines. They are relatively simple and will allow me to help you better:
+
+1. Produce a simple, short, compilable test case that reproduces your problem.
+2. Make a descriptive title that summarises the bug as a whole.
+3. Explain the bug in as much detail as you can in the body of the issue. 
+4. Include Compiler/IDE (Visual Studio, XCode...), Build and Deployment System, Language (C++, Objective-C++), and any special defines you have set.
+
+If you want to request a feature:
+
+1. Produce any relevant imaginary code that illustrates what you would like or desired behavior.
+2. Include a description and title of what you would like.
+3. Annotate and describe the behavior through comments, asserts or just a small write up.
+
+Thanks for helping sol grow!

third_party/sol2/.gitignore

@@ -0,0 +1,125 @@
+# # # # sol2
+# The MIT License (MIT)
+# 
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+# Python (Bytecode)
+*.pyc
+
+# ninja files
+*.ninja
+
+# Visual Studio
+*.props
+*.user
+.vs/
+Debug/
+Release/
+x64/
+x86/
+*.pyproj
+*.vcxproj
+*.vcxproj.filters
+*.tlog
+*.lastbuildstate
+*.idb
+*.sln
+*.gitattributes
+
+# VSCode
+.vscode/
+
+# CMake
+build/
+build-sol2/
+CMakeCache.txt
+CMakeFiles/
+
+# Compiler outputs
+obj/*
+bin/*
+main.exe
+main.o
+lua53.dll
+lua-5.3.4.dll
+main.ilk
+main.pdb
+
+# Dropbox interference
+.dropbox*
+
+# QtCreator
+*.creator.user.*
+*.config
+*.creator
+*.files
+*.includes
+
+# Scratchpad Files
+m.lua
+main.lua
+catch_mock.hpp
+main_aux.cpp
+main.hpp
+main2.cpp
+main.cpp
+
+# Local Lua Testbeds
+lua-5.4.0-cxx/
+lua-5.4.0/
+lua-5.4.0-work1-cxx/
+lua-5.4.0-work1/
+lua-5.3.4-cxx/
+lua-5.3.4/
+lua-5.3.2/
+lua-5.3.1/
+lua-5.3.0/
+lua-5.2.4/
+lua-5.2.2/
+lua-5.2.3/
+lua-5.1.5/
+LuaJIT-2.1.0/
+luajit-2.0.5/
+luajit-2.0.3/
+include/
+liblua.a
+lib/liblua5.2.a
+
+# Docs Artefacts
+docs/build/
+
+# Sublime Text
+*.sublime-workspace
+*.sublime-project
+
+
+# Windows Crap
+desktop.ini
+*.db
+
+# Miscellaneous
+external/
+scratch/
+.idea/
+cmake-build-debug/
+cmake-build-relwithdebinfo/
+cmake-build-release/
+/subprojects/*
+!/subprojects/*.wrap

third_party/sol2/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "Catch"]
+	path = Catch
+	url = https://github.com/philsquared/Catch.git

third_party/sol2/.style.yapf

@@ -0,0 +1,15 @@
+[style]
+based_on_style = pep8
+use_tabs = true
+indent_width = 5
+
+spaces_before_comment = 1
+spaces_around_power_operator = true
+space_between_ending_comma_and_closing_bracket = true
+
+continuation_align_style = SPACE
+split_before_first_argument = false
+split_complex_comprehension = true
+dedent_closing_brackets = false
+coalesce_brackets = true
+align_closing_bracket_with_visual_indent = false

third_party/sol2/.travis.yml

@@ -0,0 +1,198 @@
+# # # # sol2
+# The MIT License (MIT)
+# 
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+sudo: required
+language: cpp
+
+git:
+  depth: 2
+
+services:
+- docker
+
+before_install:
+- sudo apt install -y git
+
+script:
+- export SOL2_DIR=${TRAVIS_BUILD_DIR}
+- sudo docker image pull thephd/sol2:gcc-${GCC_VERSION}_llvm-${LLVM_VERSION}
+- sudo docker run --rm --interactive --tty --name "sol2.test" -v "${SOL2_DIR}:/root/sol2" --env "CI=${CI}" --env "PLATFORM=${PLATFORM}" --env "LUA_VERSION=${LUA_VERSION}" --env "GCC_VERSION=${GCC_VERSION}" --env "LLVM_VERSION=${LLVM_VERSION}" thephd/sol2:gcc-${GCC_VERSION}_llvm-${LLVM_VERSION}
+- sudo docker rmi $(sudo docker image ls -q)
+
+matrix:
+  fast_finish: true
+  allow_failures:
+    - os: osx
+
+  include:
+    # GCC 4.9.x, 5.x, 6.x, 7.x
+    - env:
+      - LUA_VERSION=5.3.4
+        GCC_VERSION=7
+        PLATFORM=i686
+        CI=true
+
+    - env:
+      - LUA_VERSION=luajit-2.0.5
+        GCC_VERSION=7
+        PLATFORM=i686
+        CI=true
+
+    - env:
+      - LUA_VERSION=luajit-2.1.0-beta3
+        GCC_VERSION=7
+        PLATFORM=i686
+        CI=true
+
+    - env:
+      - LUA_VERSION=5.3.4
+        GCC_VERSION=4.9
+        PLATFORM=x64
+        CI=true
+
+    - env:
+      - LUA_VERSION=5.3.4
+        GCC_VERSION=5
+        CI=true
+        PLATFORM=x64
+
+    - env:
+      - LUA_VERSION=5.3.4
+        GCC_VERSION=6
+        PLATFORM=x64
+        CI=true
+
+    - env:
+      - LUA_VERSION=5.3.4
+        GCC_VERSION=7
+        PLATFORM=x64
+        CI=true
+
+    # LLVM 3.6.x -> 5.0.x
+    - env:
+      - LUA_VERSION=5.3.4
+        LLVM_VERSION=3.6.2
+        PLATFORM=x64
+        CI=true
+
+    - env:
+      - LUA_VERSION=5.3.4
+        LLVM_VERSION=3.7.1
+        PLATFORM=x64
+        CI=true
+
+    - env:
+      - LUA_VERSION=5.3.4
+        LLVM_VERSION=3.8.1
+        PLATFORM=x64
+        CI=true
+
+    - env:
+      - LUA_VERSION=5.3.4
+        LLVM_VERSION=3.9.1
+        PLATFORM=x64
+        CI=true
+
+    - env:
+      - LUA_VERSION=5.3.4
+        LLVM_VERSION=4.0.1
+        PLATFORM=x64
+        CI=true
+
+    - env:
+      - LUA_VERSION=5.3.4
+        LLVM_VERSION=5.0.1
+        PLATFORM=x64
+        CI=true
+
+    # Lua Versions 5.2.4, 5.1.5, and LuaJIT (as well as x86)
+    - env:
+      - LUA_VERSION=5.2.4
+        GCC_VERSION=7
+        PLATFORM=x64
+        CI=true
+        
+    - env:
+      - LUA_VERSION=5.1.5
+        GCC_VERSION=7
+        PLATFORM=x64
+        CI=true
+        
+    - env:
+      - LUA_VERSION=luajit-2.0.4
+        GCC_VERSION=7
+        PLATFORM=x64
+        CI=true
+        
+    - env:
+      - LUA_VERSION=luajit-2.0.5
+        GCC_VERSION=7
+        PLATFORM=x64
+        CI=true
+
+    - os: osx
+      osx_image: xcode9.0
+      env:
+        - LUA_VERSION=lua-5.3.4
+          LLVM_VERSION=5.0.1
+      before_install:
+        - chmod +x ./scripts/run.osx.sh
+        - chmod +x ./scripts/preparation.osx.sh
+        - ./scripts/preparation.osx.sh
+      script:
+        - ./scripts/run.osx.sh
+
+    - os: osx
+      osx_image: xcode9.1
+      env:
+        - LUA_VERSION=lua-5.3.4
+          LLVM_VERSION=5.0.1
+      before_install:
+        - chmod +x ./scripts/run.osx.sh
+        - chmod +x ./scripts/preparation.osx.sh
+        - ./scripts/preparation.osx.sh
+      script:
+        - ./scripts/run.osx.sh
+
+    - os: osx
+      osx_image: xcode9.2
+      env:
+        - LUA_VERSION=lua-5.3.4
+          LLVM_VERSION=5.0.1
+      before_install:
+        - chmod +x ./scripts/run.osx.sh
+        - chmod +x ./scripts/preparation.osx.sh
+        - ./scripts/preparation.osx.sh
+      script:
+        - ./scripts/run.osx.sh
+
+notifications:
+  webhooks:
+    urls:
+      - https://webhooks.gitter.im/e/b864d553270a069d26c8
+    on_success: change
+    on_failure: always
+    on_start: always
+  email:
+    on_success: change
+    on_failure: change
+    on_start: never

third_party/sol2/CMakeLists.txt

@@ -0,0 +1,324 @@
+# # # # sol2
+# The MIT License (MIT)
+# 
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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
+# # # Required minimum version statement
+cmake_minimum_required(VERSION 3.5.0)
+
+# # # project declaration
+project(sol2 VERSION 2.20.0 LANGUAGES CXX C)
+
+include(GNUInstallDirs)
+
+# # # General Project Requirements
+# Set general standard requirements here
+set(CMAKE_CXX_STANDARD 14)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+# Features a C++ compiler must have to be used to compile sol2
+# This list is not *complete* as CMake does not support features for
+# all of the advanced features utilized.
+set(CXX_FEATURES
+	cxx_auto_type
+	cxx_constexpr
+	cxx_decltype
+	cxx_decltype_auto
+	cxx_default_function_template_args
+	cxx_final
+	cxx_lambdas
+	cxx_noexcept
+	cxx_nullptr
+	cxx_override
+	cxx_range_for
+	cxx_return_type_deduction
+	cxx_right_angle_brackets
+	cxx_static_assert
+	cxx_strong_enums
+	cxx_variadic_macros
+	cxx_variadic_templates)
+
+# # #
+if (PLATFORM MATCHES "i686" OR PLATFORM STREQUAL "x86")
+	set(IS_X86 TRUE)
+elseif (PLATFORM MATCHES "ARM64")
+	set(IS_ARM64 TRUE)
+	set(IS_X64 TRUE)
+elseif (PLATFORM MATCHES "ARM")
+	set(IS_ARM TRUE)
+elseif (PLATFORM MATCHES "x86_64" OR PLATFORM STREQUAL "x64")
+	set(IS_X64 TRUE)
+else()
+	set(IS_X64 TRUE)
+endif()
+
+# # # General project flags
+if (MSVC)
+	add_definitions(/DUNICODE /D_UNICODE /D_CRT_SECURE_NO_WARNINGS /D_CRT_SECURE_NO_DEPRECATE)
+	# Warning level, exceptions
+	add_compile_options(/W4 /EHsc)
+	add_compile_options("$<$<CONFIG:Debug>:/MDd>"
+		"$<$<CONFIG:Release>:/MD>"
+		"$<$<CONFIG:RelWithDebInfo>:/MD>"
+		"$<$<CONFIG:MinSizeRel>:/MD>")
+	if (NOT CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+		add_compile_options(/MP)
+	endif()
+else()
+	add_compile_options(-Wno-unknown-warning -Wno-unknown-warning-option -Wall -Wextra -Wpedantic -pedantic -pedantic-errors)
+endif()
+
+# # # General project output locations
+if (IS_X86 OR CMAKE_SIZEOF_VOID_P EQUAL 4)
+	set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/x86/lib")
+	set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/x86/bin")
+	set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/x86/bin")
+else()
+	set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/x64/lib")
+	set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/x64/bin")
+	set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/x64/bin")
+endif()
+
+# # # Modules
+# # Include modules useful to the project, whether locally made in our own cmake DIRECTORY
+# # our from the standard cmake libraries
+# Add home-rolled modules path to front of module path list
+set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake/Modules" "${CMAKE_MODULE_PATH}")
+
+# Include standard modules
+include(CMakeDependentOption)
+include(CMakePackageConfigHelpers)
+
+
+# # # Configuration
+# # Cached defines, strings, paths and options
+set(LUA_VERSION "5.3.4" CACHE STRING "The version of Lua needed. Can be 5.1, 5.2, 5.3, LuaJIT, or a more specific 3-part version number for a specifc Lua (e.g., 5.3.4 or luajit-2.0.5)")
+set(BUILD_LUA TRUE CACHE BOOL "Always build Lua, do not search for it in the system")
+set(PLATFORM "x64" CACHE STRING "Target platform to compile for when building binaries (x86, x64)")
+option(CI "Whether or not we are in continguous integration mode" OFF)
+option(TESTS "Enable build of tests" OFF)
+option(EXAMPLES "Enable build of examples" OFF)
+option(INTEROP_EXAMPLES "Enable build of interop examples" OFF)
+option(DYNAMIC_LOADING_EXAMPLES "Enable build of interop examples" OFF)
+option(SINGLE "Enable build of single header files" OFF)
+option(DOCS "Enable build of documentation" OFF)
+# Single tests and examples tests will only be turned on if both SINGLE and TESTS are defined
+CMAKE_DEPENDENT_OPTION(TESTS_SINGLE "Enable build of tests using the generated single headers" ON
+	"SINGLE;TESTS" OFF)
+CMAKE_DEPENDENT_OPTION(EXAMPLES_SINGLE "Enable build of examples using the generated single headers" OFF
+	"SINGLE;EXAMPLES" OFF)
+CMAKE_DEPENDENT_OPTION(INTEROP_EXAMPLES_SINGLE "Enable build of interop examples using the generated single headers" OFF
+	"SINGLE;INTEROP_EXAMPLES" OFF)
+CMAKE_DEPENDENT_OPTION(DYNAMIC_LOADING_EXAMPLES_SINGLE "Enable build of dynamic loading examples using the generated single headers" OFF
+	"SINGLE;DYNAMIC_LOADING_EXAMPLES" OFF)
+CMAKE_DEPENDENT_OPTION(TESTS_EXAMPLES "Enable build of examples as tests" ON
+	"EXAMPLES" OFF)
+CMAKE_DEPENDENT_OPTION(TESTS_INTEROP_EXAMPLES "Enable build of interop examples as tests" ON
+	"INTEROP_EXAMPLES" OFF)
+CMAKE_DEPENDENT_OPTION(TESTS_DYNAMIC_LOADING_EXAMPLES "Enable build of dynamic loading examples as tests" ON
+	"DYNAMIC_LOADING_EXAMPLES" OFF)
+
+
+# # # sol2 Library
+# # Add a target for sol2's library to be included by external users
+add_library(sol2 INTERFACE)
+add_library(sol2::sol2 ALIAS sol2)
+set_target_properties(sol2
+	PROPERTIES
+	EXPORT_NAME sol2::sol2)
+
+target_include_directories(sol2 INTERFACE
+	$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
+	$<INSTALL_INTERFACE:include>)
+
+# # Version configurations
+configure_package_config_file(
+	cmake/sol2-config.cmake.in
+	"${CMAKE_CURRENT_BINARY_DIR}/cmake/sol2-config.cmake"
+	INSTALL_DESTINATION lib/cmake/sol2
+	NO_CHECK_REQUIRED_COMPONENTS_MACRO)
+
+write_basic_package_version_file(
+	"${CMAKE_CURRENT_BINARY_DIR}/cmake/sol2-config-version.cmake"
+	COMPATIBILITY AnyNewerVersion)
+
+export(TARGETS sol2 FILE "${CMAKE_CURRENT_BINARY_DIR}/cmake/sol2-targets.cmake")
+
+install(TARGETS sol2
+	EXPORT sol2)
+
+install(EXPORT sol2
+	FILE sol2-targets.cmake
+	DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/sol2")
+
+install(DIRECTORY sol
+	DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")
+
+install(FILES sol.hpp
+	DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")
+
+install(FILES
+	"${CMAKE_CURRENT_BINARY_DIR}/cmake/sol2-config.cmake"
+	"${CMAKE_CURRENT_BINARY_DIR}/cmake/sol2-config-version.cmake"
+	DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/sol2")
+
+# # # Source Groups
+# # Sources everyone is going to need
+# Header files
+file(GLOB SOL2_HEADER_SOURCES sol*.hpp)
+source_group(headers FILES ${SOL2_HEADER_SOURCES})
+# single header files
+file(GLOB SOL2_SINGLE_HEADER_SOURCES single/sol/sol_forward.hpp single/sol/sol.hpp)
+source_group(headers FILES ${SOL2_SINGLE_HEADER_SOURCES})
+
+# # # Single header target
+# Find Python3 for single header / forward header generation
+find_package(PythonInterp 3)
+set(SOL2_SINGLE_HEADER_FOUND FALSE)
+set(SOL2_SINGLE_FOUND FALSE)
+set(SOL2_DOCS_FOUND FALSE)
+if (PYTHONINTERP_FOUND)
+	if (SINGLE)
+		set(SOL2_SINGLE_FOUND TRUE)
+		add_custom_command(OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/single/sol.hpp" "${CMAKE_CURRENT_BINARY_DIR}/single/sol_forward.hpp"
+			COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/single"
+			COMMAND ${PYTHON_EXECUTABLE} "${CMAKE_CURRENT_SOURCE_DIR}/single.py" --output "${CMAKE_CURRENT_BINARY_DIR}/single/sol.hpp")
+		add_custom_target(sol2_single_header ALL
+			DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/single/sol.hpp" "${CMAKE_CURRENT_BINARY_DIR}/single/sol_forward.hpp")
+		add_library(sol2_single INTERFACE)
+		add_library(sol2::sol2_single ALIAS sol2_single)
+		set_target_properties(sol2_single
+			PROPERTIES
+			EXPORT_NAME sol2::sol2_single
+			INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_BINARY_DIR}/single")
+		add_dependencies(sol2_single sol2_single_header)
+		install(FILES "${CMAKE_CURRENT_BINARY_DIR}/single/sol.hpp" "${CMAKE_CURRENT_BINARY_DIR}/single/sol_forward.hpp"
+			DESTINATION include/sol/single/sol)
+	endif()
+	if (DOCS)
+		set(SOL2_DOCS_FOUND TRUE)
+		add_custom_command(OUTPUT docs
+			COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_CURRENT_SOURCE_DIR}/docs" docs
+			COMMAND make -C docs html)
+		add_custom_target(documentation ALL DEPENDS docs)
+		install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/docs/build/html" DESTINATION "${CMAKE_INSTALL_DOCDIR}")
+	endif()
+else()
+	if (SINGLE)
+		message(STATUS "sol2 single_header cannot be generated as python 3 has not been found.")
+	endif()
+endif()
+
+# pkg-config support, except on Windows
+if(NOT WIN32 OR NOT CMAKE_HOST_SYSTEM_NAME MATCHES Windows)
+	set(PKGCONFIG_INSTALL_DIR
+		"${CMAKE_INSTALL_DATAROOTDIR}/pkgconfig"
+		CACHE PATH "Path where sol2.pc is installed")
+	
+	configure_file("${CMAKE_CURRENT_SOURCE_DIR}/sol2.pc.in" "${CMAKE_CURRENT_BINARY_DIR}/sol2.pc" @ONLY)
+	install(FILES "${CMAKE_CURRENT_BINARY_DIR}/sol2.pc" DESTINATION "${PKGCONFIG_INSTALL_DIR}")
+endif()
+
+if (CI)
+	message(STATUS "sol2 Contiguous Integration is on")
+endif()
+
+if (EXAMPLES OR TESTS_EXAMPLES OR EXAMPLES_SINGLE OR INTEROP_EXAMPLES OR TESTS_INTEROP_EXAMPLES OR INTEROP_EXAMPLES_SINGLE OR DYNAMIC_LOADING_EXAMPLES OR TESTS_DYNAMIC_LOADING_EXAMPLES OR DYNAMIC_LOADING_EXAMPLES_SINGLE)
+	set(DO_EXAMPLES TRUE)
+else()
+	set(DO_EXAMPLES FALSE)
+endif()
+
+if (TESTS OR TESTS_SINGLE)
+	set(DO_TESTS TRUE)
+else()
+	set(DO_TESTS FALSE)
+endif()
+
+if (DO_TESTS OR TESTS_EXAMPLES OR TESTS_INTEROP_EXAMPLES OR TESTS_DYNAMIC_LOADING_EXAMPLES)
+	set(ENABLE_TESTING TRUE)
+else()
+	set(ENABLE_TESTING FALSE)
+endif()
+
+# # # Tests, Examples and other CI suites that come with sol2
+if (DO_TESTS OR DO_EXAMPLES)
+	# # # Libraries
+	# Here, we pull in all the necessary libraries for building examples and tests
+	# Find threading library
+	if (NOT MSVC)
+		if (IS_X86)
+			set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -m32")
+			set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -m32")
+			set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -m32")
+			set(CMAKE_EXECUTABLE_LINKER_FLAGS "${CMAKE_EXECUTABLE_LINKER_FLAGS} -m32")
+		endif()
+		set(CMAKE_THREAD_PREFER_PTHREAD TRUE)
+		set(THREADS_PREFER_PTHREAD_FLAG TRUE)
+	endif()
+	find_package(Threads REQUIRED)
+	
+	string(TOLOWER ${LUA_VERSION} NORMALIZED_LUA_VERSION)
+	# Find way to get Lua: build if requested, or attempt to build if no matching version is found
+	if (BUILD_LUA)
+		find_package(LuaBuild REQUIRED COMPONENTS ${LUA_VERSION})
+	elseif (NOT LUA_VERSION)
+		find_package(LuaBuild REQUIRED)
+	else()
+		if (NORMALIZED_LUA_VERSION MATCHES "5.1")
+			find_package(Lua 5.1 EXACT REQUIRED)
+		elseif(NORMALIZED_LUA_VERSION MATCHES "5.2")
+			find_package(Lua 5.2 EXACT REQUIRED)
+		elseif(NORMALIZED_LUA_VERSION MATCHES "5.3")
+			find_package(Lua 5.3 EXACT REQUIRED)
+		elseif(NORMALIZED_LUA_VERSION MATCHES "luajit")
+			find_package(LuaJIT REQUIRED)
+		else()
+			find_package(LuaBuild ${LUA_VERSION} REQUIRED)
+		endif()
+	endif()
+	
+	if (NOT LUA_FOUND AND NOT LUABUILD_FOUND)
+		message(FATAL_ERROR "sol2 Lua \"${LUA_VERSION}\" not found and could not be targeted for building")
+	endif()
+	
+	# # Enable test harness for regular, example or single tests
+	if (ENABLE_TESTING)
+		# enable ctest
+		message(STATUS "sol2 testing enabled")
+		enable_testing()
+	endif()
+	
+	# # # Examples
+	# # Enable examples to be built against the library
+	if (DO_EXAMPLES)
+		# NOTE: will also add to tests if TESTS is defined
+		message(STATUS "sol2 adding examples...")
+		add_subdirectory(examples "${CMAKE_BINARY_DIR}/examples")
+	endif()
+	
+	# # # Tests
+	# # Add tests here
+	if (DO_TESTS)
+		# add subdir to get going
+		message(STATUS "sol2 adding tests...")
+		add_subdirectory(tests "${CMAKE_BINARY_DIR}/tests")
+	endif()
+endif()

third_party/sol2/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+## Contributing to Sol
+
+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
+
+If you found a bug, please make sure to make an issue in the issue tracker.
+
+The guidelines for reporting a bug are relatively simple and are as follows:
+
+1. Produce a simple, short, compilable test case that reproduces your problem.
+2. Make a descriptive title that summarises the bug as a whole.
+3. Explain the bug in as much detail as you can in the body of the issue.
+
+If you have all of those requirements set, then your issue reporting is golden.
+
+## Submitting a pull request
+
+Submitting a pull request is fairly simple, just make sure it focuses on a single aspect and doesn't 
+manage to have scope creep and it's probably good to go. It would be incredibly lovely if the style is 
+consistent to those found in the repository.
+
+To help with this, a `.clang-format` is included. Please run it on your code before you push anything.
+
+If you don't meet all of these style guidelines, don't fret. I'll probably fix it. But please
+do make an effort to actually meet them. Otherwise I'm more likely to reject the pull request.

third_party/sol2/CONTRIBUTORS.md

@@ -0,0 +1,9 @@
+# Donators! ♥
+
+Thank you to all patrons, donators and contributors who help keep sol2 amazing.
+
+Robert Salvet
+Ορφέας Ζαφείρης - 2x Donations!
+Michael Wallar
+Johannes Schultz
+Dailidzionak Ilya

third_party/sol2/Dockerfile

@@ -0,0 +1,67 @@
+# # # # sol2
+# The MIT License (MIT)
+# 
+# Copyright (c) 2013-2017 Rapptz, ThePhD, and contributors
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+# Start from the ubuntu:xenial image
+FROM ubuntu:xenial
+# owner
+LABEL author="ThePhD <phdofthehouse@gmail.com>"
+LABEL maintainer="ThePhD <phdofthehouse@gmail.com>"
+# We want our working directory to be the home directory
+WORKDIR /root
+
+# RUN is how you write to the image you've pulled down
+# RUN actions are "committed" to the image, and everything will
+# start from the base after all run commands are executed
+RUN apt-get update && apt-get install -y \
+    zsh
+
+# Scripts should be added directly to the docker image to get us started
+# We can mount the whole sol2 directory later as a volume
+ADD scripts/ /root/sol2-scripts
+
+RUN mkdir -p /root/build-sol2/Debug /root/build-sol2/Release
+RUN chmod +x /root/sol2-scripts/preparation.linux.sh
+
+VOLUME /root/sol2
+#ADD . /root/sol2
+
+# # Above this is more or less static parts: the rest is non-static
+# # This is ordered like this so making multiple of these
+# # containers is more or less identical up to this point
+# Command line arguments, with default values
+ARG CI=true
+ARG GCC_VERSION
+ARG LLVM_VERSION
+ARG PLATFORM=x64
+
+# Potential environment variables
+ENV CI=${CI} PLATFORM=${PLATFORM} GCC_VERSION=${GCC_VERSION} LLVM_VERSION=${LLVM_VERSION} SOL2_DIR=/root/sol2
+
+RUN ["/usr/bin/env", "zsh", "-e", "/root/sol2-scripts/preparation.linux.sh"]
+
+# CMD/ENTRYPOINT is different from RUN
+# these are done on a per-instantiation and essentially describe
+# the DEFAULT behavior of this container when its started, not what state it
+# gets "saved" in...
+# it only runs the last CMD/ENTRYPOINT as the default behavior:
+# multiple CMDs will not be respected
+ENTRYPOINT ["/usr/bin/env", "zsh", "-e", "/root/sol2/scripts/run.linux.sh"]

third_party/sol2/LICENSE.txt

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+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.

third_party/sol2/README.md

@@ -0,0 +1,136 @@
+## Sol 2.20
+
+[![Join the chat in Discord: https://discord.gg/buxkYNT](https://img.shields.io/badge/Discord-Chat!-brightgreen.svg)](https://discord.gg/buxkYNT)
+
+[![Linux & Max OSX Build Status](https://travis-ci.org/ThePhD/sol2.svg?branch=develop)](https://travis-ci.org/ThePhD/sol2)
+[![Windows Build status](https://ci.appveyor.com/api/projects/status/n38suofr21e9uk7h?svg=true)](https://ci.appveyor.com/project/ThePhD/sol2)
+[![Documentation Status](https://readthedocs.org/projects/sol2/badge/?version=latest)](http://sol2.readthedocs.io/en/latest/?badge=latest)
+
+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
+
+Find it [here](http://sol2.rtfd.io/). A run-through kind of tutorial is [here](http://sol2.readthedocs.io/en/latest/tutorial/all-the-things.html)! The API documentation goes over most cases (particularly, the "api/usertype" and "api/proxy" and "api/function" sections) that should still get you off your feet and going, and there's an examples directory [here](https://github.com/ThePhD/sol2/tree/develop/examples) as well.
+
+## Sneak Peek
+
+```cpp
+#include <sol/sol.hpp>
+#include <cassert>
+
+int main() {
+    sol::state lua;
+    int x = 0;
+    lua.set_function("beep", [&x]{ ++x; });
+    lua.script("beep()");
+    assert(x == 1);
+}
+```
+
+```cpp
+#include <sol/sol.hpp>
+#include <cassert>
+
+struct vars {
+    int boop = 0;
+};
+
+int main() {
+    sol::state lua;
+    lua.new_usertype<vars>("vars", "boop", &vars::boop);
+    lua.script("beep = vars.new()\n"
+               "beep.boop = 1");
+    assert(lua.get<vars>("beep").boop == 1);
+}
+```
+
+More examples are given in the examples directory [here](https://github.com/ThePhD/sol2/tree/develop/examples). 
+
+## Supporting
+
+Help the project grow on [patreon](https://www.patreon.com/thephd)!
+
+You can also [donate to support Sol](https://www.paypal.me/LMeneide), which is always appreciated! There are reward tiers for patrons on patreon, too!
+
+You can also help out the library by submitting pull requests to fix anything or add anything you think would be helpful! This includes making small, useful examples of something you haven't seen, or fixing typos and bad code in the documentation.
+
+## Presentations
+
+"A Sun For the Moon - A Zero-Overhead Lua Abstraction using C++"  
+ThePhD
+Lua Workshop 2016 - Mashape, San Francisco, CA  
+[Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2016.10.14%20-%20ThePhD%20-%20No%20Overhead%20C%20Abstraction.pdf)
+
+"Wrapping Lua C in C++ - Efficiently, Nicely, and with a Touch of Magic"  
+ThePhD
+Boston C++ Meetup November 2017 - CiC (Milk Street), Boston, MA  
+[Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2017.11.08%20-%20ThePhD%20-%20Wrapping%20Lua%20C%20in%20C%2B%2B.pdf)
+
+"Biting the CMake Bullet"  
+ThePhD
+Boston C++ Meetup February 2018 - CiC (Main Street), Cambridge, MA  
+[Deck](https://github.com/ThePhD/sol2/blob/develop/docs/presentations/2018.02.06%20-%20ThePhD%20-%20Biting%20the%20CMake%20Bullet.pdf)
+
+"Compile Fast, Run Faster, Scale Forever: A look into the sol2 Library"  
+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"  
+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)
+
+## Creating a single header
+
+You can grab a single header (and the single forward header) out of the library [here](https://github.com/ThePhD/sol2/tree/develop/single/sol). For stable version, check the releases tab on github for a provided single header file for maximum ease of use. A script called `single.py` is provided in the repository if there's some bleeding edge change that hasn't been published on the releases page. You can run this script to create a single file version of the library so you can only include that part of it. Check `single.py --help` for more info.
+
+If you use CMake, you can also configure and generate a project that will generate the sol2_single_header for you. You can also include the project using Cmake. Run CMake for more details. Thanks @Nava2, @alkino, @mrgreywater and others for help with making the CMake build a reality.
+
+## Features
+
+- [Fastest in the land](http://sol2.readthedocs.io/en/latest/benchmarks.html) (see: sol 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.
+  * user-defined types, with or **without** registering that type 
+  * `std::unique_ptr`, `std::shared_ptr`, and optional support of other pointer types like `boost::shared_ptr`.
+  * custom `optional<T>` that works with references.
+  * C++17 support for variants and similar new types.
+- Lambda, function, and member function bindings are supported.
+- Intermediate type for checking if a variable exists.
+- Simple API that completely abstracts away the C stack API, including `protected_function` with the ability to use an error-handling function.
+- `operator[]`-style manipulation of tables
+- C++ type representations in lua userdata as `usertype`s with guaranteed cleanup.
+- Customization points to allow your C++ objects to be pushed and retrieved from Lua as multiple consecutive objects, or anything else you desire!
+- Overloaded function calls: `my_function(1); my_function("Hello")` in the same lua script route to different function calls based on parameters
+- Support for tables, nested tables, table iteration with `table.for_each` / `begin()` and `end()` iterators.
+- Zero overhead for usertype function call lookup when using `SOL_USE_BOOST`, safe for critical applications
+
+## Supported Compilers
+
+Sol makes use of C++11 **and** C++14 features. GCC 5.x.x and Clang 3.6.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 5.x.x+ (MinGW 5.x.x+)
+- Clang 3.6.x+
+- Visual Studio 2015 Community (Visual C++ 14.0)+
+
+Please make sure you use the `-std=c++1y`, `-std=c++14`, `-std=c++1z`, `-std=c++17` or better standard flags 
+(some of these flags are the defaults in later versions of GCC, such as 6+ and better).
+
+Older compilers (GCC 4.9.x, Clang 3.4.x seem to be the lowest) can work with versions as late 
+as [v2.17.5](https://github.com/ThePhD/sol2/releases/tag/v2.17.5), with the flag `-std=c++14` or `-std=c++1y`.
+
+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.
+
+## Running the Tests
+
+Testing on Travis-CI and Appveyor use CMake. You can generate the tests by running CMake and configuring `TESTS`, `TESTS_SINGLE`, `TESTS_EXAMPLES`, and `EXAMPLES` to be on. Make sure `SINGLE` is also on.
+
+You will need any flavor of python3 and an available compiler. The testing suite will build its own version of Lua and LuaJIT, so you do not have to.
+
+## License
+
+Sol is distributed with an MIT License. You can see LICENSE.txt for more info.

third_party/sol2/appveyor.yml

@@ -0,0 +1,174 @@
+# # # # sol2
+# The MIT License (MIT)
+# 
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+version: 2.20.0-{build}
+
+max_jobs: 4
+
+pull_requests:
+  do_not_increment_build_number: true
+
+# Ordering is important!
+# specifying VS 2015 first makes all the 2015 jobs run first
+# we need this so the MinGW jobs can run first
+# In general, the matrix seems to order by appearance of first-order
+# dimensions (Image, Platform, Configuration) and then 
+# the order of whatever elements are in the matrix
+image:
+- Visual Studio 2015
+- Visual Studio 2017
+
+# Run x64 first, x86 second
+platform:
+- x64
+- x86
+
+environment:
+  matrix:
+    # apparently, I can't quite make LLVM work right now...
+  #- LUA_VERSION: 5.3.4
+  #  LLVM_VERSION: 4.0.0
+  - LUA_VERSION: 5.3.4
+    MINGW_VERSION: 7.2.0
+  - LUA_VERSION: 5.3.4
+    MINGW_VERSION: 6.3.0
+  - LUA_VERSION: luajit-2.0.5
+    MINGW_VERSION: 6.3.0
+  - LUA_VERSION: luajit-2.1.0-beta3
+    MINGW_VERSION: 6.3.0
+  - LUA_VERSION: 5.3.4
+  - LUA_VERSION: 5.2.4
+  - LUA_VERSION: 5.1.5
+  - LUA_VERSION: luajit-2.0.5
+  - LUA_VERSION: luajit-2.1.0-beta3
+
+matrix:
+  allow_failures:
+    # 32-bit builds are temperamental with exceptions
+    - platform: x86
+    # Visual Studio 2015 builds are allowed to fail, since I have no intention of dealing with bad old builds
+    - image: Visual Studio 2015
+    # LLVM is experimental as all get-out
+    - LLVM_VERSION: 4.0.0
+  exclude:
+    # Necessary: MinGW doesn't exist on VS 2017 images
+    # Also does not have MinGW x64 for 5.3.0
+    - image: Visual Studio 2017
+      MINGW_VERSION: 6.3.0
+    # LLVM exists in all images, and we only want the VS 2017 x64 versions
+    - image: Visual Studio 2015
+      LLVM_VERSION: 4.0.0
+    - platform: x86
+      LLVM_VERSION: 4.0.0
+    # Get rid of x86 builds
+    - platform: x86
+      LUA_VERSION: 5.2.4
+    - platform: x86
+      LUA_VERSION: 5.1.5
+    - platform: x86
+      MINGW_VERSION: 7.2.0
+    # Get rid of redundant Visual Studio 2015 builds
+    - image: Visual Studio 2015
+      LUA_VERSION: 5.1.5
+    - image: Visual Studio 2015
+      LUA_VERSION: 5.2.4
+
+init:
+# # Ninja
+  # make sure we have Ninja
+- set top_level=%cd%
+- cd ..
+- md tools
+- cd tools
+- set ninja_path=%cd%\ninja
+- set NINJA_URL="https://github.com/ninja-build/ninja/releases/download/v1.8.2/ninja-win.zip"
+- appveyor DownloadFile %NINJA_URL% -FileName ninja.zip
+- 7z x ninja.zip -o%cd%\ninja
+- cd "%top_level%"
+# # PATH
+  # manipulations to manupulations need to be done here
+- set python_path=C:\Python36
+- set mingw_path=
+- set llvm_path=
+- if "%MINGW_VERSION%"=="5.3.0" (set mingw_path=C:\mingw-w64\i686-5.3.0-posix-dwarf-rt_v4-rev0\mingw32\bin)
+- if "%MINGW_VERSION%"=="6.3.0" (if "%PLATFORM%"=="x64" (set mingw_path=C:\mingw-w64\x86_64-6.3.0-posix-seh-rt_v5-rev1\mingw64\bin) else ( set mingw_path=C:\mingw-w64\i686-6.3.0-posix-dwarf-rt_v5-rev1\mingw32\bin))
+- if "%MINGW_VERSION%"=="7.2.0" (if "%PLATFORM%"=="x64" (set mingw_path=C:\mingw-w64\x86_64-7.2.0-posix-seh-rt_v5-rev1\mingw64\bin) else ( set mingw_path=C:\mingw-w64\i686-7.2.0-posix-seh-rt_v5-rev1\mingw32\bin))
+- if "%LLVM_VERSION%"=="4.0.0" (set llvm_path=C:\Program Files\LLVM\bin)
+- if "%PLATFORM%"=="x64" (set python_path=C:\Python36-x64)
+- set PATH=%python_path%;%PATH%
+- set PATH=%mingw_path%;%PATH%
+- set PATH=%llvm_path%;%PATH%
+- set PATH=%ninja_path%;%PATH%
+- echo PATH=%PATH%
+# # Generators and CMake arguments
+  # configure the generator appropriately
+- set arch=
+- set parallelism=
+- set logger=
+- set build_type=
+- set build_compiler=
+- set lua_build_type=OFF
+- set vcvars_script="C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64
+- if "%PLATFORM%"=="x64" (set arch= Win64)
+- if "%APPVEYOR_BUILD_WORKER_IMAGE%"=="Visual Studio 2017" (set CMAKE_GENERATOR=Visual Studio 15 2017%arch%&&set parallelism=/maxcpucount&&set logger=/verbosity:quiet /logger:"C:\Program Files\AppVeyor\BuildAgent\Appveyor.MSBuildLogger.dll"&&set vcvars_script="C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat")
+- if "%APPVEYOR_BUILD_WORKER_IMAGE%"=="Visual Studio 2015" (set CMAKE_GENERATOR=Visual Studio 14 2015%arch%&&set parallelism=/maxcpucount&&set logger=/verbosity:quiet /logger:"C:\Program Files\AppVeyor\BuildAgent\Appveyor.MSBuildLogger.dll")
+- if "%MINGW_VERSION%"=="5.3.0" (set CMAKE_GENERATOR=Ninja&&set parallelism= &&set logger= &&set build_type=-DCMAKE_BUILD_TYPE=Release&&set build_compiler=-DCMAKE_CXX_COMPILER=g++.exe -DCMAKE_C_COMPILER=gcc.exe)
+- if "%MINGW_VERSION%"=="6.3.0" (set CMAKE_GENERATOR=Ninja&&set parallelism= &&set logger= &&set build_type=-DCMAKE_BUILD_TYPE=Release&&set build_compiler=-DCMAKE_CXX_COMPILER=g++.exe -DCMAKE_C_COMPILER=gcc.exe)
+- if "%MINGW_VERSION%"=="7.2.0" (set CMAKE_GENERATOR=Ninja&&set parallelism= &&set logger= &&set build_type=-DCMAKE_BUILD_TYPE=Release&&set build_compiler=-DCMAKE_CXX_COMPILER=g++.exe -DCMAKE_C_COMPILER=gcc.exe)
+- if "%LLVM_VERSION%"=="4.0.0"  (set CMAKE_GENERATOR=Ninja&&set parallelism= &&set logger= &&set build_type=-DCMAKE_BUILD_TYPE=Release&&set build_compiler=-DCMAKE_CXX_COMPILER=clang-cl.exe -DCMAKE_C_COMPILER=clang-cl.exe)
+# # Last printouts
+  # print out generator information
+- echo Appveyor Image is %APPVEYOR_BUILD_WORKER_IMAGE% (vcvars script is %vcvars_script%)
+- echo cmake generator is %CMAKE_GENERATOR% using build_type=%build_type% and build_compiler=%build_compiler% with special flags logger=%logger% parallelism=%parallelism%
+  # print out useful tool information
+- ninja --version
+- cmake --version
+- if DEFINED LLVM_VERSION (clang-cl.exe -v)
+- if DEFINED MINGW_VERSION (g++.exe --version)
+
+# We need to use CMAKE_BUILD_TYPE=Release since there are no "configuration"
+# toolsets for Ninja or Makefiles as far as cmake is concerned, so 
+# the --config / -C switches on builds do nothing...!
+before_build:
+- if DEFINED LLVM_VERSION (call %vcvars_script% && cd C:\projects\sol2)
+- md build-sol2
+- cd build-sol2
+- cmake .. -G "%CMAKE_GENERATOR%" %build_type% %build_compiler% -DLUA_VERSION="%LUA_VERSION%" -DCI=ON -DBUILD_LUA=ON -DBUILD_LUA_AS_DLL=%lua_build_type% -DTESTS=ON -DEXAMPLES=ON -DSINGLE=ON -DTESTS_EXAMPLES=ON -DEXAMPLES_SINGLE=ON -DTESTS_SINGLE=ON
+
+# We do not build the debug versions because the compiler
+# generates too much debug info for MinGW to handle
+# TODO: fix the damn compilation space and time already
+build_script:
+- if NOT "%build_type%"=="-DCMAKE_BUILD_TYPE=Release" (cmake --build . --config Debug -- %parallelism% %logger%)
+- cmake --build . --config Release -- %parallelism% %logger%
+
+test_script:
+- if NOT "%build_type%"=="-DCMAKE_BUILD_TYPE=Release" (ctest -C Debug --output-on-failure)
+- ctest -C Release --output-on-failure
+
+notifications:
+- provider: Webhook
+  url: https://webhooks.gitter.im/e/1af10e654a918bef7f1e
+  method: POST
+  on_build_success: true
+  on_build_failure: true
+  on_build_status_changed: true

third_party/sol2/cmake/Modules/Common/Core.cmake

@@ -0,0 +1,35 @@
+# # # # sol2
+# The MIT License (MIT)
+#
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+if(_common_core_included)
+	return()
+endif(_common_core_included)
+set(_common_core_included true)
+
+# # Prepend function (is there an equivalent in CMake somewhere...?)
+function(prepend var prefix)
+	set(l "")
+	foreach(f ${ARGN})
+		list(APPEND l "${prefix}${f}")
+	endforeach(f)
+	SET(${var} "${l}" PARENT_SCOPE)
+ENDFUNCTION(prepend)

third_party/sol2/cmake/Modules/FindCatch.cmake

@@ -0,0 +1,84 @@
+# # # # sol2
+# The MIT License (MIT)
+#
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+include(ExternalProject)
+include(FindPackageHandleStandardArgs)
+include(Common/Core)
+
+# # Base variables
+if (Catch_FIND_VERSION)
+	set(catch_version ${Catch_FIND_VERSION})
+else()
+	set(catch_version 2.1.2)
+endif()
+
+set(catch_lib catch_lib_${catch_version})
+
+# # Useful locations
+set(catch_build_toplevel "${CMAKE_BINARY_DIR}/vendor/catch_${catch_version}")
+set(catch_include_dirs "${catch_build_toplevel}")
+
+# # catch library sources
+set(catch_sources catch.hpp)
+prepend(catch_sources "${catch_build_toplevel}/" ${catch_sources})
+
+# # !! CMake 3.5 does not have DOWNLOAD_NO_EXTRACT e.e
+# # Now I know why people don't like CMake that much: the earlier versions were kind of garbage
+# # External project to get sources
+#ExternalProject_Add(CATCH_BUILD_SOURCE
+#	BUILD_IN_SOURCE TRUE
+#	BUILD_ALWAYS FALSE
+#	DOWNLOAD_NO_EXTRACT TRUE
+#	URL https://github.com/catchorg/Catch2/releases/download/v${catch_version}/catch.hpp
+#	TLS_VERIFY TRUE
+#	PREFIX ${catch_build_toplevel}
+#	SOURCE_DIR ${catch_build_toplevel}
+#	DOWNLOAD_DIR ${catch_build_toplevel}
+#	TMP_DIR "${catch_build_toplevel}-tmp"
+#	STAMP_DIR "${catch_build_toplevel}-stamp"
+#	INSTALL_DIR "${catch_build_toplevel}/local"
+#	CONFIGURE_COMMAND ""
+#	BUILD_COMMAND ""
+#	INSTALL_COMMAND ""
+#	TEST_COMMAND ""
+#	BUILD_BYPRODUCTS "${catch_sources}")
+
+file(MAKE_DIRECTORY "${catch_build_toplevel}")
+file(DOWNLOAD https://github.com/catchorg/Catch2/releases/download/v${catch_version}/catch.hpp ${catch_sources})
+
+add_library(${catch_lib} INTERFACE)
+# add_dependencies(${catch_lib} CATCH_BUILD_SOURCE)
+target_include_directories(${catch_lib} INTERFACE ${catch_include_dirs})
+
+if (MSVC)
+	target_compile_options(${catch_lib} INTERFACE
+		/D_SILENCE_CXX17_UNCAUGHT_EXCEPTION_DEPRECATION_WARNING)
+endif()
+
+set(CATCH_FOUND TRUE)
+set(CATCH_LIBRARIES ${catch_lib})
+set(CATCH_INCLUDE_DIRS ${catch_include_dirs})
+
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(Catch
+	FOUND_VAR CATCH_FOUND
+	REQUIRED_VARS CATCH_LIBRARIES CATCH_INCLUDE_DIRS
+	VERSION_VAR catch_version)

third_party/sol2/cmake/Modules/FindKaguyaBuild.cmake

@@ -0,0 +1,76 @@
+
+# # # # sol2
+# The MIT License (MIT)
+#
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+include(ExternalProject)
+include(FindPackageHandleStandardArgs)
+include(Common/Core)
+
+# # Base variables
+set(kaguya_version 1.3.2)
+set(kaguya_lib kaguya_lib_${kaguya_version})
+
+# # Useful locations
+set(kaguya_build_toplevel "${CMAKE_BINARY_DIR}/vendor/kaguya_${kaguya_version}")
+set(kaguya_include_dirs "${kaguya_build_toplevel}/include")
+
+# # kaguya library sources
+set(kaguya_sources kaguya/kaguya.hpp)
+prepend(kaguya_sources "${kaguya_build_toplevel}/include/" ${kaguya_sources})
+
+# # External project to get sources
+ExternalProject_Add(KAGUYA_BUILD_SOURCE
+	BUILD_IN_SOURCE TRUE
+	BUILD_ALWAYS FALSE
+	# # Use Git to get what we need
+	GIT_SHALLOW TRUE
+	GIT_SUBMODULES ""
+	GIT_REPOSITORY https://github.com/satoren/kaguya.git
+	PREFIX ${kaguya_build_toplevel}
+	SOURCE_DIR ${kaguya_build_toplevel}
+	DOWNLOAD_DIR ${kaguya_build_toplevel}
+	TMP_DIR "${kaguya_build_toplevel}-tmp"
+	STAMP_DIR "${kaguya_build_toplevel}-stamp"
+	INSTALL_DIR "${kaguya_build_toplevel}/local"
+	CONFIGURE_COMMAND ""
+	BUILD_COMMAND ""
+	INSTALL_COMMAND ""
+	TEST_COMMAND ""
+	BUILD_BYPRODUCTS "${kaguya_sources}")
+
+add_library(${kaguya_lib} INTERFACE)
+add_dependencies(${kaguya_lib} KAGUYA_BUILD_SOURCE)
+target_include_directories(${kaguya_lib} INTERFACE ${kaguya_include_dirs})
+target_link_libraries(${kaguya_lib} INTERFACE ${LUA_LIBRARIES})
+if (NOT MSVC)
+	target_compile_options(${kaguya_lib} INTERFACE
+		-Wno-noexcept-type -Wno-ignored-qualifiers -Wno-unused-parameter)
+endif()
+
+set(KAGUYABUILD_FOUND TRUE)
+set(KAGUYA_LIBRARIES ${kaguya_lib})
+set(KAGUYA_INCLUDE_DIRS ${kaguya_include_dirs})
+
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(KaguyaBuild
+	FOUND_VAR KAGUYABUILD_FOUND
+	REQUIRED_VARS KAGUYA_LIBRARIES KAGUYA_INCLUDE_DIRS
+	VERSION_VAR kaguya_version)

third_party/sol2/cmake/Modules/FindLua.cmake

@@ -0,0 +1,233 @@
+# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+# file Copyright.txt or https://cmake.org/licensing for details.
+
+#.rst:
+# FindLua
+# -------
+#
+#
+#
+# Locate Lua library. This module defines
+#
+# ::
+#
+#   LUA_FOUND          - if false, do not try to link to Lua
+#   LUA_LIBRARIES      - both lua and lualib
+#   LUA_INCLUDE_DIR    - where to find lua.h
+#   LUA_LIBRARY_DIR    - Dir(s) where Lua libraries are found
+#   LUA_VERSION_STRING - the version of Lua found
+#   LUA_VERSION_MAJOR  - the major version of Lua
+#   LUA_VERSION_MINOR  - the minor version of Lua
+#   LUA_VERSION_PATCH  - the patch version of Lua
+#
+#
+#
+# Note that the expected include convention is
+#
+# ::
+#
+#   #include "lua.h"
+#
+# and not
+#
+# ::
+#
+#   #include <lua/lua.h>
+#
+# This is because, the lua location is not standardized and may exist in
+# locations other than lua/
+
+unset(_lua_include_subdirs)
+unset(_lua_append_versions)
+unset(_lua_library_names)
+
+
+include(${CMAKE_CURRENT_LIST_DIR}/FindLua/set_version_vars.cmake)
+include(${CMAKE_CURRENT_LIST_DIR}/FindLua/version_check.cmake)
+
+# # this is a function only to have all the variables inside go away automatically
+# function(_lua_set_version_vars)
+#     set(LUA_VERSIONS5 5.3 5.2 5.1 5.0)
+
+#     if (Lua_FIND_VERSION_EXACT)
+#         if (Lua_FIND_VERSION_COUNT GREATER 1)
+#             set(_lua_append_versions ${Lua_FIND_VERSION_MAJOR}.${Lua_FIND_VERSION_MINOR})
+#         endif ()
+#     elseif (Lua_FIND_VERSION)
+#         # once there is a different major version supported this should become a loop
+#         if (NOT Lua_FIND_VERSION_MAJOR GREATER 5)
+#             if (Lua_FIND_VERSION_COUNT EQUAL 1)
+#                 set(_lua_append_versions ${LUA_VERSIONS5})
+#             else ()
+#                 foreach (subver IN LISTS LUA_VERSIONS5)
+#                     if (NOT subver VERSION_LESS ${Lua_FIND_VERSION})
+#                         list(APPEND _lua_append_versions ${subver})
+#                     endif ()
+#                 endforeach ()
+#             endif ()
+#         endif ()
+#     else ()
+#         # once there is a different major version supported this should become a loop
+#         set(_lua_append_versions ${LUA_VERSIONS5})
+#     endif ()
+
+#     list(APPEND _lua_include_subdirs "include/lua" "include")
+
+#     foreach (ver IN LISTS _lua_append_versions)
+#         string(REGEX MATCH "^([0-9]+)\\.([0-9]+)$" _ver "${ver}")
+#         list(APPEND _lua_include_subdirs
+#              include/lua${CMAKE_MATCH_1}${CMAKE_MATCH_2}
+#              include/lua${CMAKE_MATCH_1}.${CMAKE_MATCH_2}
+#              include/lua-${CMAKE_MATCH_1}.${CMAKE_MATCH_2}
+#         )
+#         list(APPEND _lua_library_names
+#              lua${CMAKE_MATCH_1}${CMAKE_MATCH_2}
+#              lua${CMAKE_MATCH_1}.${CMAKE_MATCH_2}
+#              lua.${CMAKE_MATCH_1}.${CMAKE_MATCH_2}
+#              lua-${CMAKE_MATCH_1}.${CMAKE_MATCH_2}
+#         )
+#     endforeach ()
+
+#     set(_lua_include_subdirs "${_lua_include_subdirs}" PARENT_SCOPE)
+#     set(_lua_append_versions "${_lua_append_versions}" PARENT_SCOPE)
+# endfunction(_lua_set_version_vars)
+
+# function(_lua_check_header_version _hdr_file)
+#     # At least 5.[012] have different ways to express the version
+#     # so all of them need to be tested. Lua 5.2 defines LUA_VERSION
+#     # and LUA_RELEASE as joined by the C preprocessor, so avoid those.
+#     file(STRINGS "${_hdr_file}" lua_version_strings
+#          REGEX "^#define[ \t]+LUA_(RELEASE[ \t]+\"Lua [0-9]|VERSION([ \t]+\"Lua [0-9]|_[MR])).*")
+
+#     string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_MAJOR[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" LUA_VERSION_MAJOR ";${lua_version_strings};")
+#     if (LUA_VERSION_MAJOR MATCHES "^[0-9]+$")
+#         string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_MINOR[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" LUA_VERSION_MINOR ";${lua_version_strings};")
+#         string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_RELEASE[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" LUA_VERSION_PATCH ";${lua_version_strings};")
+#         set(LUA_VERSION_STRING "${LUA_VERSION_MAJOR}.${LUA_VERSION_MINOR}.${LUA_VERSION_PATCH}")
+#     else ()
+#         string(REGEX REPLACE ".*;#define[ \t]+LUA_RELEASE[ \t]+\"Lua ([0-9.]+)\"[ \t]*;.*" "\\1" LUA_VERSION_STRING ";${lua_version_strings};")
+#         if (NOT LUA_VERSION_STRING MATCHES "^[0-9.]+$")
+#             string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION[ \t]+\"Lua ([0-9.]+)\"[ \t]*;.*" "\\1" LUA_VERSION_STRING ";${lua_version_strings};")
+#         endif ()
+#         string(REGEX REPLACE "^([0-9]+)\\.[0-9.]*$" "\\1" LUA_VERSION_MAJOR "${LUA_VERSION_STRING}")
+#         string(REGEX REPLACE "^[0-9]+\\.([0-9]+)[0-9.]*$" "\\1" LUA_VERSION_MINOR "${LUA_VERSION_STRING}")
+#         string(REGEX REPLACE "^[0-9]+\\.[0-9]+\\.([0-9]).*" "\\1" LUA_VERSION_PATCH "${LUA_VERSION_STRING}")
+#     endif ()
+#     foreach (ver IN LISTS _lua_append_versions)
+#         if (ver STREQUAL "${LUA_VERSION_MAJOR}.${LUA_VERSION_MINOR}")
+#             set(LUA_VERSION_MAJOR ${LUA_VERSION_MAJOR} PARENT_SCOPE)
+#             set(LUA_VERSION_MINOR ${LUA_VERSION_MINOR} PARENT_SCOPE)
+#             set(LUA_VERSION_PATCH ${LUA_VERSION_PATCH} PARENT_SCOPE)
+#             set(LUA_VERSION_STRING ${LUA_VERSION_STRING} PARENT_SCOPE)
+#             return()
+#         endif ()
+#     endforeach ()
+# endfunction(_lua_check_header_version)
+
+_lua_set_version_vars(lua "")
+
+find_path(LUA_INCLUDE_DIR lua.h
+  HINTS
+    ENV LUA_DIR
+  PATH_SUFFIXES ${_lua_include_subdirs} include
+  PATHS
+    ${LUA_DIR}
+    ~/Library/Frameworks
+    /Library/Frameworks
+    /sw # Fink
+    /opt/local # DarwinPorts
+    /opt/csw # Blastwave
+    /opt
+    /usr
+    /usr/local # Homebrew
+)
+
+if (LUA_INCLUDE_DIR AND EXISTS "${LUA_INCLUDE_DIR}/lua.h")
+    _lua_check_header_version("${LUA_INCLUDE_DIR}/lua.h" "LUA")
+endif ()
+
+if (NOT LUA_VERSION_STRING)
+    foreach (subdir IN LISTS _lua_include_subdirs)
+        unset(LUA_INCLUDE_PREFIX CACHE)
+        find_path(LUA_INCLUDE_PREFIX ${subdir}/lua.h
+          HINTS
+            ENV LUA_DIR
+          PATHS
+          ${LUA_DIR}
+          ~/Library/Frameworks
+          /Library/Frameworks
+          /sw # Fink
+          /opt/local # DarwinPorts
+          /opt/csw # Blastwave
+          /opt
+          /usr
+          /usr/local
+        )
+        if (LUA_INCLUDE_PREFIX)
+            _lua_check_header_version("${LUA_INCLUDE_PREFIX}/${subdir}/lua.h")
+            if (LUA_VERSION_STRING)
+                set(LUA_INCLUDE_DIR "${LUA_INCLUDE_PREFIX}/${subdir}")
+                break()
+            endif ()
+        endif ()
+    endforeach ()
+endif ()
+unset(_lua_include_subdirs)
+unset(_lua_append_versions)
+
+find_library(LUA_LIBRARY
+  NAMES ${_lua_library_names} lua
+  HINTS
+    ENV LUA_DIR
+  PATH_SUFFIXES lib bin
+  PATHS
+    ${LUA_DIR}
+    ~/Library/Frameworks
+    /Library/Frameworks
+    /sw
+    /opt/local
+    /opt/csw
+    /opt
+    /usr
+    /usr/local
+
+    # From the include_dir
+    ${LUA_INCLUDE_DIR}/../lib
+)
+unset(_lua_library_names)
+
+if (LUA_LIBRARY)
+    # include the math library for Unix
+    if (UNIX AND NOT APPLE AND NOT BEOS)
+        find_library(LUA_MATH_LIBRARY m)
+        set(LUA_LIBRARIES "${LUA_LIBRARY};${LUA_MATH_LIBRARY}")
+
+        # include dl library for statically-linked Lua library
+        get_filename_component(LUA_LIB_EXT ${LUA_LIBRARY} EXT)
+        if (LUA_LIB_EXT STREQUAL CMAKE_STATIC_LIBRARY_SUFFIX)
+          list(APPEND LUA_LIBRARIES ${CMAKE_DL_LIBS})
+        endif ()
+
+    # For Windows and Mac, don't need to explicitly include the math library
+    else ()
+        set(LUA_LIBRARIES "${LUA_LIBRARY}")
+    endif ()
+
+    set(LUA_LIBRARY_DIR )
+    foreach (lib ${LUA_LIBRARIES})
+        get_filename_component(lib_dir ${lib} DIRECTORY CACHE)
+        list(APPEND LUA_LIBRARY_DIR ${lib_dir})
+    endforeach ()
+    list(REMOVE_DUPLICATES LUA_LIBRARY_DIR)
+endif ()
+
+include(FindPackageHandleStandardArgs)
+
+# handle the QUIETLY and REQUIRED arguments and set LUA_FOUND to TRUE if
+# all listed variables are TRUE
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(Lua
+                                  FOUND_VAR Lua_FOUND
+                                  REQUIRED_VARS LUA_LIBRARIES LUA_LIBRARY_DIR LUA_INCLUDE_DIR
+                                  VERSION_VAR LUA_VERSION_STRING)
+
+mark_as_advanced(LUA_INCLUDE_DIR LUA_LIBRARY LUA_LIBRARY_DIR LUA_MATH_LIBRARY)

third_party/sol2/cmake/Modules/FindLua/set_version_vars.cmake

@@ -0,0 +1,77 @@
+# # # # sol2
+# The MIT License (MIT)
+# 
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+# Uses the Lua version and calculates the names of the include directories and library
+# name accordingly.
+#
+# ::
+#   _prefix     - Prefix added to all variables exposed, e.g. "lua" or "luajit"
+#   _lua_suffix - Name suffix, typically only used for specifiying luajit, which is "jit"
+
+function(_lua_set_version_vars _prefix _lua_suffix)
+    set(LUA_VERSIONS5 5.3 5.2 5.1 5.0)
+
+    if (${_prefix}_FIND_VERSION_EXACT)
+        if (${_prefix}_FIND_VERSION_COUNT GREATER 1)
+            set(_${_prefix}_append_versions ${${_prefix}_FIND_VERSION_MAJOR}.${${_prefix}_FIND_VERSION_MINOR})
+        endif ()
+    elseif (${_prefix}_FIND_VERSION)
+        # once there is a different major version supported this should become a loop
+        if (NOT ${_prefix}_FIND_VERSION_MAJOR GREATER 5)
+            if (${_prefix}_FIND_VERSION_COUNT EQUAL 1)
+                set(_${_prefix}_append_versions ${${_prefix}_VERSIONS5})
+            else ()
+                foreach (subver IN LISTS ${_prefix}_VERSIONS5)
+                    if (NOT subver VERSION_LESS ${${_prefix}_FIND_VERSION})
+                        list(APPEND _${_prefix}_append_versions ${subver})
+                    endif ()
+                endforeach ()
+            endif ()
+        endif ()
+    else ()
+        # once there is a different major version supported this should become a loop
+        set(_${_prefix}_append_versions ${LUA_VERSIONS5})
+    endif ()
+
+    list(APPEND _${_prefix}_include_subdirs "include/lua" "include")
+
+    foreach (ver IN LISTS _${_prefix}_append_versions)
+        string(REGEX MATCH "^([0-9]+)\\.([0-9]+)$" _ver "${ver}")
+        list(APPEND _${_prefix}_include_subdirs
+             include/lua${_lua_suffix}${CMAKE_MATCH_1}${CMAKE_MATCH_2}
+             include/lua${_lua_suffix}${CMAKE_MATCH_1}.${CMAKE_MATCH_2}
+             include/lua${_lua_suffix}-${CMAKE_MATCH_1}.${CMAKE_MATCH_2}
+        )
+
+        # LuaJIT hides itself as Lua lib (maintaining ABI compat)
+        list(APPEND _${_prefix}_library_names
+             lua${CMAKE_MATCH_1}${CMAKE_MATCH_2}
+             lua${CMAKE_MATCH_1}.${CMAKE_MATCH_2}
+             lua.${CMAKE_MATCH_1}.${CMAKE_MATCH_2}
+             lua-${CMAKE_MATCH_1}.${CMAKE_MATCH_2}
+        )
+    endforeach ()
+
+    set(_${_prefix}_include_subdirs "${_${_prefix}_include_subdirs}" PARENT_SCOPE)
+    set(_${_prefix}_append_versions "${_${_prefix}_append_versions}" PARENT_SCOPE)
+    set(_${_prefix}_library_names "${_${_prefix}_library_names}" PARENT_SCOPE)
+endfunction(_lua_set_version_vars)

third_party/sol2/cmake/Modules/FindLua/version_check.cmake

@@ -0,0 +1,28 @@
+# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+# file Copyright.txt or https://cmake.org/licensing for details.
+
+# Provides a common-mechanic for extracting Lua versions from Lua/LuaJIT headers
+macro(_lua_check_header_version _header_file _prefix)
+    # At least 5.[012] have different ways to express the version
+    # so all of them need to be tested. Lua 5.2 defines LUA_VERSION
+    # and LUA_RELEASE as joined by the C preprocessor, so avoid those.
+    file(STRINGS "${_header_file}" lua_version_strings
+         REGEX "^#define[ \t]+LUA_(RELEASE[ \t]+\"Lua [0-9]|VERSION([ \t]+\"Lua [0-9]|_[MR])).*")
+
+    string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_MAJOR[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" ${_prefix}_VERSION_MAJOR ";${lua_version_strings};")
+    if (${_prefix}_VERSION_MAJOR MATCHES "^[0-9]+$")
+        string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_MINOR[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" "${_prefix}_VERSION_MINOR" ";${lua_version_strings};")
+        string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_RELEASE[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" "${_prefix}_VERSION_PATCH" ";${lua_version_strings};")
+        set(${_prefix}_VERSION_STRING "${${_prefix}_VERSION_MAJOR}.${${_prefix}_VERSION_MINOR}.${${_prefix}_VERSION_PATCH}")
+    else ()
+        string(REGEX REPLACE ".*;#define[ \t]+LUA_RELEASE[ \t]+\"Lua ([0-9.]+)\"[ \t]*;.*" "\\1" ${_prefix}_VERSION_STRING ";${lua_version_strings};")
+        if (NOT LUA_VERSION_STRING MATCHES "^[0-9.]+$")
+            string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION[ \t]+\"Lua ([0-9.]+)\"[ \t]*;.*" "\\1" ${_prefix}_VERSION_STRING ";${lua_version_strings};")
+        endif ()
+        string(REGEX REPLACE "^([0-9]+)\\.[0-9.]*$" "\\1" ${_prefix}_VERSION_MAJOR "${${_prefix}_VERSION_STRING}")
+        string(REGEX REPLACE "^[0-9]+\\.([0-9]+)[0-9.]*$" "\\1" ${_prefix}_VERSION_MINOR "${${_prefix}_VERSION_STRING}")
+        string(REGEX REPLACE "^[0-9]+\\.[0-9]+\\.([0-9]).*" "\\1" ${_prefix}_VERSION_PATCH "${${_prefix}_VERSION_STRING}")
+    endif ()
+
+    unset(lua_version_strings)
+endmacro(_lua_check_header_version)

third_party/sol2/cmake/Modules/FindLuaBridgeBuild.cmake

@@ -0,0 +1,76 @@
+# # # # sol2
+# The MIT License (MIT)
+#
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+include(ExternalProject)
+include(FindPackageHandleStandardArgs)
+include(Common/Core)
+
+# # Base variables
+set(luabridge_version 1.0.2)
+set(luabridge_lib luabridge_lib_${luabridge_version})
+
+# # Useful locations
+set(luabridge_build_toplevel "${CMAKE_BINARY_DIR}/vendor/luabridge_${luabridge_version}")
+set(luabridge_include_dirs "${luabridge_build_toplevel}/Source")
+
+# # luabridge library sources
+set(luabridge_sources LuaBridge/LuaBridge.h)
+prepend(luabridge_sources "${luabridge_build_toplevel}/Source/" ${luabridge_sources})
+
+# # External project to get sources
+ExternalProject_Add(LUABRIDGE_BUILD_SOURCE
+	BUILD_IN_SOURCE TRUE
+	BUILD_ALWAYS FALSE
+	# # Use Git to get what we need
+	GIT_SHALLOW TRUE
+	GIT_SUBMODULES ""
+	GIT_REPOSITORY https://github.com/ThePhD/LuaBridge.git
+	PREFIX ${luabridge_build_toplevel}
+	SOURCE_DIR ${luabridge_build_toplevel}
+	DOWNLOAD_DIR ${luabridge_build_toplevel}
+	TMP_DIR "${luabridge_build_toplevel}-tmp"
+	STAMP_DIR "${luabridge_build_toplevel}-stamp"
+	INSTALL_DIR "${luabridge_build_toplevel}/local"
+	CONFIGURE_COMMAND ""
+	BUILD_COMMAND ""
+	INSTALL_COMMAND ""
+	TEST_COMMAND ""
+	BUILD_BYPRODUCTS "${luabridge_sources}")
+
+add_library(${luabridge_lib} INTERFACE)
+add_dependencies(${luabridge_lib} LUABRIDGE_BUILD_SOURCE)
+target_include_directories(${luabridge_lib} INTERFACE ${luabridge_include_dirs})
+target_link_libraries(${luabridge_lib} INTERFACE ${LUA_LIBRARIES})
+if (NOT MSVC)
+	target_compile_options(${luabridge_lib} INTERFACE
+		-Wno-noexcept-type -Wno-ignored-qualifiers -Wno-unused-parameter)
+endif()
+set(LUABRIDGEBUILD_FOUND TRUE)
+set(LUABRIDGE_LIBRARIES ${luabridge_lib})
+set(LUABRIDGE_INCLUDE_DIRS ${luabridge_include_dirs})
+
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(LuabridgeBuild
+	FOUND_VAR LUABRIDGEBUILD_FOUND
+	REQUIRED_VARS LUABRIDGE_LIBRARIES LUABRIDGE_INCLUDE_DIRS
+	VERSION_VAR luabridge_version)
+
+

third_party/sol2/cmake/Modules/FindLuaBuild.cmake

@@ -0,0 +1,120 @@
+# # # # sol2
+# The MIT License (MIT)
+#
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+# # Standard CMake Libraries
+include(FindPackageHandleStandardArgs)
+
+# Contain literally everything inside of this function to prevent spillage
+function(find_lua_build LUA_VERSION)
+	# # # Variables
+	# # Core Paths
+	string(TOLOWER ${LUA_VERSION} LUA_BUILD_NORMALIZED_LUA_VERSION)
+	if (LUA_BUILD_NORMALIZED_LUA_VERSION MATCHES "luajit")
+		set(LUA_BUILD_LIBNAME ${LUA_VERSION})
+	elseif (BUILD_LUAJIT)
+		set(LUA_BUILD_LIBNAME luajit-${LUA_VERSION})
+	elseif (LUA_BUILD_NORMALIZED_LUA_VERSION MATCHES "lua")
+		set(LUA_BUILD_LIBNAME ${LUA_VERSION})
+	elseif (BUILD_LUA)
+		set(LUA_BUILD_LIBNAME lua-${LUA_VERSION})
+	else()
+		set(LUA_BUILD_LIBNAME lua-${LUA_VERSION})
+	endif()
+	set(LUA_BUILD_TOPLEVEL "${CMAKE_BINARY_DIR}/vendor/${LUA_BUILD_LIBNAME}")
+	set(LUA_BUILD_INSTALL_DIR "${LUA_BUILD_TOPLEVEL}")
+	# # Misc needed variables
+	set(LUA_BUILD_LIBRARY_DESCRIPTION "The base name of the library to build either the static or the dynamic library")
+
+	# Object file suffixes
+	if (MSVC)
+		set(LUA_BUILD_BUILD_DLL_DEFAULT ON)
+		set(LUA_BUILD_OBJECT_FILE_SUFFIX .obj)
+	else()
+		set(LUA_BUILD_BUILD_DLL_DEFAULT OFF)
+		set(LUA_BUILD_OBJECT_FILE_SUFFIX .o)
+	endif()
+
+	# # # Options
+	option(BUILD_LUA_AS_DLL ${LUA_BUILD_BUILD_DLL_DEFAULT} "Build Lua or LuaJIT as a Shared/Dynamic Link Library")
+
+	STRING(TOLOWER ${LUA_BUILD_LIBNAME} LUA_BUILD_NORMALIZED_LIBNAME)
+	if (NOT LUA_LIBRARY_NAME)
+		if (LUA_BUILD_NORMALIZED_LIBNAME MATCHES "luajit")
+			set(LUA_LIBRARY luajit)
+		else()
+			set(LUA_LIBRARY ${LUA_BUILD_LIBNAME})
+		endif()
+	else()
+		set(LUA_LIBRARY_NAME ${LUA_LIBRARY_NAME}
+			CACHE STRING
+			${LUA_BUILD_LIBRARY_DESCRIPTION})
+	endif()
+	# # Dependent Variables
+	# If we're building a DLL, then set the library type to SHARED
+	if (BUILD_LUA_AS_DLL)
+		set(LUA_BUILD_LIBRARY_TYPE SHARED)
+	else()
+		set(LUA_BUILD_LIBRARY_TYPE STATIC)
+	endif()
+
+
+	# # # Build Lua
+	# # Select either LuaJIT or Vanilla Lua here, based on what we discover
+	if (BUILD_LUAJIT OR LUA_BUILD_NORMALIZED_LUA_VERSION MATCHES "luajit")
+		include(${CMAKE_CURRENT_LIST_DIR}/FindLuaBuild/LuaJIT.cmake)
+		set(LUA_VERSION_STRING ${LUA_JIT_VERSION})
+	else()
+		include(${CMAKE_CURRENT_LIST_DIR}/FindLuaBuild/LuaVanilla.cmake)
+		set(LUA_VERSION_STRING ${LUA_VANILLA_VERSION})
+	endif()
+
+	# # Export variables to the parent scope
+	set(LUA_LIBRARIES ${LUA_LIBRARIES} PARENT_SCOPE)
+	set(LUA_INTERPRETER ${LUA_INTERPRETER} PARENT_SCOPE)
+	set(LUA_INCLUDE_DIRS ${LUA_INCLUDE_DIRS} PARENT_SCOPE)
+	set(LUA_VERSION_STRING ${LUA_VERSION_STRING} PARENT_SCOPE)
+	set(LUABUILD_FOUND TRUE PARENT_SCOPE)
+endfunction(find_lua_build)
+
+# Call and then immediately undefine to avoid polluting the global scope
+if (LuaBuild_FIND_COMPONENTS)
+	list(GET LuaBuild_FIND_COMPONENTS 0 LUA_VERSION)
+endif()
+if (LuaBuild_FIND_VERSION)
+	if (LUA_VERSION)
+		set(LUA_VERSION "${LUA_VERSION}-${LuaBuild_FIND_VERSION}")
+	else()
+		set(LUA_VERSION "${LuaBuild_VERSION}")
+	endif()
+endif()
+if (NOT LUA_VERSION)
+	set(LUA_VERSION 5.3.4)
+endif()
+find_lua_build(${LUA_VERSION})
+unset(find_lua_build)
+
+# handle the QUIETLY and REQUIRED arguments and set LUABUILD_FOUND to TRUE if
+# all listed variables are TRUE
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(LuaBuild
+	FOUND_VAR LUABUILD_FOUND
+	REQUIRED_VARS LUA_LIBRARIES LUA_INTERPRETER LUA_INCLUDE_DIRS
+	VERSION_VAR LUA_VERSION_STRING)

third_party/sol2/cmake/Modules/FindLuaBuild/LuaJIT.cmake

@@ -0,0 +1,380 @@
+# # # # sol2
+# The MIT License (MIT)
+# 
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+# protect from multiple inclusion
+if(lua_jit_build_included)
+	return()
+endif(lua_jit_build_included)
+set(lua_jit_build_included true)
+
+# import necessary standard modules
+include(ExternalProject)
+
+# Latest iterations for specific sub-versions of LuaJIT
+set(LUA_JIT_2.0_LATEST_VERSION 2.0.5)
+set(LUA_JIT_${LUA_JIT_2.0_LATEST_VERSION}_COMMIT c88602f080dcafea6ba222a2f7cc1ea0e41ef3cc)
+set(LUA_JIT_2.1_LATEST_VERSION 2.1.0-beta3)
+set(LUA_JIT_${LUA_JIT_2.1_LATEST_VERSION}_COMMIT 80aaaeee99d7f7b06c9e75ed3a457c49d86fc4db)
+
+# MD5 hashes taken off of LuaJIT's website
+# must be updated whenever a new version appears
+set(LUA_JIT_MD5_2.1.0-beta3.tar.gz eae40bc29d06ee5e3078f9444fcea39b)
+set(LUA_JIT_MD5_2.1.0-beta3.zip 58d0480e1af0811e7ecee45498d62e2d)
+set(LUA_JIT_MD5_2.1.0-beta2.tar.gz fa14598d0d775a7ffefb138a606e0d7b)
+set(LUA_JIT_MD5_2.1.0-beta2.zip b5d943c0174ca217736e2ddc2d9721c3)
+set(LUA_JIT_MD5_2.1.0-beta1.tar.gz 5a5bf71666e77cf6e7a1ae851127b834)
+set(LUA_JIT_MD5_2.1.0-beta1.zip 4b5c2c9aef0e7c0b622b09e7c84d566b)
+set(LUA_JIT_MD5_2.0.5.tar.gz 48353202cbcacab84ee41a5a70ea0a2c)
+set(LUA_JIT_MD5_2.0.5.zip f7cf52a049d74aee4e624bdc1160b80d)
+set(LUA_JIT_MD5_2.0.4.tar.gz dd9c38307f2223a504cbfb96e477eca0)
+set(LUA_JIT_MD5_2.0.4.zip ed1f0caf3d390171f423f6f1b5c57aac)
+set(LUA_JIT_MD5_2.0.3.tar.gz f14e9104be513913810cd59c8c658dc0)
+set(LUA_JIT_MD5_2.0.3.zip 6c0f6958d5e1f67734fb1ff514ec4c84)
+set(LUA_JIT_MD5_2.0.2.tar.gz 112dfb82548b03377fbefbba2e0e3a5b)
+set(LUA_JIT_MD5_2.0.2.zip a57c7d1b8eaf46559303dcfd56404045)
+set(LUA_JIT_MD5_2.0.1.tar.gz 85e406e8829602988eb1233a82e29f1f)
+set(LUA_JIT_MD5_2.0.1.zip cf4aee0e40b220054ee3cffbe0cd6ed5)
+set(LUA_JIT_MD5_2.0.0.tar.gz 97a2b87cc0490784f54b64cfb3b8f5ad)
+set(LUA_JIT_MD5_2.0.0.zip 467f4f531f7e08ee252f5030ecada7ed)
+set(LUA_JIT_MD5_2.0.0-beta11.tar.gz 824aa2684a11e3cc3abe87350a7b6139)
+set(LUA_JIT_MD5_2.0.0-beta11.zip 8629401437048e477c94bd791b0a823a)
+set(LUA_JIT_MD5_2.0.0-beta10.tar.gz ed66689b96f7ad7bfeffe0b4ff2d63d4)
+set(LUA_JIT_MD5_2.0.0-beta10.zip f6bbd472726b761b29438c4a06b5ab3c)
+set(LUA_JIT_MD5_2.0.0-beta9.tar.gz e7e03e67e2550817358bc28b44270c6d)
+set(LUA_JIT_MD5_2.0.0-beta9.zip 3f9ca0309f26e789c6c3246c83696f84)
+set(LUA_JIT_MD5_2.0.0-beta8.tar.gz f0748a73ae268d49b1d01f56c4fe3e61)
+set(LUA_JIT_MD5_2.0.0-beta8.zip fb096a90c9e799c8922f32095ef3d93c)
+set(LUA_JIT_MD5_2.0.0-beta7.tar.gz b845dec15dd9eba2fd17d865601a52e5)
+set(LUA_JIT_MD5_2.0.0-beta7.zip e10fc2b19de52d8770cdf24f1791dd77)
+set(LUA_JIT_MD5_2.0.0-beta6.tar.gz bfcbe2a11162cfa84d5a1693b442c8bf)
+set(LUA_JIT_MD5_2.0.0-beta6.zip f64945c5ecaf3ea71a829fdbb5cb196c)
+set(LUA_JIT_MD5_2.0.0-beta5.tar.gz 7e0dfa03a140148149a1021d4ffd5c57)
+set(LUA_JIT_MD5_2.0.0-beta5.zip be8087fcb576c30ffbb6368ebc284498)
+set(LUA_JIT_MD5_2.0.0-beta4.tar.gz 5c5a9305b3e06765e1dae138e1a95c3a)
+set(LUA_JIT_MD5_2.0.0-beta4.zip d0b241be6207fa7d97b6afc41368e05f)
+set(LUA_JIT_MD5_2.0.0-beta3.tar.gz 313b6f164e93e1bbac7bf87abb58d4a1)
+set(LUA_JIT_MD5_2.0.0-beta3.zip bea9c7bcd5084f98830e31956f276ff6)
+set(LUA_JIT_MD5_2.0.0-beta2.tar.gz 2ebcc38fa1d9756dc2e341f191701120)
+set(LUA_JIT_MD5_2.0.0-beta2.zip 94086f99f647d46a8360adeb11851d66)
+set(LUA_JIT_MD5_2.0.0-beta1.tar.gz 9ed7646d03580a1cec4abeb74ca44843)
+set(LUA_JIT_MD5_2.0.0-beta1.zip 19d5bac616fa739343c7158d9d99a3f3)
+set(LUA_JIT_MD5_1.1.8.tar.gz ad0e319483fa235e3979537a748631e9)
+set(LUA_JIT_MD5_1.1.8.zip 92870c80f504c34c9b7547cd6c5562d0)
+set(LUA_JIT_MD5_1.1.7.tar.gz 3aed0795f7c8725d3613269cd56f8e5a)
+set(LUA_JIT_MD5_1.1.7.zip 40a8dbc214306bb4b9849fcf026c4ee0)
+set(LUA_JIT_MD5_1.1.6.tar.gz 1a1320e09d0cd5b793014556fb7d64c9)
+set(LUA_JIT_MD5_1.1.6.zip 350d7b9230637056fbd6158b95e8fa11)
+set(LUA_JIT_MD5_1.1.5.tar.gz b99d244ba4fc1979946ae1025368fc5c)
+set(LUA_JIT_MD5_1.1.5.zip d3ffbae3bfcd5914b02dc00b1118a59d)
+set(LUA_JIT_MD5_1.1.4.tar.gz 9fe29cfb8126bc9c4302701c06965f1c)
+set(LUA_JIT_MD5_1.1.4.zip 30d318e3287000ecf4c93b29e8783183)
+set(LUA_JIT_MD5_1.1.3.tar.gz f5db1a147ed3d34677ad1ef310c56da7)
+set(LUA_JIT_MD5_1.1.3.zip 5949e7bce9d97c37c282e1cbe85aa378)
+set(LUA_JIT_MD5_1.1.2.tar.gz 4ae25ce7e3f301d1fcf0b713016edab0)
+set(LUA_JIT_MD5_1.1.0.tar.gz 16d880a98a1ff6608ac1039c802233db)
+set(LUA_JIT_MD5_1.0.3.tar.gz d0a63d5394cca549889bd820a05b32d2)
+
+# Clean up some variables
+string(TOLOWER ${LUA_VERSION} LUA_JIT_NORMALIZED_LUA_VERSION)
+if (LUA_JIT_NORMALIZED_LUA_VERSION MATCHES "([0-9]+\\.[0-9]+\\.[0-9]+(-[A-Za-z0-9_-]+)?)")
+	# 3-digit with optional beta1/beta2/beta3 (or whatever): probably okay?
+	set(LUA_JIT_VERSION ${CMAKE_MATCH_1})
+elseif (LUA_JIT_NORMALIZED_LUA_VERSION MATCHES "([0-9]+\\.[0-9]+)")
+	# extend version number with prefix
+	if (${CMAKE_MATCH_1} EQUAL 2)
+		if (${CMAKE_MATCH_2} EQUAL 0)
+			set(LUA_JIT_VERSION ${LUA_JIT_2.0_LATEST_VERSION})
+		elseif (${CMAKE_MATCH_2} EQUAL 1)
+			set(LUA_JIT_VERSION ${LUA_JIT_2.1_LATEST_VERSION})
+		endif()
+	endif()
+	if (NOT LUA_JIT_VERSION)
+		# Just pick a default version and roll with it
+		set(LUA_JIT_VERSION ${CMAKE_MATCH_1}.${CMAKE_MATCH_2}.0)			
+	endif()
+elseif (LUA_JIT_NORMALIZED_LUA_VERSION MATCHES "latest")
+	set(LUA_JIT_VERSION ${LUA_JIT_2.1_LATEST_VERSION})
+else()
+	MESSAGE(FATAL "Cannot deduce LuaJIT version from ${LUA_VERSION}")
+endif()
+
+FIND_PACKAGE_MESSAGE(LUABUILD
+	"Selecting LuaJIT ${LUA_JIT_VERSION} from '${LUA_VERSION}' and building a ${LUA_BUILD_LIBRARY_TYPE} library..."
+	"[${LUA_JIT_VERSION}][${LUA_VERSION}][${LUA_BUILD_LIBRARY_TYPE}]")
+
+# Get hashes for the build
+# LuaJIT unfortunately does not give us SHA1 hashes as well
+# set(LUA_JIT_SHA1 ${LUA_JIT_SHA1_${LUA_JIT_VERSION}})
+if (WIN32)
+	set(LUA_JIT_MD5 ${LUA_JIT_MD5_${LUA_JIT_VERSION}.zip})
+	set(LUA_JIT_DOWNLOAD_URI http://luajit.org/download/LuaJIT-${LUA_JIT_VERSION}.zip)
+else()
+	set(LUA_JIT_MD5 ${LUA_JIT_MD5_${LUA_JIT_VERSION}.tar.gz})
+	set(LUA_JIT_DOWNLOAD_URI http://luajit.org/download/LuaJIT-${LUA_JIT_VERSION}.tar.gz)
+endif()
+
+if (LUA_JIT_MD5)
+	set(LUA_JIT_DOWNLOAD_MD5_COMMAND URL_MD5 ${LUA_JIT_MD5})
+else ()
+	set(LUA_JIT_DOWNLOAD_MD5_COMMAND "")
+endif()
+if (LUA_JIT_SHA1)
+	set(LUA_JIT_DOWNLOAD_SHA1_COMMAND URL_HASH SHA1=${LUA_JIT_SHA1})
+else ()
+	set(LUA_JIT_DOWNLOAD_SHA1_COMMAND "")
+endif()
+
+set(LUA_JIT_SOURCE_DIR "${LUA_BUILD_TOPLEVEL}/src")
+set(LUA_JIT_INSTALL_DIR "${LUA_BUILD_TOPLEVEL}/install")
+file(MAKE_DIRECTORY ${LUA_JIT_SOURCE_DIR})
+file(MAKE_DIRECTORY ${LUA_JIT_INSTALL_DIR})
+
+set(LUA_JIT_LIB_FILENAME "${CMAKE_STATIC_LIBRARY_PREFIX}${LUA_BUILD_LIBNAME}${CMAKE_STATIC_LIBRARY_SUFFIX}")
+set(LUA_JIT_IMP_LIB_FILENAME "${CMAKE_IMPORT_LIBRARY_PREFIX}${LUA_BUILD_LIBNAME}${CMAKE_IMPORT_LIBRARY_SUFFIX}")
+set(LUA_JIT_LIB_EXP_FILENAME "${LUA_BUILD_LIBNAME}.exp")
+set(LUA_JIT_DLL_FILENAME "${CMAKE_SHARED_LIBRARY_PREFIX}${LUA_BUILD_LIBNAME}${CMAKE_SHARED_LIBRARY_SUFFIX}")
+set(LUA_JIT_EXE_FILENAME "${LUA_BUILD_LIBNAME}${CMAKE_EXECUTABLE_SUFFIX}")
+
+set(LUA_JIT_LIB_FILE "${CMAKE_ARCHIVE_OUTPUT_DIRECTORY}/${LUA_JIT_LIB_FILENAME}")
+set(LUA_JIT_IMP_LIB_FILE "${CMAKE_ARCHIVE_OUTPUT_DIRECTORY}/${LUA_JIT_IMP_LIB_FILENAME}")
+set(LUA_JIT_LIB_EXP_FILE "${CMAKE_ARCHIVE_OUTPUT_DIRECTORY}/${LUA_JIT_LIB_EXP_FILENAME}")
+set(LUA_JIT_DLL_FILE "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/${LUA_JIT_DLL_FILENAME}")
+set(LUA_JIT_EXE_FILE "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/${LUA_JIT_EXE_FILENAME}")
+
+# # # Do the build
+if (MSVC)
+	# Visual C++ is predicated off running msvcbuild.bat
+	# which requires a Visual Studio Command Prompt
+	if (BUILD_LUA_AS_DLL)
+		set(LUA_JIT_BUILD_COMMAND BUILD_COMMAND cd src && msvcbuild.bat)
+	else()
+		set(LUA_JIT_BUILD_COMMAND BUILD_COMMAND cd src && msvcbuild.bat static)
+	endif()
+	set(LUA_JIT_PREBUILT_LIB "lua51.lib")
+	set(LUA_JIT_PREBUILT_IMP_LIB "lua51.lib")
+	set(LUA_JIT_PREBUILT_DLL "lua51.dll")
+	set(LUA_JIT_PREBUILT_EXP "lua51.exp")
+	set(LUA_JIT_PREBUILT_EXE "luajit.exe")
+else ()
+	# get the make command we need for this system
+	find_program(MAKE_PROGRAM NAMES make mingw32-make mingw64-make)
+	if (MAKE_PROGRAM MATCHES "MAKE_PROGRAM-NOTFOUND")
+		MESSAGE(FATAL_ERROR "Cannot find 'make' program or similar needed to build LuaJIT ${LUA_VERSION} (perhaps place it in the PATH environment variable if it is not already?)")
+	endif()
+
+	# we can simply reuse the makefile here
+	# so define it as an external project and then just have the proper
+	# build/install/test commands
+	# make sure to apply -pagezero_size 10000 -image_base 100000000 (done later for XCode Targets)
+	set(LUA_JIT_MAKE_BUILD_MODIFICATIONS "LUAJIT_T=${LUA_JIT_EXE_FILENAME}")
+	list(APPEND LUA_JIT_MAKE_BUILD_MODIFICATIONS "LUAJIT_A=${LUA_JIT_LIB_FILENAME}")
+	set(LUA_JIT_MAKE_CFLAGS_MODIFICATIONS "")
+	set(LUA_JIT_MAKE_HOST_CFLAGS_MODIFICATIONS "")
+	set(LUA_JIT_MAKE_TARGET_CFLAGS_MODIFICATIONS "")
+	if (BUILD_LUA_AS_DLL)
+		list(APPEND LUA_JIT_MAKE_BUILD_MODIFICATIONS "LUAJIT_SO=${LUA_JIT_DLL_FILENAME}" "TARGET_SONAME=${LUA_JIT_DLL_FILENAME}" "TARGET_DYLIBNAME=${LUA_JIT_DLL_FILENAME}" "TARGET_DLLNAME=${LUA_JIT_DLL_FILENAME}")
+		list(APPEND LUA_JIT_MAKE_BUILD_MODIFICATIONS "BUILDMODE=dynamic")
+	else()
+		list(APPEND LUA_JIT_MAKE_BUILD_MODIFICATIONS "BUILDMODE=static")
+		set(LUA_JIT_MAKE_TARGET_CFLAGS_MODIFICATIONS "${LUA_JIT_MAKE_TARGET_CFLAGS_MODIFICATIONS} -fPIC")
+	endif()
+	if (IS_X86)
+		list(APPEND LUA_JIT_MAKE_BUILD_MODIFICATIONS "CC=${CMAKE_C_COMPILER} -m32")
+		list(APPEND LUA_JIT_MAKE_BUILD_MODIFICATIONS "LDFLAGS=-m32")
+		#set(LUA_JIT_MAKE_CFLAGS_MODIFICATIONS "${LUA_JIT_MAKE_CFLAGS_MODIFICATIONS} -m32")
+		#set(LUA_JIT_MAKE_HOST_CFLAGS_MODIFICATIONS "${LUA_JIT_MAKE_HOST_CFLAGS_MODIFICATIONS} -m32")
+		#set(LUA_JIT_MAKE_TARGET_CFLAGS_MODIFICATIONS "${LUA_JIT_MAKE_TARGET_CFLAGS_MODIFICATIONS} -m32")
+	endif()
+
+	set(LUA_JIT_PREBUILT_DLL ${LUA_JIT_DLL_FILENAME})
+	set(LUA_JIT_PREBUILT_LIB ${LUA_JIT_LIB_FILENAME})
+	set(LUA_JIT_PREBUILT_IMP_LIB ${LUA_JIT_IMP_LIB_FILENAME})
+	set(LUA_JIT_PREBUILT_EXE ${LUA_JIT_EXE_FILENAME})
+	set(LUA_JIT_PREBUILT_EXP ${LUA_JIT_LIB_EXP_FILENAME})
+
+	if (WIN32)
+		list(APPEND LUA_JIT_MAKE_BUILD_MODIFICATIONS "HOST_SYS=Windows" "TARGET_SYS=Windows" "TARGET_AR=ar rcus")
+	endif()
+	list(APPEND LUA_JIT_MAKE_BUILD_MODIFICATIONS "CFLAGS=${LUA_JIT_MAKE_CFLAGS_MODIFICATIONS}")
+	list(APPEND LUA_JIT_MAKE_BUILD_MODIFICATIONS "TARGET_CFLAGS=${LUA_JIT_MAKE_TARGET_CFLAGS_MODIFICATIONS}")
+	list(APPEND LUA_JIT_MAKE_BUILD_MODIFICATIONS "HOST_CFLAGS=${LUA_JIT_MAKE_HOST_CFLAGS_MODIFICATIONS}")
+
+	set(LUA_JIT_BUILD_COMMAND BUILD_COMMAND "${MAKE_PROGRAM}" ${LUA_JIT_MAKE_BUILD_MODIFICATIONS})
+endif()
+
+set(lualib luajit_lib_${LUA_JIT_VERSION})
+set(luainterpreter luajit_${LUA_JIT_VERSION})
+
+file(TO_CMAKE_PATH "${LUA_JIT_SOURCE_DIR}/${LUA_JIT_PREBUILT_LIB}" LUA_JIT_SOURCE_LUA_LIB)
+file(TO_CMAKE_PATH "${LUA_JIT_SOURCE_DIR}/${LUA_JIT_PREBUILT_IMP_LIB}" LUA_JIT_SOURCE_LUA_IMP_LIB)
+file(TO_CMAKE_PATH "${LUA_JIT_SOURCE_DIR}/${LUA_JIT_PREBUILT_EXE}" LUA_JIT_SOURCE_LUA_INTERPRETER)
+file(TO_CMAKE_PATH "${LUA_JIT_SOURCE_DIR}/${LUA_JIT_PREBUILT_DLL}" LUA_JIT_SOURCE_LUA_DLL)
+file(TO_CMAKE_PATH "${LUA_JIT_SOURCE_DIR}/${LUA_JIT_PREBUILT_EXP}" LUA_JIT_SOURCE_LUA_LIB_EXP)
+
+file(TO_CMAKE_PATH "${LUA_JIT_DLL_FILE}" LUA_JIT_DESTINATION_LUA_DLL)
+file(TO_CMAKE_PATH "${CMAKE_ARCHIVE_OUTPUT_DIRECTORY}/${LUA_JIT_LIB_EXP_FILENAME}" LUA_JIT_DESTINATION_LUA_LIB_EXP)
+file(TO_CMAKE_PATH "${LUA_JIT_IMP_LIB_FILE}" LUA_JIT_DESTINATION_LUA_IMP_LIB)
+file(TO_CMAKE_PATH "${LUA_JIT_LIB_FILE}" LUA_JIT_DESTINATION_LUA_LIB)
+file(TO_CMAKE_PATH "${LUA_JIT_EXE_FILE}" LUA_JIT_DESTINATION_LUA_INTERPRETER)
+
+if (WIN32 AND NOT MSVC)
+	string(COMPARE EQUAL ${LUA_JIT_VERSION} ${LUA_JIT_2.0_LATEST_VERSION} lua_jit_same_version_20)
+	string(COMPARE EQUAL ${LUA_JIT_VERSION} ${LUA_JIT_2.1_LATEST_VERSION} lua_jit_same_version_21)
+	if (lua_jit_same_version_20 OR lua_jit_same_version_21)
+		#set (LUA_JIT_GIT_COMMIT ${LUA_JIT_${LUA_JIT_VERSION}_COMMIT})
+		#set(LUA_JIT_GIT_TAG GIT_TAG ${LUA_JIT_GIT_COMMIT})
+	endif()
+elseif(LUA_JIT_NORMALIZED_LUA_VERSION MATCHES "latest")
+	set(LUA_JIT_PULL_LATEST TRUE)
+endif()
+
+set(LUA_JIT_BYPRODUCTS "${LUA_JIT_SOURCE_LUA_LIB}" "${LUA_JIT_SOURCE_LUA_LIB_EXP}"
+	"${LUA_JIT_SOURCE_LUA_DLL}" "${LUA_JIT_SOURCE_LUA_INTERPRETER}")
+
+set(LUA_JIT_INSTALL_BYPRODUCTS "${LUA_JIT_DESTINATION_LUA_LIB}" "${LUA_JIT_DESTINATION_LUA_LIB_EXP}"
+	"${LUA_JIT_DESTINATION_LUA_DLL}" "${LUA_JIT_DESTINATION_LUA_INTERPRETER}")
+
+if (CMAKE_IMPORT_LIBRARY_SUFFIX)
+	set(LUA_JIT_BYPRODUCTS "${LUA_JIT_BYPRODUCTS}" "${LUA_JIT_SOURCE_LUA_IMP_LIB}")
+	set(LUA_JIT_INSTALL_BYPRODUCTS "${LUA_JIT_INSTALL_BYPRODUCTS}" "${LUA_JIT_DESTINATION_LUA_IMP_LIB}")
+endif()
+
+# # Post-Build moving steps for necessary items
+# Add post-step to move library afterwards
+set(LUA_JIT_POSTBUILD_COMMENTS "Executable - Moving \"${LUA_JIT_SOURCE_LUA_INTERPRETER}\" to \"${LUA_JIT_DESTINATION_LUA_INTERPRETER}\"...")
+set(LUA_JIT_POSTBUILD_COMMANDS COMMAND "${CMAKE_COMMAND}" -E copy "${LUA_JIT_SOURCE_LUA_INTERPRETER}" "${LUA_JIT_DESTINATION_LUA_INTERPRETER}")
+if (BUILD_LUA_AS_DLL)
+	if (MSVC)
+		set(LUA_JIT_POSTBUILD_COMMENTS "${LUA_JIT_POSTBUILD_COMMENTS}\nImport Library - Moving \"${LUA_JIT_SOURCE_LUA_IMP_LIB}\" to \"${LUA_JIT_DESTINATION_LUA_IMP_LIB}\"...")
+		set(LUA_JIT_POSTBUILD_COMMANDS ${LUA_JIT_POSTBUILD_COMMANDS} COMMAND "${CMAKE_COMMAND}" -E copy "${LUA_JIT_SOURCE_LUA_IMP_LIB}" "${LUA_JIT_DESTINATION_LUA_IMP_LIB}")
+		
+		set(LUA_JIT_POSTBUILD_COMMENTS "${LUA_JIT_POSTBUILD_COMMENTS}\nLibrary - Moving \"${LUA_JIT_SOURCE_LUA_LIB_EXP}\" to \"${LUA_JIT_DESTINATION_LUA_LIB_EXP}\"...")
+		set(LUA_JIT_POSTBUILD_COMMANDS ${LUA_JIT_POSTBUILD_COMMANDS} && "${CMAKE_COMMAND}" -E copy "${LUA_JIT_SOURCE_LUA_LIB_EXP}" "${LUA_JIT_DESTINATION_LUA_LIB_EXP}")
+	endif()
+	set(LUA_JIT_POSTBUILD_COMMENTS "${LUA_JIT_POSTBUILD_COMMENTS}\nDynamic Library - Moving \"${LUA_JIT_SOURCE_LUA_DLL}\" to \"${LUA_JIT_DESTINATION_LUA_DLL}\"...")
+	set(LUA_JIT_POSTBUILD_COMMANDS ${LUA_JIT_POSTBUILD_COMMANDS} COMMAND "${CMAKE_COMMAND}" -E copy "${LUA_JIT_SOURCE_LUA_DLL}" "${LUA_JIT_DESTINATION_LUA_DLL}")
+else()
+	set(LUA_JIT_POSTBUILD_COMMENTS "${LUA_JIT_POSTBUILD_COMMENTS}\nLibrary - Moving \"${LUA_JIT_SOURCE_LUA_LIB}\" to \"${LUA_JIT_DESTINATION_LUA_LIB}\"...")
+	set(LUA_JIT_POSTBUILD_COMMANDS ${LUA_JIT_POSTBUILD_COMMANDS} COMMAND "${CMAKE_COMMAND}" -E copy "${LUA_JIT_SOURCE_LUA_LIB}" "${LUA_JIT_DESTINATION_LUA_LIB}")
+endif()
+
+if (LUA_JIT_GIT_COMMIT OR LUA_JIT_PULL_LATEST)
+	if (LUA_JIT_PULL_LATEST)
+		MESSAGE(STATUS "Latest LuaJIT has been requested: pulling from git...")
+	elseif (LUA_JIT_GIT_COMMIT)
+		MESSAGE(STATUS "LuaJIT '${LUA_VERSION}' requested has broken static library builds: using git '${LUA_JIT_GIT_COMMIT}'...")			
+	endif()
+	ExternalProject_Add(LUA_JIT
+		BUILD_IN_SOURCE TRUE
+		BUILD_ALWAYS FALSE
+		PREFIX "${LUA_BUILD_TOPLEVEL}"
+		SOURCE_DIR "${LUA_BUILD_TOPLEVEL}"
+		DOWNLOAD_DIR "${LUA_BUILD_TOPLEVEL}"
+		TMP_DIR "${LUA_BUILD_TOPLEVEL}-tmp"
+		STAMP_DIR "${LUA_BUILD_TOPLEVEL}-stamp"
+		INSTALL_DIR "${LUA_BUILD_INSTALL_DIR}"
+		GIT_REPOSITORY https://github.com/LuaJIT/LuaJIT.git
+		GIT_REMOTE_NAME origin
+		${LUA_JIT_GIT_TAG}
+		GIT_SHALLOW TRUE
+		CONFIGURE_COMMAND ""
+		${LUA_JIT_BUILD_COMMAND}
+		INSTALL_COMMAND ""
+		TEST_COMMAND ""
+		BUILD_BYPRODUCTS ${LUA_JIT_BYPRODUCTS})
+else()
+	ExternalProject_Add(LUA_JIT
+		BUILD_IN_SOURCE TRUE
+		BUILD_ALWAYS FALSE
+		# LuaJIT does not offer a TLS/SSL port
+		TLS_VERIFY FALSE
+		PREFIX "${LUA_BUILD_TOPLEVEL}"
+		SOURCE_DIR "${LUA_BUILD_TOPLEVEL}"
+		DOWNLOAD_DIR "${LUA_BUILD_TOPLEVEL}"
+		TMP_DIR "${LUA_BUILD_TOPLEVEL}-tmp"
+		STAMP_DIR "${LUA_BUILD_TOPLEVEL}-stamp"
+		INSTALL_DIR "${LUA_BUILD_INSTALL_DIR}"
+		URL "${LUA_JIT_DOWNLOAD_URI}"
+		${LUA_JIT_DOWNLOAD_MD5_COMMAND}
+		${LUA_JIT_DOWNLOAD_SHA1_COMMAND}
+		CONFIGURE_COMMAND ""
+		${LUA_JIT_BUILD_COMMAND}
+		INSTALL_COMMAND ""
+		TEST_COMMAND ""
+		BUILD_BYPRODUCTS ${LUA_JIT_BYPRODUCTS})
+endif()
+
+# # MAYBE?:
+# Add additional post-build step to move all necessary headers/lua files
+# for now, we just point directly to the `src` directory...
+
+add_custom_command(TARGET LUA_JIT
+	POST_BUILD
+	${LUA_JIT_POSTBUILD_COMMANDS}
+	COMMENT ${LUA_JIT_POSTBUILD_COMMENTS}
+	BYPRODUCTS ${LUA_JIT_INSTALL_BYPRODUCTS})
+
+# # Lua Library
+add_library(${lualib} ${LUA_BUILD_LIBRARY_TYPE} IMPORTED)
+# make sure the library we export really does depend on Lua JIT's external project
+add_dependencies(${lualib} LUA_JIT)
+# Configure properties
+if (BUILD_LUA_AS_DLL)
+	if (MSVC)
+		set_target_properties(${lualib}
+			PROPERTIES 
+			IMPORTED_IMPLIB "${LUA_JIT_DESTINATION_LUA_IMP_LIB}")
+	endif()
+	set_target_properties(${lualib}
+		PROPERTIES 
+		IMPORTED_LOCATION "${LUA_JIT_DESTINATION_LUA_DLL}")
+else ()
+	set_target_properties(${lualib}
+		PROPERTIES 
+		IMPORTED_LOCATION "${LUA_JIT_DESTINATION_LUA_LIB}")
+endif()
+set_target_properties(${lualib}
+	PROPERTIES 
+	IMPORTED_LINK_INTERFACE_LANGUAGES C
+	INTERFACE_INCLUDE_DIRECTORIES "${LUA_JIT_SOURCE_DIR}")
+if (CMAKE_DL_LIBS)
+	set_target_properties(${lualib}
+			PROPERTIES
+			INTERFACE_LINK_LIBRARIES ${CMAKE_DL_LIBS})
+endif()
+if (XCODE)
+	target_compile_options(${lualib}
+		PUBLIC -pagezero_size 10000 -image_base 100000000)
+endif ()
+
+# # Lua Executable
+add_executable(${luainterpreter} IMPORTED)
+# Add location pointing to executable
+set_target_properties(${luainterpreter}
+	PROPERTIES
+	IMPORTED_LOCATION "${LUA_JIT_DESTINATION_LUA_INTERPRETER}")
+add_dependencies(${luainterpreter} LUA_JIT)
+
+# # set externally-visible target indicator
+set(LUA_LIBRARIES ${lualib})
+set(LUA_INTERPRETER ${luainterpreter})
+set(LUA_INCLUDE_DIRS "${LUA_JIT_SOURCE_DIR}")

third_party/sol2/cmake/Modules/FindLuaBuild/LuaVanilla.cmake

@@ -0,0 +1,401 @@
+# # # # sol2
+# The MIT License (MIT)
+# 
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+# Include guard
+if(_lua_vanilla_build_included)
+	return()
+endif(_lua_vanilla_build_included)
+set(_lua_vanilla_build_included true)
+
+# import necessary standard modules
+include(ExternalProject)
+# import other modules
+include(Common/Core)
+
+# Latest versions for specific sub-versions of Lua
+set(LUA_VANILLA_5.1_LATEST_VERSION 5.1.5)
+set(LUA_VANILLA_5.2_LATEST_VERSION 5.2.4)
+set(LUA_VANILLA_5.3_LATEST_VERSION 5.3.4)
+
+# exact version, coming from CI: pull directly from Lua and use external project to build
+# list of known md5 / sha1: must update when there are changes
+set(LUA_VANILLA_MD5_5.3.4 53a9c68bcc0eda58bdc2095ad5cdfc63)
+set(LUA_VANILLA_SHA1_5.3.4 79790cfd40e09ba796b01a571d4d63b52b1cd950)
+set(LUA_VANILLA_MD5_5.3.3 703f75caa4fdf4a911c1a72e67a27498)
+set(LUA_VANILLA_SHA1_5.3.3 a0341bc3d1415b814cc738b2ec01ae56045d64ef)
+set(LUA_VANILLA_MD5_5.3.2 33278c2ab5ee3c1a875be8d55c1ca2a1)
+set(LUA_VANILLA_SHA1_5.3.2 7a47adef554fdca7d0c5536148de34579134a973)
+set(LUA_VANILLA_MD5_5.3.1 797adacada8d85761c079390ff1d9961)
+set(LUA_VANILLA_SHA1_5.3.1 1676c6a041d90b6982db8cef1e5fb26000ab6dee)
+set(LUA_VANILLA_MD5_5.3.0 a1b0a7e92d0c85bbff7a8d27bf29f8af)
+set(LUA_VANILLA_SHA1_5.3.0 1c46d1c78c44039939e820126b86a6ae12dadfba)
+set(LUA_VANILLA_MD5_5.2.4 913fdb32207046b273fdb17aad70be13)
+set(LUA_VANILLA_SHA1_5.2.4 ef15259421197e3d85b7d6e4871b8c26fd82c1cf)
+set(LUA_VANILLA_MD5_5.2.3 dc7f94ec6ff15c985d2d6ad0f1b35654)
+set(LUA_VANILLA_SHA1_5.2.3 926b7907bc8d274e063d42804666b40a3f3c124c)
+set(LUA_VANILLA_MD5_5.2.2 efbb645e897eae37cad4344ce8b0a614)
+set(LUA_VANILLA_SHA1_5.2.2 0857e41e5579726a4cb96732e80d7aa47165eaf5)
+set(LUA_VANILLA_MD5_5.2.1 ae08f641b45d737d12d30291a5e5f6e3)
+set(LUA_VANILLA_SHA1_5.2.1 6bb1b0a39b6a5484b71a83323c690154f86b2021)
+set(LUA_VANILLA_MD5_5.2.0 f1ea831f397214bae8a265995ab1a93e)
+set(LUA_VANILLA_SHA1_5.2.0 08f84c355cdd646f617f09cebea48bd832415829)
+set(LUA_VANILLA_MD5_5.1.5 2e115fe26e435e33b0d5c022e4490567)
+set(LUA_VANILLA_SHA1_5.1.5 b3882111ad02ecc6b972f8c1241647905cb2e3fc)
+set(LUA_VANILLA_MD5_5.1.4 d0870f2de55d59c1c8419f36e8fac150)
+set(LUA_VANILLA_SHA1_5.1.4 2b11c8e60306efb7f0734b747588f57995493db7)
+set(LUA_VANILLA_MD5_5.1.3 a70a8dfaa150e047866dc01a46272599)
+set(LUA_VANILLA_SHA1_5.1.3 89bc9f5a351402565b8077e8123327e7cd15f004)
+set(LUA_VANILLA_MD5_5.1.2 687ce4c2a1ddff18f1008490fdc4e5e0)
+set(LUA_VANILLA_SHA1_5.1.2 8a460d2d7e70e93cb72bf3d584405464763cb5f0)
+set(LUA_VANILLA_MD5_5.1.1 22f4f912f20802c11006fe9b84d5c461)
+set(LUA_VANILLA_SHA1_5.1.1 be13878ceef8e1ee7a4201261f0adf09f89f1005)
+set(LUA_VANILLA_MD5_5.1 3e8dfe8be00a744cec2f9e766b2f2aee)
+set(LUA_VANILLA_SHA1_5.1 1ae9ec317511d525c7999c842ca0b1ddde84e374)
+set(LUA_VANILLA_MD5_5.0.3 feee27132056de2949ce499b0ef4c480)
+set(LUA_VANILLA_SHA1_5.0.3 e7e91f78b8a8deb09b13436829bed557a46af8ae)
+set(LUA_VANILLA_MD5_5.0.2 dea74646b7e5c621fef7174df83c34b1)
+set(LUA_VANILLA_SHA1_5.0.2 a200cfd20a9a4c7da1206ae45dddf26186a9e0e7)
+set(LUA_VANILLA_MD5_5.0.1 e0a450d84971a3f4563b98172d1e382c)
+set(LUA_VANILLA_SHA1_5.0.1 03b47b4785178aca583333f01d8726a8ab9f7ae7)
+set(LUA_VANILLA_MD5_5.0 6f14803fad389fb1cb15d17edfeddd91)
+set(LUA_VANILLA_SHA1_5.0 88b1bc057857c0db5ace491c4af2c917a2b803bf)
+set(LUA_VANILLA_MD5_4.0.1 a31d963dbdf727f9b34eee1e0d29132c)
+set(LUA_VANILLA_SHA1_4.0.1 12f1864a7ecd4b8011862a07fa3f177b2e80e7d3)
+set(LUA_VANILLA_MD5_4.0 be11522d46d33a931868c03694aaeeef)
+set(LUA_VANILLA_SHA1_4.0 8d432c73ef6e98b81d252114be1a83182cc9607a)
+set(LUA_VANILLA_MD5_3.2.2 374ba5c4839709922de40b8d10382705)
+set(LUA_VANILLA_SHA1_3.2.2 fa50ff14c00d8523c8a3d1d3f4887ecc4400d0c3)
+set(LUA_VANILLA_MD5_3.2.1 47264a1978df49fc1dea6ffcddb05b21)
+set(LUA_VANILLA_SHA1_3.2.1 d43af5a1c7a65c0ddb4b0ac06c29ecf4cdd22367)
+set(LUA_VANILLA_MD5_3.2 a6552da3d40ae9b04489a788262279e8)
+set(LUA_VANILLA_SHA1_3.2 84cf9f0e7d00eed3ea8b4ac2b84254b714510b34)
+set(LUA_VANILLA_MD5_3.1 d677f3827167eefdefc7b211397cfdfb)
+set(LUA_VANILLA_SHA1_3.1 509485e3baafd946f4ffe2a984f8a63746adc32a)
+set(LUA_VANILLA_MD5_3.0 997558ae76c2f1cd1e10fd3835c45c6a)
+set(LUA_VANILLA_SHA1_3.0 5c8c910353f717ba29b4fe7d538994454229b335)
+set(LUA_VANILLA_MD5_2.5 da915d58904e75b9b0fc18147e19b0bb)
+set(LUA_VANILLA_SHA1_2.5 7920e12c40242932c22fa261ff114cc485a39d99)
+set(LUA_VANILLA_MD5_2.4 5d035cc244285c1dbbcaaa0908b58965)
+set(LUA_VANILLA_SHA1_2.4 74036935b36e6ae4ed17bd7a9408154f9a4a6b17)
+set(LUA_VANILLA_MD5_2.2 a298b58e197ff8168ec907d6145252ef)
+set(LUA_VANILLA_SHA1_2.2 2d8b1df94b2fb76f0f16ca1ddc54d5186b10df4b)
+set(LUA_VANILLA_MD5_2.1 053a9f6728cc56f6a23716a6a1ede595)
+set(LUA_VANILLA_SHA1_2.1 b9a797547f480bcb58b5d3da846c8ac8d2201df0)
+set(LUA_VANILLA_MD5_1.1 9f83141cc8ea362497e272071eda5cf6)
+set(LUA_VANILLA_SHA1_1.1 67209701eec5cc633e829d023fbff62d5d6c8e5e)
+set(LUA_VANILLA_MD5_1.0 96e8399fc508d128badd8ac3aa8f2119)
+set(LUA_VANILLA_SHA1_1.0 6a82d2ae7ce9ad98c7b4824a325b91522c0d6ebb)
+
+# Clean up some variables
+if (LUA_VERSION MATCHES "^([0-9]+)\\.([0-9]+)\\.([0-9]+)$")
+	# probably okay!
+	set(LUA_VANILLA_VERSION ${CMAKE_MATCH_1}.${CMAKE_MATCH_2}.${CMAKE_MATCH_3})
+elseif (LUA_VERSION MATCHES "([0-9]+)\\.([0-9]+)")
+	# extend version number with prefix
+	if (${CMAKE_MATCH_1} EQUAL 5)
+		if (${CMAKE_MATCH_2} EQUAL 1)
+			set(LUA_VANILLA_VERSION ${LUA_VANILLA_5.1_LATEST_VERSION})
+		elseif (${CMAKE_MATCH_2} EQUAL 2)
+			set(LUA_VANILLA_VERSION ${LUA_VANILLA_5.2_LATEST_VERSION})
+		elseif (${CMAKE_MATCH_2} EQUAL 3)
+			set(LUA_VANILLA_VERSION ${LUA_VANILLA_5.3_LATEST_VERSION})
+		else()			
+			# default to whatever the first two
+			# numbers happen to be, plus build 0
+			set(LUA_VANILLA_VERSION ${CMAKE_MATCH_1}.${CMAKE_MATCH_2}.0)
+		endif()
+	endif()
+	if(NOT LUA_VANILLA_VERSION)			
+		# default to whatever the first two
+		# numbers happen to be, plus build 0
+		set(LUA_VANILLA_VERSION ${CMAKE_MATCH_1}.${CMAKE_MATCH_2}.0)
+	endif()
+else()
+	message(FATAL_ERROR "Cannot deduce the proper Lua version from ${LUA_VERSION}")
+endif()
+
+FIND_PACKAGE_MESSAGE(LUABUILD
+	"Selecting PUC-RIO Lua ${LUA_VANILLA_VERSION} from '${LUA_VERSION}' and building a ${LUA_BUILD_LIBRARY_TYPE} library..."
+	"[${LUA_VANILLA_VERSION}][${LUA_VERSION}][${LUA_BUILD_LIBRARY_TYPE}]")
+
+# Get Hashes to use for download
+set(LUA_VANILLA_SHA1 ${LUA_VANILLA_SHA1_${LUA_VANILLA_VERSION}})
+set(LUA_VANILLA_MD5 ${LUA_VANILLA_MD5_${LUA_VANILLA_VERSION}})
+
+if (LUA_VANILLA_MD5)
+	set(LUA_VANILLA_DOWNLOAD_MD5_COMMAND URL_MD5 ${LUA_VANILLA_MD5})
+else ()
+	set(LUA_VANILLA_DOWNLOAD_MD5_COMMAND "")
+endif()
+if (LUA_VANILLA_SHA1)
+	set(LUA_VANILLA_DOWNLOAD_SHA1_COMMAND URL_HASH SHA1=${LUA_VANILLA_SHA1})
+else ()
+	set(LUA_VANILLA_DOWNLOAD_SHA1_COMMAND "")
+endif()
+
+# # # Makefile and self-build configurations
+
+# # Potential compiler variables
+if (MSVC)
+	set(LUA_VANILLA_LUA_LUAC_COMPILER_OPTIONS "/W1")
+	if (BUILD_LUA_AS_DLL)
+		set(LUA_VANILLA_DLL_DEFINE LUA_BUILD_AS_DLL)
+	else()
+		set(LUA_VANILLA_DLL_DEFINE "")
+	endif()
+else()
+	set(LUA_VANILLA_LUALIB_COMPILER_OPTIONS "")
+	set(LUA_VANILLA_DLL_DEFINE "")
+endif()
+
+# # Source files for natural build, if we have to go that far
+# retrieve source files
+if (LUA_VANILLA_VERSION MATCHES "^5\\.1")
+	set(LUA_VANILLA_LIB_SOURCES lapi.c lcode.c ldebug.c ldo.c ldump.c lfunc.c 
+		lgc.c llex.c lmem.c lobject.c lopcodes.c lparser.c lstate.c 
+		lstring.c ltable.c ltm.c lundump.c lvm.c lzio.c lauxlib.c 
+		lbaselib.c ldblib.c liolib.c lmathlib.c loslib.c ltablib.c 
+		lstrlib.c loadlib.c linit.c)
+	set(LUA_VANILLA_LUA_SOURCES lua.c )
+	set(LUA_VANILLA_LUAC_SOURCES luac.c print.c )
+	set(LUA_VANILLA_GENERATE_LUA_HPP true)
+elseif (LUA_VANILLA_VERSION MATCHES "^5\\.2")
+	set(LUA_VANILLA_LIB_SOURCES lapi.c lcode.c lctype.c ldebug.c ldo.c ldump.c 
+		lfunc.c lgc.c llex.c lmem.c lobject.c lopcodes.c lparser.c 
+		lstate.c lstring.c ltable.c ltm.c lundump.c lvm.c lzio.c
+		lauxlib.c lbaselib.c lbitlib.c lcorolib.c ldblib.c liolib.c 
+		lmathlib.c loslib.c lstrlib.c ltablib.c loadlib.c linit.c)
+	set(LUA_VANILLA_LUA_SOURCES lua.c )
+	set(LUA_VANILLA_LUAC_SOURCES luac.c )
+	set(LUA_VANILLA_GENERATE_LUA_HPP false)
+else()
+	if (NOT LUA_VANILLA_VERSION MATCHES "^5\\.3")
+		message(STATUS "Using the Lua 5.3 sources list for a version of Lua that is not 5.3: may result in an incomplete build or errors later")
+	endif()
+	set(LUA_VANILLA_LIB_SOURCES lapi.c lcode.c lctype.c ldebug.c ldo.c ldump.c 
+		lfunc.c lgc.c llex.c lmem.c lobject.c lopcodes.c lparser.c lstate.c 
+		lstring.c ltable.c ltm.c lundump.c lvm.c lzio.c lauxlib.c 
+		lbaselib.c lbitlib.c lcorolib.c ldblib.c liolib.c lmathlib.c 
+		loslib.c lstrlib.c ltablib.c lutf8lib.c loadlib.c linit.c)
+	set(LUA_VANILLA_LUA_SOURCES lua.c )
+	set(LUA_VANILLA_LUAC_SOURCES luac.c )
+	set(LUA_VANILLA_GENERATE_LUA_HPP false)
+endif()
+
+set(LUA_VANILLA_SOURCE_DIR "${LUA_BUILD_TOPLEVEL}/src")
+prepend(LUA_VANILLA_LIB_SOURCES "${LUA_VANILLA_SOURCE_DIR}/" ${LUA_VANILLA_LIB_SOURCES})
+prepend(LUA_VANILLA_LUA_SOURCES "${LUA_VANILLA_SOURCE_DIR}/" ${LUA_VANILLA_LUA_SOURCES})
+prepend(LUA_VANILLA_LUAC_SOURCES "${LUA_VANILLA_SOURCE_DIR}/" ${LUA_VANILLA_LUAC_SOURCES})
+
+# download, just for the sake of download + extract
+# have to use 2 different commands just to have an empty command
+# that results in nothing being run
+# TODO: talk to smarter CMake people...?
+
+ExternalProject_Add(LUA_VANILLA
+	BUILD_IN_SOURCE TRUE
+	BUILD_ALWAYS FALSE
+	TLS_VERIFY TRUE
+	PREFIX ${LUA_BUILD_TOPLEVEL}
+	SOURCE_DIR ${LUA_BUILD_TOPLEVEL}
+	DOWNLOAD_DIR ${LUA_BUILD_TOPLEVEL}
+	TMP_DIR "${LUA_BUILD_TOPLEVEL}-tmp"
+	STAMP_DIR "${LUA_BUILD_TOPLEVEL}-stamp"
+	INSTALL_DIR "${LUA_BUILD_INSTALL_DIR}"
+	URL https://www.lua.org/ftp/lua-${LUA_VANILLA_VERSION}.tar.gz
+	URL_MD5 ${LUA_VANILLA_MD5}
+	URL_HASH SHA1=${LUA_VANILLA_SHA1}
+	CONFIGURE_COMMAND ""
+	BUILD_COMMAND ""
+	INSTALL_COMMAND ""
+	TEST_COMMAND ""
+	BUILD_BYPRODUCTS "${LUA_VANILLA_LIB_SOURCES}" "${LUA_VANILLA_LUA_SOURCES}" "${LUA_VANILLA_LUAC_SOURCES}")
+
+# make a quick lua.hpp for 5.1 targets that don't have it
+if (LUA_VANILLA_GENERATE_LUA_HPP)
+	set(LUA_VANILLA_LUA_HPP_CONTENT "// lua.hpp
+// Lua header files for C++
+// <<extern \"C\">> not supplied automatically because Lua also compiles as C++
+
+extern \"C\" {
+#include \"lua.h\"
+#include \"lualib.h\"
+#include \"lauxlib.h\"
+}
+")
+	set(LUA_VANILLA_SOURCE_LUA_HPP "${LUA_BUILD_TOPLEVEL}-tmp/lua.hpp")
+	set(LUA_VANILLA_DESTINATION_LUA_HPP "${LUA_VANILLA_SOURCE_DIR}/lua.hpp")
+	file(WRITE "${LUA_VANILLA_SOURCE_LUA_HPP}" "${LUA_VANILLA_LUA_HPP_CONTENT}")
+	file(TO_NATIVE_PATH "${LUA_VANILLA_SOURCE_LUA_HPP}" LUA_VANILLA_SOURCE_LUA_HPP)
+	file(TO_NATIVE_PATH "${LUA_VANILLA_DESTINATION_LUA_HPP}" LUA_VANILLA_DESTINATION_LUA_HPP)
+	ExternalProject_Add_Step(LUA_VANILLA
+		prebuild
+		# after download, before build
+		DEPENDEES download
+		DEPENDERS build
+		BYPRODUCTS "${LUA_VANILLA_DESTINATION_LUA_HPP}"
+		COMMENT "Moving \"${LUA_VANILLA_SOURCE_LUA_HPP}\" to \"${LUA_VANILLA_DESTINATION_LUA_HPP}\"..."
+		COMMAND "${CMAKE_COMMAND}" -E copy "${LUA_VANILLA_SOURCE_LUA_HPP}" "${LUA_VANILLA_DESTINATION_LUA_HPP}")
+endif()
+
+# # Target names
+set(liblua "liblua-${LUA_VANILLA_VERSION}")
+set(luainterpreter "lua-${LUA_VANILLA_VERSION}")
+set(luacompiler "luac-${LUA_VANILLA_VERSION}")
+
+# Lua does not out-of-the-box support building 
+# a shared library: http://lua-users.org/lists/lua-l/2006-10/msg00098.html
+# in this case, we essentially need to
+# build Lua for our purposes, which is annoying
+# the external project is just a dummy to get and extract the file:
+# after that, we define actual targets...!
+
+# make an actual, buildable target
+# that other parts of the code can depend on
+add_library(${liblua} ${LUA_BUILD_LIBRARY_TYPE} "${LUA_VANILLA_LIB_SOURCES}")
+set_target_properties(${liblua}
+	PROPERTIES
+	LANGUAGE C
+	LINKER_LANGUAGE C
+	C_STANDARD 99
+	C_EXTENSIONS TRUE
+	POSITION_INDEPENDENT_CODE TRUE
+	INCLUDE_DIRECTORIES ${LUA_VANILLA_SOURCE_DIR}
+	OUTPUT_NAME ${LUA_BUILD_LIBNAME}
+	RUNTIME_OUTPUT_NAME ${LUA_BUILD_LIBNAME}
+	LIBRARY_OUTPUT_NAME ${LUA_BUILD_LIBNAME}
+	ARCHIVE_OUTPUT_NAME ${LUA_BUILD_LIBNAME})
+target_include_directories(${liblua}
+	PUBLIC ${LUA_VANILLA_SOURCE_DIR})
+target_compile_definitions(${liblua}
+	PUBLIC LUA_COMPAT_ALL ${LUA_VANILLA_DLL_DEFINE})
+if (MSVC)
+	target_compile_options(${liblua}
+		PRIVATE /W1)
+else()
+	target_compile_options(${liblua}
+		PRIVATE -w)
+endif()
+if (WIN32)
+	#target_compile_definitions(${liblua}
+	#	PRIVATE LUA_USE_WINDOWS)
+else()
+	target_compile_definitions(${liblua} 
+		PRIVATE LUA_USE_LINUX)
+endif()
+target_compile_options(${liblua}
+	PRIVATE ${LUA_VANILLA_LUALIB_COMPILER_OPTIONS})
+add_dependencies(${liblua} LUA_VANILLA)
+if (CMAKE_DL_LIBS)
+	target_link_libraries(${liblua} ${CMAKE_DL_LIBS})
+endif()
+if (UNIX)
+	target_link_libraries(${liblua} m)
+endif()
+
+# we don't really need this section...
+# Lua Interpreter
+add_executable(${luainterpreter} ${LUA_VANILLA_LUA_SOURCES})
+set_target_properties(${luainterpreter}
+	PROPERTIES
+	LANGUAGE C
+	LINKER_LANGUAGE C
+	C_STANDARD 99
+	C_EXTENSIONS TRUE
+	OUTPUT_NAME lua-${LUA_VANILLA_VERSION})
+target_include_directories(${luainterpreter}
+	PRIVATE ${LUA_VANILLA_SOURCE_DIR})
+target_compile_definitions(${luainterpreter}
+	PUBLIC LUA_COMPAT_ALL ${LUA_VANILLA_DLL_DEFINE}
+	PRIVATE LUA_COMPAT_ALL ${LUA_VANILLA_DLL_DEFINE})
+if (MSVC)
+	target_compile_options(${luainterpreter}
+		PRIVATE /W1)
+else()
+	target_compile_options(${luainterpreter}
+		PRIVATE -w)
+endif()
+if (WIN32)
+	#target_compile_definitions(${luainterpreter} 
+	#	PRIVATE LUA_USE_WINDOWS)
+else()
+	target_compile_definitions(${luainterpreter} 
+		PRIVATE LUA_USE_LINUX)
+endif()
+target_compile_options(${luainterpreter}
+	PRIVATE ${LUA_VANILLA_LUA_LUAC_COMPILER_OPTIONS})
+target_link_libraries(${luainterpreter} ${liblua})
+if (CMAKE_DL_LIBS)
+	target_link_libraries(${luainterpreter} ${CMAKE_DL_LIBS})
+endif()
+if (UNIX)
+	target_link_libraries(${luainterpreter} m readline)
+endif()
+
+# LuaC Compiler
+add_executable(${luacompiler} ${LUA_VANILLA_LUAC_SOURCES})
+if (BUILD_LUA_AS_DLL)
+	# TODO: figure out how to make DLL internal symbols for lua public so we don't have to do this
+	target_sources(${luacompiler} PRIVATE ${LUA_VANILLA_LIB_SOURCES})
+endif()
+set_target_properties(${luacompiler}
+	PROPERTIES
+	LANGUAGE C
+	LINKER_LANGUAGE C
+	C_STANDARD 99
+	C_EXTENSIONS TRUE
+	OUTPUT_NAME luac-${LUA_VANILLA_VERSION})
+target_include_directories(${luacompiler}
+	PRIVATE ${LUA_VANILLA_SOURCE_DIR})
+target_compile_options(${luacompiler}
+	PRIVATE ${LUA_VANILLA_LUA_LUAC_COMPILER_OPTIONS})
+target_compile_definitions(${luacompiler}
+	PUBLIC LUA_COMPAT_ALL ${LUA_VANILLA_DLL_DEFINE}
+	PRIVATE LUA_COMPAT_ALL ${LUA_VANILLA_DLL_DEFINE})
+if (MSVC)
+	target_compile_options(${luacompiler}
+		PRIVATE /W1)
+else()
+	target_compile_options(${luacompiler}
+		PRIVATE -w)
+endif()
+if (WIN32)
+	#target_compile_definitions(${luacompiler} 
+	#	PRIVATE LUA_USE_WINDOWS)
+else()
+	target_compile_definitions(${luacompiler} 
+		PRIVATE LUA_USE_LINUX)
+endif()
+target_link_libraries(${luacompiler} ${liblua})
+if (CMAKE_DL_LIBS)
+	target_link_libraries(${luacompiler} ${CMAKE_DL_LIBS})
+endif()
+if (UNIX)
+	# TODO: make readline optional?
+	target_link_libraries(${luacompiler} m readline)
+endif()
+
+# set externally-visible target indicator
+set(LUA_LIBRARIES ${liblua})
+set(LUA_INTERPRETER ${luainterpreter})
+set(LUA_COMPILER ${luacompiler})
+set(LUA_INCLUDE_DIRS "${LUA_VANILLA_SOURCE_DIR}")

third_party/sol2/cmake/Modules/FindLuaJIT.cmake

@@ -0,0 +1,173 @@
+# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+# file Copyright.txt or https://cmake.org/licensing for details.
+
+#.rst:
+# FindLuaJIT
+# -------
+#
+#
+#
+# Locate LuaJIT library. This module defines
+#
+# ::
+#
+#   LUAJIT_FOUND                - if false, do not try to link to LuaJIT
+#   LUAJIT_LIBRARIES            - both lua and lualib
+#   LUAJIT_INCLUDE_DIR          - where to find lua.h and luajit.h
+#   LUAJIT_VERSION_STRING       - the version of LuaJIT found
+#   LUAJIT_VERSION_MAJOR        - the major version of LuaJIT
+#   LUAJIT_VERSION_MINOR        - the minor version of LuaJIT
+#   LUAJIT_VERSION_PATCH        - the patch version of LuaJIT
+#   LUAJIT_LUA_VERSION_STRING   - the version of Lua the found LuaJIT is compatible with
+#
+#
+#
+# Note that the expected include convention is
+#
+# ::
+#
+#   #include "lua.h"
+#
+# and not
+#
+# ::
+#
+#   #include <lua/lua.h>
+#
+# This is because, the lua location is not standardized and may exist in
+# locations other than lua/
+
+unset(_luajit_include_subdirs)
+unset(_luajit_append_versions)
+unset(_luajit_library_names)
+
+include(${CMAKE_CURRENT_LIST_DIR}/FindLua/set_version_vars.cmake)
+include(${CMAKE_CURRENT_LIST_DIR}/FindLua/version_check.cmake)
+
+_lua_set_version_vars(luajit "jit")
+
+find_path(LUAJIT_INCLUDE_DIR luajit.h
+  HINTS
+    ENV LUAJIT_DIR
+  PATH_SUFFIXES ${_luajit_include_subdirs} include/luajit include
+  PATHS
+    ${LUAJIT_DIR}
+    ~/Library/Frameworks
+    /Library/Frameworks
+    /sw # Fink
+    /opt/local # DarwinPorts
+    /opt/csw # Blastwave
+    /opt
+    /usr
+    /usr/local # Homebrew
+)
+
+if (LUAJIT_INCLUDE_DIR AND EXISTS "${LUAJIT_INCLUDE_DIR}/lua.h")
+    _lua_check_header_version("${LUAJIT_INCLUDE_DIR}/lua.h" "LUAJIT")
+endif ()
+
+if (NOT LUAJIT_VERSION_STRING)
+    foreach (subdir IN LISTS _luajit_include_subdirs)
+        unset(LUAJIT_INCLUDE_PREFIX CACHE)
+        find_path(LUAJIT_INCLUDE_PREFIX ${subdir}/lua.h
+          HINTS
+            ENV LUA_DIR
+          PATHS
+            ${LUA_DIR}
+            ~/Library/Frameworks
+            /Library/Frameworks
+            /sw # Fink
+            /opt/local # DarwinPorts
+            /opt/csw # Blastwave
+            /opt
+            /usr
+            /usr/local # Homebrew
+        )
+        if (LUAJIT_INCLUDE_PREFIX)
+            _lua_check_header_version("${LUAJIT_INCLUDE_PREFIX}/${subdir}/lua.h" "LUAJIT")
+            if (LUAJIT_VERSION_STRING)
+                set(LUAJIT_INCLUDE_DIR "${LUAJIT_INCLUDE_PREFIX}/${subdir}")
+                break()
+            endif ()
+        endif ()
+    endforeach ()
+endif ()
+unset(_luajit_include_subdirs)
+unset(_luajit_append_versions)
+
+if (LUAJIT_INCLUDE_DIR AND EXISTS "${LUAJIT_INCLUDE_DIR}/luajit.h")
+    # LuaJIT defines two preprocessor macros:
+    #   LUA_VERSION     -> version string with lua version in it
+    #   LUA_VERSION_NUM -> numeric representation, i.e. 20003 for 2.0.3
+    # This just parses the LUAJIT_VERSION macro and extracts the version.
+    file(STRINGS "${LUAJIT_INCLUDE_DIR}/luajit.h" version_strings
+         REGEX "^#define[ \t]+LUAJIT_VERSION?[ \t]+(\"LuaJIT [0-9\\.]+(-(beta|alpha)[0-9]*)?\").*")
+
+    string(REGEX REPLACE ".*;#define[ \t]+LUAJIT_VERSION[ \t]+\"LuaJIT ([0-9\\.]+(-(beta|alpha)[0-9]*)?)\"[ \t]*;.*" "\\1" LUAJIT_VERSION_STRING_SHORT ";${version_strings};")
+    string(REGEX REPLACE ".*;([0-9]+\\.[0-9]+\\.[0-9]+(-(beta|alpha)[0-9]*)?);.*" "\\1" luajit_version_num ";${LUAJIT_VERSION_STRING_SHORT};")
+
+    string(REGEX REPLACE "^([0-9]+)\\.[0-9]+\\.(-(beta|alpha)[0-9]*)?$" "\\1" LUAJIT_VERSION_MAJOR "${luajit_version_num}")
+    string(REGEX REPLACE "^[0-9]+\\.([0-9]+)\\.[0-9](-(beta|alpha)[0-9]*)?$" "\\1" LUAJIT_VERSION_MINOR "${luajit_version_num}")
+    string(REGEX REPLACE "^[0-9]+\\.[0-9]+\\.([0-9]+(-(beta|alpha)[0-9]*)?)$" "\\1" LUAJIT_VERSION_PATCH "${luajit_version_num}")
+
+    # We can also set the LUAJIT_LUA_VERSION_* fields that are found by FindLua.
+    # We do this as LuaJIT claims full compatibility with a certain LUA version.
+    _lua_check_header_version("${LUAJIT_INCLUDE_DIR}/lua.h" "LUAJIT_LUA_")
+
+    set(LUAJIT_VERSION_STRING "${LUAJIT_LUA_VERSION_STRING} (${LUAJIT_VERSION_STRING_SHORT})")
+endif()
+
+find_library(LUAJIT_LIBRARY
+  NAMES ${_luajit_library_names} luajit lua
+  HINTS
+    ENV LUAJIT_DIR
+  PATH_SUFFIXES lib
+  PATHS
+    ${LUAJIT_DIR}
+    ~/Library/Frameworks
+    /Library/Frameworks
+    /sw
+    /opt/local
+    /opt/csw
+    /opt
+    /usr
+    /usr/local # Homebrew
+)
+unset(_luajit_library_names)
+
+if (LUAJIT_LIBRARY)
+    # include the math library for Unix
+    if (UNIX AND NOT APPLE AND NOT BEOS)
+        find_library(LUAJIT_MATH_LIBRARY m)
+        set(LUAJIT_LIBRARIES "${LUAJIT_LIBRARY};${LUAJIT_MATH_LIBRARY}")
+    # For Windows and Mac, don't need to explicitly include the math library
+    else ()
+        set(LUAJIT_LIBRARIES "${LUAJIT_LIBRARY}")
+    endif ()
+
+    set(LUAJIT_LIBRARY_DIR )
+    foreach (lib ${LUAJIT_LIBRARIES})
+        get_filename_component(lib_dir ${lib} DIRECTORY CACHE)
+        list(APPEND LUAJIT_LIBRARY_DIR ${lib_dir})
+    endforeach ()
+    list(REMOVE_DUPLICATES LUAJIT_LIBRARY_DIR)
+endif ()
+
+if(APPLE)
+    # Not sure why this is true, but its mentioned here:
+    # http://luajit.org/install.html#embed
+    set(LUAJIT_LINK_FLAGS "-pagezero_size 10000 -image_base 100000000")
+else()
+    set(LUAJIT_LINK_FLAGS "")
+endif()
+
+include(FindPackageHandleStandardArgs)
+# handle the QUIETLY and REQUIRED arguments and set LuaJIT_FOUND to TRUE if
+# all listed variables are TRUE
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(LuaJIT
+                                  FOUND_VAR LuaJIT_FOUND
+                                  REQUIRED_VARS LUAJIT_LIBRARIES LUAJIT_INCLUDE_DIR LUAJIT_LIBRARY_DIR
+                                  VERSION_VAR LUAJIT_VERSION_STRING)
+
+mark_as_advanced(LUAJIT_INCLUDE_DIR LUAJIT_LIBRARY LUAJIT_LIBRARY_DIR LUAJIT_MATH_LIBRARY LUAJIT_LINK_FLAGS)
+

third_party/sol2/cmake/Modules/FindLuwraBuild.cmake

@@ -0,0 +1,75 @@
+# # # # sol2
+# The MIT License (MIT)
+#
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+include(ExternalProject)
+include(FindPackageHandleStandardArgs)
+include(Common/Core)
+
+# # Base variables
+set(luwra_version 0.5.0)
+set(luwra_lib luwra_lib_${luwra_version})
+
+# # Useful locations
+set(luwra_build_toplevel "${CMAKE_BINARY_DIR}/vendor/luwra_${luwra_version}")
+set(luwra_include_dirs "${luwra_build_toplevel}/lib")
+
+# # luwra library sources
+set(luwra_sources luwra.hpp)
+prepend(luwra_sources "${luwra_build_toplevel}/lib/" ${luwra_sources})
+
+# # External project to get sources
+ExternalProject_Add(LUWRA_BUILD_SOURCE
+	BUILD_IN_SOURCE TRUE
+	BUILD_ALWAYS FALSE
+	# # Use Git to get what we need
+	GIT_SHALLOW TRUE
+	#GIT_TAG e513907fc8c2d59ebd91cd5992eddf54f7e23e21
+	GIT_REPOSITORY https://github.com/vapourismo/luwra.git
+	PREFIX ${luwra_build_toplevel}
+	SOURCE_DIR ${luwra_build_toplevel}
+	DOWNLOAD_DIR ${luwra_build_toplevel}
+	TMP_DIR "${luwra_build_toplevel}-tmp"
+	STAMP_DIR "${luwra_build_toplevel}-stamp"
+	INSTALL_DIR "${luwra_build_toplevel}/local"
+	CONFIGURE_COMMAND ""
+	BUILD_COMMAND ""
+	INSTALL_COMMAND ""
+	TEST_COMMAND ""
+	BUILD_BYPRODUCTS "${luwra_sources}")
+
+add_library(${luwra_lib} INTERFACE)
+add_dependencies(${luwra_lib} LUWRA_BUILD_SOURCE)
+target_include_directories(${luwra_lib} INTERFACE ${luwra_include_dirs})
+target_link_libraries(${luwra_lib} INTERFACE ${LUA_LIBRARIES})
+if (NOT MSVC)
+	target_compile_options(${luwra_lib} INTERFACE
+		-Wno-noexcept-type -Wno-ignored-qualifiers -Wno-unused-parameter)
+endif()
+
+set(LUWRABUILD_FOUND TRUE)
+set(LUWRA_LIBRARIES ${luwra_lib})
+set(LUWRA_INCLUDE_DIRS ${luwra_include_dirs})
+
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(LuwraBuild
+	FOUND_VAR LUWRABUILD_FOUND
+	REQUIRED_VARS LUWRA_LIBRARIES LUWRA_INCLUDE_DIRS
+	VERSION_VAR luwra_version)

third_party/sol2/cmake/Modules/FindToLuappBuild.cmake

@@ -0,0 +1,95 @@
+# # # # sol2
+# The MIT License (MIT)
+#
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+# # Standard CMake Libraries
+include(ExternalProject)
+include(FindPackageHandleStandardArgs)
+include(Common/Core)
+
+# # Base variables
+set(toluapp_version 1.0.93)
+
+# # Useful locations
+set(toluapp_build_toplevel "${CMAKE_BINARY_DIR}/vendor/toluapp_${toluapp_version}")
+set(toluapp_include_dirs "${toluapp_build_toplevel}/include")
+
+# # ToLua library sources
+set(toluapp_sources tolua_event.c tolua_event.h tolua_is.c tolua_map.c tolua_push.c tolua_to.c tolua_compat.h tolua_compat.c)
+prepend(toluapp_sources "${toluapp_build_toplevel}/src/lib/" ${toluapp_sources})
+list(APPEND toluapp_sources "${toluapp_build_toplevel}/include/tolua++.h")
+
+# # External project to get sources
+ExternalProject_Add(TOLUAPP_BUILD_SOURCE
+	BUILD_IN_SOURCE TRUE
+	BUILD_ALWAYS FALSE
+	# # Use Git to get what we need
+	#GIT_SUBMODULES ""
+	GIT_SHALLOW TRUE
+	GIT_REPOSITORY https://github.com/ThePhD/toluapp
+	PREFIX ${toluapp_build_toplevel}
+	SOURCE_DIR ${toluapp_build_toplevel}
+	DOWNLOAD_DIR ${toluapp_build_toplevel}
+	TMP_DIR "${toluapp_build_toplevel}-tmp"
+	STAMP_DIR "${toluapp_build_toplevel}-stamp"
+	INSTALL_DIR "${toluapp_build_toplevel}/local"
+	CONFIGURE_COMMAND ""
+	BUILD_COMMAND ""
+	INSTALL_COMMAND ""
+	TEST_COMMAND ""
+	BUILD_BYPRODUCTS "${toluapp_sources}")
+
+set(toluapp_lib toluapp_lib_5.2.4)
+add_library(${toluapp_lib} SHARED ${toluapp_sources})
+add_dependencies(${toluapp_lib} TOLUAPP_BUILD_SOURCE)
+set_target_properties(${toluapp_lib} PROPERTIES
+	OUTPUT_NAME toluapp-${toluapp_version}
+	POSITION_INDEPENDENT_CODE TRUE)
+target_include_directories(${toluapp_lib}
+	PUBLIC ${toluapp_include_dirs})
+target_link_libraries(${toluapp_lib} PRIVATE ${LUA_LIBRARIES})
+if (MSVC)
+	target_compile_options(${toluapp_lib}
+		PRIVATE /W1)
+	target_compile_definitions(${toluapp_lib}
+		PRIVATE TOLUA_API=__declspec(dllexport))
+else()
+	target_compile_options(${toluapp_lib}
+		PRIVATE -w
+		INTERFACE -Wno-noexcept-type
+		PUBLIC -Wno-ignored-qualifiers -Wno-unused-parameter)
+endif()
+if (CMAKE_DL_LIBS)
+	target_link_libraries(${toluapp_lib} PRIVATE ${CMAKE_DL_LIBS})
+endif()
+# add compatibility define
+target_compile_definitions(${toluapp_lib}
+		PRIVATE COMPAT53_PREFIX=toluapp_compat53)
+
+# # Variables required by ToLuaBuild
+set(TOLUAPP_LIBRARIES ${toluapp_lib})
+set(TOLUAPP_INCLUDE_DIRS ${toluapp_include_dirs})
+set(TOLUAPPBUILD_FOUND TRUE)
+
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(ToLuappBuild
+	FOUND_VAR TOLUAPPBUILD_FOUND
+	REQUIRED_VARS TOLUAPP_LIBRARIES TOLUAPP_INCLUDE_DIRS
+	VERSION_VAR toluapp_version)

third_party/sol2/cmake/sol2-config.cmake.in

@@ -0,0 +1,41 @@
+# # # # sol2
+# The MIT License (MIT)
+# 
+# Copyright (c) 2013-2018 Rapptz, ThePhD, and contributors
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# 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.
+
+@PACKAGE_INIT@
+
+include("${CMAKE_CURRENT_LIST_DIR}/sol2-targets.cmake")
+
+MESSAGE(STATUS ${CMAKE_CURRENT_LIST_DIR})
+
+if (TARGET sol2)
+    get_target_property(SOL2_INCLUDE_DIRS
+        sol2 INTERFACE_INCLUDE_DIRECTORIES)
+    set_and_check(SOL2_INCLUDE_DIRS "${SOL2_INCLUDE_DIRS}")
+    set(SOL2_LIBRARIES sol2)
+endif()
+
+if(TARGET sol2_single)
+    get_target_property(SOL2_SINGLE_INCLUDE_DIRS
+        sol2_single INTERFACE_INCLUDE_DIRECTORIES)
+    set_and_check(SOL2_INCLUDE_DIRS "${SOL2_SINGLE_INCLUDE_DIRS}")
+    set(SOL2_LIBRARIES_SINGLE sol2_single)
+endif()

third_party/sol2/docs/Makefile

@@ -0,0 +1,216 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)/*
+
+.PHONY: html
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: dirhtml
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: pickle
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+.PHONY: json
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+.PHONY: htmlhelp
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+.PHONY: qthelp
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/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 "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Sol.qhc"
+
+.PHONY: applehelp
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+.PHONY: devhelp
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/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 "# devhelp"
+
+.PHONY: epub
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+.PHONY: latex
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+.PHONY: latexpdf
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: latexpdfja
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: text
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+.PHONY: man
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+.PHONY: texinfo
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+.PHONY: info
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+.PHONY: gettext
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+.PHONY: changes
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+.PHONY: linkcheck
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+.PHONY: doctest
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: coverage
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+.PHONY: xml
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+.PHONY: pseudoxml
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

third_party/sol2/docs/make.bat

@@ -0,0 +1,263 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
+set I18NSPHINXOPTS=%SPHINXOPTS% source
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  xml        to make Docutils-native XML files
+	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	echo.  coverage   to run coverage check of the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+
+REM Check if sphinx-build is available and fallback to Python version if any
+%SPHINXBUILD% 1>NUL 2>NUL
+if errorlevel 9009 goto sphinx_python
+goto sphinx_ok
+
+:sphinx_python
+
+set SPHINXBUILD=python -m sphinx.__init__
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+:sphinx_ok
+
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	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.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Sol.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdf" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdfja" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf-ja
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+if "%1" == "coverage" (
+	%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of coverage in the sources finished, look at the ^
+results in %BUILDDIR%/coverage/python.txt.
+	goto end
+)
+
+if "%1" == "xml" (
+	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The XML files are in %BUILDDIR%/xml.
+	goto end
+)
+
+if "%1" == "pseudoxml" (
+	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+	goto end
+)
+
+:end

third_party/sol2/docs/source/_themes/sol2/layout.html

@@ -0,0 +1,16 @@
+{%- extends "haiku/layout.html" %}
+
+{% set script_files = script_files + ["_static/search-fix.js"] %}
+
+{% block haikuheader %} 
+	<div class="header-left">
+		{{ super() }}
+	</div>
+	<div class="header-right">
+		<h3>Search the Documentation</h3>
+		<form action="{{ pathto('search') }}" method="get">
+			<input type="text" name="q" value="">
+			<input type="submit" value="search">
+		</form>
+	</div>
+{% endblock %}

third_party/sol2/docs/source/_themes/sol2/static/search-fix.js_t

@@ -0,0 +1,152 @@
+if (typeof window.SphinxRtdTheme !== 'undefined') {
+  Search.query = function(query) {
+    var i;
+    var stopwords = {{ search_language_stop_words }};
+
+    // stem the searchterms and add them to the correct list
+    var stemmer = new Stemmer();
+    var searchterms = [];
+    var excluded = [];
+    var hlterms = [];
+    var tmp = query.split(/\s+/);
+    var objectterms = [];
+    for (i = 0; i < tmp.length; i++) {
+      if (tmp[i] !== "") {
+          objectterms.push(tmp[i].toLowerCase());
+      }
+
+      if ($u.indexOf(stopwords, tmp[i].toLowerCase()) != -1 || tmp[i].match(/^\d+$/) ||
+          tmp[i] === "") {
+        // skip this "word"
+        continue;
+      }
+      // stem the word
+      var word = stemmer.stemWord(tmp[i].toLowerCase());
+      var toAppend;
+      // select the correct list
+      if (word[0] == '-') {
+        toAppend = excluded;
+        word = word.substr(1);
+      }
+      else {
+        toAppend = searchterms;
+        hlterms.push(tmp[i].toLowerCase());
+      }
+      // only add if not already in the list
+      if (!$u.contains(toAppend, word))
+        toAppend.push(word);
+    }
+    var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" "));
+
+    // prepare search
+    var terms = this._index.terms;
+    var titleterms = this._index.titleterms;
+
+    // array of [filename, title, anchor, descr, score]
+    var results = [];
+    $('#search-progress').empty();
+
+    // lookup as object
+    for (i = 0; i < objectterms.length; i++) {
+      var others = [].concat(objectterms.slice(0, i),
+                             objectterms.slice(i+1, objectterms.length));
+      results = results.concat(this.performObjectSearch(objectterms[i], others));
+    }
+
+    // lookup as search terms in fulltext
+    results = results.concat(this.performTermsSearch(searchterms, excluded, terms, Scorer.term))
+                     .concat(this.performTermsSearch(searchterms, excluded, titleterms, Scorer.title));
+
+    // let the scorer override scores with a custom scoring function
+    if (Scorer.score) {
+      for (i = 0; i < results.length; i++)
+        results[i][4] = Scorer.score(results[i]);
+    }
+
+    // now sort the results by score (in opposite order of appearance, since the
+    // display function below uses pop() to retrieve items) and then
+    // alphabetically
+    results.sort(function(a, b) {
+      var left = a[4];
+      var right = b[4];
+      if (left > right) {
+        return 1;
+      } else if (left < right) {
+        return -1;
+      } else {
+        // same score: sort alphabetically
+        left = a[1].toLowerCase();
+        right = b[1].toLowerCase();
+        return (left > right) ? -1 : ((left < right) ? 1 : 0);
+      }
+    });
+
+    // for debugging
+    //Search.lastresults = results.slice();  // a copy
+    //console.info('search results:', Search.lastresults);
+
+    // print the results
+    var resultCount = results.length;
+    function displayNextItem() {
+      // results left, load the summary and display it
+      if (results.length) {
+        var item = results.pop();
+        var listItem = $('<li style="display:none"></li>');
+        if (DOCUMENTATION_OPTIONS.FILE_SUFFIX === '') {
+          // dirhtml builder
+          var dirname = item[0].replace(/\.rst$/, '') + '/';
+          if (dirname.match(/\/index\/$/)) {
+            dirname = dirname.substring(0, dirname.length-6);
+          } else if (dirname == 'index/') {
+            dirname = '';
+          }
+          listItem.append($('<a/>').attr('href',
+            DOCUMENTATION_OPTIONS.URL_ROOT + dirname +
+            highlightstring + item[2]).html(item[1]));
+        } else {
+          // normal html builders
+          listItem.append($('<a/>').attr('href',
+            item[0].replace(/\.rst$/, '') + DOCUMENTATION_OPTIONS.FILE_SUFFIX +
+            highlightstring + item[2]).html(item[1]));
+        }
+        if (item[3]) {
+          listItem.append($('<span> (' + item[3] + ')</span>'));
+          Search.output.append(listItem);
+          listItem.slideDown(5, function() {
+            displayNextItem();
+          });
+        } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) {
+          $.ajax({url: DOCUMENTATION_OPTIONS.URL_ROOT + '_sources/' + item[0] + '.txt',
+                  dataType: "text",
+                  complete: function(jqxhr, textstatus) {
+                    var data = jqxhr.responseText;
+                    if (data !== '' && data !== undefined) {
+                      listItem.append(Search.makeSearchSummary(data, searchterms, hlterms));
+                    }
+                    Search.output.append(listItem);
+                    listItem.slideDown(5, function() {
+                      displayNextItem();
+                    });
+                  }});
+        } else {
+          // no source available, just display title
+          Search.output.append(listItem);
+          listItem.slideDown(5, function() {
+            displayNextItem();
+          });
+        }
+      }
+      // search finished, update title and status message
+      else {
+        Search.stopPulse();
+        Search.title.text(_('Search Results'));
+        if (!resultCount)
+          Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.'));
+        else
+            Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount));
+        Search.status.fadeIn(500);
+      }
+    }
+    displayNextItem();
+  };
+}

third_party/sol2/docs/source/_themes/sol2/static/sol2.css_t

@@ -0,0 +1,18 @@
+@import url('haiku.css');
+
+.header-left {
+	float: left;
+	display: inline-block;
+	vertical-align: top;
+}
+
+.header-right {
+	float: right;
+	display: inline-block;
+	vertical-align: top;
+}
+
+.header-right h3 {
+	margin: 0;
+    padding-top: 15px;
+}

third_party/sol2/docs/source/_themes/sol2/theme.conf

@@ -0,0 +1,4 @@
+[theme]
+inherit = haiku
+stylesheet = sol2.css
+pygments_style = autumn

third_party/sol2/docs/source/api/api-top.rst

@@ -0,0 +1,55 @@
+api reference manual
+====================
+
+Browse the various function and classes :doc:`Sol<../index>` utilizes to make your life easier when working with Lua.
+
+
+.. toctree::
+   :caption: Sol API
+   :name: apitoc
+   :maxdepth: 2
+
+   state
+   this_state
+   reference
+   stack_reference
+   make_reference
+   table
+   userdata
+   environment
+   this_environment
+   proxy
+   as_container
+   nested
+   as_table
+   usertype
+   usertype_memory
+   unique_usertype_traits
+   tie
+   function
+   protected_function
+   coroutine
+   yielding
+   error
+   object
+   thread
+   optional
+   variadic_args
+   variadic_results
+   as_args
+   as_returns
+   overload
+   property
+   var
+   protect
+   filters
+   readonly
+   as_function
+   c_call
+   resolve
+   stack
+   user
+   compatibility
+   types
+   metatable_key
+   new_table

third_party/sol2/docs/source/api/as_args.rst

@@ -0,0 +1,24 @@
+as_args
+=======
+*turn an iterable argument into multiple arguments*
+
+
+.. code-block:: cpp
+	
+	template <typename T>
+	struct as_args_t { ... };
+
+	template <typename T>
+	as_args_t<T> as_args( T&& );
+
+
+``sol::as_args`` is a function that that takes an iterable and turns it into multiple arguments to a function call. It forwards its arguments, and is meant to be used as shown below:
+
+
+.. literalinclude:: ../../../examples/args_from_container.cpp
+	: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>`.
+
+.. _one-way customization point: https://github.com/ThePhD/sol2/blob/develop/sol/as_args.hpp

third_party/sol2/docs/source/api/as_container.rst

@@ -0,0 +1,23 @@
+as_container
+============
+*force a type to be viewed as a container-type when serialized to Lua*
+
+.. code-block:: cpp
+	
+	template <typename T>
+	struct as_returns_t { ... };
+
+	template <typename T>
+	as_returns_t<T> as_returns( T&& );
+
+
+Sometimes, you have a type whose metatable you claim with a usertype metatable via :doc:`usertype semantics<usertype>`. But, it still has parts of it that make it behave like a container in C++: A ``value_type`` typedef, an ``iterator`` typedef, a ``begin``, an ``end``, and other things that satisfy the `Container requirements`_ or the `Sequence Container requirements`_ or behaves like a `forward_list`_.
+
+Whatever the case is, you need it to be returned to Lua and have many of the traits and functionality described in the :doc:`containers documentation<../containers>`. Wrap a return type or a setter in ``sol::as_container( value );`` to allow for a type to be treated like a container, regardless of whether ``sol::is_container`` triggers or not.
+
+See `this container example`_ to see how it works.
+
+.. _this container example: https://github.com/ThePhD/sol2/blob/develop/examples/container_usertype_as_container.cpp
+.. _Container requirements: http://en.cppreference.com/w/cpp/concept/Container
+.. _Sequence Container requirements: http://en.cppreference.com/w/cpp/concept/SequenceContainer
+.. _forward_list: http://en.cppreference.com/w/cpp/container/forward_list

third_party/sol2/docs/source/api/as_function.rst

@@ -0,0 +1,24 @@
+as_function
+===========
+*make sure an object is pushed as a function*
+
+
+.. code-block:: cpp
+	
+	template <typename Sig = sol::function_sig<>, typename... Args>
+	function_argumants<Sig, Args...> as_function ( Args&& ... );
+
+This function serves the purpose of ensuring that a callable struct (like a lambda) can be passed to the ``set( key, value )`` calls on :ref:`sol::table<set-value>` and be treated like a function binding instead of a userdata. It is recommended that one uses the :ref:`sol::table::set_function<set-function>` call instead, but if for some reason one must use ``set``, then ``as_function`` can help ensure a callable struct is handled like a lambda / callable, and not as just a userdata structure.
+
+This class can also make it so usertypes bind variable types as functions to for usertype bindings.
+
+.. literalinclude:: ../../../examples/docs/as_function.cpp
+	:linenos:
+
+
+Note that if you actually want a userdata, but you want it to be callable, you simply need to create a :ref:`sol::table::new_usertype<new-usertype>` and then bind the ``"__call"`` metamethod (or just use ``sol::meta_function::call`` :ref:`enumeration<meta_function_enum>`). This may or may not be done automatically for you, depending on whether or not the call operator is overloaded and such.
+
+Here's an example of binding a variable as a function to a usertype:
+
+.. literalinclude:: ../../../examples/docs/as_function_usertype_member_variable.cpp
+	:linenos:

third_party/sol2/docs/source/api/as_returns.rst

@@ -0,0 +1,19 @@
+as_returns
+==========
+*turn an iterable argument into a multiple-return type*
+
+
+.. code-block:: cpp
+	
+	template <typename T>
+	struct as_returns_t { ... };
+
+	template <typename T>
+	as_returns_t<T> as_returns( T&& );
+
+
+This allows you to wrap up a source that has ``begin`` and ``end`` iterator-returning functions on it and return it as multiple results into Lua. To have more control over the returns, use :doc:`sol::variadic_results<variadic_results>`.
+
+
+.. literalinclude:: ../../../examples/as_returns.cpp
+	:linenos:

third_party/sol2/docs/source/api/as_table.rst

@@ -0,0 +1,27 @@
+as_table
+===========
+*make sure an object is pushed as a table*
+
+
+.. code-block:: cpp
+	
+	template <typename T>
+	as_table_t { ... };
+
+	template <typename T>
+	as_table_t<T> as_function ( T&& container );
+
+This function serves the purpose of ensuring that an object is pushed -- if possible -- like a table into Lua. The container passed here can be a pointer, a reference, a ``std::reference_wrapper`` around a container, or just a plain container value. It must have a begin/end function, and if it has a ``std::pair<Key, Value>`` as its ``value_type``, it will be pushed as a dictionary. Otherwise, it's pushed as a sequence.
+
+.. literalinclude:: ../../../examples/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.*
+
+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`_.
+
+.. _this example: https://github.com/ThePhD/sol2/blob/develop/examples/containers_as_table.cpp

third_party/sol2/docs/source/api/c_call.rst

@@ -0,0 +1,29 @@
+c_call
+======
+*templated type to transport functions through templates*
+
+
+.. code-block:: cpp
+	
+	template <typename Function, Function f>
+	int c_call (lua_State* L);
+
+	template <typename... Functions>
+	int c_call (lua_State* L);
+
+The goal of ``sol::c_call<...>`` is to provide a way to wrap a function and transport it through a compile-time context. This enables faster speed at the cost of a much harder to read / poorer interface, and can alleviate some template compilation speed issues. ``sol::c_call`` expects a type for its first template argument, and a value of the previously provided type for the second template argument. To make a compile-time transported overloaded function, specify multiple functions in the same ``type, value`` pairing, but put it inside of a ``sol::wrap``.
+
+.. note::
+
+	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 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`_.
+
+Here's an example below of various ways to use ``sol::c_call``:
+
+.. literalinclude:: ../../../examples/c_call.cpp
+	:linenos:
+
+.. _one similar to this: http://stackoverflow.com/a/5628222/5280922

third_party/sol2/docs/source/api/compatibility.rst

@@ -0,0 +1,16 @@
+compatibility.hpp
+=================
+*Lua 5.3/5.2 compatibility for Lua 5.1/LuaJIT*
+
+
+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`_.
+
+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.
+
+For the licenses, see :doc:`here<../licenses>`
+
+.. _issue in the issue tracker: https://github.com/ThePhD/sol2/issues/
+.. _Lua code: http://www.Lua.org/
+.. _lua-compat: https://github.com/keplerproject/lua-compat-5.3

third_party/sol2/docs/source/api/coroutine.rst

@@ -0,0 +1,109 @@
+coroutine
+=========
+*resumable/yielding functions from Lua*
+
+
+A ``coroutine`` is a :doc:`reference<reference>` to a function in Lua that can be called multiple times to yield a specific result. It is run on the :doc:`lua_State<state>` that was used to create it (see :doc:`thread<thread>` for an example on how to get a coroutine that runs on a thread separate from your usual "main" :doc:`lua_State<state>`).
+
+The ``coroutine`` object is entirely similar to the :doc:`protected_function<protected_function>` object, with additional member functions to check if a coroutine has yielded (:doc:`call_status::yielded<types>`) and is thus runnable again, whether it has completed (:ref:`call_status::ok<call-status>`) and thus cannot yield anymore values, or whether it has suffered an error (see :ref:`status()<status>` and :ref:`call_status<call-status>`'s error codes).
+
+For example, you can work with a coroutine like this:
+
+.. code-block:: lua
+    :caption: co.lua
+
+        function loop()
+            while counter ~= 30
+            do
+                coroutine.yield(counter);
+                counter = counter + 1;
+            end
+            return counter
+        end
+
+This is a function that yields:
+
+.. code-block:: cpp
+    :caption: main.cpp
+
+    sol::state lua;
+    lua.open_libraries(sol::lib::base, sol::lib::coroutine);
+    lua.script_file("co.lua");
+    sol::coroutine cr = lua["loop"];
+
+    for (int counter = 0; // start from 0 
+        counter < 10 && cr; // we want 10 values, and we only want to run if the coroutine "cr" is valid
+        // Alternative: counter < 10 && cr.valid()
+        ++counter) {
+            // Call the coroutine, does the computation and then suspends
+            int value = cr();
+    }
+
+Note that this code doesn't check for errors: to do so, you can call the function and assign it as ``auto result = cr();``, then check ``result.valid()`` as is the case with :doc:`protected_function<protected_function>`. Finally, you can  run this coroutine on another thread by doing the following:
+
+.. code-block:: cpp
+    :caption: main_with_thread.cpp
+
+    sol::state lua;
+    lua.open_libraries(sol::lib::base, sol::lib::coroutine);
+    lua.script_file("co.lua");
+    sol::thread runner = sol::thread::create(lua.lua_state());
+    sol::state_view runnerstate = runner.state();
+    sol::coroutine cr = runnerstate["loop"];
+
+    for (int counter = 0; counter < 10 && cr; ++counter) {
+        // Call the coroutine, does the computation and then suspends
+        int value = cr();
+    }
+
+The following are the members of ``sol::coroutine``:
+
+members
+-------
+
+.. code-block:: cpp
+    :caption: function: constructor
+
+    coroutine(lua_State* L, int index = -1);
+
+Grabs the coroutine at the specified index given a ``lua_State*``. 
+
+.. code-block:: cpp
+	:caption: returning the coroutine's status
+	:name: status
+
+	call_status status() const noexcept;
+
+Returns the status of a coroutine.
+
+
+.. code-block:: cpp
+	:caption: checks for an error
+
+	bool error() const noexcept;
+
+Checks if an error occured when the coroutine was run.
+
+.. _runnable:
+
+.. code-block:: cpp
+	:caption: runnable and explicit operator bool
+
+	bool runnable () const noexcept;
+	explicit operator bool() const noexcept;
+
+These functions allow you to check if a coroutine can still be called (has more values to yield and has not errored). If you have a coroutine object ``coroutine my_co = /*...*/``, you can either check ``runnable()`` or do ``if ( my_co ) { /* use coroutine */ }``.
+
+.. code-block:: cpp
+	:caption: calling a coroutine
+
+	template<typename... Args>
+	protected_function_result operator()( Args&&... args );
+
+	template<typename... Ret, typename... Args>
+	decltype(auto) call( Args&&... args );
+
+	template<typename... Ret, typename... Args>
+	decltype(auto) operator()( types<Ret...>, Args&&... args );
+
+Calls the coroutine. The second ``operator()`` lets you specify the templated return types using the ``my_co(sol::types<int, std::string>, ...)`` syntax. Check ``status()`` afterwards for more information about the success of the run or just check the coroutine object in an ifs tatement, as shown :ref:`above<runnable>`.

third_party/sol2/docs/source/api/environment.rst

@@ -0,0 +1,79 @@
+environment
+===========
+*encapsulation table for script sandboxing*
+
+
+.. code-block:: cpp
+	:caption: environment
+
+	class environment : public table;
+
+	template <typename T>
+	void set_environment( const environment& env, const T& target );
+	template <typename E = reference, typename T>
+	basic_environment<E> get_environment( const T& target );
+
+
+This type is passed to :ref:`sol::state(_view)::script/do_x<state-script-function>` to provide an environment where local variables that are set and get retrieve. It is just a plain table, and all the same operations :doc:`from table still apply<table>`. This is important because it allows you to do things like set the table's metatable (using :doc:`sol::metatable_key<metatable_key>` for instance) and having its ``__index`` entry point to the global table, meaning you can get -- but not set -- variables from a Global environment, for example.
+
+There are many more uses, including storing state or special dependent variables in an environment that you pre-create using regular table opertions, and then changing at-will:
+
+.. literalinclude:: ../../../examples/docs/preparing_environments.cpp
+	:linenos:
+
+Also note that ``sol::environment`` derives from ``sol::table``, which also derives from ``sol::reference``: in other words, copying one ``sol::environment`` value to another ``sol::environment`` value **does not** deep-copy the table, just creates a new reference pointing to the same lua object.
+
+``sol::environment`` objects can be used with `script calls`_, and it can also be `set on functions`_. It can even be applied to :doc:`threads<thread>`.
+
+You can set the environment using ``sol::set_environment( my_env, some_reference );`` or ``my_env.set_on( some_reference );``.
+
+free functions
+--------------
+
+.. code-block:: cpp
+	:caption: function: set_environment
+
+	template <typename T>
+	void set_environment( const environment& env, const T& target );
+
+See :ref:`environment::set_on<environment-set-on>`.
+
+
+.. code-block:: cpp
+	:caption: function: get_environment
+
+	template <typename E = reference, typename T>
+	basic_environment<E> get_environment( const T& target );
+
+This function retrieves the environment from the target object. If it does not have a valid environment, then the environment's valid function will return false after creation. Every function (regular Lua function, executable script, and similar) has an environment, as well as userdata in certain versions of the Lua runtime.
+
+
+members
+-------
+
+.. code-block:: cpp
+	:caption: constructor: environment
+
+	environment(lua_State* L, sol::new_table nt);
+	environment(lua_State* L, sol::new_table nt, const sol::reference& fallback);
+	environment(sol::env_t, const sol::reference& object_that_has_environment);
+	environment(sol::env_t, const sol::stack_reference& object_that_has_environment);
+
+The ones from table are used here (of particular note is the ability to use ``sol::environment(my_lua_state, sol::create);`` to make a fresh, unnamed environment), plus the three unique constructors shown above.
+
+The first constructor is generally used as ``sol::environment my_env(my_lua_state, sol::create, my_fallback_table);``. The fallback table serves as the backup to lookup attempts on the environment table being created. It is achieved by simply creating a metatable for the ``sol::environment`` being created, and then doing ``env_metatable["__index"] = fallback;``. You can achieve fancier effects by changing the metatable of the environment to your liking, by creating it in some fashion and then setting the metatable explicitly and populating it with data, particularly with :doc:`sol::metatable_key<metatable_key>`.
+
+The second and third unique constructors take a special empty type that serves as a key to trigger this constructor and serves no other purpose, ``sol::env_t``. The shortcut value so you don't have to create one is called ``sol::env_key``. It is used like ``sol::environment my_env(sol::env_key, some_object);``. It will extract the environment out of whatever the second argument is that may or may not have an environment. If it does not have an environment, the constructor will complete but the object will have ``env.valid() == false``, since it will reference Lua's ``nil``.
+
+
+.. code-block:: cpp
+	:caption: function: set_on
+	:name: environment-set-on
+	
+	template <typename T>
+	void set_on(const T& target);
+
+This function applies the environment to the desired target. Not that lua 5.1 only tolerates the application of environments to userdata, threads and functions, while 5.2+ has different (more relaxed) rules. It is called by the free function ``sol::set_environment( env, target );``.
+
+.. _script calls: https://github.com/ThePhD/sol2/blob/develop/examples/environments.cpp
+.. _set on functions: https://github.com/ThePhD/sol2/blob/develop/examples/environments_on_functions.cpp

third_party/sol2/docs/source/api/error.rst

@@ -0,0 +1,21 @@
+error
+=====
+*the single error/exception type*
+
+
+.. code-block:: cpp
+
+	class error : public std::runtime_error {
+	public:
+		error(const std::string& str): std::runtime_error("lua: error: " + str) {}
+	};
+
+
+.. note::
+
+	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>`.
+
+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.

third_party/sol2/docs/source/api/filters.rst

@@ -0,0 +1,35 @@
+filters
+=======
+*stack modification right before lua call returns*
+
+``sol::filters`` 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 filters are defined for your use:
+
++------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| filter                             | usage                                                                                              | modification                                                                                                                                                                |
++------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``sol::returns_self``              | ``sol::filters( some_function, sol::returns_self() )``                                             | - takes the argument at stack index 1 (``self`` in member function calls and lambdas that take a specific userdata first) and makes that to be the return value             |
+|                                    |                                                                                                    | - rather than creating a new userdata that references the same C++ memory, it copies the userdata, similar to writing ``obj2 = obj1`` just increases the reference count    |
+|                                    |                                                                                                    | - saves memory space on top of keeping original memory alive                                                                                                                |
++------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``sol::returns_self_with<int...>`` | ``sol::filters( some_function, sol::returns_self_with<2, 3>() )``                                  | - same as above, with the caveat that the ``self`` is returned while also putting dependencies into the ``self``                                                            |
+|                                    |                                                                                                    | - can keep external dependencies alive                                                                                                                                      |
++------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``sol::self_dependency``           | ``sol::filters( some_function, sol::self_dependency() );``                                         | - this makes the value returned by the bindable take a dependency on the ``self`` argument                                                                                  |
+|                                    |                                                                                                    | - useful for returning a reference to a member variable and keeping the parent class of that member variable alive                                                          |
++------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``sol::stack_dependencies``        | ``sol::filters( some_function, sol::stack_dependencies( target_index, 2, 1, ... ) );``             | - whatever is at ``target_index`` on the stack is given a special "keep alive" table with the elements on the stack specified by the integer indices after ``target_index`` |
+|                                    |                                                                                                    | - allows you to keep arguments and other things alive for the duration of the existence of the class                                                                        |
++------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| custom                             | ``sol::filters( some_function, [](lua_State* L, int current_stack_return_count) -> int { ... } )`` | - whatever you want, so long as it has the form ``int (lua_State*, int )``                                                                                                  |
+|                                    |                                                                                                    | - works with callables (such as lambdas), so long as it has the correct form                                                                                                |
+|                                    |                                                                                                    | - expected to return the number of things on the stack to return to Lua                                                                                                     |
++------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| - "some_function" can be any callable function, member variable, or similar                                                                                                                                                                                                                                           |
+| - dependency additions only work on userdata                                                                                                                                                                                                                                                                          |
+|                                                                                                                                                                                                                                                                                                                       |
+| - works with ``table::set( ... )``, ``table::set_function( ... );``, and on all usertype bindings                                                                                                                                                                                                                     |
++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+You can specify multiple filters on the same ``sol::filters`` call, and can also specify custom filters as long as the signature is correct.
+
+.. _luabind's "return reference to" and "dependency": http://www.rasterbar.com/products/luabind/docs.html#dependency

third_party/sol2/docs/source/api/function.rst

@@ -0,0 +1,67 @@
+function
+========
+*calling functions bound to Lua*
+
+
+.. note::
+
+	This abstraction assumes the function runs safely. If you expect your code to have errors (e.g., you don't always have explicit control over it or are trying to debug errors), please use :doc:`sol::protected_function<protected_function>` explicitly. You can also make ``sol::function`` default to ``sol::protected_function`` by turning on :ref:`the safety features<config>`.
+
+.. code-block:: cpp
+	
+	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:
+
+.. code-block:: cpp
+	:caption: constructor: unsafe_function
+
+	unsafe_function(lua_State* L, int index = -1);
+
+
+Calls the constructor and creates this type, straight from the stack. For example:
+
+.. literalinclude:: ../../../examples/tie.cpp
+	:caption: funcs.lua
+	:lines: 9-13
+	:linenos:
+
+The following C++ code will call this function from this file and retrieve the return value:
+
+.. literalinclude:: ../../../examples/tie.cpp
+	:lines: 1-7,16-22
+	:linenos:
+
+The call ``woof(20)`` generates a :ref:`unsafe_function_result<unsafe-function-result>`, which is then implicitly converted to an ``double`` after being called. The intermediate temporary ``function_result`` is then destructed, popping the Lua function call results off the Lua stack. 
+
+You can also return multiple values by using ``std::tuple``, or if you need to bind them to pre-existing variables use ``sol::tie``:
+
+.. literalinclude:: ../../../examples/tie.cpp
+	:lines: 24-
+	:linenos:
+
+This makes it much easier to work with multiple return values. Using ``std::tie`` from the C++ standard will result in dangling references or bad behavior because of the very poor way in which C++ tuples/``std::tie`` were specified and implemented: please use ``sol::tie( ... )`` instead to satisfy any multi-return needs.
+
+.. _function-result-warning:
+
+.. warning::
+
+	Do NOT save the return type of a :ref:`unsafe_function_result<unsafe-function-result>` (``function_result`` when :ref:`safety configurations are not turned on<config>`) with ``auto``, as in ``auto numwoof = woof(20);``, and do NOT store it anywhere. Unlike its counterpart :ref:`protected_function_result<protected-function-result>`, ``function_result`` is NOT safe to store as it assumes that its return types are still at the top of the stack and when its destructor is called will pop the number of results the function was supposed to return off the top of the stack. If you mess with the Lua stack between saving ``function_result`` and it being destructed, you will be subject to an incredible number of surprising and hard-to-track bugs. Don't do it.
+
+.. code-block:: cpp
+	:caption: function: call operator / function call
+
+	template<typename... Args>
+	unsafe_function_result operator()( Args&&... args );
+
+	template<typename... Ret, typename... Args>
+	decltype(auto) call( Args&&... args );
+
+	template<typename... Ret, typename... Args>
+	decltype(auto) operator()( types<Ret...>, Args&&... args );
+
+Calls the function. The second ``operator()`` lets you specify the templated return types using the ``my_func(sol::types<int, std::string>, ...)`` syntax. Function assumes there are no runtime errors, and thusly will call the ``atpanic`` function if a detectable error does occur, and otherwise can return garbage / bogus values if the user is not careful.
+
+
+To know more about how function arguments are handled, see :ref:`this note<function-argument-handling>`

third_party/sol2/docs/source/api/make_reference.rst

@@ -0,0 +1,26 @@
+make_object/make_reference
+==========================
+*create a value in the lua registry / on the Lua stack and return it*
+
+
+.. code-block:: cpp
+	:caption: function: make_reference
+	:name: make-reference
+
+	template <typename R = reference, bool should_pop = (R is not base of sol::stack_index), typename T>
+	R make_reference(lua_State* L, T&& value);
+	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.
+
+.. code-block:: cpp
+	:caption: function: make_object
+	:name: make-object
+
+	template <typename T>
+	object make_object(lua_State* L, T&& value);
+	template <typename T, typename... Args>
+	object make_object(lua_State* L, Args&&... args);
+
+Makes an object out of the value. It pushes it onto the stack, then pops it into the returned ``sol::object``. 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 implementation essentially defers to :ref:`sol::make_reference<make-reference>` with the specified arguments, ``R == object`` and ``should_pop == true``. It is preferred that one uses the :ref:`in_place object constructor instead<overloaded-object-constructor>`, since it's probably easier to deal with, but both versions will be supported for forever, since there's really no reason not to and people already have dependencies on ``sol::make_object``.

third_party/sol2/docs/source/api/metatable_key.rst

@@ -0,0 +1,15 @@
+metatable_key
+=============
+*a key for setting and getting an object's metatable*
+
+
+.. code-block:: cpp
+
+	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:
+
+.. literalinclude:: ../../../examples/metatable_key_low_level.cpp
+	:caption: messing with metatables
+	:linenos:

third_party/sol2/docs/source/api/nested.rst

@@ -0,0 +1,19 @@
+nested
+======
+
+
+.. code-block:: cpp
+	
+	template <typename T>
+	struct nested {
+		T source;
+	};
+
+
+``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.*
+
+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

third_party/sol2/docs/source/api/new_table.rst

@@ -0,0 +1,22 @@
+new_table
+=========
+*a table creation hint to environment/table*
+
+
+.. code-block:: cpp
+	
+	struct new_table;
+
+	constexpr const new_table create = new_table{};
+
+``sol::new_table`` serves the purpose of letting you create tables using the constructor of :doc:`sol::table<table>` and :doc:`sol::environment<environment>`. It also disambiguates the other kinds of constructors, so is **necessary** to be specified. Leaving it off will result in the wrong constructor to be called, for either ``sol::table`` or ``sol::environment``.
+
+members
+-------
+
+.. code-block:: cpp
+	:caption: constructor: new_table
+
+	new_table(int sequence_hint = 0, int map_hint = 0);
+	
+The constructor's sole purpose is to either let you default-constructor the type, in which case it uses the values of "0" for its two hints, or letting you specify either ``sequence_hint`` or both the ``sequence_hint`` and ``map_hint``. Each hint is a heuristic helper for Lua to allocate an appropriately sized and structured table for what you intend to do. In 99% of cases, you will most likely not care about it and thusly will just use the constant ``sol::create`` as the second argument to object-creators like ``sol::table``'s constructor.

third_party/sol2/docs/source/api/object.rst

@@ -0,0 +1,70 @@
+object
+======
+*general-purpose safety reference to an existing object*
+
+
+.. code-block:: cpp
+	
+	class object : reference;
+
+
+``object``'s goal is to allow someone to pass around the most generic form of a reference to something in Lua (or propogate a ``nil``). It is the logical extension of :doc:`sol::reference<reference>`, and is used in :ref:`sol::table's iterators<table-iterators>`.
+
+
+members
+-------
+
+.. code-block:: cpp
+    :caption: overloaded constructor: object
+    :name: overloaded-object-constructor
+
+    template <typename T>
+    object(T&&);
+    object(lua_State* L, int index = -1);
+    template <typename T, typename... Args>
+    object(lua_State* L, in_place_t, T&& arg, Args&&... args);
+    template <typename T, typename... Args>
+    object(lua_State* L, in_place_type_t<T>, Args&&... args);
+
+There are 4 kinds of constructors here. One allows construction of an object from other reference types such as :doc:`sol::table<table>` and :doc:`sol::stack_reference<stack_reference>`. The second creates an object which references the specific element at the given index in the specified ``lua_State*``. The more advanced ``in_place...`` constructors create a single object by pushing the specified type ``T`` onto the stack and then setting it as the object. It gets popped from the stack afterwards (unless this is an instance of ``sol::stack_object``, in which case it is left on the stack). An example of using this and :doc:`sol::make_object<make_reference>` can be found in the `any_return example`_.
+
+.. code-block:: cpp
+	:caption: function: type conversion
+	
+	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>`.
+
+.. 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.
+
+
+non-members
+-----------
+
+.. code-block:: cpp
+	:caption: functions: nil comparators
+
+	bool operator==(const object& lhs, const nil_t&);
+	bool operator==(const nil_t&, const object& rhs);
+	bool operator!=(const object& lhs, const nil_t&);
+	bool operator!=(const nil_t&, const object& rhs);
+
+These allow a person to compare an ``sol::object`` against :ref:`nil<nil>`, which essentially checks if an object references a non-nil value, like so:
+
+.. code-block:: cpp
+
+	if (myobj == sol::nil) {
+		// doesn't have anything...
+	}
+
+Use this to check objects.
+
+
+.. _any_return example: https://github.com/ThePhD/sol2/blob/develop/examples/any_return.cpp

third_party/sol2/docs/source/api/optional.rst

@@ -0,0 +1,9 @@
+optional<T>
+===========
+
+This is an implemention of `optional from the standard library`_. If it detects that a proper optional exists, it will attempt to use it. This is mostly an implementation detail, used in the :ref:`sol::stack::check_get<stack-check-get>` and :ref:`sol::stack::get\<optional\<T>><stack-get>` and ``sol::optional<T> maybe_value = table["arf"];`` implementations for additional safety reasons.
+
+See `this example here`_ for a demonstration on how to use it and other features!
+
+.. _optional from the standard library: http://en.cppreference.com/w/cpp/utility/optional
+.. _this example here: https://github.com/ThePhD/sol2/blob/develop/examples/optional_with_iteration.cpp

third_party/sol2/docs/source/api/overload.rst

@@ -0,0 +1,62 @@
+overload
+========
+*calling different functions based on argument number/type*
+
+
+.. code-block:: cpp
+	:caption: function: create overloaded set
+	:linenos:
+
+	template <typename... Args>
+	struct overloaded_set : std::tuple<Args...> { /* ... */ };
+
+	template <typename... Args>
+	overloaded_set<Args...> overload( Args&&... args );
+
+The actual class produced by ``sol::overload`` is essentially a type-wrapper around ``std::tuple`` that signals to the library that an overload is being created. The function helps users make overloaded functions that can be called from Lua using 1 name but multiple arguments. It is meant to replace the spaghetti of code where users mock this up by doing strange if statements and switches on what version of a function to call based on `luaL_check{number/udata/string}`_.
+
+.. note::
+
+	Please note that default parameters in a function (e.g., ``int func(int a = 20)``) do not exist beyond C++'s compile-time fun. When that function gets bound or serialized into Lua's framework, it is bound as a function taking 1 argument, not 2 functions taking either 0 or 1 argument. If you want to achieve the same effect, then you need to use overloading and explicitly call the version of the function you want. There is no magic in C++ that allows me to retrieve default parameters and set this up automatically.
+
+.. note::
+
+	Overload resolution can be affected by configuration defines in the :doc:`safety pages<../safety>`. For example, it is impossible to differentiate between integers (uint8_t, in32_t, etc.) versus floating-point types (float, double, half) when ``SOL_SAFE_NUMERICS`` is not turned on.
+
+Its use is simple: wherever you can pass a function type to Lua, whether its on a :doc:`usertype<usertype>` or if you are just setting any kind of function with ``set`` or ``set_function`` (for :doc:`table<table>` or :doc:`state(_view)<state>`), simply wrap up the functions you wish to be considered for overload resolution on one function like so:
+
+.. code-block:: cpp
+	
+	sol::overload( func1, func2, ... funcN );
+
+
+The functions can be any kind of function / function object (lambda). Given these functions and struct:
+
+.. literalinclude:: ../../../examples/overloading_with_members.cpp
+	:linenos:
+	:lines: 1-27
+
+You then use it just like you would for any other part of the api:
+
+.. literalinclude:: ../../../examples/overloading_with_members.cpp
+	:linenos:
+	:lines: 29-45
+
+Doing the following in Lua will call the specific overloads chosen, and their associated functions:
+
+.. literalinclude:: ../../../examples/overloading_with_members.cpp
+	:linenos:
+	:lines: 47-
+
+.. note::
+
+	Overloading is done on a first-come, first-serve system. This means if two overloads are compatible, workable overloads, it will choose the first one in the list.
+
+Note that because of this system, you can use :doc:`sol::variadic_args<variadic_args>` to make a function that serves as a "fallback". Be sure that it is the last specified function in the listed functions for ``sol::overload( ... )``. `This example shows how`_.
+
+.. note::
+
+	Please keep in mind that doing this bears a runtime cost to find the proper overload. The cost scales directly not exactly with the number of overloads, but the number of functions that have the same argument count as each other (Sol will early-eliminate any functions that do not match the argument count).
+
+.. _luaL_check{number/udata/string}: http://www.Lua.org/manual/5.3/manual.html#luaL_checkinteger
+.. _This example shows how: https://github.com/ThePhD/sol2/blob/develop/examples/overloading_with_fallback.cpp

third_party/sol2/docs/source/api/property.rst

@@ -0,0 +1,18 @@
+property
+========
+*wrapper to specify read and write variable functionality using functions*
+
+.. code-block:: cpp
+	
+	template <typename Read, typename Write>
+	decltype(auto) property ( Read&& read_function, Write&& write_function );
+	template <typename Read>
+	decltype(auto) property ( Read&& read_function );
+	template <typename Write>
+	decltype(auto) property ( Write&& write_function );
+
+These set of functions create a type which allows a setter and getter pair (or a single getter, or a single setter) to be used to create a variable that is either read-write, read-only, or write-only. When used during :doc:`usertype<usertype>` construction, it will create a variable that uses the setter/getter member function specified.
+
+.. literalinclude:: ../../../examples/property.cpp
+	:linenos:
+

third_party/sol2/docs/source/api/protect.rst

@@ -0,0 +1,14 @@
+protect
+=======
+*routine to mark a function / variable as requiring safety*
+
+
+.. code-block:: cpp
+	
+	template <typename T>
+	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:
+
+.. literalinclude:: ../../../examples/protect.cpp
+	:linenos:	

third_party/sol2/docs/source/api/protected_function.rst

@@ -0,0 +1,118 @@
+protected_function
+==================
+*Lua function calls that trap errors and provide error handling*
+
+.. code-block:: cpp
+	
+	class protected_function : public reference;
+	typedef protected_function safe_function;
+
+Inspired by a request from `starwing`_ in the :doc:`old sol repository<../origin>`, this class provides the same interface as :doc:`function<function>` but with heavy protection and a potential error handler for any Lua errors and C++ exceptions. You can grab a function directly off the stack using the constructor, or pass to it 2 valid functions, which we'll demonstrate a little later.
+
+When called without the return types being specified by either a ``sol::types<...>`` list or a ``call<Ret...>( ... )`` template type list, it generates a :doc:`protected_function_result<proxy>` class that gets implicitly converted to the requested return type. For example:
+
+.. literalinclude:: ../../../examples/error_handler.cpp
+	:linenos:
+	:lines: 10-28
+
+The following C++ code will call this function from this file and retrieve the return value, unless an error occurs, in which case you can bind an error handling function like so:
+
+.. literalinclude:: ../../../examples/error_handler.cpp
+	:linenos:
+	:lines: 1-6,30-66
+
+
+This code is much more long-winded than its :doc:`function<function>` counterpart but allows a person to check for errors. The type here for ``auto`` are ``sol::protected_function_result``. They are implicitly convertible to result types, like all :doc:`proxy-style<proxy>` types are.
+
+Alternatively, with a bad or good function call, you can use ``sol::optional`` to check if the call succeeded or failed:
+
+.. literalinclude:: ../../../examples/error_handler.cpp
+	:linenos:
+	:lines: 67-
+
+
+That makes the code a bit more concise and easy to reason about if you don't want to bother with reading the error. Thankfully, unlike ``sol::unsafe_function_result``, you can save ``sol::protected_function_result`` in a variable and push/pop things above it on the stack where its returned values are. This makes it a bit more flexible  than the rigid, performant ``sol::unsafe_function_result`` type that comes from calling :doc:`sol::unsafe_function<function>`.
+
+If you're confident the result succeeded, you can also just put the type you want (like ``double`` or ``std::string``) right there and it will get it. But, if it doesn't work out, sol can throw and/or panic if you have the :doc:`safety<../safety>` features turned on:
+
+.. code-block:: cpp
+	:linenos:
+
+	// construct with function + error handler
+	// shorter than old syntax
+	sol::protected_function problematicwoof(lua["woof"], lua["got_problems"]);
+
+	// dangerous if things go wrong!
+	double value = problematicwoof(19);
+
+
+Finally, it is *important* to note you can set a default handler. The function is described below: please use it to avoid having to constantly set error handlers:
+
+.. code-block:: cpp
+	:linenos:
+
+	// sets got_problems as the default
+	// handler for all protected_function errors
+	sol::protected_function::set_default_handler(lua["got_problems"]);
+
+	sol::protected_function problematicwoof = lua["woof"];
+	sol::protected_function problematicwoofers = lua["woofers"];
+
+	double value = problematicwoof(19);
+	double value2 = problematicwoof(9);
+
+
+members
+-------
+
+.. code-block:: cpp
+	:caption: constructor: protected_function
+
+	template <typename T>
+	protected_function( T&& func, reference handler = sol::protected_function::get_default_handler() );
+	protected_function( lua_State* L, int index = -1, reference handler = sol::protected_function::get_default_handler() );
+
+Constructs a ``protected_function``. Use the 2-argument version to pass a custom error handling function more easily. You can also set the :ref:`member variable error_handler<protected-function-error-handler>` after construction later. ``protected_function`` will always use the latest error handler set on the variable, which is either what you passed to it or the default *at the time of construction*. 
+
+.. code-block:: cpp
+	:caption: function: call operator / protected function call
+
+	template<typename... Args>
+	protected_function_result operator()( Args&&... args );
+
+	template<typename... Ret, typename... Args>
+	decltype(auto) call( Args&&... args );
+
+	template<typename... Ret, typename... Args>
+	decltype(auto) operator()( types<Ret...>, Args&&... args );
+
+Calls the function. The second ``operator()`` lets you specify the templated return types using the ``my_func(sol::types<int, std::string>, ...)`` syntax. If you specify no return type in any way, it produces s ``protected_function_result``.
+
+.. note::
+
+	All arguments are forwarded. Unlike :doc:`get/set/operator[] on sol::state<state>` or :doc:`sol::table<table>`, value semantics are not used here. It is forwarding reference semantics, which do not copy/move unless it is specifically done by the receiving functions / specifically done by the user.
+
+
+.. code-block:: cpp
+	:caption: default handlers
+
+	static const reference& get_default_handler ();
+	static void set_default_handler( reference& ref );
+
+Get and set the Lua entity that is used as the default error handler. The default is a no-ref error handler. You can change that by calling ``protected_function::set_default_handler( lua["my_handler"] );`` or similar: anything that produces a reference should be fine.
+
+.. code-block:: cpp
+	:caption: variable: handler
+	:name: protected-function-error-handler
+
+	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<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::
+
+	``protected_function_result`` safely pops its values off the stack when its destructor is called, keeping track of the index and number of arguments that were supposed to be returned. If you remove items below it using ``lua_remove``, for example, it will not behave as expected. Please do not perform fundamentally stack-rearranging operations until the destructor is called (pushing/popping above it is just fine).
+
+To know more about how function arguments are handled, see :ref:`this note<function-argument-handling>`.
+
+.. _starwing: https://github.com/starwing

third_party/sol2/docs/source/api/proxy.rst

@@ -0,0 +1,175 @@
+proxy, (protected\unsafe)_function_result - proxy_base derivatives
+==================================================================
+*``table[x]`` and ``function(...)`` conversion struct*
+
+
+.. code-block:: cpp
+
+	template <typename Recurring>
+	struct proxy_base;
+
+	template <typename Table, typename Key>
+	struct proxy : proxy_base<...>;
+
+	struct stack_proxy: proxy_base<...>;
+
+	struct unsafe_function_result : proxy_base<...>;
+
+	struct protected_function_result: proxy_base<...>;
+
+
+These classes provide implicit assignment operator ``operator=`` (for ``set``) and an implicit conversion operator ``operator T`` (for ``get``) to support items retrieved from the underlying Lua implementation, specifically :doc:`sol::table<table>` and the results of function calls on :doc:`sol::function<function>` and :doc:`sol::protected_function<protected_function>`.
+
+.. _proxy:
+
+proxy
+-----
+
+``proxy`` is returned by lookups into :doc:`sol::table<table>` and table-like entities. Because it is templated on key and table type, it would be hard to spell: you can capture it using the word ``auto`` if you feel like you need to carry it around for some reason before using it. ``proxy`` evaluates its arguments lazily, when you finally call ``get`` or ``set`` on it. Here are some examples given the following lua script:
+
+.. literalinclude:: ../../../examples/table_proxy.cpp
+	:linenos:
+	:lines: 11-15
+
+After loading that file in or putting it in a string and reading the string directly in lua (see :doc:`state`), you can start kicking around with it in C++ like so:
+
+.. literalinclude:: ../../../examples/table_proxy.cpp
+	:linenos:
+	:lines: 1-8,18-40
+
+We don't recommend using ``proxy`` lazy evaluation the above to be used across classes or between function: it's more of something you can do to save a reference to a value you like, call a script or run a lua function, and then get it afterwards. You can also set functions (and function objects) this way, and retrieve them as well:
+
+.. literalinclude:: ../../../examples/table_proxy.cpp
+	:linenos:
+	:lines: 41-
+
+members
+-------
+
+.. code-block:: c++
+	:caption: functions: [overloaded] implicit conversion get
+	:name: implicit-get
+
+	requires( sol::is_primitive_type<T>::value == true )
+	template <typename T>
+	operator T() const;
+	
+	requires( sol::is_primitive_type<T>::value == false )
+	template <typename T>
+	operator T&() const;
+
+Gets the value associated with the keys the proxy was generated and convers it to the type ``T``. Note that this function will always return ``T&``, a non-const reference, to types which are not based on :doc:`sol::reference<reference>` and not a :doc:`primitive lua type<types>`
+
+.. code-block:: c++
+	:caption: function: get a value
+	:name: regular-get
+
+	template <typename T>
+	decltype(auto) get( ) const;
+
+Gets the value associated with the keys and converts it to the type ``T``.
+
+.. code-block:: c++
+	:caption: function: optionally get a value
+	:name: regular-get-or
+
+	template <typename T, typename Otherwise>
+	optional<T> get_or( Otherwise&& otherise ) const;
+
+Gets the value associated with the keys and converts it to the type ``T``. If it is not of the proper type, it will return a ``sol::nullopt`` instead.
+
+.. code-block:: c++
+	:caption: function: [overloaded] optionally get or create a value
+	:name: regular-get-or-create
+
+	template <typename T>
+	decltype(auto) get_or_create();
+	template <typename T, typename Otherwise>
+	decltype(auto) get_or_create( Otherwise&& other );
+
+Gets the value associated with the keys if it exists. If it does not, it will set it with the value and return the result.
+
+``operator[]`` proxy-only members
+---------------------------------
+
+.. code-block:: c++
+	:caption: function: valid
+	:name: proxy-valid
+
+	bool valid () const;
+
+Returns whether this proxy actually refers to a valid object. It uses :ref:`sol::stack::probe_get_field<stack-probe-get-field>` to determine whether or not its valid.
+
+.. code-block:: c++
+	:caption: functions: [overloaded] implicit set
+	:name: implicit-set
+
+	requires( sol::detail::Function<Fx> == false )
+	template <typename T>
+	proxy& operator=( T&& value );
+	
+	requires( sol::detail::Function<Fx> == true )
+	template <typename Fx>
+	proxy& operator=( Fx&& function );
+
+Sets the value associated with the keys the proxy was generated with to ``value``. If this is a function, calls ``set_function``. If it is not, just calls ``set``. Does not exist on :ref:`unsage_function_result<unsafe-function-result>` or :ref:`protected_function_result<protected-function-result>`.
+
+.. code-block:: c++
+	:caption: function: set a callable
+	:name: regular-set-function
+
+	template <typename Fx>
+	proxy& set_function( Fx&& fx );
+
+Sets the value associated with the keys the proxy was generated with to a function ``fx``. Does not exist on :ref:`unsafe_function_result<unsafe-function-result>` or :ref:`protected_function_result<protected-function-result>`.
+
+
+.. code-block:: c++
+	:caption: function: set a value
+	:name: regular-set
+
+	template <typename T>
+	proxy& set( T&& value );
+
+Sets the value associated with the keys the proxy was generated with to ``value``. Does not exist on :ref:`unsafe_function_result<unsafe-function-result>` or :ref:`protected_function_result<protected-function-result>`.
+
+.. _stack-proxy:
+
+stack_proxy
+-----------
+
+``sol::stack_proxy`` is what gets returned by :doc:`sol::variadic_args<variadic_args>` and other parts of the framework. It is similar to proxy, but is meant to alias a stack index and not a named variable.
+
+.. _unsafe-function-result:
+
+unsafe_function_result
+----------------------
+
+``unsafe_function_result`` is a temporary-only, intermediate-only implicit conversion worker for when :doc:`function<function>` is called. It is *NOT* meant to be stored or captured with ``auto``. It provides fast access to the desired underlying value. It does not implement ``set`` / ``set_function`` / templated ``operator=``, as is present on :ref:`proxy<proxy>`.
+
+
+This type does, however, allow access to multiple underlying values. Use ``result.get<Type>(index_offset)`` to retrieve an object of ``Type`` at an offset of ``index_offset`` in the results. Offset is 0 based. Not specifying an argument defaults the value to 0.
+
+``unsafe_function_result`` also has ``begin()`` and ``end()`` functions that return (almost) "random-acess" iterators. These return a proxy type that can be implicitly converted to :ref:`stack_proxy<stack-proxy>`.
+
+.. _protected-function-result:
+
+protected_function_result
+-------------------------
+
+``protected_function_result`` is a nicer version of ``unsafe_function_result`` that can be used to detect errors. Its gives safe access to the desired underlying value. It does not implement ``set`` / ``set_function`` / templated ``operator=`` as is present on :ref:`proxy<proxy>`.
+
+
+This type does, however, allow access to multiple underlying values. Use ``result.get<Type>(index_offset)`` to retrieve an object of ``Type`` at an offset of ``index_offset`` in the results. Offset is 0 based. Not specifying an argument defaults the value to 0.
+
+``unsafe_function_result`` also has ``begin()`` and ``end()`` functions that return (almost) "random-acess" iterators. These return a proxy type that can be implicitly converted to :ref:`stack_proxy<stack-proxy>`.
+
+.. _note 1:
+
+on function objects and proxies
+-------------------------------
+
+.. note::
+
+	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>`.
+

third_party/sol2/docs/source/api/readonly.rst

@@ -0,0 +1,21 @@
+readonly
+========
+*routine to mark a member variable as read-only*
+
+.. code-block:: cpp
+	
+	template <typename T>
+	auto readonly( T&& value );
+
+The goal of read-only is to protect a variable set on a usertype or a function. Simply wrap it around a member variable, e.g. ``sol::readonly( &my_class::my_member_variable )`` in the appropriate place to use it. If someone tries to set it, it will error their code.
+
+``sol::readonly`` is especially important when you're working with types that do not have a copy constructor. Lua does not understand move semantics, and therefore setters to user-defined-types require a C++ copy constructor. Containers as member variables that contain types that are not copyable but movable -- e.g. ``std::vector<my_move_only_type>`` amongst others -- also can erroneously state they are copyable but fail with compiler errors. If your type does not fit a container's definition of being copyable or is just not copyable in general and it is a member variable, please use ``sol::readonly``.
+
+If you are looking to make a read-only table, you need to go through a bit of a complicated song and dance by overriding the ``__index`` metamethod. Here's a complete example on the way to do that using ``sol``:
+
+
+.. literalinclude:: ../../../examples/read_only.cpp
+	:caption: read_only.cpp
+	:linenos:
+
+It is a verbose example, but it explains everything. Because the process is a bit involved and can have unexpected consequences for users that make their own tables, making read-only tables is something that we ask the users to do themselves with the above code, as getting the semantics right for the dozens of use cases would be tremendously difficult.

third_party/sol2/docs/source/api/reference.rst

@@ -0,0 +1,97 @@
+reference
+=========
+*general purpose reference to Lua object in registry*
+
+
+..  code-block:: cpp
+	:caption: reference
+		
+	class reference;
+
+This type keeps around a reference to something inside of Lua, whether that object was on the stack or already present as an object in the Lua Runtime. It places the object Lua registry and will keep it alive.
+
+It is the backbone for all things that reference items on the stack that need to be kept around beyond their appearance and lifetime on said Lua stack or need to be kept alive outside of a script beyond garbage collection times. Its progeny include :doc:`sol::coroutine<coroutine>`, :doc:`sol::function<function>`, :doc:`sol::protected_function<protected_function>`, :doc:`sol::object<object>`, :doc:`sol::table<table>`/:doc:`sol::global_table<table>`, :doc:`sol::thread<thread>`, and :doc:`sol::(light_)userdata<userdata>`, which are type-specific versions of ``sol::reference``.
+
+Note that if you need to keep a reference to something inside of Lua, it is better to use ``sol::reference`` or :doc:`sol::object<object>` to keep a reference to it and then use the ``obj.as<T>()`` member function to retrieve what you need than to take a direct dependency on the memory by retrieving a pointer or reference to the userdata itself. This will ensure that if a script or the Lua Runtime is finished with an object, it will not be garbage collected. Do this only if you need long-term storage.
+
+For all of these types, there's also a ``sol::stack_{x}`` version of them, such as ``sol::stack_table``. They are useful for a small performance boost at the cost of not having a strong reference, which has implications for what happens when the item is moved off of the stack. See :doc:`sol::stack_reference<stack_reference>` for more details.
+
+
+members
+-------
+
+.. code-block:: cpp
+	:caption: constructor: reference
+	:name: reference-constructor
+
+	reference(lua_State* L, int index = -1);
+	reference(lua_State* L, lua_nil_t);
+	reference(lua_State* L, absolute_index index);
+	reference(lua_State* L, raw_index index);
+	reference(lua_State* L, ref_index index);
+	template <typename Object>
+	reference(Object&& o);
+	template <typename Object>
+	reference(lua_State* L, Object&& o);
+
+The first constructor creates a reference from the Lua stack at the specified index, saving it into the metatable registry. The second attemtps to register something that already exists in the registry. The third attempts to reference a pre-existing object and create a reference to it. These constructors are exposed on all types that derive from ``sol::reference``, meaning that you can grab tables, functions, and coroutines from the registry, stack, or from other objects easily.
+
+.. _lua_xmove-note:
+
+.. note::
+
+	Note that the last constructor has ``lua_xmove`` safety built into it. You can pin an object to a certain thread (or the main thread) by initializing it with ``sol::reference pinned(state, other_reference_object);``. This ensures that ``other_reference_object`` will exist in the state/thread of ``state``. Also note that copy/move assignment operations will also use pinning semantics if it detects that the state of the object on the right is ``lua_xmove`` compatible. (But, the ``reference`` object on the left must have a valid state as well. You can have a nil ``reference`` with a valid state by using the ``sol::reference pinned(state, sol::lua_nil)`` constructor as well.) This applies for any ``sol::reference`` derived type.
+
+	You can un-pin and null the state by doing ``ref = sol::lua_nil;``. This applies to **all derived types**, including ``sol::(protected_)function``, ``sol::thread``, ``sol::object``, ``sol::table``, and similar.
+
+.. code-block:: cpp
+	:caption: function: push referred-to element from the stack
+
+	int push() const noexcept;
+
+This function pushes the referred-to data onto the stack and returns how many things were pushed. Typically, it returns 1.
+
+.. code-block:: cpp
+	:caption: function: reference value
+
+	int registry_index() const noexcept;
+
+The value of the reference in the registry.
+
+.. code-block:: cpp
+	:caption: functions: non-nil, non-null check
+
+	bool valid () const noexcept;
+	explicit operator bool () const noexcept;
+
+These functions check if the reference at ``T`` is valid: that is, if it is not :ref:`nil<nil>` and if it is not non-existing (doesn't refer to anything, including nil) reference. The explicit operator bool allows you to use it in the context of an ``if ( my_obj )`` context.
+
+.. code-block:: cpp
+	:caption: function: retrieves the type
+
+	type get_type() const noexcept;
+
+Gets the :doc:`sol::type<types>` of the reference; that is, the Lua reference.
+
+.. code-block:: cpp
+	:caption: function: lua_State* of the reference
+
+	lua_State* lua_state() const noexcept;
+
+Gets the ``lua_State*`` this reference exists in.
+
+
+non-members
+-----------
+
+.. code-block:: cpp
+	:caption: operators: reference comparators
+	:name: reference-operators-comparators
+
+	bool operator==(const reference&, const reference&);
+	bool operator!=(const reference&, const reference&);
+
+Compares two references using the Lua API's `lua_compare`_ for equality.
+
+
+.. _lua_compare: https://www.lua.org/manual/5.3/manual.html#lua_compare

third_party/sol2/docs/source/api/resolve.rst

@@ -0,0 +1,69 @@
+resolve
+=======
+*utility to pick overloaded C++ function calls*
+
+
+.. code-block:: cpp
+	:caption: function: resolve C++ overload
+
+	template <typename... Args, typename F>
+	constexpr auto resolve( F f );
+
+``resolve`` is a function that is meant to help users pick a single function out of a group of overloaded functions in C++. It works for *both member and free functions* You can use it to pick overloads by specifying the signature as the first template argument. Given a collection of overloaded functions:
+
+.. code-block:: cpp
+	:linenos:
+
+	int overloaded(int x);
+	int overloaded(int x, int y);
+	int overloaded(int x, int y, int z);
+
+	struct thing {
+		int overloaded() const;
+		int overloaded(int x);
+		int overloaded(int x, int y);
+		int overloaded(int x, int y, int z);
+	};
+
+You can disambiguate them using ``resolve``:
+
+..  code-block:: cpp
+	:linenos:
+
+	auto one_argument_func = resolve<int(int)>( overloaded );
+	auto two_argument_func = resolve<int(int, int)>( overloaded );
+	auto three_argument_func = resolve<int(int, int, int)>( overloaded );
+	auto member_three_argument_func = resolve<int(int, int, int)>( &thing::overloaded );
+	auto member_zero_argument_const_func = resolve<int() const>( &thing::overloaded );
+
+It is *important* to note that ``const`` is placed at the end for when you desire const overloads. You will get compiler errors if you are not specific and do not properly disambiguate for const member functions. This resolution also becomes useful when setting functions on a :doc:`table<table>` or :doc:`state_view<state>`:
+
+..  code-block:: cpp
+	:linenos:
+
+	sol::state lua;
+
+	lua.set_function("a", resolve<int(int)>( overloaded ) );
+	lua.set_function("b", resolve<int(int, int)>( overloaded ));
+	lua.set_function("c", resolve<int(int, int, int)>( overloaded ));
+
+
+It can also be used with :doc:`sol::c_call<c_call>`:
+
+.. code-block:: cpp
+	:linenos:
+
+	sol::state lua;
+	
+	auto f = sol::c_call<
+		decltype(sol::resolve<int(int, int)>(&overloaded)), 
+		sol::resolve<int(int, int)>(&overloaded)
+	>;
+	lua.set_function("f", f);
+	
+	lua.script("f(1, 2)");
+
+
+.. note::
+
+	You cannot use ``sol::resolve<...>(...)`` when one function is templated and it has a non-templated overload: it will always fail in this case. To resolve this, please use a manual ``static_cast<R(Args...)>( &func )`` or ``static_cast<R (T::*)(Args...)>( &T::overloaded_member_func )`` (with the right const-ness and volatile-ness and r-value/l-value qualifiers if necessary).

third_party/sol2/docs/source/api/stack.rst

@@ -0,0 +1,334 @@
+stack namespace
+===============
+*the nitty-gritty core abstraction layer over Lua*
+
+
+.. code-block:: cpp
+
+	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<api-top>`.
+
+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<extension_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<extension_points>` at your own discretion.
+
+structures
+----------
+
+.. code-block:: cpp
+	:caption: struct: record
+	:name: stack-record
+
+	struct record {
+		int last;
+		int used;
+
+		void use(int count);
+	};
+
+This structure is for advanced usage with :ref:`stack::get<stack-get>` and :ref:`stack::check_get<stack-get>`. When overriding the customization points, it is important to call the ``use`` member function on this class with the amount of things you are pulling from the stack. ``used`` contains the total accumulation of items produced. ``last`` is the number of items gotten from the stack with the last operation (not necessarily popped from the stack). In all trivial cases for types, ``last == 1`` and ``used == 1`` after an operation; structures such as ``std::pair`` and ``std::tuple`` may pull more depending on the classes it contains.
+
+When overriding the :doc:`customization points<../tutorial/customization>`, please note that this structure should enable you to push multiple return values and get multiple return values to the stack, and thus be able to seamlessly pack/unpack return values from Lua into a single C++ struct, and vice-versa. This functionality is only recommended for people who need to customize the library further than the basics. It is also a good way to add support for the type and propose it back to the original library so that others may benefit from your work.
+
+Note that customizations can also be put up on a separate page here, if individuals decide to make in-depth custom ones for their framework or other places.
+
+.. code-block:: cpp
+	:caption: struct: probe
+	:name: stack-probe-struct
+
+	struct probe {
+		bool success;
+		int levels;
+
+		probe(bool s, int l);
+		operator bool() const;
+	};
+
+This struct is used for showing whether or not a :ref:`probing get_field<stack-probe-get-field>` was successful or not.
+
+
+members
+-------
+
+.. code-block:: cpp
+	:caption: function: call_lua
+	:name: stack-call-lua
+
+	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 sol2. Use the more advanced versions at your own peril.
+
+.. code-block:: cpp
+	:caption: function: get
+	:name: stack-get
+
+	template <typename T>
+	auto get( lua_State* L, int index = -1 )
+	template <typename T>
+	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\<T><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\<T><getter>` struct. ``stack::get`` will default to forwarding all arguments to the :ref:`stack::check_get<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\<T><optional>` from this as well, to have it attempt to not throw errors when performing the get and the type is not correct.
+
+.. code-block:: cpp
+	:caption: function: check
+	:name: stack-check
+
+	template <typename T>
+	bool check( lua_State* L, int index = -1 )
+
+	template <typename T, typename Handler>
+	bool check( lua_State* L, int index, Handler&& handler )
+
+	template <typename T, typename Handler>
+	bool check( lua_State* L, int index, Handler&& handler, record& tracking )
+
+Checks if the object at ``index`` is of type ``T``. If it is not, it will call the ``handler`` function with ``lua_State* L``, ``int index``, ``sol::type expected``, and ``sol::type actual`` as arguments (and optionally with a 5th string argument ``sol::string_view message``. If you do not pass your own handler, a ``no_panic`` handler will be passed.
+
+.. code-block:: cpp
+	:caption: function: get_usertype
+	:name: stack-get-usertype
+
+	template <typename T>
+	auto get_usertype( lua_State* L, int index = -1 )
+	template <typename T>
+	auto get_usertype( lua_State* L, int index, record& tracking )
+
+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
+	:name: stack-check-usertype
+
+	template <typename T>
+	bool check_usertype( lua_State* L, int index = -1 )
+
+	template <typename T, typename Handler>
+	bool check_usertype( lua_State* L, int index, Handler&& handler )
+
+	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 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
+	:name: stack-check-get
+
+	template <typename T>
+	auto check_get( lua_State* L, int index = -1 )
+	template <typename T, typename Handler>
+	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<U>``, where ``U`` in this case is the return type deduced from ``stack::get<T>``. 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.
+
+.. code-block:: cpp
+	:caption: function: push
+	:name: stack-push
+
+	// push T inferred from call site, pass args... through to extension point
+	template <typename T, typename... Args>
+	int push( lua_State* L, T&& item, Args&&... args )
+
+	// push T that is explicitly specified, pass args... through to extension point
+	template <typename T, typename Arg, typename... Args>
+	int push( lua_State* L, Arg&& arg, Args&&... args )
+
+	// recursively call the the above "push" with T inferred, one for each argument
+	template <typename... Args>
+	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<T>( 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\<T><pusher>` struct.
+
+.. code-block:: cpp
+	:caption: function: push_reference
+	:name: stack-push-reference
+
+	// push T inferred from call site, pass args... through to extension point
+	template <typename T, typename... Args>
+	int push_reference( lua_State* L, T&& item, Args&&... args )
+
+	// push T that is explicitly specified, pass args... through to extension point
+	template <typename T, typename Arg, typename... Args>
+	int push_reference( lua_State* L, Arg&& arg, Args&&... args )
+
+	// recursively call the the above "push" with T inferred, one for each argument
+	template <typename... Args>
+	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 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
+	:name: stack-pop
+
+	template <typename... Args>
+	auto pop( lua_State* L );
+
+Pops an object off the stack. Will remove a fixed number of objects off the stack, generally determined by the ``sol::lua_size<T>`` traits of the arguments supplied. Generally a simplicity function, used for convenience.
+
+.. code-block:: cpp
+	:caption: function: top
+	:name: stack-top
+
+	int top( lua_State* L );
+
+Returns the number of values on the stack.
+
+.. code-block:: cpp
+	:caption: function: set_field
+
+	template <bool global = false, typename Key, typename Value>
+	void set_field( lua_State* L, Key&& k, Value&& v );
+
+	template <bool global = false, typename Key, typename Value>
+	void set_field( lua_State* L, Key&& k, Value&& v, int objectindex);
+
+Sets the field referenced by the key ``k`` to the given value ``v``, by pushing the key onto the stack, pushing the value onto the stack, and then doing the equivalent of ``lua_setfield`` for the object at the given ``objectindex``. Performs optimizations and calls faster verions of the function if the type of ``Key`` is considered a c-style string and/or if its also marked by the templated ``global`` argument to be a global.
+
+.. code-block:: cpp
+	:caption: function: get_field
+
+	template <bool global = false, typename Key>
+	void get_field( lua_State* L, Key&& k [, int objectindex] );
+
+Gets the field referenced by the key ``k``, by pushing the key onto the stack, and then doing the equivalent of ``lua_getfield``. Performs optimizations and calls faster verions of the function if the type of ``Key`` is considered a c-style string and/or if its also marked by the templated ``global`` argument to be a global.
+
+This function leaves the retrieved value on the stack.
+
+.. code-block:: cpp
+	:caption: function: probe_get_field
+	:name: stack-probe-get-field
+
+	template <bool global = false, typename Key>
+	probe probe_get_field( lua_State* L, Key&& k [, int objectindex] );
+
+Gets the field referenced by the key ``k``, by pushing the key onto the stack, and then doing the equivalent of ``lua_getfield``. Performs optimizations and calls faster verions of the function if the type of ``Key`` is considered a c-style string and/or if its also marked by the templated ``global`` argument to be a global. Furthermore, it does this safely by only going in as many levels deep as is possible: if the returned value is not something that can be indexed into, then traversal queries with ``std::tuple``/``std::pair`` will stop early and return probing information with the :ref:`probe struct<stack-probe-struct>`.
+
+This function leaves the retrieved value on the stack.
+
+.. _extension_points:
+
+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>`.
+
+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: struct: getter
+	:name: getter
+
+	template <typename T, typename = void>
+	struct getter {
+		static T get (lua_State* L, int index, record& tracking) {
+			// ...
+			return // T, or something related to T.
+		}
+	};
+
+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<types>` and anything as upvalues with :doc:`upvalue_index<types>`, getting raw `lua_CFunction`_ s, and finally pulling out Lua functions into ``std::function<R(Args...)>``. It is also defined for anything that derives from :doc:`sol::reference<reference>`. It also has a special implementation for the 2 standard library smart pointers (see :doc:`usertype memory<usertype_memory>`).
+
+.. code-block:: cpp
+	:caption: struct: pusher
+	:name: pusher
+
+	template <typename X, typename = void>
+	struct pusher {
+		template <typename T>
+		static int push ( lua_State* L, T&&, ... ) {
+			// can optionally take more than just 1 argument
+			// ...
+			return // number of things pushed onto the stack
+		}
+	};
+
+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<types>` and raw upvalues with :doc:`upvalue<types>`, 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<reference>`. It also has a special implementation for the 2 standard library smart pointers (see :doc:`usertype memory<usertype_memory>`).
+
+.. code-block:: cpp
+	:caption: struct: checker
+	:name: checker
+
+	template <typename T, type expected = lua_type_of<T>, typename = void>
+	struct checker {
+		template <typename Handler>
+		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.
+
+.. _userdata-interop:
+
+.. code-block:: cpp
+	:caption: struct: userdata_checker
+	:name: userdata_checker
+
+	template <typename T, typename = void>
+	struct userdata_checker {
+		template <typename Handler>
+		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
+		}
+	};
+
+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 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::
+
+	You must turn this feature on with ``SOL_ENABLE_INTEROP``, as described in the :ref:`config and safety section<config>`.
+
+
+.. code-block:: cpp
+	:caption: struct: userdata_getter
+	:name: userdata_getter
+
+	template <typename T, typename = void>
+	struct userdata_getter {
+		static std::pair<bool, T*> get ( lua_State* L, int index, void* unadjusted_pointer, record& tracking ) {
+			// implement custom getting here for non-sol2 userdatas:
+			// if it doesn't match, return "false" and regular 
+			// sol userdata checks 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 sol2 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<usertype_memory>` is compatible. (For example, ``toLua`` stores userdata in a sol2-compatible way.)
+
+
+.. note::
+
+	You must turn it on with ``SOL_ENABLE_INTEROP``, as described in the :ref:`config and safety section<config>`.
+
+
+.. _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
+.. _interop examples: https://github.com/ThePhD/sol2/blob/develop/examples/interop
+.. _providing your own customization: https://github.com/ThePhD/sol2/blob/develop/examples/customization_convert_on_get.cpp

third_party/sol2/docs/source/api/stack_reference.rst

@@ -0,0 +1,29 @@
+stack_reference
+===============
+*zero-overhead object on the stack*
+
+
+When you work with a :doc:`sol::reference<reference>`, the object gotten from the stack has a reference to it made in the registry, keeping it alive. If you want to work with the Lua stack directly without having any additional references made, ``sol::stack_reference`` is for you. Its API is identical to ``sol::reference`` in every way, except it contains a ``int stack_index()`` member function that allows you to retrieve the stack index.
+
+Note that this will not pin the object since a copy is not made in the registry, meaning things can be pulled out from under it, the stack can shrink under it, things can be added onto the stack before this object's position, and what ``sol::stack_reference`` will point to will change. Please know what the Lua stack is and have discipline while managing your Lua stack when working at this level.
+
+All of the base types have ``stack`` versions of themselves, and the APIs are identical to their non-stack forms. This includes :doc:`sol::stack_table<table>`, :doc:`sol::stack_function<function>`, :doc:`sol::stack_protected_function<protected_function>`, :doc:`sol::stack_(light\_)userdata<userdata>` and :doc:`sol::stack_object<object>`. There is a special case for ``sol::stack_function``, which has an extra type called ``sol::stack_aligned_function`` (and similar ``sol::stack_aligned_protected_function``).
+
+
+stack_aligned_function
+----------------------
+
+This type is particular to working with the stack. It does not push the function object on the stack before pushing the arguments, assuming that the function present is already on the stack before going ahead and invoking the function it is targeted at. It is identical to :doc:`sol::function<function>` and has a protected counterpart as well. If you are working with the stack and know there is a callable object in the right place (i.e., at the top of the Lua stack), use this abstraction to have it call your stack-based function while still having the easy-to-use Lua abstractions.
+
+Furthermore, if you know you have a function in the right place alongside proper arguments on top of it, you can use the ``sol::stack_count`` structure and give its constructor the number of arguments off the top that you want to call your pre-prepared function with:
+
+.. literalinclude:: ../../../examples/stack_aligned_function.cpp
+	:caption: stack_aligned_function.cpp
+	:linenos:
+	:name: stack-aligned-function-example
+
+Finally, there is a special abstraction that provides further stack optimizations for ``sol::protected_function`` variants that are aligned, and it is called ``sol::stack_aligned_stack_handler_protected_function``. This typedef expects you to pass a ``stack_reference`` handler to its constructor, meaning that you have already placed an appropriate error-handling function somewhere on the stack before the aligned function. You can use ``sol::stack_count`` with this type as well.
+
+.. warning::
+
+	Do not use ``sol::stack_count`` with a ``sol::stack_aligned_protected_function``. The default behavior checks if the ``error_handler`` member variable is valid, and attempts to push the handler onto the stack in preparation for calling the function. This inevitably changes the stack. Only use ``sol::stack_aligned_protected_function`` with ``sol::stack_count`` if you know that the handler is not valid (it is ``nil`` or its ``error_handler.valid()`` function returns ``false``), or if you use ``sol::stack_aligned_stack_handler_protected_function``, which references an existing stack index that can be before the precise placement of the function and its arguments.

third_party/sol2/docs/source/api/state.rst

@@ -0,0 +1,205 @@
+state
+=====
+*owning and non-owning state holders for registry and globals*
+
+
+.. code-block:: cpp
+
+	class state_view;
+	
+	class state : state_view, std::unique_ptr<lua_State*, deleter>;
+
+The most important class here is ``state_view``. This structure takes a ``lua_State*`` that was already created and gives you simple, easy access to Lua's interfaces without taking ownership. ``state`` derives from ``state_view``, inheriting all of this functionality, but has the additional purpose of creating a fresh ``lua_State*`` and managing its lifetime for you in its constructors.
+
+The majority of the members between ``state_view`` and :doc:`sol::table<table>` are identical, with a few added for this higher-level type. Therefore, all of the examples and notes in :doc:`sol::table<table>` apply here as well.
+
+``state_view`` is cheap to construct and creates 2 references to things in the ``lua_State*`` while it is alive: the global Lua table, and the Lua C Registry.
+
+.. _state-automatic-handlers:
+
+``sol::state`` automatic handlers
+---------------------------------
+
+One last thing you should understand: constructing a ``sol::state`` does a few things behind-the-scenes for you, mostly to ensure compatibility and good error handler/error handling. The function it uses to do this is ``set_default_state``. They are as follows:
+
+* set a default panic handler with ``state_view::set_panic``/``lua_atpnic``
+* set a default ``sol::protected_function`` handler with ``sol::protected_function::set_default_handler``, using a ``sol::reference`` to ``&sol::detail::default_traceback_error_handler`` as the default handler function
+* set a default exception handler to ``&sol::detail::default_exception_handler``
+* register the state as the main thread (only does something for Lua 5.1, which does not have a way to get the main thread) using ``sol::stack::register_main_thread(L)``
+* register the LuaJIT C function exception handler with ``stack::luajit_exception_handler(L)``
+
+You can read up on the various panic and exception handlers on the :ref:`exceptions page<lua-handlers>`.
+
+sol::state_view does none of these things for you. If you want to make sure your self-created or self-managed state has the same properties, please apply this function once to the state. Please note that it will override your panic handler and, if using LuaJIT, your LuaJIT C function handler.
+
+.. warning::
+
+	It is your responsibility to make sure ``sol::state_view`` goes out of scope before you call ``lua_close`` on a pre-existing state, or before ``sol::state`` goes out of scope and its destructor gets called. Failure to do so can result in intermittent crashes because the ``sol::state_view`` has outstanding references to an already-dead ``lua_State*``, and thusly will try to decrement the reference counts for the Lua Registry and the Global Table on a dead state. Please use ``{`` and ``}`` to create a new scope, or other lifetime techniques, when you know you are going to call ``lua_close`` so that you have a chance to specifically control the lifetime of a ``sol::state_view`` object.
+
+enumerations
+------------
+
+.. code-block:: cpp
+	:caption: in-lua libraries
+	:name: lib-enum
+
+	enum class lib : char {
+	    base,
+	    package,
+	    coroutine,
+	    string,
+	    os,
+	    math,
+	    table,
+	    debug,
+	    bit32,
+	    io,
+	    ffi,
+	    jit,
+	    count // do not use
+	};
+
+This enumeration details the various base libraries that come with Lua. See the `standard lua libraries`_ for details about the various standard libraries.
+
+
+members
+-------
+
+.. code-block:: cpp
+	:caption: function: open standard libraries/modules
+	:name: open-libraries
+
+	template<typename... Args>
+	void open_libraries(Args&&... args);
+
+This function takes a number of :ref:`sol::lib<lib-enum>` as arguments and opens up the associated Lua core libraries.
+
+.. code-block:: cpp
+	:caption: function: script / safe_script / script_file / safe_script_file / unsafe_script / unsafe_script_file
+	:name: state-script-function
+
+	function_result script(const string_view& code, const std::string& chunk_name = "[string]", load_mode mode = load_mode::any);
+	protected_function_result script(const string_view& code, const environment& env, const std::string& chunk_name = "[string]", load_mode mode = load_mode::any);
+	template <typename ErrorFunc>
+	protected_function_result script(const string_view& code, ErrorFunc&& on_error, const std::string& chunk_name = "[string]", load_mode mode = load_mode::any);
+	template <typename ErrorFunc>
+	protected_function_result script(const string_view& code, const environment& env, ErrorFunc&& on_error, const std::string& chunk_name = "[string]", load_mode mode = load_mode::any);
+
+	function_result script_file(const std::string& filename, load_mode mode = load_mode::any);
+	protected_function_result script_file(const std::string& filename, const environment& env, load_mode mode = load_mode::any);
+	template <typename ErrorFunc>
+	protected_function_result script_file(const std::string& filename, ErrorFunc&& on_error, load_mode mode = load_mode::any);
+	template <typename ErrorFunc>
+	protected_function_result script_file(const std::string& filename, const environment& env, ErrorFunc&& on_error, load_mode mode = load_mode::any);
+
+If you need safety, please use the version of these functions with ``safe`` (such as ``safe_script(_file)``) appended in front of them. They will always check for errors and always return a ``sol::protected_function_result``. If you explicitly do not want to check for errors and want to simply invoke ``lua_error`` in the case of errors (which will call ``panic``), use ``unsafe_script(_file)`` versions.
+
+These functions run the desired blob of either code that is in a string, or code that comes from a filename, on the ``lua_State*``. It will not run isolated: any scripts or code run will affect code in the ``lua_State*`` the object uses as well (unless ``local`` is applied to a variable declaration, as specified by the Lua language). Code ran in this fashion is not isolated. If you need isolation, consider creating a new state or traditional Lua sandboxing techniques.
+
+If your script returns a value, you can capture it from the returned :ref:`sol::unsafe_function_result<unsafe-function-result>`/:ref:`sol::protected_function_result<protected-function-result>`. Note that the plain versions that do not take an environment or a callback function assume that the contents internally not only loaded properly but ran to completion without errors, for the sake of simplicity and performance.
+
+To handle errors when using the second overload, provide a callable function/object that takes a ``lua_State*`` as its first argument and a ``sol::protected_function_result`` as its second argument. ``sol::script_default_on_error`` and ``sol::script_pass_on_error`` are 2 functions provided by sol that will either generate a traceback error to return / throw (if throwing is allowed); or, pass the error on through and return it to the user (respectively). An example of having your:
+
+.. literalinclude:: ../../../examples/docs/state_script_safe.cpp
+	:linenos:
+	:name: state-script-safe
+
+You can also pass a :doc:`sol::environment<environment>` to ``script``/``script_file`` to have the script have sandboxed / contained in a way inside of a state. This is useful for runnig multiple different "perspectives" or "views" on the same state, and even has fallback support. See the :doc:`sol::environment<environment>` documentation for more details. 
+
+.. code-block:: cpp
+	:caption: function: require / require_file
+	:name: state-require-function
+
+	sol::object require(const std::string& key, lua_CFunction open_function, bool create_global = true);
+	sol::object require_script(const std::string& key, const std::string& code, bool create_global = true);
+	sol::object require_file(const std::string& key, const std::string& file, bool create_global = true);
+
+These functions play a role similar to `luaL_requiref`_ except that they make this functionality available for loading a one-time script or a single file. The code here checks if a module has already been loaded, and if it has not, will either load / execute the file or execute the string of code passed in. If ``create_global`` is set to true, it will also link the name ``key`` to the result returned from the open function, the code or the file. Regardless or whether a fresh load happens or not, the returned module is given as a single :doc:`sol::object<object>` for you to use as you see fit.
+
+Thanks to `Eric (EToreo) for the suggestion on this one`_!
+
+.. code-block:: cpp
+	:caption: function: load / load_file
+	:name: state-load-code
+
+	sol::load_result load(lua_Reader reader, void* data, const std::string& chunk_name = "[string]", load_mode mode = load_mode::any);
+	sol::load_result load(const string_view& code, const std::string& chunk_name = "[string]", load_mode mode = load_mode::any);
+	sol::load_result load_buffer(const char* buff, std::size_t buffsize, const std::string& chunk_name = "[string]", load_mode mode = load_mode::any);
+	sol::load_result load_file(const std::string& filename, load_mode mode = load_mode::any);
+
+These functions *load* the desired blob of either code that is in a string, or code that comes from a filename, on the ``lua_State*``. That blob will be turned into a Lua Function. It will not be run: it returns a ``load_result`` proxy that can be called to actually run the code, when you are ready. It can also be turned into a ``sol::function``, a ``sol::protected_function``, or some other abstraction that can serve to call the function. If it is called, it will run on the object's current ``lua_State*``: it is not isolated. If you need isolation, consider using :doc:`sol::environment<environment>`, creating a new state, or other Lua sandboxing techniques.
+
+Finally, if you have a custom source of data, you can use the ``lua_Reader`` overloaded function alongside passing in a ``void*`` pointing to a single type that has everything you need to run it. Use that callback to provide data to the underlying Lua implementation to read data, as explained `in the Lua manual`_.
+
+This is a low-level function and if you do not understand the difference between loading a piece of code versus running that code, you should be using :ref:`state_view::script<state-script-function>`.
+
+.. code-block:: cpp
+	:caption: function: do_string / do_file
+	:name: state-do-code
+
+	sol::protected_function_result do_string(const string_view& code);
+	sol::protected_function_result do_file(const std::string& filename);
+	sol::protected_function_result do_string(const string_view& code, sol::environment env);
+	sol::protected_function_result do_file(const std::string& filename, sol::environment env);
+
+These functions *loads and performs* the desired blob of either code that is in a string, or code that comes from a filename, on the ``lua_State*``. It *will* run, and then return a ``protected_function_result`` proxy that can be examined for either an error or the return value. This function does not provide a callback like :ref:`state_view::script<state-script-function>` does. It is a lower-level function that performs less checking and directly calls ``load(_file)`` before running the result, with the optional environment.
+
+It is advised that, unless you have specific needs or the callback function is not to your liking, that you work directly with :ref:`state_view::script<state-script-function>`.
+
+.. code-block:: cpp
+	:caption: function: global table / registry table
+
+	sol::global_table globals() const;
+	sol::table registry() const;
+
+Get either the global table or the Lua registry as a :doc:`sol::table<table>`, which allows you to modify either of them directly. Note that getting the global table from a ``state``/``state_view`` is usually unnecessary as it has all the exact same functions as a :doc:`sol::table<table>` anyhow.
+
+
+.. code-block:: cpp
+	:caption: function: set_panic
+	:name: set-panic
+
+	void set_panic(lua_CFunction panic);
+
+Overrides the panic function Lua calls when something unrecoverable or unexpected happens in the Lua VM. Must be a function of the that matches the ``int(lua_State*)`` function signature.
+
+
+.. code-block:: cpp
+	:caption: function: memory_used
+	:name: memory-used
+
+	std::size_t memory_used() const;
+
+Returns the amount of memory used *in bytes* by the Lua State.
+
+
+.. code-block:: cpp
+	:caption: function: collect_garbage
+	:name: collect-garbage
+
+	void collect_garbage();
+
+Attempts to run the garbage collector. Note that this is subject to the same rules as the Lua API's collect_garbage function: memory may or may not be freed, depending on dangling references or other things, so make sure you don't have tables or other stack-referencing items currently alive or referenced that you want to be collected.
+
+
+.. code-block:: cpp
+	:caption: function: make a table
+
+	sol::table create_table(int narr = 0, int nrec = 0);
+	template <typename Key, typename Value, typename... Args>
+	sol::table create_table(int narr, int nrec, Key&& key, Value&& value, Args&&... args);
+
+
+	template <typename... Args>
+	sol::table create_table_with(Args&&... args);
+	
+	static sol::table create_table(lua_State* L, int narr = 0, int nrec = 0);
+	template <typename Key, typename Value, typename... Args>
+	static sol::table create_table(lua_State* L, int narr, int nrec, Key&& key, Value&& value, Args&&... args);
+
+Creates a table. Forwards its arguments to :ref:`table::create<table-create>`. Applies the same rules as :ref:`table.set<set-value>` when putting the argument values into the table, including how it handles callable objects.
+
+.. _standard lua libraries: http://www.lua.org/manual/5.3/manual.html#6 
+.. _luaL_requiref: https://www.lua.org/manual/5.3/manual.html#luaL_requiref
+.. _Eric (EToreo) for the suggestion on this one: https://github.com/ThePhD/sol2/issues/90
+.. _in the Lua manual: https://www.lua.org/manual/5.3/manual.html#lua_Reader

third_party/sol2/docs/source/api/table.rst

@@ -0,0 +1,252 @@
+table
+=====
+*a representation of a Lua (meta)table*
+
+
+.. code-block:: cpp
+	
+	template <bool global>
+	class table_core;
+
+	typedef table_core<false> table;
+	typedef table_core<true> 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<proxy>`), ``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.
+
+
+members
+-------
+
+.. code-block:: cpp
+	:caption: constructor: table
+
+	table(lua_State* L, int index = -1);
+	table(lua_State* L, sol::new_table nt)
+
+The first takes a table from the Lua stack at the specified index and allows a person to use all of the abstractions therein. The second creates a new table using the capacity hints specified in ``sol::new_table``'s structure (``sequence_hint`` and ``map_hint``). If you don't care exactly about the capacity, create a table using ``sol::table my_table(my_lua_state, sol::create);``. Otherwise, specify the table creation size hints by initializing it manually through :doc:`sol::new_table's simple constructor<new_table>`.
+
+.. code-block:: cpp
+	:caption: function: get / traversing get
+	:name: get-value
+
+	template<typename... Args, typename... Keys>
+	decltype(auto) get(Keys&&... keys) const;
+
+	template<typename T, typename... Keys>
+	decltype(auto) traverse_get(Keys&&... keys) const;
+
+	template<typename T, typename Key>
+	decltype(auto) get_or(Key&& key, T&& otherwise) const;
+
+	template<typename T, typename Key, typename D>
+	decltype(auto) get_or(Key&& key, D&& otherwise) const;
+
+
+These functions retrieve items from the table. The first one (``get``) can pull out *multiple* values, 1 for each key value passed into the function. In the case of multiple return values, it is returned in a ``std::tuple<Args...>``. It is similar to doing ``return table["a"], table["b"], table["c"]``. Because it returns a ``std::tuple``, you can use ``std::tie``/``std::make_tuple`` on a multi-get to retrieve all of the necessary variables. The second one (``traverse_get``) pulls out a *single* value,	using each successive key provided to do another lookup into the last. It is similar to doing ``x = table["a"]["b"]["c"][...]``.
+
+If the keys within nested queries try to traverse into a table that doesn't exist, it will first pull out a ``nil`` value. If there are further lookups past a key that do not exist, the additional lookups into the nil-returned variable will cause a panic to be fired by the lua C API. If you need to check for keys, check with ``auto x = table.get<sol::optional<int>>( std::tie("a", "b", "c" ) );``, and then use the :doc:`optional<optional>` interface to check for errors. As a short-hand, easy method for returning a default if a value doesn't exist, you can use ``get_or`` instead.
+
+This function does not create tables where they do not exist.
+
+.. code-block:: cpp
+	:caption: function: raw get / traversing raw get
+	:name: raw-get-value
+
+	template<typename... Args, typename... Keys>
+	decltype(auto) raw_get(Keys&&... keys) const;
+
+	template<typename T, typename... Keys>
+	decltype(auto) traverse_raw_get(Keys&&... keys) const;
+
+	template<typename T, typename Key>
+	decltype(auto) raw_get_or(Key&& key, T&& otherwise) const;
+
+	template<typename T, typename Key, typename D>
+	decltype(auto) raw_get_or(Key&& key, D&& otherwise) const;
+
+
+Similar to :ref:`get<get-value>`, but it does so "raw" (ignoring metamethods on the table's metatable).
+
+.. code-block:: cpp
+	:caption: function: set / traversing set
+	:name: set-value
+
+	template<typename... Args>
+	table& set(Args&&... args);
+
+	template<typename... Args>
+	table& traverse_set(Args&&... args);
+
+These functions set items into the table. The first one (``set``) can set  *multiple* values, in the form ``key_a, value_a, key_b, value_b, ...``. It is similar to ``table[key_a] = value_a; table[key_b] = value_b, ...``. The second one (``traverse_set``) sets a *single* value, using all but the last argument as keys to do another lookup into the value retrieved prior to it. It is equivalent to ``table[key_a][key_b][...] = value;``.
+
+If the keys within nested queries try to traverse into a table that doesn't exist, it will first pull out a ``nil`` value. If there are further lookups past a key that do not exist, the additional lookups into the nil-returned variable will cause a panic to be fired by the lua C API.
+
+Please note how callables and lambdas are serialized, as there may be issues on GCC-based implementations. See this :ref:`note here<lambda-registry>`.
+
+This function does not create tables where they do not exist.
+
+.. code-block:: cpp
+	:caption: function: raw set / traversing raw set
+	:name: raw-set-value
+
+	template<typename... Args>
+	table& raw_set(Args&&... args);
+
+	template<typename... Args>
+	table& traverse_raw_set(Args&&... args);
+
+Similar to :ref:`set<set-value>`, but it does so "raw" (ignoring metamethods on the table's metatable).
+
+Please note how callables and lambdas are serialized, as there may be issues on GCC-based implementations. See this :ref:`note here<lambda-registry>`.
+
+.. note::
+
+	Value semantics are applied to all set operations. If you do not ``std::ref( obj )`` or specifically make a pointer with ``std::addressof( obj )`` or ``&obj``, it will copy / move. This is different from how :doc:`sol::function<function>` behaves with its call operator. Also note that this does not detect callables by default: see the :ref:`note here<binding-callable-objects>`.
+
+.. code-block:: cpp
+	:caption: function: set a function with the specified key into lua
+	:name: set-function
+
+	template<typename Key, typename Fx>
+	state_view& set_function(Key&& key, Fx&& fx, [...]);
+
+Sets the desired function to the specified key value. Note that it also allows for passing a member function plus a member object or just a single member function: however, using a lambda is almost always better when you want to bind a member function + class instance to a single function call in Lua. Also note that this will allow Lua to understand that a callable object (such as a lambda) should be serialized as a function and not as a userdata: see the :ref:`note here<binding-callable-objects>` for more details.
+
+.. code-block:: cpp
+	:caption: function: add
+
+	template<typename... Args>
+	table& add(Args&&... args);
+
+This function appends a value to a table. The definition of appends here is only well-defined for a table which has a perfectly sequential (and integral) ordering of numeric keys with associated non-null values (the same requirement for the :ref:`size<size-function>` function). Otherwise, this falls to the implementation-defined behavior of your Lua VM, whereupon is may add keys into empty 'holes' in the array (e.g., the first empty non-sequential integer key it gets to from ``size``) or perhaps at the very "end" of the "array". Do yourself the favor of making sure your keys are sequential.
+
+Each argument is appended to the list one at a time.
+
+.. code-block:: cpp
+	:caption: function: size
+	:name: size-function
+
+	std::size_t size() const;
+
+This function returns the size of a table. It is only well-defined in the case of a Lua table which has a perfectly sequential (and integral) ordering of numeric keys with associated non-null values.
+	
+.. code-block:: cpp
+	:caption: function: setting a usertype
+	:name: new-usertype
+
+	template<typename Class, typename... Args>
+	table& new_usertype(const std::string& name, Args&&... args);
+	template<typename Class, typename CTor0, typename... CTor, typename... Args>
+	table& new_usertype(const std::string& name, Args&&... args);
+	template<typename Class, typename... CArgs, typename... Args>
+	table& new_usertype(const std::string& name, constructors<CArgs...> ctor, Args&&... args);
+
+This class of functions creates a new :doc:`usertype<usertype>` with the specified arguments, providing a few extra details for constructors. After creating a usertype with the specified argument, it passes it to :ref:`set_usertype<set_usertype>`.
+	
+.. code-block:: cpp
+	:caption: function: creating an enum
+	:name: new-enum
+
+	template<bool read_only = true, typename... Args>
+	basic_table_core& new_enum(const std::string& name, Args&&... args);
+	template<typename T, bool read_only = true>
+	basic_table_core& new_enum(const std::string& name, std::initializer_list<std::pair<string_view, T>> items);
+	
+Use this function to create an enumeration type in Lua. By default, the enum will be made read-only, which creates a tiny performance hit to make the values stored in this table behave exactly like a read-only enumeration in C++. If you plan on changing the enum values in Lua, set the ``read_only`` template parameter in your ``new_enum`` call to false. The arguments are expected to come in ``key, value, key, value, ...`` list.
+
+If you use the second overload, you will create a (runtime) ``std::initializer_list``. This will avoid compiler overhead for excessively large enumerations. For this overload, hoever, you must pass the enumeration name as a template parameter first, and then the ``read_only`` parameter, like ``lua.new_enum<my_enum>( "my_enum", { {"a", my_enum:: a}, { "b", my_enum::b } } );``.
+
+.. _set_usertype:
+
+.. code-block:: cpp
+	:caption: function: setting a pre-created usertype
+	:name: set-usertype
+
+	template<typename T>
+	table& set_usertype(usertype<T>& user);
+	template<typename Key, typename T>
+	table& set_usertype(Key&& key, usertype<T>& user);
+
+Sets a previously created usertype with the specified ``key`` into the table. Note that if you do not specify a key, the implementation falls back to setting the usertype with a ``key`` of ``usertype_traits<T>::name``, which is an implementation-defined name that tends to be of the form ``{namespace_name 1}_[{namespace_name 2 ...}_{class name}``.
+
+.. code-block:: cpp
+	:caption: function: begin / end for iteration
+	:name: table-iterators
+
+	table_iterator begin () const;
+	table_iterator end() const;
+	table_iterator cbegin() const;
+	table_iterator cend() const;
+
+Provides (what can barely be called) `input iterators`_ for a table. This allows tables to work with single-pass, input-only algorithms (like ``std::for_each``). Note that manually getting an iterator from ``.begin()`` without a ``.end()`` or using postfix incrementation (``++mytable.begin()``) will lead to poor results. The Lua stack is manipulated by an iterator and thusly not performing the full iteration once you start is liable to ruin either the next iteration or break other things subtly. Use a C++11 ranged for loop, ``std::for_each``, or other algorithims which pass over the entire collection at least once and let the iterators fall out of scope.
+
+.. _iteration_note:
+.. warning::
+
+	The iterators you use to walk through a ``sol::table`` are NOT guaranteed to iterate in numeric order, or ANY kind of order. They may iterate backwards, forwards, in the style of cuckoo-hashing, by accumulating a visited list while calling ``rand()`` to find the next target, or some other crazy scheme. Now, no implementation would be crazy, but it is behavior specifically left undefined because there are many ways that your Lua package can implement the table type.
+
+	Iteration order is NOT something you should rely on. If you want to figure out the length of a table, call the length operation (``int count = mytable.size();`` using the sol API) and then iterate from ``1`` to ``count`` (inclusive of the value of count, because Lua expects iteration to work in the range of ``[1, count]``). This will save you some headaches in the future when the implementation decides not to iterate in numeric order.
+
+
+.. code-block:: cpp
+	:caption: function: iteration with a function
+	:name: table-for-each
+
+	template <typename Fx>
+	void for_each(Fx&& fx);
+
+A functional ``for_each`` loop that calls the desired function. The passed in function must take either ``sol::object key, sol::object value`` or take a ``std::pair<sol::object, sol::object> key_value_pair``. This version can be a bit safer as allows the implementation to definitively pop the key/value off the Lua stack after each call of the function.
+
+.. code-block:: cpp
+	:caption: function: operator[] access
+
+	template<typename T>
+	proxy<table&, T> operator[](T&& key);
+	template<typename T>
+	proxy<const table&, T> operator[](T&& key) const;
+
+Generates a :doc:`proxy<proxy>` that is templated on the table type and the key type. Enables lookup of items and their implicit conversion to a desired type. Lookup is done lazily.
+
+Please note how callables and lambdas are serialized, as there may be issues on GCC-based implementations. See this :ref:`note here<lambda-registry>`.
+
+.. code-block:: cpp
+	:caption: function: create a table with defaults
+	:name: table-create
+
+	table create(int narr = 0, int nrec = 0);
+	template <typename Key, typename Value, typename... Args>
+	table create(int narr, int nrec, Key&& key, Value&& value, Args&&... args);
+	
+	static table create(lua_State* L, int narr = 0, int nrec = 0);
+	template <typename Key, typename Value, typename... Args>
+	static table create(lua_State* L, int narr, int nrec, Key&& key, Value&& value, Args&&... args);
+
+Creates a table, optionally with the specified values pre-set into the table. If ``narr`` or ``nrec`` are 0, then compile-time shenanigans are used to guess the amount of array entries (e.g., integer keys) and the amount of hashable entries (e.g., all other entries).
+
+.. code-block:: cpp
+	:caption: function: create a table with compile-time defaults assumed
+	:name: table-create-with
+
+	template <typename... Args>
+	table create_with(Args&&... args);
+	template <typename... Args>
+	static table create_with(lua_State* L, Args&&... args);
+	
+
+Creates a table, optionally with the specified values pre-set into the table. It checks every 2nd argument (the keys) and generates hints for how many array or map-style entries will be placed into the table. Applies the same rules as :ref:`table.set<set-value>` when putting the argument values into the table, including how it handles callable objects.
+
+.. code-block:: cpp
+	:caption: function: create a named table with compile-time defaults assumed
+	:name: table-create-named
+
+	template <typename Name, typename... Args>
+	table create_named(Name&& name, Args&&... args);
+	
+
+Creates a table, optionally with the specified values pre-set into the table, and sets it as the key ``name`` in the table. Applies the same rules as :ref:`table.set<set-value>` when putting the argument values into the table, including how it handles callable objects.
+
+.. _input iterators: http://en.cppreference.com/w/cpp/concept/InputIterator

third_party/sol2/docs/source/api/this_environment.rst

@@ -0,0 +1,46 @@
+this_environment
+================
+*retrieving the environment of the calling function*
+
+
+Sometimes in C++ it's useful to know where a Lua call is coming from and what :doc:`environment<environment>` it is from. The former is covered by Lua's Debug API, which is extensive and is not fully wrapped up by sol2. But, sol2 covers the latter in letting you get the environment of the calling script / function, if it has one. ``sol::this_environment`` is a *transparent argument* and does not need to be passed in Lua scripts or provided when using :doc:`sol::function<function>`, similar to :doc:`sol::this_state<this_state>`:
+
+.. code-block:: cpp
+	:linenos:
+
+	#define SOL_CHECK_ARGUMENTS
+	#include <sol.hpp>
+
+	#include <iostream>
+
+
+	void env_check(sol::this_state ts, int x, sol::this_environment te) {
+		std::cout << "In C++, 'int x' is in the second position, and its value is: " << x << std::endl;
+		if (!te) {
+			std::cout << "function does not have an environment: exiting function early" << std::endl;
+			return;
+		}
+		sol::environment& env = te;
+		sol::state_view lua = ts;
+		sol::environment freshenv = lua["freshenv"];
+		bool is_same_env = freshenv == env;
+		std::cout << "env == freshenv : " << is_same_env << std::endl;
+	}
+
+	int main() {
+		sol::state lua;
+		sol::environment freshenv(lua, sol::create, lua.globals());
+		lua["freshenv"] = freshenv;
+		
+		lua.set_function("f", env_check);
+		
+		// note that "f" only takes 1 argument and is okay here
+		lua.script("f(25)", freshenv);
+		
+		return 0;
+	}
+
+
+Also see `this example`_ for more details.
+
+.. _this example: https://github.com/ThePhD/sol2/blob/develop/examples/environment_snooping.cpp

third_party/sol2/docs/source/api/this_state.rst

@@ -0,0 +1,13 @@
+this_state
+==========
+*transparent state argument for the current state*
+
+
+.. code-block:: cpp
+	
+	struct this_state;
+
+This class is a transparent type that is meant to be gotten in functions to get the current lua state a bound function or usertype method is being called from. It does not actually retrieve anything from lua nor does it increment the argument count, making it "invisible" to function calls in lua and calls through ``std::function<...>`` and :doc:`sol::function<function>` on this type. It can be put in any position in the argument list of a function:
+
+.. literalinclude:: ../../../examples/this_state.cpp
+	:linenos:

third_party/sol2/docs/source/api/thread.rst

@@ -0,0 +1,79 @@
+thread
+======
+*a separate state that can contain and run functions*
+
+.. code-block:: cpp
+	
+	class thread : public reference { /* ... */ };
+
+``sol::thread`` is a separate runnable part of the Lua VM that can be used to execute work separately from the main thread, such as with :doc:`coroutines<coroutine>`. To take a table or a coroutine and run it specifically on the ``sol::thread`` you either pulled out of lua or created, just get that function through the :ref:`state of the thread<thread_state>`
+
+.. note::
+
+	A CPU thread is not always equivalent to a new thread in Lua: ``std::this_thread::get_id()`` can be the same for 2 callbacks that have 2 distinct Lua threads. In order to know which thread a callback was called in, hook into :doc:`sol::this_state<this_state>` from your Lua callback and then construct a ``sol::thread``, passing in the ``sol::this_state`` for both the first and last arguments. Then examine the results of the status and ``is_...`` calls below.
+
+free function
+-------------
+
+.. code-block:: cpp
+	:caption: function: main_thread
+
+	main_thread(lua_State* current, lua_State* backup_if_bad_platform = nullptr);
+
+The function ``sol::main_thread( ... )`` retrieves the main thread of the application on Lua 5.2 and above *only*. It is designed for code that needs to be multithreading-aware (e.g., uses multiple :doc:`threads<thread>` and :doc:`coroutines<coroutine>`).
+
+.. warning::
+	
+	This code function will be present in Lua 5.1/LuaJIT, but only have proper behavior when given a single argument on Lua 5.2 and beyond. Lua 5.1 does not support retrieving the main thread from its registry, and therefore it is entirely suggested if you are writing cross-platform Lua code that you must store the main thread of your application in some global storage accessible somewhere. Then, pass this item into the ``sol::main_thread( possibly_thread_state, my_actual_main_state )`` and it will select that ``my_actual_main_state`` every time. If you are not going to use Lua 5.1 / LuaJIT, you can ignore the last parameter.
+
+
+members
+-------
+
+.. code-block:: cpp
+	:caption: constructor: thread
+
+	thread(stack_reference r);
+	thread(lua_State* L, int index = -1);
+	thread(lua_State* L, lua_State* actual_thread);
+
+Takes a thread from the Lua stack at the specified index and allows a person to use all of the abstractions therein. It can also take an actual thread state to make a thread from that as well.
+
+.. code-block:: cpp
+	:caption: function: view into thread_state()'s state
+
+	state_view state() const;
+
+This retrieves the current state of the thread, producing a :doc:`state_view<state>` that can be manipulated like any other. :doc:`Coroutines<coroutine>` pulled from Lua using the thread's state will be run on that thread specifically.
+
+.. _thread_state:
+
+.. code-block:: cpp
+	:caption: function: retrieve thread state object
+
+	lua_State* thread_state () const;
+
+This function retrieves the ``lua_State*`` that represents the thread.
+
+.. code-block:: cpp
+	:caption: current thread status
+
+	thread_status status () const;
+
+Retrieves the :doc:`thread status<types>` that describes the current state of the thread.
+
+.. code-block:: cpp
+	:caption: main thread status
+
+	bool is_main_thread () const;
+
+Checks to see if the thread is the main Lua thread.
+
+.. code-block:: cpp
+	:caption: function: thread creation
+	:name: thread-create
+
+	thread create();
+	static thread create (lua_State* L);
+
+Creates a new thread from the given a ``lua_State*``.

third_party/sol2/docs/source/api/tie.rst

@@ -0,0 +1,11 @@
+tie
+===
+*improved version of std::tie*
+
+
+`std::tie()`_ does not work well with :doc:`sol::function<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/tie.cpp
+	:linenos:
+
+.. _std::tie(): http://en.cppreference.com/w/cpp/utility/tuple/tie

third_party/sol2/docs/source/api/types.rst

@@ -0,0 +1,227 @@
+types
+=====
+*nil, lua_primitive type traits, and other fundamentals*
+
+The ``types.hpp`` header contains various fundamentals and utilities of Sol.
+
+
+enumerations
+------------
+
+.. code-block:: cpp
+	:caption: syntax of a function called by Lua
+	:name: call-syntax
+	
+	enum class call_syntax {
+    	dot = 0,
+    	colon = 1
+	};
+
+This enumeration indicates the syntax a function was called with in a specific scenario. There are two ways to call a function: with ``obj:func_name( ... )`` or ``obj.func_name( ... );`` The first one passes "obj" as the first argument: the second one does not. In the case of usertypes, this is used to determine whether the call to a :doc:`constructor/initializer<usertype>` was called with a ``:`` or a ``.``, and not misalign the arguments.
+
+.. code-block:: cpp
+	:caption: status of a Lua function call
+	:name: call-status
+	
+	enum class call_status : int {
+	    ok      = LUA_OK,
+	    yielded = LUA_YIELD,
+	    runtime = LUA_ERRRUN,
+	    memory  = LUA_ERRMEM,
+	    handler = LUA_ERRERR,
+	    gc      = LUA_ERRGCMM
+	};
+
+This strongly-typed enumeration contains the errors potentially generated by a call to a :doc:`protected function<protected_function>` or a :doc:`coroutine<coroutine>`.
+
+.. code-block:: cpp
+	:caption: status of a Lua thread
+	:name: thread-status
+	
+	enum class thread_status : int {
+	    ok  = LUA_OK,
+	    yielded = LUA_YIELD,
+	    runtime = LUA_ERRRUN,
+	    memory  = LUA_ERRMEM,
+	    gc      = LUA_ERRGCMM,
+	    handler = LUA_ERRERR,
+	    dead,
+	};
+
+This enumeration contains the status of a thread. The ``thread_status::dead`` state is generated when the thread has nothing on its stack and it is not running anything.
+
+.. code-block:: cpp
+	:caption: status of a Lua load operation
+	:name: load-status
+	
+	enum class load_status : int {
+	    ok      = LUA_OK,
+	    runtime = LUA_ERRSYNTAX,
+	    memory  = LUA_ERRMEM,
+	    gc      = LUA_ERRGCMM,
+	    file    = LUA_ERRFILE,
+	};
+
+This enumeration contains the status of a load operation from :ref:`state::load(_file)<state-load-code>`.
+
+.. code-block:: cpp
+	:caption: type enumeration
+	:name: type-enum
+
+	enum class type : int {
+	    none          = LUA_TNONE,
+	    nil           = LUA_TNIL,
+	    string        = LUA_TSTRING,
+	    number        = LUA_TNUMBER,
+	    thread        = LUA_TTHREAD,
+	    boolean       = LUA_TBOOLEAN,
+	    function      = LUA_TFUNCTION,
+	    userdata      = LUA_TUSERDATA,
+	    lightuserdata = LUA_TLIGHTUSERDATA,
+	    table         = LUA_TTABLE,
+	    poly          = none   | nil     | string   | number   | thread          |
+	                    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).
+
+
+type traits
+-----------
+
+.. code-block:: cpp
+	:caption: lua_type_of trait
+	:name: lua-type-of
+
+	template <typename T>
+	struct lua_type_of;
+
+This type trait maps a C++ type to a :ref:`type enumeration<type-enum>` value. The default value is ``type::userdata``.
+
+.. code-block:: cpp
+	:caption: primitive checking traits
+	:name: is-primitive
+	
+	template <typename T>
+	struct is_lua_primitive;
+
+	template <typename T>
+	struct is_proxy_primitive;
+
+
+This trait is used by :doc:`proxy<proxy>` to know which types should be returned as references to internal Lua memory (e.g., ``userdata`` types) and which ones to return as values (strings, numbers, :doc:`references<reference>`). ``std::reference_wrapper``, ``std::tuple<...>`` are returned as values, but their contents can be references. The default value is false.
+
+special types
+-------------
+
+.. code-block:: cpp
+	:caption: nil
+	:name: nil
+
+	strunil_t {};
+	const nil_t nil {};
+	bool operator==(nil_t, nil_t);
+	bool operator!=(nil_t, nil_t);
+
+``nil`` is a constant used to signify Lua's ``nil``, which is a type and object that something does not exist. It is comparable to itself, :doc:`sol::object<object>` and :doc:`proxy values<proxy>`.
+
+
+.. code-block:: cpp
+	:caption: non_null
+
+	template <typename T>
+	struct non_null {};
+
+A tag type that, when used with :doc:`stack::get\<non_null\<T*>><stack>`, does not perform a ``nil`` check when attempting to retrieve the userdata pointer.
+
+
+.. code-block:: cpp
+	:caption: type list
+	:name: type-list
+
+	template <typename... Args>
+	struct types;
+
+A type list that, unlike ``std::tuple<Args...>``, does not actually contain anything. Used to indicate types and groups of types all over Sol.
+
+
+functions
+---------
+
+.. code-block:: cpp
+	:caption: type_of
+
+	template<typename T>
+	type type_of();
+
+	type type_of(lua_State* L, int index);
+
+
+These functions get the type of a C++ type ``T``; or the type at the specified index on the Lua stack.
+
+.. code-block:: cpp
+	:caption: type checking convenience functions
+
+	int type_panic_string(lua_State* L, int index, type expected, type actual, const std::string& message);
+
+	int type_panic_c_str(lua_State* L, int index, type expected, type actual, const char* message);
+
+	int no_panic(lua_State*, int, type, type, const char*) noexcept;
+
+	void type_error(lua_State* L, int expected, int actual);
+
+	void type_error(lua_State* L, type expected, type actual);
+
+	void type_assert(lua_State* L, int index, type expected, type actual);
+
+	void type_assert(lua_State* L, int index, type expected);
+
+The purpose of these functions is to assert / throw / crash / error (or do nothing, as is the case with ``no_panic``). They're mostly used internally in the framework, but they're provided here if you should need them.
+
+.. code-block:: cpp
+	:caption: type name retrieval
+
+	std::string type_name(lua_State*L, type t);
+
+Gets the Lua-specified name of the :ref:`type<type-enum>`.
+
+structs
+-------
+
+.. code-block:: cpp
+
+	struct userdata_value {
+		void* value;
+	};
+
+	struct light_userdata_value {
+		void* value;
+	};
+
+	struct upvalue_index {
+    		int index;
+	};
+
+	struct raw_index {
+    		int index;
+	};
+
+	struct absolute_index {
+    		int index;
+	};
+
+	struct ref_index {
+    		int index;
+	};
+
+
+Types that differentiate between the two kinds of ``void*`` Lua hands back from its API: full userdata and light userdata, as well as a type that modifies the index passed to ``get`` to refer to `up values`_ These types can be used to trigger different underlying API calls to Lua when working with :doc:`stack<stack>` namespace and the ``push``/``get``/``pop``/``check`` functions.
+
+The ``raw_index`` type is used to tell a :doc:`sol::reference<reference>` type or similar that the desired index -- negative or not -- should be passed through directly to the API.
+
+The ``absolute_index`` type is used to tell a :doc:`sol::reference<reference>` type or similar that the desired index -- negative or not -- should be passed through Lua's `lua_absindex`_ function first to adjust where it is, and then given to the underlying API.
+
+The ``ref_index`` type is used to tell a :doc:`sol::reference<reference>` type or similar that it should look into the Lua C Registry for its type.
+
+.. _up values: http://www.Lua.org/manual/5.3/manual.html#4.4
+.. _lua_absindex: https://www.lua.org/manual/5.3/manual.html#lua_absindex

third_party/sol2/docs/source/api/unique_usertype_traits.rst

@@ -0,0 +1,50 @@
+unique_usertype_traits<T>
+=========================
+*trait for hooking special handles / pointers*
+
+
+.. code-block:: cpp
+	:caption: unique_usertype
+	:name: unique-usertype
+
+	template <typename T>
+	struct unique_usertype_traits {
+		typedef T type;
+		typedef T actual_type;
+		static const bool value = false;
+
+		static bool is_null(const actual_type&) {...}
+
+		static type* get (const actual_type&) {...}
+	};
+
+This is a customization point for users who need to *work with special kinds of pointers/handles*. The traits type alerts the library that a certain type is to be pushed as a special userdata with special deletion / destruction semantics, like many smart pointers / custom smart pointers / handles. It is already defined for ``std::unique_ptr<T, D>`` and ``std::shared_ptr<T>`` and works properly with those types (see `shared_ptr here`_ and `unique_ptr here`_ for examples). You can specialize this to get ``unique_usertype_traits`` semantics with your code. For example, here is how ``boost::shared_ptr<T>`` would look:
+
+.. code-block:: cpp
+	
+	namespace sol {
+		template <typename T>
+		struct unique_usertype_traits<boost::shared_ptr<T>> {
+			typedef T type;
+			typedef boost::shared_ptr<T> actual_type;
+			static const bool value = true;
+    
+			static bool is_null(const actual_type& value) {
+				return value == nullptr;
+			}
+
+			static type* get (const actual_type& p) {
+				return p.get();
+			}
+		}
+	}
+
+This will allow the library to properly handle ``boost::shared_ptr<T>``, 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::
+	
+	If ``is_null`` triggers (returns ``true``), a ``nil`` value will be pushed into Lua rather than an empty structure.
+
+
+.. _shared_ptr here: https://github.com/ThePhD/sol2/blob/develop/examples/shared_ptr.cpp
+.. _unique_ptr here: https://github.com/ThePhD/sol2/blob/develop/examples/unique_ptr.cpp

third_party/sol2/docs/source/api/user.rst

@@ -0,0 +1,19 @@
+light<T>/user<T>
+================
+*utility class for the cheapest form of (light) userdata*
+
+
+.. code-block:: cpp
+	
+	template <typename T>
+	struct user;
+
+	template <typename T>
+	struct light;
+
+
+``sol::user<T>`` and ``sol::light<T>`` are two utility classes that do not participate in the full :doc:`sol::usertype\<T><usertype>` system. The goal of these classes is to provide the most minimal memory footprint and overhead for putting a single item and getting a single item out of Lua. ``sol::user<T>``, when pushed into Lua, will create a thin, unnamed metatable for that instance specifically which will be for calling its destructor. ``sol::light<T>`` specifically pushes a reference / pointer into Lua as a ``sol::type::lightuserdata``.
+
+If you feel that you do not need to have something participate in the full :doc:`usertype\<T><usertype>` system, use the utility functions ``sol::make_user( ... )`` and ``sol::make_light( ... )`` to create these types and store them into Lua. You can get them off the Lua stack / out of the Lua system by using the same retrieval techniques on ``get`` and ``operator[]`` on tables and with stack operations.
+
+Both have implicit conversion operators to ``T*`` and ``T&``, so you can set them immediately to their respective pointer and reference types if you need them.

third_party/sol2/docs/source/api/userdata.rst

@@ -0,0 +1,12 @@
+userdata
+========
+*reference to a userdata*
+
+.. code-block:: cpp
+	:caption: (light\_)userdata reference
+
+	class userdata : public table;
+
+	class light_userdata : public table;
+
+These types are meant to hold a reference to a (light) userdata from Lua and make it easy to push an existing userdata onto the stack. It is essentially identical to :doc:`table<table>` in every way, just with a definitive C++ type that ensures the type is some form of userdata (helpful for trapping type errors with :doc:`safety features turned on<../safety>`). You can also use its ``.is<T>()`` and ``.as<T>()`` methods to check if its of a specific type and retrieve that type, respectively.

third_party/sol2/docs/source/api/usertype.rst

@@ -0,0 +1,292 @@
+usertype<T>
+===========
+*structures and classes from C++ made available to Lua code*
+
+
+.. note::
+	
+	``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`_.
+
+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).
+
+enumerations
+------------
+
+.. _meta_function_enum:
+
+.. code-block:: cpp
+	:caption: meta_function enumeration for names
+	:linenos:
+
+	enum class meta_function {
+		construct,
+		index,
+		new_index,
+		mode,
+		call,
+		call_function = call,
+		metatable,
+		to_string,
+		length,
+		unary_minus,
+		addition,
+		subtraction,
+		multiplication,
+		division,
+		modulus,
+		power_of,
+		involution = power_of,
+		concatenation,
+		equal_to,
+		less_than,
+		less_than_or_equal_to,
+		garbage_collect,
+		floor_division,
+		bitwise_left_shift,
+		bitwise_right_shift,
+		bitwise_not,
+		bitwise_and,
+		bitwise_or,
+		bitwise_xor,
+		pairs,
+		ipairs,
+		next,
+		type,
+		type_info,
+	};
+
+	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
+-------
+
+.. code-block:: cpp
+	:caption: function: usertype<T> constructor
+	:name: usertype-constructor
+
+	template<typename... Args>
+	usertype<T>(Args&&... args);
+
+
+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<constructor>`). Names can either be strings, :ref:`special meta_function enumerations<meta_function_enum>`, or one of the special indicators for initializers.
+
+
+usertype constructor 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:
+ 
+..  _constructor:
+
+* ``"{name}", constructors<T(), T(arg-1-0), T(arg-2-0, arg-2-1), ...>``
+	- Specify the constructors to be bound under ``name``: list constructors by specifying their function signature with ``class_type(arg0, arg1, ... argN)``
+	- If you pass the ``constructors<...>`` argument first when constructing the usertype, then it will automatically be given a ``"{name}"`` of ``"new"``
+* ``"{name}", constructors<Type-List-0, Type-List-1, ...>``
+	- This syntax is longer and provided for backwards-compatibility: the above argument syntax is shorter and cleaner
+	- ``Type-List-N`` must be a ``sol::types<Args...>``, where ``Args...`` is a list of types that a constructor takes. Supports overloading by default
+	- If you pass the ``constructors<...>`` argument first when constructing the usertype, then it will automatically be given a ``"{name}"`` of ``"new"``
+* ``"{name}", sol::initializers( func1, func2, ... )``
+	- Used to handle *initializer functions* that need to initialize the memory itself (but not actually allocate the memory, since that comes as a userdata block from Lua)
+	- Given one or more functions, provides an overloaded Lua function for creating the specified type
+		+ The function must have the argument signature ``func( T*, Arguments... )`` or ``func( T&, Arguments... )``, where the pointer or reference will point to a place of allocated memory that has an uninitialized ``T``. Note that Lua controls the memory, so performing a ``new`` and setting it to the ``T*`` or ``T&`` is a bad idea: instead, use ``placement new`` to invoke a constructor, or deal with the memory exactly as you see fit
+* ``{anything}, sol::factories( func1, func2, ... )``
+	- Used to indicate that a factory function (e.g., something that produces a ``std::unique_ptr<T, ...>``, ``std::shared_ptr<T>``, ``T``, or similar) will be creating the object type
+	- Given one or more functions, provides an overloaded function for invoking
+		+ The functions can take any form and return anything, since they're just considered to be some plain function and no placement new or otherwise needs to be done. Results from this function will be pushed into Lua according to the same rules as everything else.
+		+ Can be used to stop the generation of a ``.new()`` default constructor since a ``sol::factories`` entry will be recognized as a constructor for the usertype
+		+ If this is not sufficient, see next 2 entries on how to specifically block a constructor
+* ``{anything}, {some_factory_function}``
+	- Essentially binds whatever the function is to name ``{anything}``
+	- When used WITH the ``sol::no_constructor`` option below (e.g. ``"new", sol::no_constructor`` and after that having ``"create", &my_creation_func``), one can remove typical constructor avenues and then only provide specific factory functions. Note that this combination is similar to using the ``sol::factories`` method mentioned earlier in this list. To control the destructor as well, see further below
+* ``sol::call_constructor, {valid constructor / initializer / factory}``
+	- The purpose of this is to enable the syntax ``local v = my_class( 24 )`` and have that call a constructor; it has no other purpose
+	- 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
+	- 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*
+
+usertype destructor options
++++++++++++++++++++++++++++
+
+If you don't specify anything at all and the type is `destructible`_, then a destructor will be bound to the garbage collection metamethod. Otherwise, the following are special ways to handle the destruction of a usertype:
+
+* ``"__gc", sol::destructor( func )`` or ``sol::meta_function::garbage_collect, sol::destructor( func )``
+	- Creates a custom destructor that takes an argument ``T*`` or ``T&`` and expects it to be destructed/destroyed. Note that lua controls the memory and thusly will deallocate the necessary space AFTER this function returns (e.g., do not call ``delete`` as that will attempt to deallocate memory you did not ``new``)
+	- If you just want the default constructor, you can replace the second argument with ``sol::default_destructor``
+	- The usertype will error / throw if you specify a destructor specifically but do not map it to ``sol::meta_function::gc`` or a string equivalent to ``"__gc"``
+
+.. note::
+
+	You MUST specify ``sol::destructor`` around your destruction function, otherwise it will be ignored.
+
+
+.. _automagical-registration:
+
+usertype automatic meta functions
++++++++++++++++++++++++++++++++++
+
+If you don't specify a ``sol::meta_function`` name (or equivalent string metamethod name) and the type ``T`` supports certain operations, sol2 will generate the following operations provided it can find a good default implementation:
+
+* for ``to_string`` operations where ``std::ostream& operator<<( std::ostream&, const T& )``, ``obj.to_string()``, or ``to_string( const T& )`` (in the namespace) exists on the C++ type
+	- a ``sol::meta_function::to_string`` operator will be generated
+	- writing is done into either
+		+ a ``std::ostringstream`` before the underlying string is serialized into Lua
+		+ directly serializing the return value of ``obj.to_string()`` or ``to_string( const T& )``
+	- order of preference is the ``std::ostream& operator<<``, then the member function ``obj.to_string()``, then the ADL-lookup based ``to_string( const T& )``
+	- if you need to turn this behavior off for a type (for example, to avoid compiler errors for ADL conflicts), specialize ``sol::is_to_stringable<T>`` for your type to be ``std::false_type``, like so:
+
+.. code-block:: cpp
+
+	namespace sol {
+		template <>
+		struct is_to_stringable<my_type> : std::false_type {};
+	}
+
+
+* for call operations where ``operator()( parameters ... )`` exists on the C++ type
+	- a ``sol::meta_function::call`` operator will be generated
+	- the function call operator in C++ must not be overloaded, otherwise sol will be unable to bind it automagically
+	- the function call operator in C++ must not be templated, otherwise sol will be unable to bind it automagically
+	- if it is overloaded or templated, it is your reponsibility to bind it properly
+* for automatic iteration where ``begin()`` and ``end()`` exist on the C++ type
+	- a ``sol::meta_function::pairs`` operator is generated for you
+	- Allows you to iterate using ``for k, v in pairs( obj ) do ... end`` in Lua
+	- **Lua 5.2 and better only: LuaJIT does not allow this, Lua 5.1 does NOT allow this**
+* for cases where ``.size()`` exists on the C++ type
+	- the length operator of Lua (``#my_obj``) operator is generated for you
+* for comparison operations where ``operator <`` and ``operator <=`` exist on the C++ type 
+	- These two ``sol::meta_function::less_than(_or_equal_to)`` are generated for you
+	- ``>`` and ``>=`` operators are generated in Lua based on ``<`` and ``<=`` operators
+* for ``operator==``
+	- An equality operator will always be generated, doing pointer comparison if ``operator==`` on the two value types is not supported or doing a reference comparison and a value comparison if ``operator==`` is supported
+* heterogenous operators cannot be supported for equality, as Lua specifically checks if they use the same function to do the comparison: if they do not, then the equality method is not invoked; one way around this would be to write one ``int super_equality_function(lua_State* L) { ... }``, pull out arguments 1 and 2 from the stack for your type, and check all the types and then invoke ``operator==`` yourself after getting the types out of Lua (possibly using :ref:`sol::stack::get<stack-get>` and :ref:`sol::stack::check_get<stack-check-get>`)
+
+
+
+usertype regular function options
++++++++++++++++++++++++++++++++++
+
+Otherwise, the following is used to specify functions to bind on the specific usertype for ``T``.
+
+* ``"{name}", &free_function``
+	- Binds a free function / static class function / function object (lambda) to ``"{name}"``. If the first argument is ``T*`` or ``T&``, then it will bind it as a member function. If it is not, it will be bound as a "static" function on the lua table
+* ``"{name}", &type::function_name`` or ``"{name}", &type::member_variable``
+	- Binds a typical member function or variable to ``"{name}"``. In the case of a member variable or member function, ``type`` must be ``T`` or a base of ``T``
+* ``"{name}", sol::readonly( &type::member_variable )``
+	- Binds a typical variable to ``"{name}"``. Similar to the above, but the variable will be read-only, meaning an error will be generated if anything attemps to write to this variable
+* ``"{name}", sol::as_function( &type::member_variable )``
+	- Binds a typical variable to ``"{name}"`` *but forces the syntax to be callable like a function*. This produces a getter and a setter accessible by ``obj:name()`` to get and ``obj:name(value)`` to set.
+* ``"{name}", sol::property( getter_func, setter_func )``
+	- Binds a typical variable to ``"{name}"``, but gets and sets using the specified setter and getter functions. Not that if you do not pass a setter function, the variable will be read-only. Also not that if you do not pass a getter function, it will be write-only
+* ``"{name}", sol::var( some_value )`` or ``"{name}", sol::var( std::ref( some_value ) )``
+	- Binds a typical variable to ``"{name}"``, optionally by reference (e.g., refers to the same memory in C++). This is useful for global variables / static class variables and the like
+* ``"{name}", sol::overload( Func1, Func2, ... )``
+	- Creates an oveloaded member function that discriminates on number of arguments and types
+	- Dumping multiple functions out with the same name **does not make an overload**: you must use **this syntax** in order for it to work
+* ``sol::base_classes, sol::bases<Bases...>``
+	- Tells a usertype what its base classes are. You need this to have derived-to-base conversions work properly. See :ref:`inheritance<usertype-inheritance>`
+
+
+runtime functions
+-----------------
+
+You can add functions at runtime **to the whole class** (not to individual objects). Set a name under the metatable name you bound using ``new_usertype`` to an object. For example:
+
+.. literalinclude:: ../../../examples/docs/runtime_extension.cpp
+	:caption: runtime_extension.cpp
+	:name: runtime-extension-example
+	:linenos:
+
+.. note::
+
+	You cannot add functions to an individual object. You can only add functions to the whole class / usertype.
+
+
+overloading
+-----------
+
+Functions set on a usertype support overloading. See :doc:`here<overload>` for an example.
+
+
+.. _usertype-inheritance:
+
+inheritance
+-----------
+
+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.)
+
+For the rest of us safe individuals out there: You must specify the ``sol::base_classes`` tag with the ``sol::bases<Types...>()`` argument, where ``Types...`` are all the base classes of the single type ``T`` that you are making a usertype out of.
+
+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.
+
+.. literalinclude:: ../../../examples/docs/inheritance.cpp
+	:caption: inheritance.cpp
+	:name: inheritance-example
+	:linenos:
+	:emphasize-lines: 23
+
+.. 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.
+
+.. note::
+	
+	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.
+
+.. _automagical:
+
+automagical usertypes
+---------------------
+
+Usertypes automatically register special functions, whether or not they're bound using `new_usertype`. You can turn this off by specializing the ``sol::is_automagical<T>`` template trait:
+
+.. code-block:: cpp
+
+	struct my_strange_nonconfirming_type { /* ... */ };
+
+	namespace sol {
+		template <>
+		struct is_automagical<my_strange_nonconforming_type> : std::false_type {};
+	}
+
+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.
+
+compilation speed
+-----------------
+
+.. note::
+
+	MSVC and clang/gcc may need additional compiler flags to handle compiling extensive use of usertypes. See: :ref:`the error documentation<compilation_errors_warnings>` for more details.
+
+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.*
+
+.. _destructible: http://en.cppreference.com/w/cpp/types/is_destructible
+.. _default_constructible: http://en.cppreference.com/w/cpp/types/is_constructible
+.. _small starter example here: https://github.com/ThePhD/sol2/blob/develop/examples/usertype_basics.cpp
+.. _runtime extensible: https://github.com/ThePhD/sol2/blob/develop/examples/usertype_advanced.cpp#L81
+.. _the metamethods in the Lua manual: https://www.lua.org/manual/5.3/manual.html#2.4

third_party/sol2/docs/source/api/usertype_memory.rst

@@ -0,0 +1,63 @@
+usertype memory
+===============
+*memory layout of usertypes*
+
+.. 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<unique_usertype_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``.
+
+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.
+
+.. warning::
+
+	The layout of memory described below does **not** take into account alignment. sol2 now takes alignment into account and aligns memory, which is important for misbehaving allocators and types that do not align well to the size of a pointer on their system. If you need to obtain proper alignments for usertypes stored in userdata pointers, **please** use the detail functions named ``sol::detail::align_usertype_pointer``, ``sol::detail::align_usertype``, and ``sol::detail::align_usertype_unique``. This will shift a ``void*`` pointer by the appropriate amount to reach a certain section in memory. For almost all other use cases, please use ``void* memory = lua_touserdata(L, index);``, followed by ``memory = sol::detail::align_usertype_pointer( memory );`` to adjust the pointer to be at the right place.
+
+
+.. warning::
+
+	The diagrams and explanations from below is only guaranteed to work 100% of the time if you define :ref:`SOL_NO_MEMORY_ALIGNMENT<config-memory>`. Be aware that this may result in unaligned reads/writes, which can crash some older processors and trigger static analyzer/instrumentation tool warnings, like Clang's Address Sanitizer (ASan).
+
+
+To retrieve a ``T``
+-------------------
+
+If you want to retrieve a ``T*`` pointer to the data managed by a sol2 userdata and are not using sol2's abstractions to do it (e.g., messing with the plain Lua C API), simply use ``lua_touserdata`` to get the ``void*`` pointer. Then, execute a ``T* object_pointer = *static_cast<T**>(the_void_pointer);``. Every type pushed into C++ that is classified as a userdata (e.g., all user-defined objects that are not covered by the stack abstraction's basic types) can be retrieved in this format, whether they are values or pointers or ``unique_ptr``. The reasons for why this works is below.
+
+For ``T``
+---------
+
+These are classified with a metatable name generally derived from the class name itself.
+
+The data layout for references is as follows::
+
+	|        T*        |               T              |
+	^-sizeof(T*) bytes-^-sizeof(T) bytes, actual data-^
+
+Lua will clean up the memory itself but does not know about any destruction semantics T may have imposed, so when we destroy this data we simply call the destructor to destroy the object and leave the memory changes to for lua to handle after the "__gc" method exits.
+
+
+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<T>`` 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::
+
+	|        T*        |
+	^-sizeof(T*) bytes-^
+
+That is it. No destruction semantics need to be called.
+
+For ``std::unique_ptr<T, D>`` and ``std::shared_ptr<T>``
+--------------------------------------------------------
+
+These are classified as :ref:`"unique usertypes"<unique-usertype>`, and have a special metatable for them as well. The special metatable is either generated when you add the usertype to Lua using :ref:`set_usertype<set-usertype>` or when you first push one of these special types. In addition to the data, a deleter function that understands the following layout is injected into the userdata layout.
+
+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.

third_party/sol2/docs/source/api/var.rst

@@ -0,0 +1,9 @@
+var
+===
+*For hooking up static / global variables to Lua usertypes*
+
+
+The sole purpose of this tagging type is to work with :doc:`usertypes<usertype>` to provide ``my_class.my_static_var`` access, and to also provide reference-based access as well.
+
+.. literalinclude:: ../../../examples/usertype_var.cpp
+	:linenos:

third_party/sol2/docs/source/api/variadic_args.rst

@@ -0,0 +1,25 @@
+variadic_args
+=============
+*transparent argument to deal with multiple parameters to a function*
+
+
+.. code-block:: cpp
+
+	struct variadic_args;
+
+This class is meant to represent every single argument at its current index and beyond in a function list. It does not increment the argument count and is thus transparent. You can place it anywhere in the argument list, and it will represent all of the objects in a function call that come after it, whether they are listed explicitly or not.
+
+``variadic_args`` also has ``begin()`` and ``end()`` functions that return (almost) random-acess iterators. These return a proxy type that can be implicitly converted to a type you want, much like the :doc:`table proxy type<proxy>`.
+
+.. literalinclude:: ../../../examples/variadic_args.cpp
+	:linenos:
+
+You can also "save" arguments and the like later, by stuffing them into a ``std::vector<sol::object>`` or something similar that serializes them into the registry. Below is an example of saving all of the arguments provided by ``sol::variadic_args`` in a lambda capture variable called ``args``.
+
+.. literalinclude:: ../../../examples/variadic_args_storage.cpp
+	:linenos:
+
+Finally, note that you can use ``sol::variadic_args`` constructor to "offset"/"shift over" the arguments being viewed:
+
+.. literalinclude:: ../../../examples/variadic_args_shifted.cpp
+	:linenos:

third_party/sol2/docs/source/api/variadic_results.rst

@@ -0,0 +1,11 @@
+variadic_results
+================
+*push multiple disparate arguments into lua*
+
+.. code-block:: cpp
+	
+	struct variadic_results : std::vector<object> { ... };
+
+This type allows someone to prepare multiple returns before returning them into Lua. It derives from ``std::vector``, so it can be used exactly like that, and objects can be added using the various constructors and functions relating to :doc:`sol::object<object>`. You can see it and other return-type helpers in action `here`_.
+
+.. _here: https://github.com/ThePhD/sol2/blob/develop/examples/multi_results.cpp

third_party/sol2/docs/source/api/yielding.rst

@@ -0,0 +1,10 @@
+yielding
+========
+*telling a C++ function to yield its results into Lua*
+
+.. code-block:: cpp
+
+	template <typename F>
+	yield_wrapper<F> yielding( F&& f )
+
+``sol::yielding`` is useful for calling C++ functions which need to yield into a Lua coroutine. It is a wrapper around a single argument which is expected to be bound as a function. You can pass it anywhere a regular function can be bound, **except for in usertype definitions**.

third_party/sol2/docs/source/benchmarks.rst

@@ -0,0 +1,104 @@
+benchmarks
+==========
+because somebody is going to ask eventually...
+----------------------------------------------
+
+
+Here are measurements of the *overhead that libraries impose around the Lua C API*: that is, the cost of abstracting / wrapping the plain Lua C API. Measurements are (at the time of writing) done with all libraries compiled against a DLL version of Lua 5.3.3 to make sure each Lua call has the same overhead between libraries (no Link Time Optimizations or other static library optimizations).
+
+These are some informal and formal benchmarks done by both the developers of sol and other library developers / users. We leave you to interpret the data as you see fit.
+
+* `lua_binding_benchmarks`_ by satoren (developer of `kaguya`_) (`sol`_ is the "sol2" entry)
+* `lua-bindings-shootout`_ by ThePhD (developer of `sol`_)
+
+As of the writing of this documentation (May 17th, 2018), :doc:`sol<index>` seems to take the cake in most categories for speed! Below are some graphs from `lua-bindings-shootout`_. You can read the benchmarking code there if you think something was done wrong, and submit a pull requests or comment on something to make sure that ThePhD is being honest about his work. All categories are the performance of things described at the top of the :doc:`feature table<features>`.
+
+Note that sol here makes use of its more performant variants (see :doc:`c_call<api/c_call>` and others), and ThePhD also does his best to make use of the most performant variants for other frameworks by disabling type checks where possible as well (Thanks to Liam Devine of OOLua for explaining how to turn off type checks in OOLua).
+
+Bars go up to the average execution time. Lower is better. Reported times are for the desired operation run through `nonius`_. Results are sorted from top to bottom by best to worst. Note that there are error bars to show potential variance in performance: generally, same-sized errors bars plus very close average execution time implies no significant difference in speed, despite the vastly different abstraction techniques used.
+
+.. image:: /media/bench/member_function_call.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/member%20function%20call.png
+	:alt: bind several member functions to an object and call them in Lua code
+
+.. image:: /media/bench/userdata_variable_access.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/userdata%20variable%20access.png
+	:alt: bind a variable to an object and call it in Lua code
+
+.. image:: /media/bench/userdata_variable_access_large.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/userdata%20variable%20access%20large.png
+	:alt: bind MANY variables to an object and access them in Lua code
+
+.. image:: /media/bench/c_function_through_lua_in_c.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/c%20function%20through%20lua%20in%20c.png
+	:alt: retrieve a C function bound in Lua and call it from C++
+
+.. image:: /media/bench/stateful_function_object.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/stateful%20function%20object.png
+	:alt: bind a stateful C function (e.g., a mutable lambda), retrieve it, and call it from C++
+
+.. image:: /media/bench/c_function.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/c%20function.png
+	:alt: call a C function through Lua code
+
+.. image:: /media/bench/lua_function_in_c.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/lua%20function%20in%20c.png
+	:alt: retrieve a plain Lua function and call it from C++
+
+.. image:: /media/bench/multi_return.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/multi%20return.png
+	:alt: return mutliple objects from C++ using std::tuple or through a library-defined mechanism
+
+.. image:: /media/bench/multi_return_lua.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/multi%20return%20lua.png
+	:alt: return mutliple objects from C++ using std::tuple or through a library-defined mechanism and use it in Lua
+
+.. image:: /media/bench/table_global_string_get.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/table%20global%20string%20get.png
+	:alt: retrieve a value from the global table
+
+.. image:: /media/bench/table_global_string_set.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/table%20global%20string%20set.png
+	:alt: set a value into the global table
+
+.. image:: /media/bench/table_chained_get.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/table%20chained%20get.png
+	:alt: measures the cost of doing consecutive lookups into a table that exists from C++; some libraries fail here because they do not do lazy evaluation or chaining properly
+
+.. image:: /media/bench/table_get.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/table%20get.png
+	:alt: measures the cost of retrieving a value from a table in C++; this nests 1 level so as to not be equivalent to any measured global table get optimzations
+
+.. image:: /media/bench/table_chained_set.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/table%20chained%20set.png
+	:alt: measures the cost of doing consecutive lookups into a table that exists from C++ and setting the final value; some libraries fail here because they do not do lazy evaluation or chaining properly
+
+.. image:: /media/bench/table_set.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/table%20set.png
+	:alt: measures the cost of setting a value into a table in C++; this nests 1 level so as to not be equivalent to any measured global table set optimzations
+
+.. image:: /media/bench/return_userdata.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/return%20userdata.png
+	:alt: bind a C function which returns a custom class by-value and call it through Lua code
+
+.. image:: /media/bench/optional_failure.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/optional%20failure.png
+	:alt: retrieve an item from a table that does not exist in Lua and check for its existence (testing the cost of the failure case)
+
+.. image:: /media/bench/optional_half_failure.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/optional%20half%20failure.png
+	:alt: retrieve an item from a table that does not exist in Lua and check for its existence (testing the cost of the first level success, second level failure case)
+
+.. image:: /media/bench/optional_success.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/optional%20success.png
+	:alt: retrieve an item from a table that does not exist in Lua and check for its existence (testing the cost of the success case)
+
+.. image:: /media/bench/base_derived.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bindings-shootout/master/benchmark_results/base%20derived.png
+	:alt: retrieve base class pointer out of Lua without knowing exact derived at compile-time, and have it be correct for multiple-inheritance
+
+.. _lua-bindings-shootout: https://github.com/ThePhD/lua-bindings-shootout
+.. _lua_binding_benchmarks: http://satoren.github.io/lua_binding_benchmark/
+.. _kaguya: https://github.com/satoren/kaguya
+.. _sol: https://github.com/ThePhD/sol2
+.. _nonius: https://github.com/rmartinho/nonius/

third_party/sol2/docs/source/build.rst

@@ -0,0 +1,8 @@
+Build
+=====
+
+sol2 comes with a CMake script in the top level. It is primarily made for building and running the examples and tests, but it includes exported and configured targets (``sol2``, ``sol2_single``) for your use.
+
+sol2 also comes with a Meson Script. If things stop working, file a bug report.
+
+

third_party/sol2/docs/source/codecvt.rst

@@ -0,0 +1,14 @@
+unicode transformation format handling
+======================================
+because this is surprisingly hard using standard C++
+----------------------------------------------------
+
+.. note::
+
+	The ``<codecvt>`` header is no longer used and sol2 now converts utf8, utf16, and utf32 with internal routines. If you have a problem with the transcoding, please `file an issue report`_.
+
+``std::(w)string(u16/u32)`` are assumed to be in the platform's native wide (for ``wstring``) or unicode format. Lua canonically stores its string literals as utf8 and embraces utf8, albeit its storage is simply a sequence of bytes that are also null-terminated (it is also counted and the size is kept around, so embedded nulls can be used in the string). Therefore, if you need to interact with the unicode or wide alternatives of strings, runtime conversions are performed from the (assumed) utf8 string data into other forms. These conversions check for well-formed UTF, and will replace ill-formed characters with the unicode replacement codepoint, 0xFFFD.
+
+Note that we cannot give you a ``string_view`` to utf16 or utf32 strings: Lua does not hold them in memory this way. You can perhaps do your own customization to provide for this if need be. Remember that Lua stores a counted sequence of bytes: serializing your string as bytes and pushing a string type into Lua's stack will work, though do not except any complex string routines or printing to behave nicely with your code.
+
+.. _file an issue report: https://github.com/ThePhD/sol2/issues

third_party/sol2/docs/source/compilation.rst

@@ -0,0 +1,100 @@
+supported compilers, binary size, compile time
+==============================================
+getting good final product out of sol
+-------------------------------------
+
+supported compilers
+-------------------
+
+GCC 7.x is now out alongside Visual Studio 2018. This means that `sol release v2.20.1`_ is the current version of the code targeted at the older compilers not listed below. Newer code will be targeted at working with the following compilers and leveraging their features, possibly taking advantage of whatever C++17 features are made available by the compilers and standard libraries bundled by-default with them.
+
+``v2.20.1`` supports:
+
+* VC++
+	- Visual Studio 2018
+	- Visual Studio 2015 (Latest updates)
+* GCC (includes MinGW)
+	- v7.x
+	- v6.x
+	- v5.x
+	- v4.8+
+* Clang
+	- v4.x
+	- v3.9.x
+	- v3.8.x
+	- v3.7.x
+	- v3.6.x
+	- Note: this applies to XCode's Apple Clang as well, but that compiler packs its own deficiencies and problems as well
+
+**This does not mean we are immediately abandoning older compilers.** We will update this page as relevant bugfixes are backported to the v2.x.x releases. Remember that sol2 is feature-complete: there is nothing more we can add to the library at this time with C++11/C++14 compiler support, so your code will be covered for a long time to come.
+
+Newer features will be targeted at the following compilers:
+
+* VC++
+	- Visual Studio vNext
+	- Visual Studio 2018
+* GCC (includes MinGW)
+	- v8.x
+	- v7.x
+* Clang
+	- v7.x
+	- v6.x
+	- v5.x
+	- v4.x
+	- v3.9.x
+
+Note that Visual Studio's 2018 Community Edition is absolutely free now, and installs faster and easier than ever before. It also removes a lot of hacky work arounds and formally supports decltype SFINAE.
+
+MinGW's GCC version 7.x of the compiler fixes a long-standing derp in the <codecvt> header that swapped the endianness of utf16 and utf32 strings.
+
+Clang 3.4, 3.5 and 3.6 have many bugs we have run into when developing sol2 and that have negatively impacted users for a long time now.
+
+We encourage all users to upgrade immediately. If you need old code for some reason, use `sol release v2.20.1`_: otherwise, always grab sol2's latest.
+
+
+feature support
+---------------
+
+track future compiler and feature support in `this issue here`_.
+
+supported Lua version
+---------------------
+
+We support:
+
+* Lua 5.3+
+* Lua 5.2
+* Lua 5.1
+* LuaJIT 2.0.x+
+* LuaJIT 2.1.x-beta3+
+
+
+binary sizes
+------------
+
+For individiauls who use :doc:`usertypes<api/usertype>` a lot, they can find their compilation times increase. This is due to C++11 and C++14 not having very good facilities for handling template parameters and variadic template parameters. There are a few things in cutting-edge C++17 and C++Next that sol can use, but the problem is many people cannot work with the latest and greatest: therefore, we have to use older techniques that result in a fair amount of redundant function specializations that can be subject to the pickiness of the compiler's inlining and other such techniques.
+
+compile speed improvemements
+----------------------------
+
+Here are some notes on achieving better compile times without sacrificing too much performance:
+
+* When you bind lots of usertypes, put them all in a *single* translation unit (one C++ file) so that it is not recompiled multiple times over, only to be discarded later by the linker.
+	- Remember that the usertype binding ends up being serialized into the Lua state, so you never need them to appear in a header and cause that same compilation overhead for every compiled unit in your project.
+* Consider placing groups of bindings in multiple different translation units (multiple C++ source files) so that only part of the bindings are recompiled when you have to change the bindings.
+	- Avoid putting your bindings into headers: it *will* slow down your compilation
+* If you are developing a shared library, restrict your overall surface area by specifically and explicitly marking functions as visible and exported and leaving everything else as hidden or invisible by default
+* For people who already have a tool that retrieves function signatures and arguments, it might be in your best interest to hook into that tool or generator and dump out the information once using sol2's lower-level abstractions. An `issue describing preliminary steps can be found here`_.
+
+
+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).
+
+Hopefully, as things progress, we move things forward.
+
+
+.. _sol release v2.20.1: https://github.com/ThePhD/sol2/releases/tag/v2.20.1
+.. _issue describing preliminary steps can be found here: https://github.com/ThePhD/sol2/issues/436#issuecomment-312021508
+.. _this issue here: https://github.com/ThePhD/sol2/issues/426

third_party/sol2/docs/source/conf.py

@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# 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
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'Sol'
+copyright = '2018, ThePhD'
+author = 'ThePhD'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '2.20'
+# The full version, including alpha/beta/rc tags.
+release = '2.20.5'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# The default highlighting language: default is python
+highlight_language = 'c++'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = "sol2"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = [
+    "_themes",
+]
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (relative to this directory) to use as a favicon of
+# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
+#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
+#html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# Now only 'ja' uses this config value
+#html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Soldoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #'preamble': '',
+
+    # Latex figure (float) alignment
+    #'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'Sol.tex', 'Sol Documentation', 'ThePhD', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+# -- Options for manual page output ---------------------------------------
+
+# 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)]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'Sol', 'Sol Documentation', author, 'Sol',
+     'One line description of project.', 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False

third_party/sol2/docs/source/containers.rst

@@ -0,0 +1,245 @@
+containers
+==========
+*working with containers in sol2*
+
+Containers are objects that are meant to be inspected and iterated and whose job is to typically provide storage to a collection of items. The standard library has several containers of varying types, and all of them have ``begin()`` and ``end()`` methods which return iterators. C-style arrays are also containers, and sol2 will detect all of them for use and bestow upon them special properties and functions.
+
+* Containers from C++ are stored as ``userdata`` with special ``usertype`` metatables with :ref:`special operations<container-operations>`
+	- In Lua 5.1, this means containers pushed without wrappers like :doc:`as_table<api/as_table>` and :doc:`nested<api/nested>` will not work with ``pairs`` or other built-in iteration functions from Lua
+		+ Lua 5.2+ will behave just fine (does not include LuaJIT 2.0.x)
+	- You must push containers into C++ by returning them directly and getting/setting them directly, and they will have a type of ``sol::type::userdata`` and treated like a usertype
+* Containers can be manipulated from both C++ and Lua, and, like userdata, will `reflect changes if you use a reference`_ to the data.
+* This means containers **do not automatically serialize as Lua tables**
+	- 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<containers-pairs-example>` for more details
+* You can override container behavior by overriding :ref:`the detection trait<container-detection>` and :ref:`specializing the container_traits template<container-traits>`
+* You can bind typical C-style arrays, but must follow :ref:`the rules<container-c-array>`
+
+.. _container-c-array:
+
+.. note::
+	
+	Please note that c-style arrays must be added to Lua using ``lua["my_arr"] = &my_c_array;`` or ``lua["my_arr"] = std::ref(my_c_array);`` to be bestowed these properties. No, a plain ``T*`` pointer is **not** considered an array. This is important because ``lua["my_string"] = "some string";`` is also typed as an array (``const char[n]``) and thusly we can only use ``std::reference_wrapper``\s or pointers to the actual array types to work for this purpose.
+
+.. _container-detection:
+
+container detection
+-------------------
+
+containers are detected by the type trait ``sol::is_container<T>``. If that turns out to be true, sol2 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<T>``, 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<T>`` 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<T>`` 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:
+
+.. code-block:: cpp
+	:caption: not_container.hpp
+
+	struct not_container {
+		void begin() {
+
+		}
+
+		void end() {
+
+		}
+	};
+
+	namespace sol {
+		template <>
+		struct is_container<not_container> : std::false_type {};
+	}
+
+This will let the type be pushed as a regular userdata.
+
+.. note::
+
+	Pushing a new :doc:`usertype<api/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<api/as_container>`. 
+
+
+.. _container-traits:
+
+container overriding
+--------------------
+
+If you **want** it to participate as a table, use ``std::true_type`` instead of ``std::false_type`` from the :ref:`containter detection<container-detection>` example. and provide the appropriate ``iterator`` and ``value_type`` definitions on the type. Failure to do so will result in a container whose operations fail by default (or compilation will fail).
+
+If you need a type whose declaration and definition you do not have control over to be a container, then you must override the default behavior by specializing container traits, like so:
+
+.. code-block:: cpp
+	:caption: specializing.hpp
+
+	struct not_my_type { ... };
+
+	namespace sol {
+		template <>
+		struct is_container<not_my_type> : std::true_type {};
+
+		template <>
+		struct container_traits<not_my_type> {
+
+			...
+			// see below for implemetation details	
+		};
+	}
+
+
+The various operations provided by ``container_traits<T>`` 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<raw-function-note>`. 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<api/stack>` to achieve whatever behavior you need.
+
+.. warning::
+
+	Exception handling **WILL** be provided around these particular raw C functions, so you do not need to worry about exceptions or errors bubbling through and handling that part. It is specifically handled for you in this specific instance, and **ONLY** in this specific instance. The raw note still applies to every other raw C function you make manually.
+
+.. _container-operations:
+
+container operations
+-------------------------
+
+Below are the many container operations and their override points for ``container_traits<T>``. Please use these to understand how to use any part of the implementation.
+
++-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| operation | lua syntax                                | container_traits<T>                              | 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              |                                                                                                                                                                                              |
++-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| index_set | ``c[key] = value``                        | ``static int index_set(lua_State*);``            | 1 self               | - default implementation calls "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                                                                                                                 |
+|           |                                           |                                                  |                      | - 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"                                                                                                                                                    |
+|           |                                           |                                                  |                      | - 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)                                                        |
+|           |                                           |                                                  | 2 target             |                                                                                                                                                                                              |
++-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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                                                                                                                                                                      |
++-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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              |                                                                                                                                                                                              |
++-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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)                                  |
++-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| begin     | n/a                                       | ``static iterator begin(lua_State*, T&);``       | n/a                  | - called by default implementation                                                                                                                                                           |
+|           |                                           |                                                  |                      | - 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                                                                                                                                                           |
+|           |                                           |                                                  |                      | - 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                                                                                                                               |
+|           |                                           |                                                  |                      |                                                                                                                                                                                              |
+|           |                                           |                                                  |                      |                                                                                                                                                                                              |
++-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| pairs     |                                           | ``static int pairs(lua_State*);``                | 1 self               | - implement if advanced user only that understands caveats                                                                                                                                   |
+|           |                                           |                                                  |                      | - override begin and end instead and leave this to default implementation if you do not know what ``__pairs`` is for or how to implement it and the ``next`` function                        |
+|           |                                           |                                                  |                      | - works only in Lua 5.2+                                                                                                                                                                     |
+|           |                                           |                                                  |                      | - calling ``pairs( c )`` in Lua 5.1 / LuaJIT will crash with assertion failure (Lua expects ``c`` to be a table); can be used as regular function ``c:pairs()`` to get around limitation     |
++-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ipairs    |                                           | ``static int ipairs(lua_State*);``               | 1 self               | - implement if advanced user only that understands caveats                                                                                                                                   |
+|           |                                           |                                                  |                      | - override begin and end instead and leave this to default implementation if you do not know what ``__ipairs`` is for or how to implement it and the ``next`` function                       |
+|           |                                           |                                                  |                      | - works only in Lua 5.2, deprecated in Lua 5.3 (but might still be called in compatibiltiy modes)                                                                                            |
+|           |                                           |                                                  |                      | - calling ``ipairs( c )`` in Lua 5.1 / LuaJIT will crash with assertion failure (Lua expects ``c`` to be a table)                                                                            |
++-----------+-------------------------------------------+--------------------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. note::
+
+	If your type does not adequately support ``begin()`` and ``end()`` and you cannot override it, use the ``sol::is_container`` trait override along with a custom implementation of ``pairs`` on your usertype to get it to work as you want it to. Note that a type not having proper ``begin()`` and ``end()`` will not work if you try to forcefully serialize it as a table (this means avoid using :doc:`sol::as_table<api/as_table>` and :doc:`sol::nested<api/nested>`, otherwise you will have compiler errors). Just set it or get it directly, as shown in the examples, to work with the C++ containers.
+
+.. note::
+
+	Overriding the detection traits and operation traits listed above and then trying to use ``sol::as_table`` or similar can result in compilation failures if you do not have a proper ``begin()`` or ``end()`` function on the type. If you want things to behave with special usertype considerations, please do not wrap the container in one of the special table-converting/forcing abstractions.
+
+
+.. _container-classifications: 
+
+container classifications
+-------------------------
+
+When you serialize a container into sol2, the default container handler deals with the containers by inspecting various properties, functions, and typedefs on them. Here are the broad implications of containers sol2's defaults will recognize, and which already-known containers fall into their categories:
+
++------------------------+----------------------------------------+-------------------------+-----------------------------------------------------------------------------------------------+
+| container type         | requirements                           | known containers        | notes/caveats                                                                                 |
++------------------------+----------------------------------------+-------------------------+-----------------------------------------------------------------------------------------------+
+| sequence               | ``erase(iterator)``                    | std::vector             | - ``find`` operation is linear in size of list (searches all elements)                        |
+|                        | ``push_back``/``insert(value_type)``   | std::deque              | - std::forward_list has forward-only iterators: set/find is a linear operation                |
+|                        |                                        | std::list               | - std::forward_list uses "insert_after" idiom, requires special handling internally           |
+|                        |                                        | std::forward_list       |                                                                                               |
++------------------------+----------------------------------------+-------------------------+-----------------------------------------------------------------------------------------------+
+| fixed                  | lacking ``push_back``/``insert``       | std::array<T, n>        | - regular c-style arrays must be set with ``std::ref( arr )`` or ``&arr`` to be usable        |
+|                        | lacking ``erase``                      | T[n] (fixed arrays)     |                                                                                               |
+|                        |                                        |                         |                                                                                               |
++------------------------+----------------------------------------+-------------------------+-----------------------------------------------------------------------------------------------+
+| ordered                | ``key_type`` typedef                   | std::set                | - ``container[key] = stuff`` operation erases when ``stuff`` is nil, inserts/sets when not    |
+|                        | ``erase(key)``                         | std::multi_set          | - ``container.get(key)`` returns the key itself                                               |
+|                        | ``find(key)``                          |                         |                                                                                               |
+|                        | ``insert(key)``                        |                         |                                                                                               |
++------------------------+----------------------------------------+-------------------------+-----------------------------------------------------------------------------------------------+
+| associative, ordered   | ``key_type``, ``mapped_type`` typedefs | std::map                |                                                                                               |
+|                        | ``erase(key)``                         | std::multi_map          |                                                                                               |
+|                        | ``find(key)``                          |                         |                                                                                               |
+|                        | ``insert({ key, value })``             |                         |                                                                                               |
++------------------------+----------------------------------------+-------------------------+-----------------------------------------------------------------------------------------------+
+| unordered              | same as ordered                        | std::unordered_set      | - ``container[key] = stuff`` operation erases when ``stuff`` is nil, inserts/sets when not    |
+|                        |                                        | std::unordered_multiset | - ``container.get(key)`` returns the key itself                                               |
+|                        |                                        |                         | - iteration not guaranteed to be in order of insertion, just like in C++ container            |
+|                        |                                        |                         |                                                                                               |
++------------------------+----------------------------------------+-------------------------+-----------------------------------------------------------------------------------------------+
+| unordered, associative | same as ordered, associative           | std::unordered_map      | - iteration not guaranteed to be in order of insertion, just like in C++ container            |
+|                        |                                        | std::unordered_multimap |                                                                                               |
++------------------------+----------------------------------------+-------------------------+-----------------------------------------------------------------------------------------------+
+
+
+a complete example
+------------------
+
+Here's a complete working example of it working for Lua 5.3 and Lua 5.2, and how you can retrieve out the container in all versions:
+
+.. literalinclude:: ../../examples/containers.cpp
+	:name: containers-example
+	:linenos:
+
+
+Note that this will not work well in Lua 5.1, as it has explicit table checks and does not check metamethods, even when ``pairs`` or ``ipairs`` is passed a table. In that case, you will need to use a more manual iteration scheme or you will have to convert it to a table. In C++, you can use :doc:`sol::as_table<api/as_table>` when passing something to the library to get a table out of it: ``lua["arr"] = as_table( std::vector<int>{ ... });``. For manual iteration in Lua code without using ``as_table`` for something with indices, try:
+
+.. code-block:: lua
+	:caption: iteration.lua
+	:linenos:
+
+	for i = 1, #vec do
+		print(i, vec[i]) 
+	end
+
+There are also other ways to iterate over key/values, but they can be difficult AND cost your performance due to not having proper support in Lua 5.1. We recommend that you upgrade to Lua 5.2 or 5.3 if this is integral to your infrastructure.
+
+If you can't upgrade, use the "member" function ``my_container:pairs()`` in Lua to perform iteration:
+
+.. literalinclude:: ../../examples/container_with_pairs.cpp
+	:name: containers-pairs-example
+	:linenos:
+
+.. _online version's information: https://www.lua.org/pil/26.html
+.. _reflect changes if you use a reference: https://github.com/ThePhD/sol2/blob/develop/examples/containers.cpp
+.. _this table serialization example: https://github.com/ThePhD/sol2/blob/develop/examples/containers_as_table.cpp

third_party/sol2/docs/source/errors.rst

@@ -0,0 +1,107 @@
+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.
+
+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<state-script-function>`, 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:
+
+Compiler Errors / Warnings
+--------------------------
+
+A myriad of compiler errors can occur when something goes wrong. Here is some basic advice about working with these types:
+
+* If there are a myriad of errors relating to ``std::index_sequence``, type traits, and other ``std::`` members, it is likely you have not turned on your C++14 switch for your compiler. Visual Studio 2015 turns these on by default, but g++ and clang++ do not have them as defaults and you should pass the flag ``--std=c++1y`` or ``--std=c++14``, or similar for your compiler.
+* If you are pushing a non-primitive type into Lua, you may get strange errors about initializer lists or being unable to initializer a ``luaL_Reg``. This may be due to :ref:`automatic function and operator registration<automagical-registration>`. :ref:`Disabling it<automagical>` may help.
+* Sometimes, a generated usertype can be very long if you are binding a lot of member functions. You may end up with a myriad of warnings about debug symbols being cut off or about ``__LINE_VAR`` exceeding maximum length. You can silence these warnings safely for some compilers.
+* Template depth errors may also be a problem on earlier versions of clang++ and g++. Use ``-ftemplate-depth`` compiler flag and specify really high number (something like 2048 or even double that amount) to let the compiler work freely.
+* When using usertype templates extensively, MSVC may invoke `compiler error C1128 <https://msdn.microsoft.com/en-us/library/8578y171.aspx>`_ , which is solved by using the `/bigobj compilation flag <https://msdn.microsoft.com/en-us/library/ms173499.aspx>`_.
+* If you have a move-only type, that type may need to be made ``readonly`` if it is bound as a member variable on a usertype or bound using ``state_view::set_function``. See :doc:`sol::readonly<api/readonly>` for more details.
+* Assigning a ``std::string`` or a ``std::pair<T1, T2>`` using ``operator=`` after it's been constructed can result in compiler errors when working with ``sol::function`` and its results. See `this issue for fixes to this behavior`_.
+* Sometimes, using ``__stdcall`` in a 32-bit (x86) environment on VC++ can cause problems binding functions because of a compiler bug. We have a prelimanry fix in, but if it doesn't work and there are still problems: put the function in a ``std::function`` to make the compiler errors and other problems go away. Also see `this __stdcall issue report`_ for more details.
+* If you are using ``/std:c++latest`` on VC++ and get a number of errors for ``noexcept`` specifiers on functions, you may need to file an issue or wait for the next release of the VC++ compiler.
+
+Mac OSX Crashes
+---------------
+
+On LuaJIT, your code may crash at seemingly random points when using Mac OSX. Make sure that your build has these flags, as advised by the LuaJIT website::
+
+	-pagezero_size 10000 -image_base 100000000
+
+These will allow your code to run properly, without crashing arbitrarily. Please read the LuaJIT documentation on compiling and running with LuaJIT for more information.
+
+
+"compiler out of heap space"
+----------------------------
+
+Typical of Visual Studio, the compiler will complain that it is out of heap space because Visual Studio defaults to using the x86 (32-bit) version of itself (it will still compile x86 or x64 or ARM binaries, just the compiler **itself** is a 32-bit executable). In order to get around heap space requirements, add the following statement in your ``.vcoxproj`` files under the ``<Import .../>`` statement, as instructed by `OrfeasZ in this issue`_::
+
+	<PropertyGroup>
+		<PreferredToolArchitecture>x64</PreferredToolArchitecture>
+	</PropertyGroup>
+
+
+This should use the 64-bit tools by default, and increase your maximum heap space to whatever a 64-bit windows machine can handle. If you do not have more than 4 GB of RAM, or you still encounter issues, you should look into using ``create_simple_usertype`` and adding functions 1 by 1 using ``.set( ... )``, as shown in `the simple usertype example here`_.
+
+
+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.
+
+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 sol2, 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.
+
+Note that you should not be defining these with standard builds of either Lua or LuaJIT. See the :ref:`config page<config-linker>` for more details.
+
+"caught (...) exception" errors
+-------------------------------
+
+Sometimes, you expect properly written errors and instead receive an error about catching a ``...`` exception instead. This might mean that you either built Lua as C++ or are using a framework like LuaJIT that has full interopability support for exceptions on certain system types (x64 for LuaJIT 2.0.5, x86 and x64 on LuaJIT 2.1.x-beta and later).
+
+Please make sure to use the ``SOL_EXCEPTIONS_SAFE_PROPAGATION`` define before including sol2 to make this work out. You can read more :ref:`at the exception page here<exception-interop>`.
+
+Catch and CRASH!
+----------------
+
+By default, Sol will add a ``default_at_panic`` handler to states opened by Sol (see :ref:`sol::state automatic handlers<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<exceptions>`.
+
+Lua is a C API first and foremost: exceptions bubbling out of it is essentially last-ditch, terminal behavior that the VM does not expect. You can see an example of handling a panic on the exceptions page :ref:`here<typical-panic-function>`. This means that setting up a ``try { ... } catch (...) {}`` around an unprotected sol2 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.
+
+Furthermore, it would be a great idea for you to use the safety features talked about :doc:`safety section<safety>`, especially for those related to functions.
+
+
+Destructors and Safety
+----------------------
+
+Another issue is that Lua is a C API. It uses ``setjmp`` and ``longjmp`` to jump out of code when an error occurs. This means it will ignore destructors in your code if you use the library or the underlying Lua VM improperly. To solve this issue, build Lua as C++. When a Lua VM error occurs and ``lua_error`` is triggered, it raises it as an exception which will provoke proper unwinding semantics.
+
+Building Lua as C++ gets around this issue, and allows lua-thrown errors to properly stack unwind.
+
+
+Protected Functions and Access
+------------------------------
+
+By default, :doc:`sol::function<api/function>` assumes the code ran just fine and there are no problems. :ref:`sol::state(_view)::script(_file)<state-script-function>` also assumes that code ran just fine. Use :doc:`sol::protected_function<api/protected_function>` to have function access where you can check if things worked out. Use :doc:`sol::optional<api/optional>` to get a value safely from Lua. Use :ref:`sol::state(_view)::do_string/do_file/load/load_file<state-do-code>` to safely load and get results from a script. The defaults are provided to be simple and fast with thrown exceptions to violently crash the VM in case things go wrong.
+
+Protected Functions Are Not Catch All
+-------------------------------------
+
+Sometimes, some scripts load poorly. Even if you protect the function call, the actual file loading or file execution will be bad, in which case :doc:`sol::protected_function<api/protected_function>` will not save you. Make sure you register your own panic handler so you can catch errors, or follow the advice of the catch + crash behavior above. Remember that you can also bind your own functions and forego sol2's built-in protections for you own by binding a :ref:`raw lua_CFunction function<raw-function-note>`
+
+Iteration
+---------
+
+Tables may have other junk on them that makes iterating through their numeric part difficult when using a bland ``for-each`` loop, or when calling sol's ``for_each`` function. Use a numeric look to iterate through a table. Iteration does not iterate in any defined order also: see :ref:`this note in the table documentation for more explanation<iteration_note>`.
+
+.. _OrfeasZ in this issue: https://github.com/ThePhD/sol2/issues/329#issuecomment-276824983
+.. _this issue for fixes to this behavior: https://github.com/ThePhD/sol2/issues/414#issuecomment-306839439
+.. _this __stdcall issue report: https://github.com/ThePhD/sol2/issues/463
+.. _the simple usertype example here: https://github.com/ThePhD/sol2/blob/develop/examples/usertype_simple.cpp#L45

third_party/sol2/docs/source/exceptions.rst

@@ -0,0 +1,74 @@
+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<LuaJIT and exceptions>` ).
+
+If you turn this off, the default `at_panic`_ function :doc:`state<api/state>` set for you will not throw  (see :ref:`sol::state's automatic handlers<state-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).
+
+To make this not be the case, you can set a panic function directly with ``lua_atpanic( lua, my_panic_function );`` or when you create the ``sol::state`` with ``sol::state lua(my_panic_function);``. Here's an example ``my_panic_function`` you can have that prints out its errors:
+
+.. literalinclude:: ../../examples/docs/my_panic.cpp
+	:caption: typical panic function
+	:name: typical-panic-function
+	:linenos:
+
+
+Note that ``SOL_NO_EXCEPTIONS`` will also disable :doc:`sol::protected_function<api/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!
+
+.. _lua-handlers:
+
+various sol and lua handlers
+----------------------------
+
+Lua comes with two kind of built-in handlers that sol provides easy opt-ins for. One is the ``panic`` function, as :ref:`demonstrated above<typical-panic-function>`. Another is the ``pcall`` error handler, used with :doc:`sol::protected_function<api/protected_function>`. It is any function that takes a single argument. The single argument is the error type being passed around: in Lua, this is a single string message:
+
+.. literalinclude:: ../../examples/protected_functions.cpp
+	:caption: regular error handling
+	:name: regular-error-handling
+	:linenos:
+
+
+The other handler is specific to sol2. If you open a ``sol::state``, or open the default state handlers for your ``lua_State*`` (see :ref:`sol::state's automatic handlers<state-automatic-handlers>` for more details), there is a ``sol::exception_handler_function`` type. It allows you to register a function in the event that an exception happens that bubbles out of your functions. The function requires that you push 1 item onto the stack that will be used with a call to `lua_error`_
+
+.. literalinclude:: ../../examples/exception_handler.cpp
+	:caption: exception handling
+	:name: exception-handling
+	:linenos:
+
+
+.. _LuaJIT and exceptions:
+
+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.
+
+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:
+
+Lua and LuaJIT C++ Exception Full Interoperability
+--------------------------------------------------
+
+You can ``#define SOL_EXCEPTIONS_SAFE_PROPAGATION`` before including Sol or define ``SOL_EXCEPTIONS_SAFE_PROPAGATION`` on the command line if you know your implmentation of Lua has proper unwinding semantics that can be thrown through the version of the Lua API you have built / are using.
+
+This will prevent sol from catching ``(...)`` errors in platforms and compilers that have full C++ exception interoperability. This means that Lua errors can be caught with ``catch (...)`` in the C++ end of your code after it goes through Lua, and exceptions can pass through the Lua API and Stack safely.
+
+Currently, the only known platform to do this is the listed "Full" `platforms for LuaJIT`_ and Lua compiled as C++. This define is turned on automatically for compiling Lua as C++ and ``SOL_USING_CXX_LUA`` (or ``SOL_USING_CXX_LUA_JIT``) is defined.
+
+.. 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*!
+
+
+.. _issue: https://github.com/ThePhD/sol2/issues/
+.. _at_panic: http://www.Lua.org/manual/5.3/manual.html#4.6
+.. _lua_error: https://www.lua.org/manual/5.3/manual.html#lua_error
+.. _caveats regarding exceptions: http://luajit.org/extensions.html#exceptions
+.. _platforms for LuaJIT: http://luajit.org/extensions.html#exceptions
+.. _this closed issue: https://github.com/ThePhD/sol2/issues/28

third_party/sol2/docs/source/features.rst

@@ -0,0 +1,268 @@
+features
+========
+*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."
+
+For the hard technical components of Lua and its ecosystem we support, here is the full rundown:
+
+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<api/compatibility>` header.
+
+* :doc:`Table<api/table>` support: setting values, getting values of multiple (different) types
+	- :doc:`Lazy evaluation<api/proxy>` for nested/chained queries
+		``table["a"]["b"]["c"] = 24;``
+	- Implicit conversion to the types you want
+		``double b = table["computed_value"];``
+
+* :doc:`yielding<api/yielding>` support: tag a function as whose return is meant to yield into a coroutine
+
+* :doc:`Optional<api/optional>` support: setting values, getting values of multiple (different) types
+	- :doc:`Lazy evaluation<api/proxy>` for nested/chained queries
+		``optional<int> maybe_number = table["a"]["b"]["invalid_key"];``
+	- Turns on safety when you want it: speed when you don't
+
+* Support for callables (functions, lambdas, member functions)
+ 	- Pull out any Lua function with :doc:`sol::function<api/function>`: ``sol::function fx = table["socket_send"];``
+ 	- Can also set callables into :doc:`operator[] proxies<api/proxy>`: ``table["move_dude"] = &engine::move_dude;``
+ 	- Safety: use :doc:`sol::protected_function<api/protected_function>` to catch any kind of error
+ 		+ ANY kind: C++ exception or Lua erors are trapped and run through the optional ``error_handler`` variable
+ 	- *Advanced:* :doc:`overloading of a single function name<api/overload>` so you don't need to do boring typechecks
+ 	- *Advanced:* :doc:`efficient handling and well-documented<functions>` way of dealing with arguments
+
+* User-Defined Type (:doc:`sol::usertype<api/usertype>` in the API) support:
+	- Set member functions to be called
+	- Set member variables
+	- Set variables on a class that are based on setter/getter functions using properties
+	- Use free-functions that take the Type as a first argument (pointer or reference)
+	- Support for "Factory" classes that do not expose constructor or destructor
+	- Modifying memory of userdata in C++ directly affects Lua without copying, and
+	- Modifying userdata in Lua directly affects C++ references/pointers
+		``my_class& a = table["a"];`` 
+		``my_class* a_ptr = table["a"];`` 
+	- If you want a copy, just use value semantics and get copies:
+		``my_class a = table["a"];``
+
+* Thread/Coroutine support
+	- Use, resume, and play with :doc:`coroutines<api/coroutine>` like regular functions
+	- Get and use them even on a separate Lua :doc:`thread<api/thread>` 
+	- Monitor status and get check errors
+
+* *Advanced:* Customizable and extensible to your own types if you override :doc:`getter/pusher/checker<api/stack>` template struct definitions.
+
+
+The Feature Matrix™
+-------------------
+
+The below feature table checks for the presence of something. It, however, does not actually account for any kind of laborious syntax.
+
+✔ full support: works as you'd expect (operator[] on tables, etc...)
+
+~ partial support / wonky support: this means its either supported through some other fashion (not with the desired syntax, serious caveats, etc.). Sometimes means dropping down to use the plain C API (at which point, what was the point of the abstraction?).
+
+✗ no support: feature doesn't work or, if it's there, it REALLY sucks to use
+
+Implementation notes from using the libraries are below the tables.
+
+
+category explanations
+---------------------
+
+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.
+* 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.
+* udts - table variables: C++ member variables/properties, manipulated by ``my_object.var = 24`` and in Lua
+* function binding: Support for binding all types of functions. Lambdas, member functions, free functions, in different contexts, etc... 
+* protected function: Use of ``lua_pcall`` to call a function, which offers error-handling and trampolining (as well as the ability to opt-in / opt-out of this behavior)
+* multi-return: returning multiple values from and to Lua (generally through ``std::tuple<...>`` or in some other way)
+* variadic/variant argument: being able to accept "anything" from Lua, and even return "anything" to Lua (``object`` abstraction, variadic arguments, etc...)
+* inheritance: allowing some degree of subtyping or inheritance on classes / userdata from Lua - this generally means that you can retrieve a base pointer from Lua even if you hand the library a derived pointer
+* overloading: the ability to call overloaded functions, matched based on arity or type (``foo( 1 )`` from lua calls a different function then ``foo( "bark" )``).
+* Lua thread: basic wrapping of the lua thread API; ties in with coroutine.
+* coroutines: allowing a function to be called multiple times, resuming the execution of a Lua coroutine each time
+* yielding C++ functions: allowing a function from C++ to be called multiple times, and yield any results it has back through the C API or into Lua
+* environments: an abstraction for getting, setting and manipulating an environment, using table techniques, functions or otherwise. Typically for the purposes of sandboxing
+
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+|                           |   plain C   | luawrapper | lua-intf | luabind |  Selene  |    Sol2   |   oolua   |   lua-api-pp   |  kaguya  |   SLB3   |    SWIG   | luacppinterface | luwra  |
+|                           |             |            |          |         |          |           |           |                |          |          |           |                 |        |
++===========================+=============+============+==========+=========+==========+===========+===========+================+==========+==========+===========+=================+========+
+| optional                  |      ~      |     ✗      |     ✔    |    ✗    |     ✗    |     ✔     |     ✗     |        ✗       |     ✔    |     ✗    |     ✗     |        ✗        |    ✗   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| tables                    |      ~      |     ~      |     ~    |    ✔    |     ✔    |     ✔     |     ~     |        ✔       |     ✔    |     ✗    |     ✗     |        ~        |    ✔   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| table chaining            |      ~      |     ~      |     ~    |    ✔    |     ✔    |     ✔     |     ✗     |        ✔       |     ✔    |     ✗    |     ✗     |        ~        |    ✔   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| arbitrary keys            |      ~      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ✗     |        ~       |     ✔    |     ✗    |     ✗     |        ✗        |    ✗   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| user-defined types (udts) |      ~      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ~     |        ✔       |     ✔    |     ✔    |     ✔     |        ✔        |    ✔   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| udts: member functions    |      ~      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ~     |        ✔       |     ✔    |     ✔    |     ✔     |        ✔        |    ✔   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| udts: table variables     |      ~      |     ~      |     ~    |    ~    |     ~    |     ✔     |     ~     |        ~       |     ~    |     ✗    |     ✔     |        ✗        |    ~   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| stack abstractions        |      ~      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ✔     |        ✔       |     ✔    |     ~    |     ✗     |        ~        |    ✔   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| lua callables from C(++)  |      ~      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ✔     |        ✔       |     ✔    |     ✔    |     ✔     |        ✔        |    ~   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| function binding          |      ~      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ~     |        ~       |     ✔    |     ~    |     ~     |        ~        |    ✔   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| protected call            |      ~      |     ✗      |     ~    |    ~    |     ~    |     ✔     |     ~     |        ✔       |     ~    |     ~    |     ~     |        ~        |    ~   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| multi-return              |      ~      |     ✗      |     ✔    |    ✔    |     ✔    |     ✔     |     ~     |        ✔       |     ✔    |     ~    |     ✔     |        ~        |    ✗   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| variadic/variant argument |      ~      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ~     |        ✔       |     ✔    |     ~    |     ~     |        ~        |    ✗   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| inheritance               |      ~      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ~     |        ~       |     ✔    |     ~    |     ✔     |        ~        |    ✗   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| overloading               |      ~      |     ✗      |     ✔    |    ✗    |     ✗    |     ✔     |     ✗     |        ✗       |     ✔    |     ✔    |     ✔     |        ✗        |    ✗   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| Lua thread                |      ~      |     ✗      |     ~    |    ✗    |     ✗    |     ✔     |     ✔     |        ✗       |     ✔    |     ✗    |     ✗     |        ✔        |    ✗   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| environments              |      ✗      |     ✗      |     ✗    |    ✗    |     ✗    |     ✔     |     ✗     |        ✗       |     ✗    |     ✗    |     ✗     |        ✗        |    ✗   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| coroutines                |      ~      |     ✗      |     ~    |    ✔    |     ✔    |     ✔     |     ✗     |        ✗       |     ✔    |     ✗    |     ✗     |        ✔        |    ✗   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| yielding C++ functions    |      ~      |     ✔      |     ✔    |    ✔    |     ~    |     ✔     |     ~     |        ✗       |     ✔    |     ✗    |     ~     |        ✔        |    ~   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| no-rtti support           |      ✔      |     ✗      |     ✔    |    ✗    |     ✗    |     ✔     |     ✔     |        ✗       |     ✔    |     ✔    |     ~     |        ✔        |    ✔   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| no-exception support      |      ✔      |     ✗      |     ✔    |    ~    |     ✗    |     ✔     |     ✔     |        ✗       |     ✔    |     ✔    |     ~     |        ✔        |    ✔   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| Lua 5.1                   |      ✔      |     ✔      |     ✔    |    ✔    |     ✗    |     ✔     |     ✔     |        ✔       |     ✔    |     ✔    |     ✔     |        ✗        |    ✔   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| Lua 5.2                   |      ✔      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ✔     |        ✔       |     ✔    |     ✔    |     ✔     |        ✔        |    ✔   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| Lua 5.3                   |      ✔      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ✔     |        ✔       |     ✔    |     ✔    |     ✔     |        ✔        |    ✔   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| luajit                    |      ✔      |     ✔      |     ✔    |    ✔    |     ~    |     ✔     |     ✔     |        ✔       |     ✔    |     ✔    |     ✔     |        ✗        |    ✔   |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+| distribution              |   compile   |   header   |   both   | compile |  header  |   header  |  compile  |     compile    |  header  |  compile | generated |     compile     | header |
++---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+--------+
+
+
+notes on implementations
+------------------------
+
+Plain C - 
+
+* Obviously you can do anything you want with Plain C, but the effort involved is astronomical in comparison to what other wrappers, libraries and frameworks offer
+* Does not scale very well (in terms of developer ease of use)
+* Compilation (or package manager use) is obviously required for your platform and required to use ANY of these libraries, but that's okay because all libraries need some version of Lua anyways, so you always have this!
+
+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
+* 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 -
+
+* One of the few libraries with optional support!
+* Basically the fastest in almomst all respects: http://sol2.readthedocs.io/en/latest/benchmarks.html
+* Overloading support can get messy with inheritance, see :doc:`here<api/overload>`
+* C++14/"C++1y" (-std=c++14, -std=c++1y, =std=c++1z) flags are used (available since GCC 4.9 and Clang 3.5)
+* Active issues, active individuals
+* Deserves lots of love!
+  
+lua-intf -
+
+* Can be both header-only or compiled
+* Has optional support
+* C++11
+* Macro-based registration (strange pseudo-language)
+* Fairly fast in most regards
+* Registering classes/"modules" in using C++ code is extremely verbose
+* In order to chain lookups, one has to glue the keys together (e.g. ``"mykey.mykey2"``) on the ``operator[]`` lookup (e.g., you can't nest them arbitrarily, you have to pre-compose the proper lookup string) (fails miserably for non-string lookups!).
+* Not too shabby!
+
+Selene -
+
+* Table variables / member variables are automatically turned into ``obj:set_x( value )`` to set and ``obj:x()`` to get
+* Registering classes/"modules" using C++ code is extremely verbose, similar to lua-intf's style
+* Eats crap when it comes to performance, most of the time (see :doc:`benchmarks<benchmarks>`)
+* Lots of users (blogpost etc. made it popular), but the Repository is kinda stagnant...
+
+luawrapper -
+
+* Takes the approach of writing and reading tables using ``readVariable`` and ``writeVariable`` functions
+* C++11, no macros!
+* The interface can be clunky (no table-like data structures: most things go though ``readVariable`` / ``writeVariable``)
+* Internal Compiler errors in Visual Studio 2015 - submitted a PR to fix it, hopefully it'll get picked up
+
+SWIG (3.0) - 
+
+* Very comprehensive for binding concepts of C++ (classes, variables, etc.) to Lua
+* Helps with literally nothing else (tables, threads, stack abstractions, etc.)
+* Not really a good, full-featured Library...
+* Requires preprocessing step (but it's not a... TERRIBLY complicated preprocessing step); some boilerplate in writing additional classes that you've already declared
+
+luacppinterface -
+
+* The branch that fixes VC++ warnings and introduces some new work has type checker issues, so use the stable branch only
+* No table variable support
+* Actually has tables (but no operator[])
+* Does not support arbitrary keys
+
+luabind -
+
+* One of the older frameworks, but has many people updating it and providing "deboostified" versions
+* Strange in-lua keywords and parsing to allow for classes to be written in lua
+	- not sure if good feature; vendor lock-in to that library to depend on this specific class syntax?
+* Comprehensive lua bindings (can even bind "properties")
+* There's some code that produces an ICE in Visual C++: I submitted a fix to the library in the hopes that it'll get accepted
+* Wonky table support: no basic conversion functions on ``luabind::object``; have to push object then use lua API to get what you want
+
+lua-api-pp -
+
+* Compiled, but the recommendation is to add the source files directly to your project
+* Userdata registration with thick setup-macros: LUAPP_USERDATA( ... ) plus a bunch of free functions that take a ``T& self`` argument
+    - You can bind member functions directly but only if you override metatable entries
+    - Otherwise, COMPLICATED self-registration that makes you wonder why you're using the framework
+* You have to create a context and then call it to start accessing the lua state (adding more boilerplate... thanks)
+    - Thankfully, unlike many libraries, it actually has a Table type that can be used semi-easily. FINALLY
+* C++11-ish in some regards
+* Sad face, thanks to the way userdata registration is handled
+
+SLB3 -
+
+* Old code exported to github from dying google code
+* ".NET Style" - to override functionality, derive from class -- boilerplate (isn't that what we're trying to get rid of?)
+* Pointers everywhere: ownership semantics unclear
+* Piss-poor documentation, ugh!
+* Least favorite to work with, for sure!
+
+oolua -
+
+* The syntax for this library is not my favorite... `go read the docs`_, decide for yourself! 
+* The worst in terms of how to use it: may have docs, but the DSL is extraordinarily crappy with thick, hard-to-debug/hard-to-error-check macros
+    - Same problem as lua-api-pp: cannot have the declaration macros anywhere but the toplevel namespace because of template declaration macro
+* Supports not having exceptions or rtti turned on (shiny!)
+* Poor RAII support: default-construct-and-get style (requires some form of initalization to perform a ``get`` of an object, and it's hard to extend)
+	- The library author has informed me that he does personally advises individuals do not use the ``Table`` abstraction in OOLua... Do I likewise tell people to consider its table abstractions defunct?
+* Table variables / member variables from C++ are turned into function calls (``get_x`` and ``set_x`` by default)
+
+luwra - 
+
+* How do you store stateful functors / lambas? So far, no support for such.
+* 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!)
+* No table variable support - get turned into getter/setter functions, similar to kaguya
+* Table variables become class statics (surprising)
+* Tanks in later MSVCs
+
+.. _Go read the docs: https://oolua.org/docs/index.html

third_party/sol2/docs/source/functions.rst

@@ -0,0 +1,108 @@
+functions
+=========
+*working with functions in sol2*
+
+
+There are a number of examples dealing with functions and how they can be bound to sol2:
+
+* For a quicker walkthrough that demonstrates almost everything, see `the examples`_ and the :doc:`the quick and dirty tutorial<tutorial/all-the-things>`
+* For a full explanation, :doc:`read the tutorial<tutorial/functions>` and consult the subjects below
+* If you have bindings and set-ups that want to leverage the C API without sol2's interference, you can push a raw function, which has certain implications (noted :ref:`below<raw-function-note>`)
+* Return multiple values into Lua by:
+	- returning a ``std::tuple``
+	- using :doc:`sol::variadic_results<api/variadic_results>`
+* :doc:`Overload function calls with different argument types and count on a single name<api/overload>` (first-bound, first-serve overloading)
+	- Note: because of this feature, automatic number to string conversion from Lua is not permitted for overloads and does not work when safeties are turned on
+	- int/float overloads must have ``SOL_SAFE_NUMERICS`` turned on to differentiate between the two
+	- Use C++ captures and lambdas to bind member functions tied to a single object /
+* You can work with **transparent arguments** that provide you with special information, such as
+	- :doc:`sol::variadic_args<api/variadic_args>`, for handling variable number of arguments at runtime
+	- :doc:`sol::this_state<api/this_state>`, for getting the current Lua state
+	- :doc:`sol::this_environment<api/this_environment>`, for potentially retrieving the current Lua environment
+* Control serialization of arguments and return types with :doc:`sol::nested<api/nested>`, :doc:`sol::as_table<api/nested>`, :doc:`sol::as_args<api/as_args>` and :doc:`sol::as_function<api/as_function>`
+* Set environments for Lua functions and scripts with :doc:`sol::environment<api/environment>`
+* You can use :doc:`filters<api/filters>` to control dependencies and streamline return values, as well as apply custom behavior to a functions return
+
+
+
+.. _binding-callable-objects:
+
+working with callables/lambdas
+------------------------------
+
+To be explicit about wanting a struct to be interpreted as a function, use ``my_table.set_function( key, func_value );``. You can also use the :doc:`sol::as_function<../api/as_function>` call, which will wrap and identify your type as a function.
+
+.. _lambda-registry:
+.. note::
+
+	When you set lambdas/callables through ``my_table.set( ... )`` using the same function signature, you can suffer from ``const static`` data (like string literals) from not "behaving properly". This is because some compilers do not provide unique type names that we can get at in C++ with RTTI disabled, and thusly it will register the first lambda of the specific signature as the one that will be called. The result is that string literals and other data stored in an compiler implementation-defined manner might be folded and the wrong routine run, even if other observable side effects are nice.
+
+	To avoid this problem, register all your lambdas with :ref:`my_table.set_function<set-function>` and `avoid the nightmare altogether`_.
+
+
+Furthermore, it is important to know that lambdas without a specified return type (and a non-const, non-reference-qualified ``auto``) will decay return values. To capture or return references explicitly, use ``decltype(auto)`` or specify the return type **exactly** as desired:
+
+.. literalinclude:: ../../examples/docs/references_in_lambdas.cpp
+	:name: refereces-in-lambdas-example
+	:linenos:
+	
+.. _function-exception-handling:
+
+exception safety/handling
+-------------------------
+
+All functions bound to sol2 set up an exception trampoline around the function (unless you are working with a :ref:`raw lua_CFunction you pushed yourself<raw-function-note>`). :doc:`protected_function<api/protected_function>` also has an error handler member and an exception trampoline around its internals, but it is not guaranteed safe if an exception bubbles outside of it. Catching that exception is not safe either: if an exception has exploded out from the sol2 API somehow, you must assume the VM is in some indeterminate and/or busted state.
+
+Please read the :doc:`error page<errors>` and :doc:`exception page<exceptions>` for more details about what to do with exceptions that explode out from the API.
+
+
+.. _function-argument-handling:
+
+functions and argument passing
+------------------------------
+
+All arguments are forwarded. Unlike :doc:`get/set/operator[] on sol::state<api/state>` or :doc:`sol::table<api/table>`, value semantics are not used here. It is forwarding reference semantics, which do not copy/move unless it is specifically done by the receiving functions / specifically done by the user.
+
+.. note::
+
+	This also means that you should pass and receive arguments in certain ways to maximize efficiency. For example, ``sol::table``, ``sol::object``, ``sol::userdata`` and friends are cheap to copy, and should simply by taken as values. This includes primitive types like ``int`` and ``double``. However, C++ types -- if you do not want copies -- should be taken as ``const type&`` or ``type&``, to save on copies if it's important. Note that taking references from Lua also means you can modify the data inside of Lua directly, so be careful. Lua by default deals with things mostly by reference (save for primitive types).
+
+
+When you bind a function to Lua, please take any pointer arguments as ``T*``, unless you specifically know you are going to match the exact type of the unique/shared pointer and the class it wraps. sol2 cannot support "implicit wrapped pointer casting", such as taking a ``std::shared_ptr<MySecondBaseClass>`` when the function is passed a ``std::shared_ptr<MyDerivedClass>``. Sometimes it may work because the compiler might be able to line up your classes in such a way that raw casts work, but this is undefined behavior through and through and sol2 has no mechanisms by which it can make this safe and not blow up in the user's face.
+
+.. note::
+
+	Please avoid taking special unique_usertype arguments, by either reference or value. In many cases, by-value does not work (e.g., with ``std::unique_ptr``) because many types are move-only and Lua has no concept of "move" semantics. By-reference is dangerous because sol2 will hand you a reference to the original data: but, any pointers stored in Lua can be invalidated if you call ``.reset()`` or similar on the core pointer. Please take a pointer (``T*``) if you anticipate ``nil``/``nullptr`` being passed to your function, or a reference (``const T&`` or ``T&``) if you do not. As a side note, if you write a small wrapping class that holds a base pointer type, and interact using the wrapper, then when you get the wrapper as an argument in a C++-function bound to Lua you can cast the internal object freely. It is simply a direct cast as an argument to a function that is the problem.
+
+
+.. note::
+
+	You can get even more speed out of ``sol::object`` style of types by taking a ``sol::stack_object`` (or ``sol::stack_...``, where ``...`` is ``userdata``, ``reference``, ``table``, etc.). These reference a stack position directly rather than cheaply/safely the internal Lua reference to make sure it can't be swept out from under you. Note that if you manipulate the stack out from under these objects, they may misbehave, so please do not blow up your Lua stack when working with these types.
+
+	``std::string`` (and ``std::wstring``) are special. Lua stores strings as ``const char*`` null-terminated strings. ``std::string`` will copy, so taking a ``std::string`` by value or by const reference still invokes a copy operation. You can take a ``const char*``, but that will mean you're exposed to what happens on the Lua stack (if you change it and start chopping off function arguments from it in your function calls and such, as warned about previously).
+
+
+.. _function-argument-safety:
+
+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<api/overload>`). See :doc:`safety<../safety>` for more information.
+
+
+.. _raw-function-note:
+
+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.
+
+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<api/this_state>`.
+
+.. warning::
+	
+	Do NOT assume that building Lua as C++ will allow you to throw directly from a raw function. If an exception is raised and it bubbles into the Lua framework, even if you compile as C++, Lua does not recognize exceptions other than the ones that it uses with ``lua_error``. In other words, it will return some completely bogus result, potentially leave your Lua stack thrashed, and the rest of your VM *can* be in a semi-trashed state. Please avoid this!
+
+
+.. _the examples: https://github.com/ThePhD/sol2/blob/develop/examples/functions.cpp
+.. _avoid the nightmare altogether: https://github.com/ThePhD/sol2/issues/608#issuecomment-372876206