Fix Stack<bool>::get type checking; add LUABRIDGE_STRICT_STACK_CONVERSIONS (#215)

Author: Copilot

Distribution/LuaBridge/LuaBridge.h

@@ -91,6 +91,10 @@
 #define LUABRIDGE_SAFE_STACK_CHECKS 1
 #endif
 
+#if !defined(LUABRIDGE_STRICT_STACK_CONVERSIONS)
+#define LUABRIDGE_STRICT_STACK_CONVERSIONS 0
+#endif
+
 #if !defined(LUABRIDGE_SAFE_LUA_C_EXCEPTION_HANDLING)
 #define LUABRIDGE_SAFE_LUA_C_EXCEPTION_HANDLING 0
 #endif
@@ -4055,6 +4059,11 @@ struct Stack<bool>
 
     [[nodiscard]] static TypeResult<bool> get(lua_State* L, int index)
     {
+#if LUABRIDGE_STRICT_STACK_CONVERSIONS
+        if (lua_type(L, index) != LUA_TBOOLEAN)
+            return makeErrorCode(ErrorCode::InvalidTypeCast);
+#endif
+
         return lua_toboolean(L, index) ? true : false;
     }
 
@@ -4795,6 +4804,7 @@ struct Stack<std::string>
         {
             str = lua_tolstring(L, index, &length);
         }
+#if !LUABRIDGE_STRICT_STACK_CONVERSIONS
         else
         {
 #if LUABRIDGE_SAFE_STACK_CHECKS
@@ -4806,6 +4816,7 @@ struct Stack<std::string>
             str = lua_tolstring(L, -1, &length);
             lua_pop(L, 1);
         }
+#endif
 
         if (str == nullptr)
             return makeErrorCode(ErrorCode::InvalidTypeCast);

Manual.md

@@ -67,6 +67,13 @@ Contents
 
 *   [5 - Security](#5---security)
 
+*   [6 - Configuration](#6---configuration)
+
+    * [6.1 - LUABRIDGE_SAFE_STACK_CHECKS](#61---luabridge-safe-stack-checks)
+    * [6.2 - LUABRIDGE_STRICT_STACK_CONVERSIONS](#62---luabridge-strict-stack-conversions)
+    * [6.3 - LUABRIDGE_SAFE_LUA_C_EXCEPTION_HANDLING](#63---luabridge-safe-c-exception-handling)
+    * [6.4 - LUABRIDGE_RAISE_UNREGISTERED_CLASS_USAGE](#64---luabridge-raise-unregistered-class-usage)
+
 *   [Appendix - API Reference](#appendix---api-reference)
 
 1 - Introduction
@@ -1717,6 +1724,93 @@ luabridge::getGlobalNamespace (L)
   .endNamespace ()
 ```
 
+6 - Configuration
+=================
+
+LuaBridge3 exposes several compile-time configuration macros. Each macro can be overridden by defining it **before** including any LuaBridge header, or by passing it as a compiler flag (e.g. `-DLUABRIDGE_SAFE_STACK_CHECKS=0`).
+
+6.1 - LUABRIDGE_SAFE_STACK_CHECKS
+----------------------------------
+
+**Default: `1` (enabled)**
+
+When enabled, every `Stack<T>::push` operation calls `lua_checkstack` before pushing a value. This prevents silent stack overflows when the Lua stack is exhausted.
+
+Disable this flag only when you are certain that the Lua stack will never overflow and you need to squeeze out the last bit of performance:
+
+```cpp
+#define LUABRIDGE_SAFE_STACK_CHECKS 0
+#include <LuaBridge/LuaBridge.h>
+```
+
+6.2 - LUABRIDGE_STRICT_STACK_CONVERSIONS
+-----------------------------------------
+
+**Default: `0` (disabled)**
+
+Controls how permissive the `Stack<T>::get` operations are when reading values off the Lua stack.
+
+| Type | Non-strict (default) | Strict |
+|------|---------------------|--------|
+| `bool` | Any Lua value is accepted via `lua_toboolean` (legacy behavior) | Only `LUA_TBOOLEAN` is accepted |
+| Integers | Any `LUA_TNUMBER` that fits the target integer type is accepted | Any `LUA_TNUMBER` that fits the target integer type is accepted (same behavior) |
+| `std::string` | `LUA_TSTRING` and `LUA_TNUMBER` accepted (numbers coerced to strings) | Only `LUA_TSTRING` is accepted |
+
+In non-strict mode (the default), `lua_toboolean` semantics apply to `bool`: every Lua value except `false` and `nil` is truthy. This preserves backward-compatible behavior for existing code bases.
+
+Enable strict mode when you want explicit, type-safe conversions:
+
+```cpp
+#define LUABRIDGE_STRICT_STACK_CONVERSIONS 1
+#include <LuaBridge/LuaBridge.h>
+```
+
+With strict mode enabled:
+
+```cpp
+lua_pushinteger (L, 42);
+auto r = luabridge::Stack<bool>::get (L, -1); // error: not a boolean
+
+lua_pushnil (L);
+auto r = luabridge::Stack<bool>::get (L, -1); // error: not a boolean
+
+lua_pushstring (L, "hello");
+auto r = luabridge::Stack<bool>::get (L, -1); // error: not a boolean
+
+lua_pushboolean (L, 1);
+auto r = luabridge::Stack<bool>::get (L, -1); // ok: true
+```
+
+6.3 - LUABRIDGE_SAFE_LUA_C_EXCEPTION_HANDLING
+-----------------------------------------------
+
+**Default: `0` (disabled). Only meaningful when `LUABRIDGE_HAS_EXCEPTIONS` is `1`.**
+
+When Lua is compiled as C and a C++ exception escapes a registered `lua_CFunction`, the Lua runtime will call `longjmp` instead of propagating the exception, which leads to undefined behavior. Enabling this flag adds a safe indirection that catches C++ exceptions at the CFunction boundary and re-raises them as Lua errors.
+
+Enable this flag only if you are compiling Lua as C (not as C++), have exceptions enabled in your application, and you observe crashes when registered CFunctions throw:
+
+```cpp
+#define LUABRIDGE_SAFE_LUA_C_EXCEPTION_HANDLING 1
+#include <LuaBridge/LuaBridge.h>
+```
+
+> **Warning:** Enabling this flag introduces a small performance overhead on every registered CFunction call through the library.
+
+6.4 - LUABRIDGE_RAISE_UNREGISTERED_CLASS_USAGE
+------------------------------------------------
+
+**Default: `1` when exceptions are enabled, `0` otherwise.**
+
+When enabled, using an unregistered class with LuaBridge (for example, passing an instance of a type that has not been registered via `beginClass`) will raise an error rather than silently failing. With exceptions enabled this translates to a `luabridge::LuaException`; with exceptions disabled it translates to a Lua error via `lua_error`.
+
+Override the default when you need fine-grained control:
+
+```cpp
+#define LUABRIDGE_RAISE_UNREGISTERED_CLASS_USAGE 0
+#include <LuaBridge/LuaBridge.h>
+```
+
 Appendix - API Reference
 ========================
 

Source/LuaBridge/detail/Config.h

@@ -67,6 +67,25 @@
 #define LUABRIDGE_SAFE_STACK_CHECKS 1
 #endif
 
+/**
+ * @brief Enable strict stack conversions to enforce exact type matching when getting values from the stack.
+ *
+ * When enabled:
+ * - `Stack<bool>::get` only accepts `LUA_TBOOLEAN` (nil is not convertible to bool).
+ * - Integer `Stack` specializations only accept Lua integer values (not floats with integer representation, on Lua 5.3+).
+ * - `Stack<std::string>::get` only accepts `LUA_TSTRING` (numbers are not coerced to strings).
+ *
+ * When disabled (default), a more permissive conversion is used:
+ * - `Stack<bool>::get` accepts `LUA_TBOOLEAN` and `LUA_TNIL` (nil converts to false).
+ * - Integer `Stack` specializations accept any `LUA_TNUMBER` that can be represented as the target integer type.
+ * - `Stack<std::string>::get` accepts `LUA_TSTRING` and `LUA_TNUMBER` (numbers are coerced to strings).
+ *
+ * @note Default is disabled.
+ */
+#if !defined(LUABRIDGE_STRICT_STACK_CONVERSIONS)
+#define LUABRIDGE_STRICT_STACK_CONVERSIONS 0
+#endif
+
 /**
  * @brief Enable safe exception handling when lua is compiled as `C` and exceptions raise during execution of registered `lua_CFunction`.
  * 

Source/LuaBridge/detail/Stack.h

@@ -176,6 +176,11 @@ struct Stack<bool>
 
     [[nodiscard]] static TypeResult<bool> get(lua_State* L, int index)
     {
+#if LUABRIDGE_STRICT_STACK_CONVERSIONS
+        if (lua_type(L, index) != LUA_TBOOLEAN)
+            return makeErrorCode(ErrorCode::InvalidTypeCast);
+#endif
+
         return lua_toboolean(L, index) ? true : false;
     }
 
@@ -995,6 +1000,7 @@ struct Stack<std::string>
         {
             str = lua_tolstring(L, index, &length);
         }
+#if !LUABRIDGE_STRICT_STACK_CONVERSIONS
         else
         {
 #if LUABRIDGE_SAFE_STACK_CHECKS
@@ -1010,6 +1016,7 @@ struct Stack<std::string>
             str = lua_tolstring(L, -1, &length);
             lua_pop(L, 1);
         }
+#endif
 
         if (str == nullptr)
             return makeErrorCode(ErrorCode::InvalidTypeCast);

Tests/Source/StackTests.cpp

@@ -190,11 +190,13 @@ TEST_F(StackTests, BoolStackOverflow)
 
 TEST_F(StackTests, BoolInvalidType)
 {
+#if !LUABRIDGE_STRICT_STACK_CONVERSIONS
+    // Non-strict mode: any Lua value is accepted via lua_toboolean
     {
         (void)luabridge::Stack<int>::push(L, 0);
         auto result = luabridge::Stack<bool>::get(L, -1);
         ASSERT_TRUE(result);
-        EXPECT_TRUE(*result);
+        EXPECT_TRUE(*result); // integer 0 is truthy in Lua
     }
 
     {
@@ -208,8 +210,28 @@ TEST_F(StackTests, BoolInvalidType)
         (void)luabridge::Stack<std::nullptr_t>::push(L, nullptr);
         auto result = luabridge::Stack<bool>::get(L, -1);
         ASSERT_TRUE(result);
-        EXPECT_FALSE(*result);
+        EXPECT_FALSE(*result); // nil is falsy
     }
+#else
+    // Strict mode: only LUA_TBOOLEAN is accepted
+    {
+        (void)luabridge::Stack<int>::push(L, 0);
+        auto result = luabridge::Stack<bool>::get(L, -1);
+        ASSERT_FALSE(result);
+    }
+
+    {
+        (void)luabridge::Stack<int>::push(L, 42);
+        auto result = luabridge::Stack<bool>::get(L, -1);
+        ASSERT_FALSE(result);
+    }
+
+    {
+        (void)luabridge::Stack<std::nullptr_t>::push(L, nullptr);
+        auto result = luabridge::Stack<bool>::get(L, -1);
+        ASSERT_FALSE(result);
+    }
+#endif
 }
 
 TEST_F(StackTests, CharType)

Tests/Source/Tests.cpp

@@ -1243,9 +1243,24 @@ TEST_F(LuaBridgeTest, BooleanNoValue)
             .endClass()
         .endNamespace();
 
+#if !LUABRIDGE_STRICT_STACK_CONVERSIONS
+    // Non-strict mode: no value at the argument index is accepted as false via lua_toboolean
     runLua("local foo = test.ConstructibleFromBool(); result = foo:val()");
     ASSERT_TRUE(result().isBool());
     EXPECT_FALSE(result<bool>());
+#else
+    // Strict mode: missing bool argument must fail
+#if LUABRIDGE_HAS_EXCEPTIONS
+    EXPECT_THROW(runLua("local foo = test.ConstructibleFromBool(); result = foo:val()"), std::runtime_error);
+#else
+    EXPECT_FALSE(runLua("local foo = test.ConstructibleFromBool(); result = foo:val()"));
+#endif
+#endif
+
+    // Passing false explicitly must work
+    runLua("local foo = test.ConstructibleFromBool(false); result = foo:val()");
+    ASSERT_TRUE(result().isBool());
+    EXPECT_FALSE(result<bool>());
 }
 
 #if LUABRIDGE_HAS_EXCEPTIONS