rod.hpp File Reference

welder LuaCATS stub rod (header-only, text-emitting). More...

#include <cstddef>
#include <meta>
#include <ostream>
#include <string>
#include <type_traits>
#include <utility>
#include <vector>
#include <welder/welder.hpp>
#include <welder/rods/lua/luacats/document.hpp>
#include <welder/rods/lua/luacats/type_map.hpp>
#include <welder/bind_traits.hpp>
#include <welder/doc.hpp>

Include dependency graph for rod.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	welder::rods::luacats::rod
	The LuaCATS stub rod: a stateless policy satisfying welder::rod that emits text instead of registering a live module. More...
struct	welder::rods::luacats::rod::session
	No deferred module state. More...

Namespaces
namespace	welder
namespace	welder::rods
namespace	welder::rods::luacats

Detailed Description

welder LuaCATS stub rod (header-only, text-emitting).

Lua has no runtime docstring slot, so the sol2 backend drops every [[=welder::doc]] / returns / parameter annotation at load time — a loaded sol2 usertype exposes nothing an introspecting tool could scrape back. This backend is their home: it reflects the same welded types and emits a LuaCATS **---@meta definition file** (.lua), the analogue of the Python backends' .pyi stubs, carrying the class/field/function types and the docstrings for editor completion and the Lua language server.

Unlike Python's .pyi (pybind11-stubgen loads the built module and introspects it), a Lua stub cannot be scraped from a loaded module — so it is reflection-emitted at build time**. This is a genuine welder rod: it plugs the same generic driver (<welder/welder.hpp>) that pybind11/nanobind/sol2 use, so member selection, base-class flattening, policy/mark resolution and the bindability gate are reused verbatim. Only the emission primitives differ — instead of registering a live class they append LuaCATS text to a growing document. A tiny generator executable runs the driver in main() and prints the document; a CMake helper (welder_luacats_generate_stub) captures it to <name>.lua.

The emission primitives are thin: the C++→LuaCATS type map and the small text helpers live in <welder/rods/lua/luacats/type_map.hpp>, and the document assembler (signature rendering + the *_writer handle types the driver's module/class/enum handles deduce to) in <welder/rods/lua/luacats/document.hpp>. The rod struct below only wires those to the driver contract.

Requires the welder vocabulary first (#include <welder/vocabulary.hpp>). This header exposes exactly one thing: the rod type welder::rods::luacats::rod. Drive it by hand:

#include <welder/rods/lua/luacats/rod.hpp>
welder::rods::luacats::rod::generate<^^mymod>(std::cout);

or through the generator-main() macro (include this directory's module.hpp instead):

#include <welder/rods/lua/luacats/module.hpp>
WELDER_LUACATS_MAIN(mymod)   // main(): print the ---@meta stub for ^^mymod

Definition in file rod.hpp.