refactor: javascript/lua parity

Author: alandefreitas

include/mrdocs/Support/Lua.hpp

@@ -348,6 +348,11 @@ enum class Type
 };
 
 /** A Lua value.
+
+    Table values map to DOM arrays when they contain only positive
+    integer keys without gaps (Lua's 1-based indices are normalized to
+    zero-based arrays). Otherwise tables map to DOM objects with
+    stringified keys.
 */
 class MRDOCS_DECL
     Value
@@ -423,6 +428,33 @@ class MRDOCS_DECL
     */
     bool isTable() const noexcept;
 
+    /** Return the underlying boolean value.
+
+        @note Behavior is undefined if `!isBoolean()`
+    */
+    bool getBool() const noexcept;
+
+    /** Return the underlying integer value (Lua numbers are coerced).
+
+        @note Behavior is undefined if `!isNumber()`
+    */
+    std::int64_t getInteger() const noexcept;
+
+    /** Return the underlying string view.
+
+        @note Behavior is undefined if `!isString()`
+    */
+    std::string_view getString() const noexcept;
+
+    /** Convert the value to a DOM value.
+
+        Tables are converted to a DOM array when they contain only
+        positive integer keys with no gaps (Lua 1-based indices are
+        normalized to zero-based DOM arrays). Otherwise tables are
+        converted to DOM objects with stringified keys.
+    */
+    dom::Value getDom() const;
+
     /** Return a string representation.
 
         This function is used for diagnostics.

src/lib/Support/Lua.cpp

@@ -11,13 +11,18 @@
 #include <lib/Support/LuaHandlebars.hpp>
 #include <mrdocs/Support/Lua.hpp>
 #include <mrdocs/Support/Path.hpp>
+#include <mrdocs/Support/Assert.hpp>
 #include <mrdocs/Support/Report.hpp>
 #include <llvm/Support/raw_ostream.h>
+extern "C" {
 #include <lua.h>
 #include <lualib.h>
-#include <format>
 #include <lauxlib.h>
+}
+#include <format>
 #include <print>
+#include <algorithm>
+#include <map>
 
 namespace mrdocs {
 namespace lua {
@@ -34,6 +39,7 @@ static char gImplKey{};
 //------------------------------------------------
 
 static void domObject_push_metatable(Access& A);
+static void domArray_push_metatable(Access& A);
 static void domValue_push(Access& A, dom::Value const&);
 
 //------------------------------------------------
@@ -278,6 +284,19 @@ domArray_get(
         lua_touserdata(A, index));
 }
 
+static void
+domArray_push(
+    Access& A,
+    dom::Array const& arr)
+{
+    auto& arr_ = *static_cast<
+        dom::Array*>(lua_newuserdatauv(
+            A, sizeof(dom::Array), 0));
+    domArray_push_metatable(A);
+    lua_setmetatable(A, -2);
+    std::construct_at(&arr_, arr);
+}
+
 // Push the domObject metatable onto the stack
 [[maybe_unused]]
 static
@@ -591,8 +610,7 @@ domValue_push(
     case dom::Kind::String:
         return luaM_pushstring(A, value.getString());
     case dom::Kind::Array:
-        MRDOCS_UNREACHABLE();
-        //return domArray_push(A, value.getArray());
+        return domArray_push(A, value.getArray());
     case dom::Kind::Object:
         return domObject_push(A, value.getObject());
     default:
@@ -939,6 +957,104 @@ type() const noexcept
     }
 }
 
+bool
+Value::getBool() const noexcept
+{
+    MRDOCS_ASSERT(isBoolean());
+    Access A(*scope_);
+    return lua_toboolean(A, index_);
+}
+
+std::int64_t
+Value::getInteger() const noexcept
+{
+    MRDOCS_ASSERT(isNumber());
+    Access A(*scope_);
+    return static_cast<std::int64_t>(lua_tonumber(A, index_));
+}
+
+std::string_view
+Value::getString() const noexcept
+{
+    MRDOCS_ASSERT(isString());
+    Access A(*scope_);
+    return luaM_getstring(A, index_);
+}
+
+static dom::Value
+luaValue_toDom(Access& A, int idx)
+{
+    switch (lua_type(A, idx))
+    {
+    case LUA_TNIL:
+        return dom::Value(nullptr);
+    case LUA_TBOOLEAN:
+        return dom::Value(lua_toboolean(A, idx) != 0);
+    case LUA_TNUMBER:
+        return dom::Value(static_cast<std::int64_t>(lua_tonumber(A, idx)));
+    case LUA_TSTRING:
+        return dom::Value(luaM_getstring(A, idx));
+    case LUA_TFUNCTION:
+        return dom::Value(dom::Kind::Undefined); // no Lua->DOM function bridge yet
+    case LUA_TTABLE:
+    {
+        // Decide between array-like and object-like
+        std::map<std::size_t, dom::Value> intItems;
+        dom::Object obj;
+        bool arrayLike = true;
+        std::size_t maxIndex = 0;
+
+        lua_pushnil(A); // first key
+        while (lua_next(A, idx) != 0)
+        {
+            if (lua_isinteger(A, -2))
+            {
+                auto k = static_cast<std::size_t>(lua_tointeger(A, -2));
+                maxIndex = std::max(maxIndex, k);
+                intItems[k] = luaValue_toDom(A, -1);
+            }
+            else
+            {
+                arrayLike = false;
+                obj.set(std::string(luaM_getstring(A, -2)), luaValue_toDom(A, -1));
+            }
+            lua_pop(A, 1); // pop value keep key
+        }
+
+        if (arrayLike && obj.empty())
+        {
+            dom::Array arr;
+            for (std::size_t i = 1; i <= maxIndex; ++i)
+            {
+                auto it = intItems.find(i);
+                if (it != intItems.end())
+                    arr.push_back(it->second);
+                else
+                    arr.push_back(dom::Value());
+            }
+            return dom::Value(std::move(arr));
+        }
+
+        for (auto const& [k, v] : intItems)
+        {
+            obj.set(std::to_string(k), v);
+        }
+        return dom::Value(std::move(obj));
+    }
+    default:
+        return dom::Value(dom::Kind::Undefined);
+    }
+}
+
+dom::Value
+Value::getDom() const
+{
+    if (!scope_)
+        return dom::Value();
+    Access A(*scope_);
+    return luaValue_toDom(A, index_);
+}
+
 std::string
 Value::
 displayString() const

src/lib/Support/LuaHandlebars.hpp

@@ -16,7 +16,11 @@
 
 namespace mrdocs {
 
-/** Add the Handlebars Lua instance as a global
+/** Add the Handlebars Lua instance as a global.
+
+    Lua integration does not currently expose a per-helper registration API
+    like the JavaScript bridge; helpers are loaded via the embedded scripts
+    provided by tryLoadHandlebars().
 */
 MRDOCS_DECL
 Expected<void>

src/test/Support/Lua.cpp

@@ -0,0 +1,86 @@
+//
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2025 Alan de Freitas ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdocs
+//
+
+#include <mrdocs/Support/Lua.hpp>
+#include <test_suite/test_suite.hpp>
+
+namespace mrdocs {
+namespace lua {
+
+struct LuaSupportTest
+{
+    void test_primitives()
+    {
+        Context ctx;
+        Scope scope(ctx);
+
+        auto fnBool = scope.loadChunk("return true").value();
+        Value b = fnBool();
+        BOOST_TEST(b.isBoolean());
+        BOOST_TEST(b.getBool() == true);
+        BOOST_TEST(b.getDom().getBool() == true);
+
+        auto fnInt = scope.loadChunk("return 42").value();
+        Value i = fnInt();
+        BOOST_TEST(i.isNumber());
+        BOOST_TEST(i.getInteger() == 42);
+        BOOST_TEST(i.getDom().getInteger() == 42);
+
+        auto fnStr = scope.loadChunk("return 'hello'").value();
+        Value s = fnStr();
+        BOOST_TEST(s.isString());
+        BOOST_TEST(s.getString() == "hello");
+        BOOST_TEST(s.getDom().getString() == "hello");
+    }
+
+    void test_array_table()
+    {
+        Context ctx;
+        Scope scope(ctx);
+
+        auto fnArr = scope.loadChunk("return {1, 2, 3}").value();
+        Value arr = fnArr();
+        BOOST_TEST(arr.isTable());
+        auto dv = arr.getDom();
+        BOOST_TEST(dv.isArray());
+        auto da = dv.getArray();
+        BOOST_TEST(da.size() == 3);
+        BOOST_TEST(da.get(0).getInteger() == 1);
+        BOOST_TEST(da.get(1).getInteger() == 2);
+        BOOST_TEST(da.get(2).getInteger() == 3);
+    }
+
+    void test_object_table()
+    {
+        Context ctx;
+        Scope scope(ctx);
+
+        auto fnObj = scope.loadChunk("return { a = 1, b = 'x' }").value();
+        Value obj = fnObj();
+        BOOST_TEST(obj.isTable());
+        auto dv = obj.getDom();
+        BOOST_TEST(dv.isObject());
+        auto dObj = dv.getObject();
+        BOOST_TEST(dObj.get("a").getInteger() == 1);
+        BOOST_TEST(dObj.get("b").getString() == "x");
+    }
+
+    void run()
+    {
+        test_primitives();
+        test_array_table();
+        test_object_table();
+    }
+};
+
+TEST_SUITE(LuaSupportTest, "mrdocs.lua.support");
+
+} // namespace lua
+} // namespace mrdocs