document.hpp

Go to the documentation of this file.

#pragma once
#include <algorithm>
#include <array>
#include <cstddef>
#include <meta>
#include <string>
#include <string_view>
#include <type_traits>
#include <utility>
#include <vector>
 
#include <welder/rods/lua/luacats/type_map.hpp> // lua_type / text helpers
#include <welder/bind_traits.hpp>                    // param_types / aggregate_fields
#include <welder/doc.hpp> // doc_of / param_docs / return_doc_of

 
namespace welder::inline v0::rods::luacats {
 
// --- signature rendering ----------------------------------------------------

template <std::meta::info Fn>
consteval auto param_lua_types() {
    // Guard n != 0: param_types<Fn> materializes std::array<info, n> and indexes
    // it, and std::array<T, 0>::operator[] is not usable (as the rest of welder
    // guards too), so it must not be instantiated for a parameterless function.
    constexpr std::size_t n{std::meta::parameters_of(Fn).size()};
    std::array<const char*, n> out{};
    if constexpr (n != 0) {
        constexpr auto types{::welder::detail::param_types<Fn>()};
        for (std::size_t i{0}; i < n; ++i)
            out[i] = std::define_static_string(lua_type_string(types[i]));
    }
    return out;
}

template <std::meta::info Fn>
std::string arg_list() {
    static constexpr auto pds{::welder::param_docs<Fn>()};
    std::string out{};
    for (std::size_t i{0}; i < pds.size(); ++i) {
        if (i)
            out += ", ";
        out += pds[i].name ? std::string{pds[i].name}
                           : "arg" + std::to_string(i + 1);
    }
    return out;
}

template <std::meta::info Fn>
void emit_params(std::string& out) {
    static constexpr auto pds{::welder::param_docs<Fn>()};
    static constexpr auto types{param_lua_types<Fn>()};
    for (std::size_t i{0}; i < pds.size(); ++i) {
        out += "---@param ";
        out += pds[i].name ? std::string{pds[i].name}
                           : "arg" + std::to_string(i + 1);
        out += ' ';
        out += types[i];
        const std::string d{one_line(pds[i].text)};
        if (!d.empty())
            out += ' ' + d;
        out += '\n';
    }
}

template <std::meta::info Fn>
std::string fun_signature(const std::string& ret_override) {
    static constexpr auto pds{::welder::param_docs<Fn>()};
    static constexpr auto types{param_lua_types<Fn>()};
    std::string s{"fun("};
    for (std::size_t i{0}; i < pds.size(); ++i) {
        if (i)
            s += ", ";
        s += pds[i].name ? std::string{pds[i].name} : "arg" + std::to_string(i + 1);
        s += ": ";
        s += types[i];
    }
    s += ")";
    std::string ret{ret_override};
    if (ret.empty()) {
        if constexpr (!std::meta::is_constructor(Fn)) {
            using R = [:std::meta::return_type_of(Fn):];
            if constexpr (!std::is_void_v<R>)
                ret = lua_type(std::meta::return_type_of(Fn));
        }
    }
    if (!ret.empty())
        s += ": " + ret;
    return s;
}

struct func_overload {
    std::string doc{};      
    std::string params{};   
    std::string ret_line{}; 
    std::string args{};     
    std::string fun_sig{};  
};

template <std::meta::info Fn>
func_overload build_overload(const std::string& ret_override) {
    func_overload o{};
    if (const char* d{::welder::doc_of<Fn>()})
        o.doc = d;
    emit_params<Fn>(o.params);
    if (!ret_override.empty()) {
        o.ret_line = "---@return " + ret_override + '\n';
    } else if constexpr (!std::meta::is_constructor(Fn)) {
        using R = [:std::meta::return_type_of(Fn):];
        if constexpr (!std::is_void_v<R>) {
            o.ret_line = "---@return ";
            o.ret_line += lua_type(std::meta::return_type_of(Fn));
            const std::string d{one_line(::welder::return_doc_of<Fn>())};
            if (!d.empty())
                o.ret_line += ' ' + d;
            o.ret_line += '\n';
        }
    }
    o.args = arg_list<Fn>();
    o.fun_sig = fun_signature<Fn>(ret_override);
    return o;
}

template <auto Grp, std::size_t... I>
void collect_overloads(std::vector<func_overload>& out, std::index_sequence<I...>) {
    (out.push_back(build_overload<Grp[I]>({})), ...);
}

inline void render_overload_group(std::string& out, const std::string& callee,
                                  const std::vector<func_overload>& sigs) {
    std::size_t primary{0};
    for (std::size_t i{0}; i < sigs.size(); ++i)
        if (!sigs[i].doc.empty()) {
            primary = i;
            break;
        }
    const func_overload& p{sigs[primary]};
    emit_doc_comment(out, p.doc.empty() ? nullptr : p.doc.c_str());
    out += p.params;
    out += p.ret_line;
    for (std::size_t i{0}; i < sigs.size(); ++i)
        if (i != primary)
            out += "---@overload " + sigs[i].fun_sig + '\n';
    out += "function " + callee + "(" + p.args + ") end\n\n";
}
 
// --- the document + its writer handles --------------------------------------

inline std::string apply_type_renames(
    std::string_view text,
    const std::vector<std::pair<std::string, std::string>>& renames) {
    if (renames.empty())
        return std::string{text};
    auto is_name_char = [](char c) {
        return c == '.' || c == '_' || (c >= 'A' && c <= 'Z') ||
               (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9');
    };
    std::string out{};
    out.reserve(text.size());
    for (std::size_t i{0}; i < text.size();) {
        if (!is_name_char(text[i])) {
            out += text[i++];
            continue;
        }
        std::size_t j{i};
        while (j < text.size() && is_name_char(text[j]))
            ++j;
        const std::string_view tok{text.substr(i, j - i)};
        const auto it{std::find_if(renames.begin(), renames.end(),
                                   [&](const auto& r) { return r.first == tok; })};
        out += (it != renames.end()) ? std::string_view{it->second} : tok;
        i = j;
    }
    return out;
}

struct table_decl {
    std::string prefix{}; 
    std::string doc{};    
};

struct document {
    std::vector<table_decl> tables{};
    std::string body{};
    std::vector<std::pair<std::string, std::string>> type_renames{};

    void declare_table(std::string_view prefix, const char* doc = nullptr) {
        for (auto& t : tables)
            if (t.prefix == prefix) {
                if (doc && *doc)
                    t.doc = doc;
                return;
            }
        tables.push_back({std::string{prefix}, doc ? doc : ""});
    }

    void record_type_name(std::string_view raw, std::string_view styled) {
        if (raw == styled)
            return;
        for (const auto& [r, s] : type_renames)
            if (r == raw)
                return;
        type_renames.emplace_back(std::string{raw}, std::string{styled});
    }

    std::string render() const {
        auto depth = [](const std::string& s) {
            return std::count(s.begin(), s.end(), '.');
        };
        std::vector<table_decl> decls{tables};
        std::stable_sort(decls.begin(), decls.end(),
                         [&](const table_decl& a, const table_decl& b) {
                             return depth(a.prefix) < depth(b.prefix);
                         });
        std::string out{"---@meta\n\n"};
        for (const auto& d : decls) {
            emit_doc_comment(out, d.doc.empty() ? nullptr : d.doc.c_str());
            out += d.prefix + " = {}\n\n";
        }
        out += body;
        // Reconcile type *references* (raw C++ names, as the type map emits them)
        // with their styled/weld_as declarations, now that every type is registered.
        return apply_type_renames(out, type_renames);
    }
};

struct module_writer {
    document* doc{nullptr};
    std::string prefix{};
};

struct class_writer {
    document* doc{nullptr};
    std::string* sink{nullptr}; 
    std::string qualified{};  
    std::string cls_doc{};    
    std::string bases{};      
    std::string fields{};     
    std::string methods{};    
    std::string trailing{};   
    std::vector<func_overload> ctors{}; 
 
    class_writer() = default;
    class_writer(const class_writer&) = delete;
    class_writer& operator=(const class_writer&) = delete;
    class_writer(class_writer&& o) noexcept { *this = std::move(o); }
    class_writer& operator=(class_writer&& o) noexcept {
        doc = o.doc;
        sink = o.sink;
        qualified = std::move(o.qualified);
        cls_doc = std::move(o.cls_doc);
        bases = std::move(o.bases);
        fields = std::move(o.fields);
        methods = std::move(o.methods);
        trailing = std::move(o.trailing);
        ctors = std::move(o.ctors);
        o.doc = nullptr; // the source no longer flushes
        return *this;
    }
    ~class_writer() {
        if (!doc)
            return;
        std::string& out{sink ? *sink : doc->body};
        emit_doc_comment(out, cls_doc.empty() ? nullptr : cls_doc.c_str());
        out += "---@class " + qualified;
        if (!bases.empty())
            out += " : " + bases;
        out += '\n';
        out += fields;
        out += qualified + " = {}\n\n";
        // Constructors (all producing `Class.new`) are grouped into one documented
        // function with `---@overload` signatures; they precede the methods.
        if (!ctors.empty())
            render_overload_group(out, qualified + ".new", ctors);
        out += methods;
        out += trailing; // nested types' blocks, after this class is complete
    }
};

struct enum_writer {
    document* doc{nullptr};
    std::string* sink{nullptr}; 
    std::string qualified{};
    std::string enum_doc{};
    std::string values{}; 
 
    enum_writer() = default;
    enum_writer(const enum_writer&) = delete;
    enum_writer& operator=(const enum_writer&) = delete;
    enum_writer(enum_writer&& o) noexcept { *this = std::move(o); }
    enum_writer& operator=(enum_writer&& o) noexcept {
        doc = o.doc;
        sink = o.sink;
        qualified = std::move(o.qualified);
        enum_doc = std::move(o.enum_doc);
        values = std::move(o.values);
        o.doc = nullptr;
        return *this;
    }
    ~enum_writer() {
        if (!doc)
            return;
        std::string& out{sink ? *sink : doc->body};
        emit_doc_comment(out, enum_doc.empty() ? nullptr : enum_doc.c_str());
        out += "---@enum " + qualified + '\n';
        out += qualified + " = {\n" + values + "}\n\n";
    }
};
 
} // namespace welder::rods::luacats