Classes
struct	class_writer
	A class handle. More...
struct	document
	The growing LuaCATS document shared by every writer handle. More...
struct	enum_writer
	An enum handle: the value table text accumulated by add_enumerator, flushed as a ---@enum block by RAII (same rationale as class_writer). More...
struct	func_overload
	One overload of a callee, pre-rendered into the pieces a group needs: the summary doc, the ---@param block, the ---@return line, the function argument list, and the fun(…) signature for a ---@overload line. More...
struct	module_writer
	A module handle: the shared document plus this (sub)module's dotted table path. More...
struct	rod
	The LuaCATS stub rod: a stateless policy satisfying welder::rod that emits text instead of registering a live module. More...
struct	table_decl
	A module/submodule table to declare (prefix = {}), with its optional doc. More...

Functions
template<std::meta::info Fn>
consteval auto	param_lua_types ()
	The LuaCATS type name of each parameter of Fn, as a splice-ready array parallel to param_docs<Fn>().
template<std::meta::info Fn>
std::string	arg_list ()
	The comma-joined argument-name list for Fn's declaration line (an unnamed parameter becomes arg<N>).
template<std::meta::info Fn>
void	emit_params (std::string &out)
	Emit the ---@param lines for Fn (name, LuaCATS type, and its doc).
template<std::meta::info Fn>
std::string	fun_signature (const std::string &ret_override)
	The fun(<name>: <type>, …): <ret> signature of Fn, for a ---@overload line.
template<std::meta::info Fn>
func_overload	build_overload (const std::string &ret_override)
	Build the func_overload for function/constructor Fn.
template<auto Grp, std::size_t... I>
void	collect_overloads (std::vector< func_overload > &out, std::index_sequence< I... >)
	Append build_overload for each member of overload group Grp to out.
void	render_overload_group (std::string &out, const std::string &callee, const std::vector< func_overload > &sigs)
	Emit one documented function <callee>(…) for overload group sigs, with a ---@overload fun(…) line per additional signature — the idiomatic LuaCATS shape (one symbol, several signatures), rather than repeated function defs.
std::string	apply_type_renames (std::string_view text, const std::vector< std::pair< std::string, std::string > > &renames)
	Rewrite every whole dotted-name token of text that is a key in renames to its mapped value.
void	emit_doc_comment (std::string &out, const char *text)
	Append text as --- comment lines (each source line prefixed), so a multiline summary lands as a LuaCATS description block.
std::string	one_line (const char *text)
	A one-line description for a @field/@param/@return tail: newlines in text collapse to spaces (LuaCATS tags are single-line).
consteval std::string	qualified_name (std::meta::info ent)
	The dotted LuaCATS name of a namespace-or-type reflection: its own identifier prefixed by each enclosing named namespace and enclosing class (a nested type binds under its outer's table), dot-joined — so geometry::Point → "geometry.Point" and geometry::Robot::Sensor → "geometry.Robot.Sensor".
consteval bool	type_trait (std::meta::info trait_var, std::meta::info t)
	Evaluate a standard unary type-trait variable template (e.g.
consteval bool	is_wrapper (std::meta::info type, std::meta::info &tmpl_out)
	Whether type (already a bare type) is a listed element-wise wrapper whose LuaCATS spelling this map renders.
consteval std::string	lua_type_string (std::meta::info type)
	The LuaCATS type name for a C++ type reflection.
consteval const char *	lua_type (std::meta::info type)
	lua_type_string as a static-storage C string, callable on a constant type reflection.
consteval const char *	operator_luacats (std::meta::info f)
	A member operator's LuaCATS ---@operator name, or nullptr if not rendered.

Variables
template<class U>
constexpr bool	is_native_lua
	Whether the backend converts U without welder registering a type: scalars, strings and char*.

Function Documentation

◆ apply_type_renames()

std::string welder::rods::luacats::apply_type_renames	(	std::string_view	text,
		const std::vector< std::pair< std::string, std::string > > &	renames )

inline

Rewrite every whole dotted-name token of text that is a key in renames to its mapped value.

A LuaCATS type reference (a ---@field/---@param/---@return type, a ---@class … : Base base, a T[]/table<K, V>/T? element) is emitted from the type map as the referenced type's raw C++ dotted name (qualified_name) — the type map sees only a std::meta::info, with no access to the name style or the referenced type's weld_as, both of which need the type as a constant. So references are reconciled here instead: each welded class/enum registers its raw→styled name as it is declared (where the type is a constant), and this final pass maps the references to match. Deferring to render() means declaration order is irrelevant — every type is registered before any reference is rewritten.

Tokenizing on the identifier+. character class makes each qualified name atomic, so geometry.Point is remapped as a unit: it neither collides with a longer name (geometry.Point3) nor with a substring (Point inside it), and a styled declaration name (never a key) is left untouched. Keys are always dotted (every welded type sits under the module table), so ordinary prose in a docstring is not at risk unless it spells a fully-qualified type path verbatim.

Parameters

text	the assembled document text.
renames	the raw→styled name map (may be empty — then text is returned).

Returns: the reconciled text.

Definition at line 232 of file document.hpp.

Referenced by welder::rods::luacats::document::render().

◆ arg_list()

template<std::meta::info Fn>

std::string welder::rods::luacats::arg_list ( )

The comma-joined argument-name list for Fn's declaration line (an unnamed parameter becomes arg<N>).

Template Parameters

Fn	a reflection of the function.

Returns: the argument-name list (e.g. "x, y").

Definition at line 63 of file document.hpp.

References welder::param_docs().

Referenced by build_overload().

◆ build_overload()

template<std::meta::info Fn>

func_overload welder::rods::luacats::build_overload ( const std::string & ret_override )

Build the func_overload for function/constructor Fn.

A non-empty ret_override supplies the return type for a constructor (which has none).

Template Parameters

Fn	a reflection of the function or constructor.

Parameters

ret_override the return type to force for a constructor (empty otherwise).

Returns: the pre-rendered overload pieces.

Definition at line 146 of file document.hpp.

References arg_list(), welder::rods::luacats::func_overload::args, welder::rods::luacats::func_overload::doc, welder::doc_of(), emit_params(), welder::rods::luacats::func_overload::fun_sig, fun_signature(), lua_type(), one_line(), welder::rods::luacats::func_overload::params, welder::rods::luacats::func_overload::ret_line, and welder::return_doc_of().

Referenced by welder::rods::luacats::rod::add_constructors(), and collect_overloads().

◆ collect_overloads()

template<auto Grp, std::size_t... I>

void welder::rods::luacats::collect_overloads	(	std::vector< func_overload > &	out,
		std::index_sequence< I... >	)

Append build_overload for each member of overload group Grp to out.

Template Parameters

Grp	the overload group (a static array of reflections).
I	the group index pack.

Parameters

out	the vector to append the built overloads to.

Definition at line 174 of file document.hpp.

References build_overload().

Referenced by welder::rods::luacats::rod::add_function(), welder::rods::luacats::rod::add_method(), and welder::rods::luacats::rod::add_static_method().

◆ emit_doc_comment()

void welder::rods::luacats::emit_doc_comment	(	std::string &	out,
		const char *	text )

inline

Append text as --- comment lines (each source line prefixed), so a multiline summary lands as a LuaCATS description block.

A null/empty text emits nothing.

Parameters

out	the document buffer to append to.
text	the summary text (may be null/empty).

Definition at line 36 of file type_map.hpp.

Referenced by welder::rods::luacats::rod::add_variable(), welder::rods::luacats::document::render(), render_overload_group(), welder::rods::luacats::class_writer::~class_writer(), and welder::rods::luacats::enum_writer::~enum_writer().

◆ emit_params()

template<std::meta::info Fn>

void welder::rods::luacats::emit_params ( std::string & out )

Emit the ---@param lines for Fn (name, LuaCATS type, and its doc).

Template Parameters

Fn	a reflection of the function.

Parameters

out	the buffer to append the ---@param lines to.

Definition at line 79 of file document.hpp.

References one_line(), welder::param_docs(), and param_lua_types().

Referenced by build_overload().

◆ fun_signature()

template<std::meta::info Fn>

std::string welder::rods::luacats::fun_signature ( const std::string & ret_override )

The fun(<name>: <type>, …): <ret> signature of Fn, for a ---@overload line.

A non-empty ret_override forces the return type — used for a constructor, whose reflection carries no return type (so return_type_of must not be instantiated for it: the is_constructor guard discards that branch).

Template Parameters

Fn	a reflection of the function or constructor.

Parameters

ret_override forces the return type when non-empty (for a constructor).

Returns: the fun(…) signature string.

Definition at line 104 of file document.hpp.

References lua_type(), welder::param_docs(), and param_lua_types().

Referenced by build_overload().

◆ is_wrapper()

bool welder::rods::luacats::is_wrapper	(	std::meta::info	type,
		std::meta::info &	tmpl_out )

consteval

Whether type (already a bare type) is a listed element-wise wrapper whose LuaCATS spelling this map renders.

Parameters

	type	a reflection of the (cv/ref-stripped) type to classify.
[out]	tmpl_out	receives type's class template when it is a wrapper.

Returns: true iff type is a class template specialization.

Definition at line 106 of file type_map.hpp.

Referenced by lua_type_string().

◆ lua_type()

const char * welder::rods::luacats::lua_type ( std::meta::info type )

consteval

lua_type_string as a static-storage C string, callable on a constant type reflection.

Parameters

type	a reflection of the type to render.

Returns: the LuaCATS type string, in static storage.

Definition at line 180 of file type_map.hpp.

References lua_type_string().

Referenced by welder::rods::luacats::rod::_aggregate_fun_params(), welder::rods::luacats::rod::_aggregate_param_lines(), welder::rods::luacats::rod::add_field(), welder::rods::luacats::rod::add_operator(), welder::rods::luacats::rod::add_variable(), build_overload(), and fun_signature().

◆ lua_type_string()

std::string welder::rods::luacats::lua_type_string ( std::meta::info type )

consteval

The LuaCATS type name for a C++ type reflection.

Strips cv/ref/pointer, then: known STL wrappers render structurally (recursing on their value arguments); std::string/std::string_view/char* → string; bool → boolean; integral → integer; floating → number; a class/enum → its qualified_name; anything else → any. The recursion mirrors welder's bindability wrapper table so a std::vector<Point> renders as Point[].

Parameters

type	a reflection of the type to render.

Returns: the LuaCATS type string.

Definition at line 122 of file type_map.hpp.

References is_wrapper(), lua_type_string(), qualified_name(), and type_trait().

Referenced by lua_type(), lua_type_string(), and param_lua_types().

◆ one_line()

std::string welder::rods::luacats::one_line ( const char * text )

inline

A one-line description for a @field/@param/@return tail: newlines in text collapse to spaces (LuaCATS tags are single-line).

Parameters

text	the source text (may be null).

Returns: the flattened text, empty if text is null.

Definition at line 52 of file type_map.hpp.

Referenced by welder::rods::luacats::rod::add_field(), build_overload(), and emit_params().

◆ operator_luacats()

const char * welder::rods::luacats::operator_luacats ( std::meta::info f )

consteval

A member operator's LuaCATS ---@operator name, or nullptr if not rendered.

LuaCATS names only the arithmetic / bitwise / call metamethods; unary vs binary is by arity (a member operator takes 0 parameters when unary). The set is exactly lua-language-server's vm.OP_*_MAP — add sub mul div mod pow idiv band bor bxor shl shr concat (binary), unm bnot len (unary), call — so anything we return here must be one of those or the language server rejects the stub with unknown-operator. This mirrors the sol2 runtime metamethod map (operator_mm), minus one distinction: sol2 #if-gates the bitwise metamethods to Lua ≥ 5.3, whereas the stub carries no Lua headers (pure reflection + text), so it documents the 5.3+ surface unconditionally — the stub's target version is the reader's .luarc.json runtime.version, not a compile-time LUA_VERSION_NUM.

Deliberately absent: comparison (==/</<=) and subscript ([]). They have no ---@operator spelling — lua-language-server always permits == (yielding boolean) and models indexing through ---@field [key] value, so there is nothing to annotate. They still bind at runtime (sol2 __eq/__lt/ __le/__index); the stub simply can't type them, so we drop them here rather than emit an annotation the language server can't consume.

Parameters

f	a reflection of the operator function.

Returns: the ---@operator name (static storage), or nullptr.

Definition at line 219 of file type_map.hpp.

References welder::detail::is_unary_operator().

Referenced by welder::rods::luacats::rod::add_operator(), and welder::rods::luacats::rod::special_method_name().

◆ param_lua_types()

template<std::meta::info Fn>

auto welder::rods::luacats::param_lua_types ( )

consteval

The LuaCATS type name of each parameter of Fn, as a splice-ready array parallel to param_docs<Fn>().

Template Parameters

Fn	a reflection of the function.

Returns: an array of the parameters' LuaCATS type strings (empty if none).

Definition at line 44 of file document.hpp.

References lua_type_string(), and welder::detail::param_types().

Referenced by welder::rods::luacats::rod::add_operator(), emit_params(), and fun_signature().

◆ qualified_name()

std::string welder::rods::luacats::qualified_name ( std::meta::info ent )

consteval

The dotted LuaCATS name of a namespace-or-type reflection: its own identifier prefixed by each enclosing named namespace and enclosing class (a nested type binds under its outer's table), dot-joined — so geometry::Point → "geometry.Point" and geometry::Robot::Sensor → "geometry.Robot.Sensor".

The global namespace (and an unnameable scope, e.g. a class-template specialization) contributes nothing.

Parameters

ent	a reflection of the namespace or type to name.

Returns: the dotted LuaCATS name.

Definition at line 71 of file type_map.hpp.

Referenced by welder::rods::luacats::rod::_bases_string(), welder::rods::luacats::rod::generate(), lua_type_string(), welder::rods::luacats::rod::make_class(), welder::rods::luacats::rod::make_enum(), welder::rods::luacats::rod::make_nested_class(), and welder::rods::luacats::rod::make_nested_enum().

◆ render_overload_group()

void welder::rods::luacats::render_overload_group	(	std::string &	out,
		const std::string &	callee,
		const std::vector< func_overload > &	sigs )

inline

Emit one documented function <callee>(…) for overload group sigs, with a ---@overload fun(…) line per additional signature — the idiomatic LuaCATS shape (one symbol, several signatures), rather than repeated function defs.

sigs is non-empty. The "primary" overload — the one whose full docs and parameter block are kept — is the first that carries a docstring (else the first), so a documented overload's @param/summary text survives; the rest, of which LuaCATS ---@overload records only the bare signature, follow it.

Parameters

out	the document buffer to append to.
callee	the fully-qualified LuaCATS name of the function being defined.
sigs	the group's pre-rendered overloads (non-empty).

Definition at line 189 of file document.hpp.

References welder::rods::luacats::func_overload::args, welder::doc(), welder::rods::luacats::func_overload::doc, emit_doc_comment(), welder::rods::luacats::func_overload::params, and welder::rods::luacats::func_overload::ret_line.

Referenced by welder::rods::luacats::rod::add_function(), welder::rods::luacats::rod::add_method(), welder::rods::luacats::rod::add_static_method(), and welder::rods::luacats::class_writer::~class_writer().

◆ type_trait()

bool welder::rods::luacats::type_trait	(	std::meta::info	trait_var,
		std::meta::info	t )

consteval

Evaluate a standard unary type-trait variable template (e.g.

^^std::is_integral_v) on the type t.

Parameters

trait_var	a reflection of the trait variable template.
t	a reflection of the type to test.

Returns: the trait's bool value for t.

Definition at line 97 of file type_map.hpp.

Referenced by lua_type_string().

Variable Documentation

◆ is_native_lua

template<class U>

bool welder::rods::luacats::is_native_lua

inlineconstexpr

Initial value:

                                =
std::is_arithmetic_v<U> ||
std::is_same_v<std::remove_cv_t<U>, std::string> ||
std::is_same_v<std::remove_cv_t<U>, std::string_view> ||
std::is_same_v<std::remove_cv_t<std::remove_pointer_t<std::remove_cvref_t<U>>>,
               char>

Whether the backend converts U without welder registering a type: scalars, strings and char*.

Classes and enums are program-defined, so they must be welded — mirrors the sol2 oracle without depending on sol2.

Template Parameters

U	the type to classify.

Definition at line 189 of file type_map.hpp.

Classes

Functions

Variables

Function Documentation

◆ apply_type_renames()

◆ arg_list()

◆ build_overload()

◆ collect_overloads()

◆ emit_doc_comment()

◆ emit_params()

◆ fun_signature()

◆ is_wrapper()

◆ lua_type()

◆ lua_type_string()

◆ one_line()

◆ operator_luacats()

◆ param_lua_types()

◆ qualified_name()

◆ render_overload_group()

◆ type_trait()

Variable Documentation

◆ is_native_lua