rod.hpp

Go to the documentation of this file.

#pragma once
#include <array>
#include <cstddef>
#include <functional>
#include <meta>
#include <type_traits>
#include <utility>
#include <vector>
 
#include <welder/welder.hpp>           // welder::welder + rod contract + driver
#include <welder/rods/lua/sol2/metamethods.hpp> // operator -> sol2 metamethod map
#include <welder/bind_traits.hpp>      // aggregate_* helpers
 
#include <sol/sol.hpp>
 
namespace welder::inline v0::rods::sol2 {
 
// Note: the namespace is `welder::rods::sol2`; the library namespace is `::sol`. They do
// not collide, so `sol::` below refers to the library without an alias (unlike the
// Python backends, whose namespace shadowed the library's).

template <class T, class... A>
using ctor_sig = T(A...);

struct rod {
    static constexpr lang language{lang::lua}; 
    using module_type = ::sol::table;          

    struct session {
        ::sol::table getters{}; 
        ::sol::table setters{}; 
        bool has_live{false};   
    };
 
  protected:
    // --- implementation helpers (not part of the welder::rod contract) --

    template <class T>
    static constexpr bool _needs_registration =
        std::is_enum_v<std::remove_cvref_t<T>> ||
        ::sol::lua_type_of<std::remove_cvref_t<T>>::value == ::sol::type::userdata;

    template <class E>
    struct _enum_binding {
        ::sol::table values;      
        std::function<void(const char*, lua_Integer)>
            mirror;               
        bool scoped;              
    };

    template <class T, auto Ctors, bool HasDefault, bool Aggregate>
    static consteval std::vector<std::meta::info> _ctor_signatures() {
        std::vector<std::meta::info> sigs;
        auto sig = [](std::vector<std::meta::info> targs) {
            return std::meta::dealias(std::meta::substitute(^^ctor_sig, targs));
        };
        if (HasDefault)
            sigs.push_back(sig({^^T}));
        for (auto c : Ctors) {
            std::vector<std::meta::info> targs{^^T};
            for (auto p : std::meta::parameters_of(c))
                targs.push_back(std::meta::type_of(p));
            sigs.push_back(sig(targs));
        }
        // constexpr-if: the branch indexes the field array, which must not be
        // instantiated for a fieldless type (the array<info, 0> trap) — and
        // Aggregate guarantees at least one field.
        if constexpr (Aggregate) {
            // One arity per omissible NSDMI-suffix tail (aggregate_required_arity):
            // C++26 parenthesized aggregate init fills omitted trailing fields
            // from their NSDMIs, so T(prefix…) is valid for every prefix length
            // down to the required arity. Arity 0 would duplicate the default
            // constructor's signature, so it starts at 1 when that is bound.
            auto fields{::welder::detail::aggregate_fields<T>()};
            std::size_t start{::welder::detail::aggregate_required_arity<T>()};
            if (HasDefault && start == 0)
                start = 1;
            for (std::size_t arity{start}; arity <= fields.size(); ++arity) {
                std::vector<std::meta::info> targs{^^T};
                for (std::size_t i{0}; i < arity; ++i)
                    targs.push_back(std::meta::type_of(fields[i]));
                sigs.push_back(sig(targs));
            }
        }
        return sigs;
    }

    template <class T, auto Ctors, bool HasDefault, bool Aggregate>
    static consteval auto _ctor_sigs_array() {
        constexpr std::size_t n{
            _ctor_signatures<T, Ctors, HasDefault, Aggregate>().size()};
        std::array<std::meta::info, n> out{};
        // Guard the fill: std::array<T, 0>::operator[] is not consteval, so it must
        // not be instantiated for a type with no exposed constructors.
        if constexpr (n != 0) {
            auto v{_ctor_signatures<T, Ctors, HasDefault, Aggregate>()};
            for (std::size_t i{0}; i < n; ++i)
                out[i] = v[i];
        }
        return out;
    }

    template <class T, auto Sigs, std::size_t... I>
    static void _set_constructors(::sol::usertype<T>& ut,
                                  std::index_sequence<I...>) {
        // Expose both the call form `T(…)` and the idiomatic `T.new(…)`.
        ut[::sol::call_constructor] = ::sol::constructors<typename [:Sigs[I]:]...>();
        ut["new"] = ::sol::constructors<typename [:Sigs[I]:]...>();
    }
 

    template <class T, auto Bases, std::size_t... I>
    static auto _make_usertype(::sol::table& m, const char* name,
                               std::index_sequence<I...>) {
        // sol2's "automagic" enrollment would auto-register metamethods straight
        // off the C++ type (SFINAE-detected operator==/</<=, operator(), the
        // ostream inserter) — bypassing welder's resolution, so an excluded or
        // per-language-scoped operator would leak into Lua anyway. Welder
        // registers every operator slot itself (add_operator/add_comparisons/
        // add_stringifier), so those enrollments are switched off; the
        // default constructor is off too (the real set is installed afterwards
        // by add_constructors, the driver's one call — this is what
        // sol::no_constructor achieved before enrollments took its overload
        // slot). Destructor/pairs/length automagic stay on (welder has no
        // opinion there).
        ::sol::automagic_enrollments enroll{};
        enroll.default_constructor = false;
        enroll.to_string_operator = false;
        enroll.call_operator = false;
        enroll.less_than_operator = false;
        enroll.less_than_or_equal_to_operator = false;
        enroll.equal_to_operator = false;
        ::sol::usertype<T> ut{m.new_usertype<T>(name, enroll)};
        if constexpr (sizeof...(I) != 0)
            ut[::sol::base_classes] =
                ::sol::bases<typename [:Bases[I]:]...>();
        return ut;
    }

    static consteval void _collect_welded_bases(
        std::meta::info type, lang L, std::vector<std::meta::info>& out) {
        for (auto base : ::welder::public_bases(type)) {
            const bool welded{::welder::welded_for(base, L)};
            if (welded) {
                bool seen{false};
                for (auto e : out)
                    if (e == base) {
                        seen = true;
                        break;
                    }
                if (seen)
                    continue;
                out.push_back(base);
            }
            _collect_welded_bases(base, L, out); // descend (into welded bases too)
        }
    }

    template <class T>
    static consteval auto _welded_bases_array() {
        constexpr std::size_t n{[] {
            std::vector<std::meta::info> v;
            _collect_welded_bases(^^T, lang::lua, v);
            return v.size();
        }()};
        std::array<std::meta::info, n> out{};
        // Guard the fill: std::array<T, 0>::operator[] is not consteval.
        if constexpr (n != 0) {
            std::vector<std::meta::info> v;
            _collect_welded_bases(^^T, lang::lua, v);
            for (std::size_t i{0}; i < n; ++i)
                out[i] = v[i];
        }
        return out;
    }

    template <auto Grp, class Target, std::size_t... I>
    static void _register_named(Target& t, const char* name,
                                std::index_sequence<I...>) {
        // sol2 owns a returned object structurally (a value → a Lua-owned
        // copy/move; a pointer/reference → a non-owning view), so a
        // [[=welder::return_policy]] has no runtime effect here — but a
        // self-contradictory one (a reference to a returned temporary) is still
        // rejected, uniformly with the Python rods.
        (::welder::validate_return_policy<Grp[I], language>(), ...);
        if constexpr (sizeof...(I) == 1)
            t[name] = &[:Grp[0]:];
        else
            t[name] = ::sol::overload(&[:Grp[I]:]...);
    }

    template <auto Grp, class Target, std::size_t... I>
    static void _register_operator(Target& t, std::index_sequence<I...>) {
        (::welder::validate_return_policy<Grp[I], language>(), ...);
        constexpr auto slot{operator_mm(Grp[0]).fn};
        if constexpr (sizeof...(I) == 1)
            t[slot] = &[:Grp[0]:];
        else
            t[slot] = ::sol::overload(&[:Grp[I]:]...);
    }
 
    // --- live namespace-variable proxy --------------------------------------

    static ::sol::object _prev_index(::sol::this_state ts, const ::sol::object& prev,
                                     const ::sol::table& self, const ::sol::object& key) {
        if (prev.get_type() == ::sol::type::function)
            return ::sol::object{prev.as<::sol::function>()(self, key)};
        if (prev.get_type() == ::sol::type::table)
            return ::sol::object{prev.as<::sol::table>()[key]};
        return ::sol::make_object(ts, ::sol::lua_nil);
    }

    static void _prev_newindex(const ::sol::object& prev, ::sol::table self,
                               const ::sol::object& key, const ::sol::object& value) {
        if (prev.get_type() == ::sol::type::function) {
            prev.as<::sol::function>()(self, key, value);
            return;
        }
        if (prev.get_type() == ::sol::type::table) {
            prev.as<::sol::table>()[key] = value;
            return;
        }
        self.raw_set(key, value);
    }

    static void _install_live_variables(module_type& m, ::sol::table getters,
                                        ::sol::table setters) {
        lua_State* L{m.lua_state()};
        ::sol::state_view lua{L};
        // Fetch any existing metatable via the raw C API: reading it through a
        // checked sol::table would fail SOL_ALL_SAFETIES_ON when there is none (nil
        // is not a table). A pre-existing metatable (a prior live-variable install
        // onto the same table) is reused and chained; otherwise a fresh one is made.
        m.push();                                        // [module]
        const bool had_mt{lua_getmetatable(L, -1) != 0}; // [module, mt?]
        ::sol::table mt{had_mt ? ::sol::stack::pop<::sol::table>(L)
                               : lua.create_table()};
        lua_pop(L, 1);                                    // pop [module]
        // Capture any metamethods to chain (a state-bound nil when absent, so the
        // fallback helpers can safely query get_type()).
        ::sol::object prev_index{mt["__index"]};
        ::sol::object prev_newindex{mt["__newindex"]};
 
        mt["__index"] = [getters, prev_index](::sol::this_state ts, ::sol::table self,
                                              ::sol::object key) -> ::sol::object {
            ::sol::object g{getters[key]};
            if (g.get_type() == ::sol::type::function)
                return ::sol::object{g.as<::sol::function>()()}; // live read of the C++ global
            return _prev_index(ts, prev_index, self, key);
        };
        mt["__newindex"] = [setters, prev_newindex](::sol::table self, ::sol::object key,
                                                    ::sol::object value) {
            ::sol::object s{setters[key]};
            if (s.get_type() == ::sol::type::function) {
                s.as<::sol::function>()(value); // live write through to the C++ global
                return;                         // no rawset: the key stays live
            }
            _prev_newindex(prev_newindex, self, key, value);
        };
        m[::sol::metatable_key] = mt;
    }
 
  public:
    // --- caster oracle + emission primitives (the welder::rod contract) --

    template <class T> using class_handle_type = ::sol::usertype<T>;
    template <class E> using enum_handle_type = _enum_binding<E>;

    template <class T>
    static constexpr bool has_native_caster = !_needs_registration<T>;

    static consteval const char* special_method_name(std::meta::info op_fn) {
        return operator_mm(op_fn).name;
    }
 
    // --- class binding ------------------------------------------------------

    template <class T, auto Bases, std::size_t... I>
    static auto make_class(module_type& m, const char* name, const char* /*doc*/,
                           std::index_sequence<I...> /*seq*/) {
        constexpr auto bases{_welded_bases_array<T>()};
        return _make_usertype<T, bases>(
            m, name, std::make_index_sequence<bases.size()>{});
    }

    template <class T, auto Bases, std::size_t... I>
    static auto make_nested_class(module_type& m, auto& outer, const char* name,
                                  const char* doc, std::index_sequence<I...> seq) {
        auto ut{make_class<T, Bases>(m, name, doc, seq)};
        outer[name] = ut;          // Outer.Inner = the usertype (a lua reference
                                   // value registers as a static entry)
        m[name] = ::sol::lua_nil;  // drop the temporary module-scope key
        return ut;
    }

    template <class T, auto Ctors, bool HasDefault, bool Aggregate, bool Copyable,
              class Style = ::welder::naming::none>
    static void add_constructors(::sol::usertype<T>& ut) {
        constexpr auto sigs{_ctor_sigs_array<T, Ctors, HasDefault, Aggregate>()};
        if constexpr (sigs.size() != 0)
            _set_constructors<T, sigs>(ut, std::make_index_sequence<sigs.size()>{});
    }

    template <std::meta::info Mem, class Style = ::welder::naming::none>
    static void add_field(auto& ut) {
        constexpr const char* name{
            ::welder::name_of<Mem, language, Style, ::welder::ent_kind::field>()};
        constexpr bool read_only{std::meta::is_const_type(std::meta::type_of(Mem)) ||
                                 ::welder::member_no_reassign(Mem, language)};
        if constexpr (!std::meta::is_public(Mem)) {
            // A protected member (admitted under policy::weld_protected) binds
            // as a sol::property over welder::detail::field_access — gcc-16
            // rejects the dependent `&[:Mem:]` for protected data (see
            // field_access).
            using fa = ::welder::detail::field_access<Mem>;
            if constexpr (read_only)
                ut[name] = ::sol::readonly_property(&fa::get);
            else
                ut[name] = ::sol::property(&fa::get, &fa::set);
        } else if constexpr (read_only) {
            ut[name] = ::sol::readonly(&[:Mem:]);
        } else {
            ut[name] = &[:Mem:];
        }
    }

    template <class T, std::meta::info Getter, std::meta::info Setter>
    static void add_property(auto& ut, const char* name) {
        ::welder::validate_return_policy<Getter, language>();
        if constexpr (Setter == std::meta::info{}) {
            ut[name] = ::sol::readonly_property(&[:Getter:]);
        } else if constexpr (std::is_void_v<
                                 typename [:std::meta::return_type_of(Setter):]>) {
            ut[name] = ::sol::property(&[:Getter:], &[:Setter:]);
        } else {
            // A value-returning setter (a fluent T& set_x(…)): discard the
            // return — the property protocol has no slot for it, and the gate
            // deliberately never checked it.
            using Arg = typename
                [:std::meta::type_of(std::meta::parameters_of(Setter)[0]):];
            static constexpr auto sp{&[:Setter:]};
            ut[name] = ::sol::property(
                &[:Getter:],
                [](T& self, Arg v) { (self.*sp)(std::forward<Arg>(v)); });
        }
    }

    template <auto Fns, class Style = ::welder::naming::none>
    static void add_method(auto& ut) {
        _register_named<Fns>(
            ut,
            ::welder::name_of<Fns[0], language, Style, ::welder::ent_kind::method>(),
            std::make_index_sequence<Fns.size()>{});
    }

    template <auto Fns, class Style = ::welder::naming::none>
    static void add_static_method(auto& ut) {
        _register_named<Fns>(
            ut,
            ::welder::name_of<Fns[0], language, Style,
                              ::welder::ent_kind::static_method>(),
            std::make_index_sequence<Fns.size()>{});
    }

    template <class T, auto Fns>
    static void add_operator(auto& ut) {
        _register_operator<Fns>(ut, std::make_index_sequence<Fns.size()>{});
    }

    template <class T, auto Fns, auto Covered>
    static void add_comparisons(auto& ut) {
        constexpr auto seq{std::make_index_sequence<Fns.size()>{}};
        if constexpr (!Covered[0])
            _register_synth_cmp<T, Fns, ::welder::detail::cmp_slot::lt>(ut, seq);
        if constexpr (!Covered[1])
            _register_synth_cmp<T, Fns, ::welder::detail::cmp_slot::le>(ut, seq);
    }

    template <class T, std::meta::info Fn>
    static void add_stringifier(auto& ut) {
        ut[::sol::meta_function::to_string] = &::welder::detail::stringify<T, Fn>;
    }
 
  private:
    template <class T, auto Fns, ::welder::detail::cmp_slot S, class Target,
              std::size_t... I>
    static void _register_synth_cmp(Target& ut, std::index_sequence<I...>) {
        constexpr ::sol::meta_function slot{
            S == ::welder::detail::cmp_slot::lt
                ? ::sol::meta_function::less_than
                : ::sol::meta_function::less_than_or_equal_to};
        using ::welder::detail::synthesized_comparison;
        ut[slot] = ::sol::overload(
            &synthesized_comparison<
                T,
                std::remove_cvref_t<typename [: ::welder::detail::
                                                    comparison_operand(
                                                        Fns[I], ^^T) :]>,
                S>::call...,
            &synthesized_comparison<
                std::remove_cvref_t<typename [: ::welder::detail::
                                                    comparison_operand(
                                                        Fns[I], ^^T) :]>,
                T, S>::call...);
    }
 
  public:
 
    // --- enum binding -------------------------------------------------------

    template <class E>
    static auto make_enum(module_type& m, const char* name, const char* /*doc*/) {
        ::sol::table values{::sol::state_view{m.lua_state()}.create_table()};
        m[name] = values;
        return _enum_binding<E>{
            values, [m](const char* n, lua_Integer v) mutable { m[n] = v; },
            std::is_scoped_enum_v<E>};
    }

    template <class E>
    static auto make_nested_enum(module_type& m, auto& outer, const char* name,
                                 const char* /*doc*/) {
        ::sol::table values{::sol::state_view{m.lua_state()}.create_table()};
        outer[name] = values; // a reference value registers as a static entry
        return _enum_binding<E>{
            values,
            // sol::var marks the plain integer as a STATIC variable — a bare
            // value assignment would be wrapped as a bound function.
            [outer](const char* n, lua_Integer v) mutable {
                outer[n] = ::sol::var(v);
            },
            std::is_scoped_enum_v<E>};
    }

    template <std::meta::info Enum, class Style = ::welder::naming::none>
    static void add_enumerator(auto& e) {
        constexpr const char* name{
            ::welder::name_of<Enum, language, Style, ::welder::ent_kind::enumerator>()};
        const lua_Integer value{static_cast<lua_Integer>(std::to_underlying([:Enum:]))};
        e.values[name] = value;
        if (!e.scoped)
            e.mirror(name, value);
    }

    template <class /*E*/>
    static void finish_enum(auto&) {}
 
    // --- namespace / module binding -----------------------------------------

    static session open_module(module_type&) { return {}; }

    static void set_module_doc(module_type&, const char*) {}

    template <auto Fns, class Style = ::welder::naming::none>
    static sol::object add_function(module_type& m, const char* name = nullptr) {
        const char* fn_name{::welder::name_of_or<
            Fns[0], language, Style, ::welder::ent_kind::function>(name)};
        _register_named<Fns>(m, fn_name, std::make_index_sequence<Fns.size()>{});
        return m.get<sol::object>(fn_name);
    }

    template <std::meta::info Var, class Style = ::welder::naming::none>
    static void add_variable(module_type& m, session& s, const char* name = nullptr) {
        const char* key{::welder::name_of_or<Var, language, Style,
                                             ::welder::ent_kind::variable>(name)};
        if constexpr (std::meta::is_const_type(std::meta::type_of(Var))) {
            m[key] = [:Var:]; // immutable: a value snapshot at load time
        } else {
            if (!s.has_live) {
                ::sol::state_view lua{m.lua_state()};
                s.getters = lua.create_table();
                s.setters = lua.create_table();
                s.has_live = true;
            }
            s.getters[key] = [] { return [:Var:]; };
            s.setters[key] = [](typename [:std::meta::type_of(Var):] v) {
                [:Var:] = v;
            };
        }
    }

    static module_type add_submodule(module_type& m, const char* name) {
        ::sol::table sub{::sol::state_view{m.lua_state()}.create_table()};
        m[name] = sub;
        return sub;
    }

    static void close_module(module_type& m, session& s) {
        if (s.has_live)
            _install_live_variables(m, s.getters, s.setters);
    }
};
 
static_assert(::welder::rod<rod>,
              "welder::rods::sol2::rod must satisfy welder::rod");
 
} // namespace welder::rods::sol2