The LuaCATS stub rod: a stateless policy satisfying welder::rod that emits text instead of registering a live module. More...

#include <welder/rods/lua/luacats/rod.hpp>

Classes
struct	session
	No deferred module state. More...

Public Types
using	module_type = module_writer
template<class>
using	class_handle_type = class_writer
	The class / enum handles the per-class / per-enum hooks write into — exactly what make_class / make_enum return (a stub handle carries no type parameter).
template<class>
using	enum_handle_type = enum_writer

Static Public Member Functions
static consteval const char *	special_method_name (std::meta::info op_fn)
	Member operator → its ---@operator name, or nullptr (also gates eligibility, like every backend).
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)
	Open a ---@class block for T and register its raw→styled name for later type-reference reconciliation.
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)
	The declaring-entity-aware form the carriage prefers: Decl is ^^T, or the namespace-scope alias a class-template specialization was welded through.
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)
	Open a ---@class block for a nested member type, declared under the OUTER's dotted name (mod.Outer.Inner — matching where the sol2 runtime places it) and flushed into the outer's trailing buffer, so its block lands after the outer's own declaration (the stub assigns mod.Outer.Inner = {} only once mod.Outer = {} exists).
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)
	The declaring-entity-aware nested form the carriage prefers: Decl is ^^T, or the member alias an (otherwise unnameable) template specialization was registered through.
template<class T, auto Ctors, bool HasDefault, bool Aggregate>
static void	add_constructors (class_writer &w)
	Emit the whole .new(…) constructor overload set (the driver-passed pieces: a no-argument overload when HasDefault, one per member of Ctors, and the aggregate field constructor when Aggregate); grouped into ---@overload lines on flush.
template<std::meta::info Mem, class Style = ::welder::naming::none>
static void	add_field (class_writer &w)
	Emit a ---@field line for data member Mem (const → a (read-only) note, since LuaCATS has no const modifier).
template<auto Fns, class Style = ::welder::naming::none>
static void	add_method (class_writer &w)
	Emit method overload group Fns as one documented Class:name(…) (further overloads as ---@overload lines; name from Fns[0]).
template<auto Fns, class Style = ::welder::naming::none>
static void	add_static_method (class_writer &w)
	Emit static-method overload group Fns as a documented Class.name(…) (dotted, no self).
template<auto Fns>
static void	add_operator (class_writer &w)
	Emit operator overload group Fns as ---@operator name(rhs): R lines on the class block (one line per overload — LuaCATS has no operator ---@overload form, the tag itself repeats).
template<class E>
static enum_writer	make_enum (module_type &m, const char name, const char doc)
	Open an enum table declaration for E and register its raw→styled name.
template<class E>
static enum_writer	make_nested_enum (module_type &m, class_writer &outer, const char name, const char doc)
	Open the enum table declaration for a nested member enum, declared under the OUTER's dotted name and flushed into the outer's trailing buffer (see make_nested_class).
template<std::meta::info Enum, class Style = ::welder::naming::none>
static void	add_enumerator (enum_writer &w)
	Emit an Name = <int> line for enumerator Enum.
template<class E>
static void	finish_enum (enum_writer &)
	No finalizer needed — the enum_writer flushes on destruction.
static session	open_module (module_type &)
	Open a per-module session (no deferred state).
static void	set_module_doc (module_type &m, const char *doc)
	Declare the (sub)module table, carrying doc as its comment.
template<auto Fns, class Style = ::welder::naming::none>
static void	add_function (module_type &m, const char *name=nullptr)
	Emit free-function overload group Fns as one documented module-level function (further overloads as ---@overload; name from Fns[0]).
template<std::meta::info Var, class Style = ::welder::naming::none>
static void	add_variable (module_type &m, session &, const char *name=nullptr)
	Emit a ---@type-annotated <name> = nil module variable declaration.
static module_type	add_submodule (module_type &m, const char *name)
	Declare a nested submodule table under m and return its writer.
static void	close_module (module_type &, session &)
	Close the session (no-op; the document accumulates directly).
template<std::meta::info Ns, class Style = ::welder::naming::none>
static void	generate (std::ostream &os)
	Emit the LuaCATS ---@meta stub for top-level namespace Ns to os.

Static Public Attributes
static constexpr lang	language {lang::lua}
	Stubs are for the Lua binding.
template<class T>
static constexpr bool	has_native_caster
	is_native_lua drives the shared bindability gate.

Static Protected Member Functions
template<auto Bases, std::size_t... I>
static consteval const char *	_bases_string (std::index_sequence< I... >)
	The comma-joined LuaCATS names of a class's welded bases (for ---@class X : …).
template<class T, std::size_t... J>
static void	_aggregate_param_lines (std::string &out, std::string &args, std::index_sequence< J... >)
	Precompute an aggregate's ---@param lines and its .new argument list.
template<class T, std::size_t... J>
static std::string	_aggregate_fun_params (std::index_sequence< J... >)
	The <field>: <type>, … list for an aggregate's .new fun(…) signature (its ---@overload line).

Detailed Description

The LuaCATS stub rod: a stateless policy satisfying welder::rod that emits text instead of registering a live module.

Its public static members are the emission primitives welder's driver calls; they wire the type map (type_map.hpp) and document assembler (document.hpp) to the driver contract. The protected members below are the few helpers that are purely internal to the struct (prefixed _).

Definition at line 70 of file rod.hpp.

Member Typedef Documentation

◆ class_handle_type

template<class>

using welder::rods::luacats::rod::class_handle_type = class_writer

The class / enum handles the per-class / per-enum hooks write into — exactly what make_class / make_enum return (a stub handle carries no type parameter).

Named as associated types so the welder::rod concept can shape-check the per-handle hooks against them.

Definition at line 78 of file rod.hpp.

◆ enum_handle_type

template<class>

using welder::rods::luacats::rod::enum_handle_type = enum_writer

Definition at line 79 of file rod.hpp.

◆ module_type

using welder::rods::luacats::rod::module_type = module_writer

Definition at line 72 of file rod.hpp.

Member Function Documentation

◆ _aggregate_fun_params()

template<class T, std::size_t... J>

std::string welder::rods::luacats::rod::_aggregate_fun_params ( std::index_sequence< J... > )

inlinestaticprotected

The <field>: <type>, … list for an aggregate's .new fun(…) signature (its ---@overload line).

Same field source as _aggregate_param_lines.

Definition at line 124 of file rod.hpp.

References welder::detail::aggregate_fields(), and welder::rods::luacats::lua_type().

Referenced by add_constructors().

◆ _aggregate_param_lines()

template<class T, std::size_t... J>

void welder::rods::luacats::rod::_aggregate_param_lines	(	std::string &	out,
		std::string &	args,
		std::index_sequence< J... >	)

inlinestaticprotected

Precompute an aggregate's ---@param lines and its .new argument list.

A flat function template (not an immediately-invoked generic lambda): a splice + constant-index pack expansion inside such a lambda misbehaves on gcc-16, so the field names/types are materialized into constant arrays by the pack, then consumed by a plain runtime loop. The driver only calls this for an aggregate with at least one field, so the pack is never empty.

Definition at line 103 of file rod.hpp.

References welder::detail::aggregate_fields(), and welder::rods::luacats::lua_type().

Referenced by add_constructors().

◆ _bases_string()

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

consteval const char * welder::rods::luacats::rod::_bases_string ( std::index_sequence< I... > )

inlinestaticconstevalprotected

The comma-joined LuaCATS names of a class's welded bases (for ---@class X : …).

Definition at line 89 of file rod.hpp.

References welder::rods::luacats::qualified_name().

Referenced by make_class(), and make_nested_class().

◆ add_constructors()

template<class T, auto Ctors, bool HasDefault, bool Aggregate>

void welder::rods::luacats::rod::add_constructors ( class_writer & w )

inlinestatic

Emit the whole .new(…) constructor overload set (the driver-passed pieces: a no-argument overload when HasDefault, one per member of Ctors, and the aggregate field constructor when Aggregate); grouped into ---@overload lines on flush.

See also: welder::rod

Definition at line 239 of file rod.hpp.

References _aggregate_fun_params(), _aggregate_param_lines(), welder::detail::aggregate_fields(), welder::rods::luacats::func_overload::args, welder::rods::luacats::build_overload(), welder::rods::luacats::class_writer::ctors, welder::rods::luacats::func_overload::fun_sig, welder::rods::luacats::func_overload::params, welder::rods::luacats::class_writer::qualified, and welder::rods::luacats::func_overload::ret_line.

◆ add_enumerator()

template<std::meta::info Enum, class Style = ::welder::naming::none>

void welder::rods::luacats::rod::add_enumerator ( enum_writer & w )

inlinestatic

Emit an Name = <int> line for enumerator Enum.

See also: welder::rod

Definition at line 373 of file rod.hpp.

References welder::name_of(), and welder::rods::luacats::enum_writer::values.

◆ add_field()

template<std::meta::info Mem, class Style = ::welder::naming::none>

void welder::rods::luacats::rod::add_field ( class_writer & w )

inlinestatic

Emit a ---@field line for data member Mem (const → a (read-only) note, since LuaCATS has no const modifier).

See also: welder::rod

Definition at line 264 of file rod.hpp.

References welder::doc_of(), welder::rods::luacats::class_writer::fields, welder::rods::luacats::lua_type(), welder::name_of(), and welder::rods::luacats::one_line().

◆ add_function()

template<auto Fns, class Style = ::welder::naming::none>

void welder::rods::luacats::rod::add_function	(	module_type &	m,
		const char *	name = nullptr )

inlinestatic

Emit free-function overload group Fns as one documented module-level function (further overloads as ---@overload; name from Fns[0]).

A non-null name overrides the leaf name (beating any weld_as).

See also: welder::rod

Definition at line 402 of file rod.hpp.

References welder::rods::luacats::document::body, welder::rods::luacats::collect_overloads(), welder::rods::luacats::module_writer::doc, welder::function, language, welder::name_of_or(), welder::rods::luacats::module_writer::prefix, and welder::rods::luacats::render_overload_group().

◆ add_method()

template<auto Fns, class Style = ::welder::naming::none>

void welder::rods::luacats::rod::add_method ( class_writer & w )

inlinestatic

Emit method overload group Fns as one documented Class:name(…) (further overloads as ---@overload lines; name from Fns[0]).

See also: welder::rod

Definition at line 285 of file rod.hpp.

References welder::rods::luacats::collect_overloads(), language, welder::method, welder::rods::luacats::class_writer::methods, welder::name_of(), welder::rods::luacats::class_writer::qualified, and welder::rods::luacats::render_overload_group().

◆ add_operator()

template<auto Fns>

void welder::rods::luacats::rod::add_operator ( class_writer & w )

inlinestatic

Emit operator overload group Fns as ---@operator name(rhs): R lines on the class block (one line per overload — LuaCATS has no operator ---@overload form, the tag itself repeats).

See also: welder::rod

Definition at line 316 of file rod.hpp.

References welder::rods::luacats::class_writer::fields, welder::detail::is_unary_operator(), welder::rods::luacats::lua_type(), welder::rods::luacats::operator_luacats(), and welder::rods::luacats::param_lua_types().

◆ add_static_method()

template<auto Fns, class Style = ::welder::naming::none>

void welder::rods::luacats::rod::add_static_method ( class_writer & w )

inlinestatic

Emit static-method overload group Fns as a documented Class.name(…) (dotted, no self).

See also: welder::rod

Definition at line 301 of file rod.hpp.

References welder::rods::luacats::collect_overloads(), language, welder::rods::luacats::class_writer::methods, welder::name_of(), welder::rods::luacats::class_writer::qualified, welder::rods::luacats::render_overload_group(), and welder::static_method.

◆ add_submodule()

module_type welder::rods::luacats::rod::add_submodule	(	module_type &	m,
		const char *	name )

inlinestatic

Declare a nested submodule table under m and return its writer.

See also: welder::rod

Definition at line 429 of file rod.hpp.

References welder::rods::luacats::document::declare_table(), welder::rods::luacats::module_writer::doc, and welder::rods::luacats::module_writer::prefix.

◆ add_variable()

template<std::meta::info Var, class Style = ::welder::naming::none>

void welder::rods::luacats::rod::add_variable	(	module_type &	m,
		session &	,
		const char *	name = nullptr )

inlinestatic

Emit a ---@type-annotated <name> = nil module variable declaration.

See also: welder::rod

Definition at line 416 of file rod.hpp.

References welder::rods::luacats::document::body, welder::rods::luacats::module_writer::doc, welder::doc_of(), welder::rods::luacats::emit_doc_comment(), language, welder::rods::luacats::lua_type(), welder::name_of_or(), welder::rods::luacats::module_writer::prefix, and welder::variable.

◆ close_module()

void welder::rods::luacats::rod::close_module	(	module_type &	,
		session &	)

inlinestatic

Close the session (no-op; the document accumulates directly).

See also: welder::rod

Definition at line 437 of file rod.hpp.

◆ finish_enum()

template<class E>

void welder::rods::luacats::rod::finish_enum ( enum_writer & )

inlinestatic

No finalizer needed — the enum_writer flushes on destruction.

See also: welder::rod

Definition at line 385 of file rod.hpp.

◆ generate()

template<std::meta::info Ns, class Style = ::welder::naming::none>

void welder::rods::luacats::rod::generate ( std::ostream & os )

inlinestatic

Emit the LuaCATS ---@meta stub for top-level namespace Ns to os.

Runs welder's generic driver over Ns with this text-emitting backend, so the stub covers exactly what the sol2 backend binds — classes, enums, free functions, namespace variables and nested namespaces — now carrying the types and docstrings Lua drops at runtime. The stub-specific extra over welder::welder<…>::weld_namespace is the document/writer setup and the final render, which is why the backend carries it.

Template Parameters

Ns a reflection of the (top-level) namespace whose name is the module.

Style the name style to render member names with — pass the same style the sol2 runtime binding uses, so the stub matches the loaded module. (Defaults to welder::naming::none.) A style or weld_as that renames a type is reflected in the stub's type references and base lists as well as its declarations — references carry the raw C++ name until welder::rods::luacats::apply_type_renames reconciles them at render().

Parameters

os	the stream to write the finished stub to.

Definition at line 462 of file rod.hpp.

References welder::doc(), welder::doc_of(), welder::rods::luacats::module_writer::prefix, and welder::rods::luacats::qualified_name().

◆ make_class() [1/2]

template<class T, std::meta::info Decl, auto Bases, std::size_t... I>

class_writer welder::rods::luacats::rod::make_class	(	module_type &	m,
		const char *	name,
		const char *	doc,
		std::index_sequence< I... >	seq )

inlinestatic

The declaring-entity-aware form the carriage prefers: Decl is ^^T, or the namespace-scope alias a class-template specialization was welded through.

The raw C++ name registered for reference reconciliation must be derived from Decl — a specialization has no identifier, so qualified_name(^^T) would collapse to the bare namespace and corrupt the rename table (rewriting the module root).

See also: welder::rod

Definition at line 173 of file rod.hpp.

References _bases_string(), welder::rods::luacats::class_writer::bases, welder::rods::luacats::class_writer::cls_doc, welder::doc(), welder::rods::luacats::class_writer::doc, welder::rods::luacats::module_writer::doc, welder::rods::luacats::module_writer::prefix, welder::rods::luacats::class_writer::qualified, welder::rods::luacats::qualified_name(), and welder::rods::luacats::document::record_type_name().

◆ make_class() [2/2]

template<class T, auto Bases, std::size_t... I>

class_writer welder::rods::luacats::rod::make_class	(	module_type &	m,
		const char *	name,
		const char *	doc,
		std::index_sequence< I... >	seq )

inlinestatic

Open a ---@class block for T and register its raw→styled name for later type-reference reconciliation.

See also: welder::rod

Definition at line 161 of file rod.hpp.

References welder::doc(), and make_class().

Referenced by make_class().

◆ make_enum()

template<class E>

enum_writer welder::rods::luacats::rod::make_enum	(	module_type &	m,
		const char *	name,
		const char *	doc )

inlinestatic

Open an enum table declaration for E and register its raw→styled name.

See also: welder::rod

Definition at line 341 of file rod.hpp.

References welder::doc(), welder::rods::luacats::enum_writer::doc, welder::rods::luacats::module_writer::doc, welder::rods::luacats::enum_writer::enum_doc, welder::rods::luacats::module_writer::prefix, welder::rods::luacats::enum_writer::qualified, welder::rods::luacats::qualified_name(), and welder::rods::luacats::document::record_type_name().

◆ make_nested_class() [1/2]

template<class T, std::meta::info Decl, auto Bases, std::size_t... I>

class_writer welder::rods::luacats::rod::make_nested_class	(	module_type &	m,
		class_writer &	outer,
		const char *	name,
		const char *	doc,
		std::index_sequence< I... >	seq )

inlinestatic

The declaring-entity-aware nested form the carriage prefers: Decl is ^^T, or the member alias an (otherwise unnameable) template specialization was registered through.

The raw name recorded for reference reconciliation derives from Decl — qualified_name(^^T) on a specialization would collapse to the bare enclosing scope and corrupt the rename table, exactly as in the namespace-alias make_class form.

See also: welder::rod

Definition at line 210 of file rod.hpp.

References _bases_string(), welder::rods::luacats::class_writer::bases, welder::rods::luacats::class_writer::cls_doc, welder::doc(), welder::rods::luacats::class_writer::doc, welder::rods::luacats::module_writer::doc, welder::rods::luacats::class_writer::qualified, welder::rods::luacats::qualified_name(), welder::rods::luacats::document::record_type_name(), welder::rods::luacats::class_writer::sink, and welder::rods::luacats::class_writer::trailing.

◆ make_nested_class() [2/2]

template<class T, auto Bases, std::size_t... I>

class_writer welder::rods::luacats::rod::make_nested_class	(	module_type &	m,
		class_writer &	outer,
		const char *	name,
		const char *	doc,
		std::index_sequence< I... >	seq )

inlinestatic

Open a ---@class block for a nested member type, declared under the OUTER's dotted name (mod.Outer.Inner — matching where the sol2 runtime places it) and flushed into the outer's trailing buffer, so its block lands after the outer's own declaration (the stub assigns mod.Outer.Inner = {} only once mod.Outer = {} exists).

See also: welder::rod

Definition at line 196 of file rod.hpp.

References welder::doc(), and make_nested_class().

Referenced by make_nested_class().

◆ make_nested_enum()

template<class E>

enum_writer welder::rods::luacats::rod::make_nested_enum	(	module_type &	m,
		class_writer &	outer,
		const char *	name,
		const char *	doc )

inlinestatic

Open the enum table declaration for a nested member enum, declared under the OUTER's dotted name and flushed into the outer's trailing buffer (see make_nested_class).

See also: welder::rod

Definition at line 359 of file rod.hpp.

References welder::doc(), welder::rods::luacats::enum_writer::doc, welder::rods::luacats::module_writer::doc, welder::rods::luacats::enum_writer::enum_doc, welder::rods::luacats::class_writer::qualified, welder::rods::luacats::enum_writer::qualified, welder::rods::luacats::qualified_name(), welder::rods::luacats::document::record_type_name(), welder::rods::luacats::enum_writer::sink, and welder::rods::luacats::class_writer::trailing.

◆ open_module()

session welder::rods::luacats::rod::open_module ( module_type & )

inlinestatic

Open a per-module session (no deferred state).

See also: welder::rod

Definition at line 390 of file rod.hpp.

◆ set_module_doc()

void welder::rods::luacats::rod::set_module_doc	(	module_type &	m,
		const char *	doc )

inlinestatic

Declare the (sub)module table, carrying doc as its comment.

See also: welder::rod

Definition at line 393 of file rod.hpp.

References welder::rods::luacats::document::declare_table(), welder::doc(), welder::rods::luacats::module_writer::doc, and welder::rods::luacats::module_writer::prefix.

◆ special_method_name()

consteval const char * welder::rods::luacats::rod::special_method_name ( std::meta::info op_fn )

inlinestaticconsteval

Member operator → its ---@operator name, or nullptr (also gates eligibility, like every backend).

See also: welder::rod

Definition at line 152 of file rod.hpp.

References welder::rods::luacats::operator_luacats().

Member Data Documentation

◆ has_native_caster

template<class T>

bool welder::rods::luacats::rod::has_native_caster

staticconstexpr

Initial value:

=

is_native_lua<std::remove_cvref_t<T>>

welder::rods::luacats::is_native_lua

constexpr bool is_native_lua

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

Definition type_map.hpp:189

is_native_lua drives the shared bindability gate.

Template Parameters

T	the type to classify.

See also: welder::caster_oracle

Definition at line 147 of file rod.hpp.

◆ language

lang welder::rods::luacats::rod::language {lang::lua}

staticconstexpr

Stubs are for the Lua binding.

Definition at line 71 of file rod.hpp.

Referenced by add_function(), add_method(), add_static_method(), and add_variable().

The documentation for this struct was generated from the following file:

src/welder/rods/lua/luacats/rod.hpp

Classes

Public Types

Static Public Member Functions

Static Public Attributes

Static Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ class_handle_type

◆ enum_handle_type

◆ module_type

Member Function Documentation

◆ _aggregate_fun_params()

◆ _aggregate_param_lines()

◆ _bases_string()

◆ add_constructors()

◆ add_enumerator()

◆ add_field()

◆ add_function()

◆ add_method()

◆ add_operator()

◆ add_static_method()

◆ add_submodule()

◆ add_variable()

◆ close_module()

◆ finish_enum()

◆ generate()

◆ make_class() [1/2]

◆ make_class() [2/2]

◆ make_enum()

◆ make_nested_class() [1/2]

◆ make_nested_class() [2/2]

◆ make_nested_enum()

◆ open_module()

◆ set_module_doc()

◆ special_method_name()

Member Data Documentation

◆ has_native_caster

◆ language