rod.hpp

Go to the documentation of this file.

#pragma once
 
#include <cstddef>
#include <meta>
#include <ostream>
#include <string>
#include <type_traits>
#include <utility>
#include <vector>
 
#include <welder/welder.hpp>           // welder::welder + rod contract + driver
#include <welder/rods/lua/luacats/document.hpp> // the document + writer handles
#include <welder/rods/lua/luacats/type_map.hpp> // lua_type / operator map / text
#include <welder/bind_traits.hpp>      // aggregate_fields / is_unary_operator
#include <welder/doc.hpp>              // doc_of / param_docs / return_doc_of
 
namespace welder::inline v0::rods::luacats {

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

    template <class> using class_handle_type = class_writer;
    template <class> using enum_handle_type = enum_writer;
 
    struct session {}; 
 
  protected:
    // --- implementation helpers (not part of the welder::rod contract) --

    template <auto Bases, std::size_t... I>
    static consteval const char* _bases_string(std::index_sequence<I...>) {
        std::string out{};
        ((out += (out.empty() ? "" : ", ") + qualified_name(Bases[I])), ...);
        return std::define_static_string(out);
    }

    template <class T, std::size_t... J>
    static void _aggregate_param_lines(std::string& out, std::string& args,
                                       std::index_sequence<J...>) {
        static constexpr auto fields{::welder::detail::aggregate_fields<T>()};
        static constexpr const char* names[]{
            std::define_static_string(std::meta::identifier_of(fields[J]))...};
        static constexpr const char* types[]{
            lua_type(std::meta::type_of(fields[J]))...};
        for (std::size_t i{0}; i < sizeof...(J); ++i) {
            out += "---@param ";
            out += names[i];
            out += ' ';
            out += types[i];
            out += '\n';
            args += (args.empty() ? "" : ", ");
            args += names[i];
        }
    }

    template <class T, std::size_t... J>
    static std::string _aggregate_fun_params(std::index_sequence<J...>) {
        static constexpr auto fields{::welder::detail::aggregate_fields<T>()};
        static constexpr const char* names[]{
            std::define_static_string(std::meta::identifier_of(fields[J]))...};
        static constexpr const char* types[]{
            lua_type(std::meta::type_of(fields[J]))...};
        std::string s{};
        for (std::size_t i{0}; i < sizeof...(J); ++i) {
            if (i)
                s += ", ";
            s += names[i];
            s += ": ";
            s += types[i];
        }
        return s;
    }
 
  public:
    // --- caster oracle + emission primitives (the welder::rod contract) --

    template <class T>
    static constexpr bool has_native_caster =
        is_native_lua<std::remove_cvref_t<T>>;

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

    template <class T, auto Bases, std::size_t... I>
    static class_writer make_class(module_type& m, const char* name,
                                   const char* doc, std::index_sequence<I...> seq) {
        return make_class<T, ^^T, Bases>(m, name, doc, seq);
    }

    template <class T, std::meta::info Decl, auto Bases, std::size_t... I>
    static class_writer make_class(module_type& m, const char* name,
                                   const char* doc, std::index_sequence<I...> seq) {
        class_writer w{};
        w.doc = m.doc;
        w.qualified = m.prefix.empty() ? std::string{name}
                                       : m.prefix + "." + name;
        w.cls_doc = doc ? doc : "";
        w.bases = _bases_string<Bases>(seq);
        // Register raw C++ name -> this styled/weld_as declaration, so references to
        // T elsewhere (fields, params, returns, bases, containers) are reconciled at
        // render(). qualified_name(Decl) is exactly what the type map emits for them.
        m.doc->record_type_name(std::define_static_string(qualified_name(Decl)),
                                w.qualified);
        return w;
    }

    template <class T, auto Bases, std::size_t... I>
    static class_writer make_nested_class(module_type& m, class_writer& outer,
                                          const char* name, const char* doc,
                                          std::index_sequence<I...> seq) {
        return make_nested_class<T, ^^T, Bases>(m, outer, name, doc, seq);
    }

    template <class T, std::meta::info Decl, auto Bases, std::size_t... I>
    static class_writer make_nested_class(module_type& m, class_writer& outer,
                                          const char* name, const char* doc,
                                          std::index_sequence<I...> seq) {
        class_writer w{};
        w.doc = m.doc;
        w.sink = &outer.trailing;
        w.qualified = outer.qualified + "." + name;
        w.cls_doc = doc ? doc : "";
        w.bases = _bases_string<Bases>(seq);
        // The rename key must be what the type map emits for REFERENCES to T:
        // the target's own dotted name when it has one (a member-alias target
        // declared elsewhere — `vendor.Plate` — so its references remap to this
        // declaration), else the alias Decl's (an unnameable specialization,
        // whose qualified_name(^^T) would collapse to the bare enclosing scope
        // and corrupt the rename table). For a declared nested type the two
        // coincide and the record is a no-op unless a style/weld_as renames.
        m.doc->record_type_name(
            std::define_static_string(std::meta::has_identifier(^^T)
                                          ? qualified_name(^^T)
                                          : qualified_name(Decl)),
            w.qualified);
        return w;
    }

    template <class T, auto Ctors, bool HasDefault, bool Aggregate>
    static void add_constructors(class_writer& w) {
        if constexpr (HasDefault) {
            func_overload o{};
            o.ret_line = "---@return " + w.qualified + '\n';
            o.fun_sig = "fun(): " + w.qualified;
            w.ctors.push_back(std::move(o));
        }
        template for (constexpr auto ctor : std::define_static_array(Ctors)) {
            w.ctors.push_back(build_overload<ctor>(w.qualified));
        }
        if constexpr (Aggregate) {
            // C++26 aggregate field constructor: one `.new` param per field.
            static constexpr auto seq{std::make_index_sequence<
                ::welder::detail::aggregate_fields<T>().size()>{}};
            func_overload o{};
            _aggregate_param_lines<T>(o.params, o.args, seq);
            o.ret_line = "---@return " + w.qualified + '\n';
            o.fun_sig = "fun(" + _aggregate_fun_params<T>(seq) + "): " + w.qualified;
            w.ctors.push_back(std::move(o));
        }
    }

    template <std::meta::info Mem, class Style = ::welder::naming::none>
    static void add_field(class_writer& w) {
        w.fields += "---@field ";
        w.fields += ::welder::name_of<Mem, language, Style, ::welder::ent_kind::field>();
        w.fields += ' ';
        w.fields += lua_type(std::meta::type_of(Mem));
        std::string d{one_line(::welder::doc_of<Mem>())};
        // LuaCATS has no read-only/const field modifier (an open feature request on
        // lua-language-server), so a const member's immutability — which the sol2
        // runtime backend enforces with sol::readonly — is surfaced as a description
        // note rather than an (unrecognized) tag.
        if constexpr (std::meta::is_const_type(std::meta::type_of(Mem)))
            d = d.empty() ? "(read-only)" : d + " (read-only)";
        if (!d.empty())
            w.fields += ' ' + d;
        w.fields += '\n';
    }

    template <auto Fns, class Style = ::welder::naming::none>
    static void add_method(class_writer& w) {
        // A method is `Class:name(...)` (implicit self); reflection's parameters
        // already exclude self, so the arg list renders directly.
        std::vector<func_overload> sigs{};
        collect_overloads<Fns>(sigs, std::make_index_sequence<Fns.size()>{});
        render_overload_group(
            w.methods,
            w.qualified + ":" +
                ::welder::name_of<Fns[0], language, Style,
                                  ::welder::ent_kind::method>(),
            sigs);
    }

    template <auto Fns, class Style = ::welder::naming::none>
    static void add_static_method(class_writer& w) {
        std::vector<func_overload> sigs{};
        collect_overloads<Fns>(sigs, std::make_index_sequence<Fns.size()>{});
        render_overload_group(
            w.methods,
            w.qualified + "." +
                ::welder::name_of<Fns[0], language, Style,
                                  ::welder::ent_kind::static_method>(),
            sigs);
    }

    template <auto Fns>
    static void add_operator(class_writer& w) {
        template for (constexpr auto fn : std::define_static_array(Fns)) {
            const char* op{operator_luacats(fn)};
            w.fields += "---@operator ";
            w.fields += op;
            if constexpr (!::welder::detail::is_unary_operator(fn)) {
                constexpr auto types{param_lua_types<fn>()};
                w.fields += "(";
                w.fields += types[0];
                w.fields += ")";
            }
            using R = [:std::meta::return_type_of(fn):];
            if constexpr (!std::is_void_v<R>) {
                w.fields += ": ";
                w.fields += lua_type(std::meta::return_type_of(fn));
            }
            w.fields += '\n';
        }
    }
 
    // --- enum binding -------------------------------------------------------

    template <class E>
    static enum_writer make_enum(module_type& m, const char* name,
                                 const char* doc) {
        enum_writer w{};
        w.doc = m.doc;
        w.qualified = m.prefix.empty() ? std::string{name}
                                       : m.prefix + "." + name;
        w.enum_doc = doc ? doc : "";
        // Register raw -> styled so references to E (e.g. a field of enum type) are
        // reconciled at render(); see the same call in make_class.
        m.doc->record_type_name(std::define_static_string(qualified_name(^^E)),
                                w.qualified);
        return w;
    }

    template <class E>
    static enum_writer make_nested_enum(module_type& m, class_writer& outer,
                                        const char* name, const char* doc) {
        enum_writer w{};
        w.doc = m.doc;
        w.sink = &outer.trailing;
        w.qualified = outer.qualified + "." + name;
        w.enum_doc = doc ? doc : "";
        m.doc->record_type_name(std::define_static_string(qualified_name(^^E)),
                                w.qualified);
        return w;
    }

    template <std::meta::info Enum, class Style = ::welder::naming::none>
    static void add_enumerator(enum_writer& w) {
        w.values += "    ";
        w.values +=
            ::welder::name_of<Enum, language, Style, ::welder::ent_kind::enumerator>();
        w.values += " = ";
        constexpr long long v{static_cast<long long>(std::to_underlying([:Enum:]))};
        w.values += std::to_string(v);
        w.values += ",\n";
    }

    template <class E>
    static void finish_enum(enum_writer&) {} // RAII flush handles it
 
    // --- namespace / module binding -----------------------------------------

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

    static void set_module_doc(module_type& m, const char* doc) {
        m.doc->declare_table(m.prefix, doc);
    }

    template <auto Fns, class Style = ::welder::naming::none>
    static void add_function(module_type& m, const char* name = nullptr) {
        std::vector<func_overload> sigs{};
        collect_overloads<Fns>(sigs, std::make_index_sequence<Fns.size()>{});
        render_overload_group(
            m.doc->body,
            (m.prefix.empty() ? std::string{} : m.prefix + ".") +
                ::welder::name_of_or<Fns[0], language, Style,
                                     ::welder::ent_kind::function>(name),
            sigs);
    }

    template <std::meta::info Var, class Style = ::welder::naming::none>
    static void add_variable(module_type& m, session&, const char* name = nullptr) {
        std::string& out{m.doc->body};
        emit_doc_comment(out, ::welder::doc_of<Var>());
        out += "---@type ";
        out += lua_type(std::meta::type_of(Var));
        out += '\n';
        out += (m.prefix.empty() ? std::string{} : m.prefix + ".") +
               ::welder::name_of_or<Var, language, Style,
                                    ::welder::ent_kind::variable>(name) +
               " = nil\n\n";
    }

    static module_type add_submodule(module_type& m, const char* name) {
        const std::string prefix{m.prefix.empty() ? std::string{name}
                                                  : m.prefix + "." + name};
        m.doc->declare_table(prefix);
        return module_type{m.doc, prefix};
    }

    static void close_module(module_type&, session&) {}
 
    // --- whole-stub generation (this backend's extra entry point) -----------

    template <std::meta::info Ns, class Style = ::welder::naming::none>
    static void generate(std::ostream& os) {
        static_assert(std::meta::is_namespace(Ns),
                      "welder: luacats::generate<Ns>: Ns must reflect a namespace");
        document doc{};
        module_writer m{&doc,
                        std::define_static_string(qualified_name(Ns))};
        doc.declare_table(m.prefix, ::welder::doc_of<Ns>());
        ::welder::welder<rod, Style>::template weld_namespace<Ns>(m);
        os << doc.render();
    }
};
 
static_assert(::welder::rod<rod>,
              "welder::rods::luacats::rod must satisfy welder::rod");
 
} // namespace welder::rods::luacats