|
welder 0.1.0
Bindings for annotated C++ types, from C++26 reflection
|
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, bool Copyable, class Style = ::welder::naming::none> | |
| 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, or a [[=welder::mark::no_reassign]] mark → a (read-only) note, since LuaCATS has no const modifier). | |
| template<class T, std::meta::info Getter, std::meta::info Setter> | |
| static void | add_property (class_writer &w, const char *name) |
| Emit a ---@field line for the resolved property (Getter + optional Setter) under the driver-resolved name — the stub's view of a method-backed property is exactly a field of the getter's (dereferenced) return type, with the getter's [[=welder::doc]] as the description and, when no setter participates, the same (read-only) note a const data member gets. | |
| 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<class T, auto Fns> | |
| static void | add_operator (class_writer &w) |
| Emit operator slot 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 T, auto Fns, auto Covered> | |
| static void | add_comparisons (class_writer &) |
| Comparison synthesis has no stub form: LuaLS rejects ---@operator
lt/le (unknown-operator), exactly as it does for explicit relational operators — the synthesized __lt/__le work at runtime, the stub just cannot type them. | |
| template<class T, std::meta::info Fn> | |
| static void | add_stringifier (class_writer &) |
| __tostring needs no LuaCATS tag — tostring()/print() are typed generically by the language server. | |
| 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, preceded by its doc rendered as a nested --- comment block. | |
| 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). | |
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 _).
| 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.
| using welder::rods::luacats::rod::enum_handle_type = enum_writer |
|
inlinestaticprotected |
The <field>: <type>, … list for an aggregate's .new fun(…) signature (its ---@overload line).
Same field source as _aggregate_param_lines, with the same ? marking of the omissible NSDMI suffix.
Definition at line 131 of file rod.hpp.
References welder::detail::aggregate_fields(), welder::detail::aggregate_required_arity(), and welder::rods::luacats::lua_type().
Referenced by add_constructors().
|
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(), welder::detail::aggregate_required_arity(), and welder::rods::luacats::lua_type().
Referenced by add_constructors().
|
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().
|
inlinestatic |
Comparison synthesis has no stub form: LuaLS rejects ---@operator lt/le (unknown-operator), exactly as it does for explicit relational operators — the synthesized __lt/__le work at runtime, the stub just cannot type them.
|
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.
Copyable is ignored — the stub mirrors the Lua runtime rods, and Lua has no copy protocol for the copy constructor to bind to.
Definition at line 253 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.
|
inlinestatic |
Emit an Name = <int> line for enumerator Enum, preceded by its doc rendered as a nested --- comment block.
LuaCATS has no per-member tag for an enum, but the language server attaches a --- comment above a field inside the ---@enum table to that member (surfaced on hover/completion) — the Lua analogue of the Python rods folding enumerator docs into the class docstring.
Definition at line 436 of file rod.hpp.
References welder::doc_of(), welder::rods::luacats::emit_doc_comment(), welder::name_of(), and welder::rods::luacats::enum_writer::values.
|
inlinestatic |
Emit a ---@field line for data member Mem (const, or a [[=welder::mark::no_reassign]] mark → a (read-only) note, since LuaCATS has no const modifier).
Definition at line 279 of file rod.hpp.
References welder::doc_of(), welder::rods::luacats::class_writer::fields, language, welder::rods::luacats::lua_type(), welder::member_no_reassign(), welder::name_of(), and welder::rods::luacats::one_line().
|
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).
Definition at line 466 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().
|
inlinestatic |
Emit method overload group Fns as one documented Class:name(…) (further overloads as ---@overload lines; name from Fns[0]).
Definition at line 322 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().
|
inlinestatic |
Emit operator slot 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).
Member and anchored free entries mix in one group; a free entry's operand is its second parameter (the first is the anchor). A REVERSED free entry (T on the right — operator*(double, Vec)) is runtime-only: ---@operator types self as the left operand, so it is dropped here, like the eq/lt/le slots LuaLS rejects.
Definition at line 358 of file rod.hpp.
References welder::rods::luacats::class_writer::fields, welder::detail::free_operator_reflected(), welder::detail::is_unary_operator(), welder::rods::luacats::lua_type(), welder::rods::luacats::operator_luacats(), and welder::rods::luacats::param_lua_types().
|
inlinestatic |
Emit a ---@field line for the resolved property (Getter + optional Setter) under the driver-resolved name — the stub's view of a method-backed property is exactly a field of the getter's (dereferenced) return type, with the getter's [[=welder::doc]] as the description and, when no setter participates, the same (read-only) note a const data member gets.
Definition at line 305 of file rod.hpp.
References welder::doc_of(), welder::rods::luacats::class_writer::fields, welder::rods::luacats::lua_type(), and welder::rods::luacats::one_line().
|
inlinestatic |
Emit static-method overload group Fns as a documented Class.name(…) (dotted, no self).
Definition at line 338 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.
|
inlinestatic |
__tostring needs no LuaCATS tag — tostring()/print() are typed generically by the language server.
|
inlinestatic |
Declare a nested submodule table under m and return its writer.
Definition at line 493 of file rod.hpp.
References welder::rods::luacats::document::declare_table(), welder::rods::luacats::module_writer::doc, and welder::rods::luacats::module_writer::prefix.
|
inlinestatic |
Emit a ---@type-annotated <name> = nil module variable declaration.
Definition at line 480 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.
|
inlinestatic |
Close the session (no-op; the document accumulates directly).
|
inlinestatic |
No finalizer needed — the enum_writer flushes on destruction.
|
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.
| 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(). |
| os | the stream to write the finished stub to. |
Definition at line 526 of file rod.hpp.
References welder::doc(), welder::doc_of(), welder::rods::luacats::module_writer::prefix, and welder::rods::luacats::qualified_name().
|
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).
Definition at line 184 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().
|
inlinestatic |
Open a ---@class block for T and register its raw→styled name for later type-reference reconciliation.
Definition at line 172 of file rod.hpp.
References welder::doc(), and make_class().
Referenced by make_class().
|
inlinestatic |
Open an enum table declaration for E and register its raw→styled name.
Definition at line 399 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().
|
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.
Definition at line 221 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.
|
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).
Definition at line 207 of file rod.hpp.
References welder::doc(), and make_nested_class().
Referenced by make_nested_class().
|
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).
Definition at line 417 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.
|
inlinestatic |
Open a per-module session (no deferred state).
|
inlinestatic |
Declare the (sub)module table, carrying doc as its comment.
Definition at line 457 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.
|
inlinestaticconsteval |
Member operator → its ---@operator name, or nullptr (also gates eligibility, like every backend).
Definition at line 163 of file rod.hpp.
References welder::rods::luacats::operator_luacats().
|
staticconstexpr |
is_native_lua drives the shared bindability gate.
| T | the type to classify. |
Stubs are for the Lua binding.
Definition at line 71 of file rod.hpp.
Referenced by add_field(), add_function(), add_method(), add_static_method(), and add_variable().