Namespaces
namespace	carriages
namespace	detail
	The stored forms of the annotation vocabulary.
namespace	diag
namespace	mark
	The bare mark annotation objects — use directly or call to scope by language.
namespace	naming
namespace	policy
	The policy annotation values.
namespace	rods
namespace	rv
	The return-value policy values, the user-facing spelling of rv_kind.

Classes
struct	welded_registration
	The default registration oracle of the bindability gate: a program-defined class/enum type counts as registered iff it is welded for the language. More...
struct	welder
	welder's binding entry point, parameterized on a rod. More...

Concepts
concept	caster_oracle
	The one bindability fact a backend must provide: can it natively convert a type without welder registering it?
concept	rod
	The contract a rod (a welder backend, welder::rods::…::rod) must satisfy to plug into the generic driver.
concept	resolution
	The contract a resolution — the carriage's which-participates policy — must satisfy to be injected as welder::carriages::basic_carriage's Resolution argument.
concept	doc_style
	A style folds a welder::detail::function_doc into one docstring.

Typedefs
using	size_type = decltype(sizeof(0))
	std::size_t named without a standard-library include, keeping this vocabulary header std-free (see the file note).
using	stitch_welding_carriage = carriages::basic_carriage<carriages::marker_resolution>
	The stitch-welding carriage (the default): binds only where welder's weld / policy / marks direct — intermittent, marker-driven, like a stitch weld.
using	tack_welding_carriage
	The tack-welding carriage: binds an unmarked library greedily — every reflectable type / function / global, namespaces recursed, bases flattened — ignoring the weld markers, while still enforcing the bindability gate.
using	carriage = stitch_welding_carriage
	The default carriage — an alias for welder::stitch_welding_carriage.

Enumerations
enum class	policy_kind : unsigned char { automatic , opt_in }
	How greedily a type's members are reflected for binding. More...
enum class	rv_kind : unsigned char { automatic , automatic_reference , take_ownership , copy , move , reference , reference_internal , none }
	How a bound callable's returned object is owned/converted in the target language — welder's backend-neutral spelling of the return-value policy. More...
enum class	lang : unsigned char { py , lua }
	The target languages welder ships rods for — but not the whole value space. More...
enum class	ent_kind { class_ , enum_ , enumerator , method , static_method , function , field , variable , submodule }
	The nameable entity kinds welder distinguishes, one per name-style hook — picked by the driver/rod so name_of calls the right transform. More...

Functions
consteval unsigned	lang_bit (lang l)
	The single-language bit for l within a language mask.
template<class... Ls>
consteval unsigned	lang_mask (Ls... ls)
	The mask naming the languages ls.
template<class... Ls>
consteval detail::weld_spec	weld (Ls... ls)
	Build a weld annotation naming the target languages.
template<size_type N>
consteval detail::doc_spec< N >	doc (const char(&s)[N])
	Attach a docstring to a namespace, class, function, or function parameter.
template<size_type N>
consteval detail::return_doc_spec< N >	returns (const char(&s)[N])
	Document a function's return value.
template<size_type N, size_type M>
consteval detail::tparam_spec< N, M >	tparam (const char(&name)[N], const char(&text)[M])
	Document a template parameter (repeatable, ordered).
template<size_type N>
consteval detail::weld_as_spec< N >	weld_as (const char(&s)[N])
	Force s as the target name in every welded language.
template<class... Args>
consteval auto	weld_as (Args &&... args)
	Force a verbatim target name, optionally scoped to one or more languages.
template<class... Args>
consteval detail::return_policy_spec	return_policy (Args... args)
	Force a return-value policy on a callable, optionally scoped to one or more languages.
consteval detail::keep_alive_spec	keep_alive (unsigned nurse, unsigned patient)
	Keep the call entity patient alive at least until nurse is collected.
template<caster_oracle B, class T, lang L, class Reg = welded_registration>
consteval bool	bindable ()
	Is T bindable to language L under backend B?
template<caster_oracle B, class T, lang L, class Reg = welded_registration>
consteval void	assert_bindable ()
	Hard error the instant welder would bind an unbindable type.
template<caster_oracle B, std::meta::info Fn, lang L, class Reg = welded_registration>
consteval void	assert_signature_bindable ()
	Assert every parameter type and the (non-void) return type of Fn binds.
template<caster_oracle B, std::meta::info Member, lang L, class Reg = welded_registration>
consteval void	assert_member_bindable ()
	Assert the type of a data member / namespace variable binds, unless trusted.
template<caster_oracle B, std::meta::info Fn, lang L, class Reg = welded_registration>
consteval void	assert_callable_bindable ()
	Assert a function/method/operator/constructor signature binds, unless trusted.
consteval bool	is_nested_type (std::meta::info type)
	Is type declared at class scope — a nested (member) type?
consteval std::string	cleandoc (std::string_view text)
	Normalize a docstring the way Python's inspect.cleandoc (PEP 257) does, so a multiline doc/returns can be indented to line up with the surrounding C++ source without that indentation reaching the target language's docstring.
template<std::meta::info Ent, std::meta::info SpecTmpl>
consteval const char *	annotation_text_of ()
	The text of the annotation on Ent whose class template is SpecTmpl, or nullptr if it carries none.
template<std::meta::info Ent>
consteval const char *	doc_of ()
	The doc text on Ent (a class, namespace, function, or parameter), or nullptr.
template<std::meta::info Fn>
consteval const char *	return_doc_of ()
	The returns text on function Fn (documentation of its return value), or nullptr.
template<std::meta::info Ent>
consteval size_type	tparam_count ()
	How many tparam annotations Ent carries.
template<std::meta::info Ent>
consteval auto	tparam_docs ()
	The template-parameter docs declared on Ent via [[=welder::tparam("T","…")]], in annotation order.
template<std::meta::info Fn>
consteval auto	param_docs ()
	The parameter docs of function Fn, in declaration order.
template<std::meta::info Fn, doc_style Style>
std::string	function_docstring ()
	The complete docstring for function Fn under Style.
template<std::meta::info Ent, lang L>
consteval const char *	weld_as_of ()
	The verbatim weld_as name forced on Ent for language L, or nullptr.
template<std::meta::info Ent, lang L, class Style, ent_kind K>
consteval const char *	name_of ()
	The final bound name of Ent (a K-kind entity) for language L under name style Style.
template<std::meta::info Ent, lang L, class Style, ent_kind K>
constexpr const char *	name_of_or (const char *override_)
	Resolve a bound name with a call-site override: override_ wins verbatim, nullptr falls back to name_of.
consteval bool	welded_for (std::meta::info type, lang L)
	Is type welded for language L — i.e.
consteval bool	names_template_specialization (std::meta::info mem)
	Is mem a namespace-scope alias naming a class-template specialization — the one way an instantiation can enter a namespace sweep?
consteval bool	alias_welded_for (std::meta::info mem, lang L)
	Is the specialization named by alias mem welded for language L — reading the alias's own weld first, the instantiation's (via its template) second?
consteval bool	alias_marks_admissible (std::meta::info mem)
	May the annotations on alias-declaration mem appear there?
consteval bool	member_alias_marks_admissible (std::meta::info mem)
	May the annotations on member type-alias mem appear there?
consteval policy_kind	policy_of (std::meta::info type)
	The reflection policy declared on type, defaulting to automatic.
consteval bool	protected_welded (std::meta::info type, lang L)
	Does type admit its protected members for language L — i.e.
consteval bool	excluded_for (std::meta::info member, lang L)
	Does member carry an exclude mark covering language L?
consteval bool	included_for (std::meta::info member, lang L)
	Does member carry an include mark covering language L?
consteval bool	trusted_for (std::meta::info member, lang L)
	Does member carry a trust_bindable mark covering language L?
consteval rv_kind	return_policy_of (std::meta::info fn, lang L)
	The return-value policy declared on callable fn for language L.
template<std::meta::info Fn, lang L>
consteval void	validate_return_policy ()
	Reject a return_policy on Fn (for language L) that contradicts Fn's return type.
consteval bool	member_bound (std::meta::info member, lang L, policy_kind pol)
	The core decision a backend asks for each member: does member bind for language L under policy pol?
consteval std::vector< std::meta::info >	public_bases (std::meta::info type)
	The types of the public base classes of type.

Variables
template<class T>
constexpr bool	trust_bindable = false
	The type-level trust customization point: specialize to true to trust T wherever it appears (member, parameter, return, container element, …).
template<unsigned char Slot>
constexpr lang	user_lang {static_cast<lang>(16 + Slot)}
	A user-defined language: the Slot-th identity from the mask's user range (bit 16 + Slot) — for binding a language welder does not ship, without touching welder.

Typedef Documentation

◆ carriage

using welder::carriage = stitch_welding_carriage

The default carriage — an alias for welder::stitch_welding_carriage.

Definition at line 1305 of file carriage.hpp.

◆ size_type

using welder::size_type = decltype(sizeof(0))

std::size_t named without a standard-library include, keeping this vocabulary header std-free (see the file note).

sizeof yields std::size_t by definition, so decltype(sizeof(0)) is that type — this alias just gives it a readable name for the array-length template parameters below.

Definition at line 24 of file annotations.hpp.

◆ stitch_welding_carriage

using welder::stitch_welding_carriage = carriages::basic_carriage<carriages::marker_resolution>

The stitch-welding carriage (the default): binds only where welder's weld / policy / marks direct — intermittent, marker-driven, like a stitch weld.

This is welder::welder's default Carriage.

See also: welder::carriages::basic_carriage

Definition at line 1291 of file carriage.hpp.

◆ tack_welding_carriage

using welder::tack_welding_carriage

Initial value:

carriages::basic_carriage<carriages::greedy_resolution<>>

welder::carriages::basic_carriage

A carriage: welder's reflection-driven traversal, parameterized on a Resolution (which markers it obe...

Definition carriage.hpp:467

The tack-welding carriage: binds an unmarked library greedily — every reflectable type / function / global, namespaces recursed, bases flattened — ignoring the weld markers, while still enforcing the bindability gate.

For consuming a third-party library that carries no welder annotations. Public members only, like the stitch default; to tack a library's protected members too (it cannot carry the policy::weld_protected annotation), use carriages::basic_carriage<carriages::greedy_resolution<true>>.

See also: welder::carriages::greedy_resolution for the exact rules and caveats.

Definition at line 1301 of file carriage.hpp.

Enumeration Type Documentation

◆ ent_kind

enum class welder::ent_kind

strong

The nameable entity kinds welder distinguishes, one per name-style hook — picked by the driver/rod so name_of calls the right transform.

Enumerator
class_	a class/struct type → transform_class.
enum_	an enum type → transform_enum.
enumerator	an enumerator → transform_enumerator.
method	a member function → transform_method.
static_method	a static member function → transform_static_method.
function	a free function → transform_function.
field	a data member → transform_field.
variable	a namespace variable → transform_variable.
submodule	a namespace bound as a submodule → transform_submodule.

Definition at line 239 of file naming.hpp.

◆ lang

enum class welder::lang : unsigned char

strong

The target languages welder ships rods for — but not the whole value space.

A language is a bit index into the unsigned mask the annotation vocabulary stores (lang_bit / lang_mask in <welder/annotations.hpp>), and the value space is deliberately open: these enumerators are the languages welder ships, yet any in-range welder::lang value is a valid language. Indices 0–15 are reserved for welder; an out-of-tree rod binding a language welder doesn't ship mints its identity from the user range (16–31) with welder::user_lang — see the "Extending welder" guide page.

Enumerator
py	Python (via the pybind11 and nanobind backends).
lua	Lua (via the sol2 and LuaBridge3 backends).

Definition at line 42 of file lang.hpp.

◆ policy_kind

enum class welder::policy_kind : unsigned char

strong

How greedily a type's members are reflected for binding.

Enumerator
automatic	Reflect every member unless explicitly excluded (default).
opt_in	Reflect only members explicitly marked include.

Definition at line 61 of file annotations.hpp.

◆ rv_kind

enum class welder::rv_kind : unsigned char

strong

How a bound callable's returned object is owned/converted in the target language — welder's backend-neutral spelling of the return-value policy.

The names mirror pybind11's return_value_policy / nanobind's rv_policy (the frameworks that have an explicit knob): a rod translates each to its framework's enumerator. The garbage-collected Lua runtimes (sol2, LuaBridge3) have no such knob — ownership there is decided structurally by the C++ return type (a value → a VM-owned copy/move; a pointer/reference → a non-owning view) — so the Lua rods ignore this at runtime, exactly as they ignore welder::doc. What no rod ignores is a contradiction: a reference-category policy on a by-value return references a temporary, so it is a hard error for every language (see validate_return_policy).

See also: welder::return_policy for the annotation; the welder::rv constants for the user-facing spellings.

Enumerator
automatic	The rod default — emit no explicit policy.
automatic_reference	Like automatic but never take ownership (used for arguments).
take_ownership	The target owns the returned pointer and frees it.
copy	Copy the returned object into a target-owned value.
move	Move the returned object into a target-owned value.
reference	A non-owning reference; the caller keeps the C++ object alive.
reference_internal	A non-owning reference tied to the parent's lifetime (implies keep_alive).
none	Do not convert (nanobind rv_policy::none); pybind11 has no equivalent.

Definition at line 81 of file annotations.hpp.

Function Documentation

◆ alias_marks_admissible()

bool welder::alias_marks_admissible ( std::meta::info mem )

consteval

May the annotations on alias-declaration mem appear there?

Only weld and weld_as are meaningful on a namespace-scope alias (they override the template's); every other welder mark — policy, exclude / include / only, trust_bindable, doc / returns / tparam, return_policy, keep_alive — belongs on the class template itself, where it applies to all instantiations, and is diagnosed here so it cannot be silently ignored. Non-welder annotations are not welder's business and pass.

Parameters

mem	a reflection of the alias to check.

Returns: true iff mem carries no welder annotation besides weld/weld_as.

Definition at line 78 of file reflect.hpp.

Referenced by welder::carriages::basic_carriage< carriages::marker_resolution >::bind_namespace().

◆ alias_welded_for()

bool welder::alias_welded_for	(	std::meta::info	mem,
		lang	L )

consteval

Is the specialization named by alias mem welded for language L — reading the alias's own weld first, the instantiation's (via its template) second?

A weld on the alias-declaration takes precedence over the template's: it is the more specific declaration, and the opt-in for a third-party template you cannot annotate (using VBuf [[=welder::weld(welder::lang::py)]] = vendor::Buf<int>;). With no alias-level weld, the mark on the class template is read through the instantiation as usual.

Parameters

mem	a reflection of the alias (see names_template_specialization).
L	the target language.

Returns: true iff the aliased specialization is welded for L.

Definition at line 60 of file reflect.hpp.

References lang_bit(), and welded_for().

Referenced by welder::carriages::marker_resolution::alias_participates(), and welder::carriages::basic_carriage< carriages::marker_resolution >::bind_namespace().

◆ annotation_text_of()

template<std::meta::info Ent, std::meta::info SpecTmpl>

const char * welder::annotation_text_of ( )

consteval

The text of the annotation on Ent whose class template is SpecTmpl, or nullptr if it carries none.

Ent / SpecTmpl are template parameters rather than runtime arguments because matching requires splicing the annotation's concrete SpecTmpl<N> type, which must be a constant.

Template Parameters

Ent	a reflection of the entity to read.
SpecTmpl	a class template whose specialization has a .text member convertible to a C string (detail::doc_spec, detail::return_doc_spec).

Returns: the annotation text, dedented and with static storage (define_static_string, so usable at runtime), or nullptr.

Definition at line 118 of file doc.hpp.

References cleandoc().

Referenced by doc_of(), and return_doc_of().

◆ assert_bindable()

template<caster_oracle B, class T, lang L, class Reg = welded_registration>

void welder::assert_bindable ( )

consteval

Hard error the instant welder would bind an unbindable type.

The offending type is the template argument of the failing instantiation, so it is named in the diagnostic backtrace.

Template Parameters

B	the rod.
T	the type being bound.
L	the target language.
Reg	the registration oracle (see welder::bindable).

Definition at line 224 of file bindable.hpp.

References bindable().

Referenced by assert_member_bindable(), welder::detail::assert_params_bindable(), and assert_signature_bindable().

◆ assert_callable_bindable()

template<caster_oracle B, std::meta::info Fn, lang L, class Reg = welded_registration>

void welder::assert_callable_bindable ( )

consteval

Assert a function/method/operator/constructor signature binds, unless trusted.

Template Parameters

B	the rod.
Fn	a reflection of the callable.
L	the target language.

Definition at line 300 of file bindable.hpp.

References assert_signature_bindable(), and trusted_for().

Referenced by welder::carriages::basic_carriage< carriages::marker_resolution >::bind_class_interior(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_function(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_members(), and welder::carriages::basic_carriage< carriages::marker_resolution >::bind_namespace().

◆ assert_member_bindable()

template<caster_oracle B, std::meta::info Member, lang L, class Reg = welded_registration>

void welder::assert_member_bindable ( )

consteval

Assert the type of a data member / namespace variable binds, unless trusted.

Template Parameters

B	the rod.
Member	a reflection of the data member or variable.
L	the target language.

Definition at line 288 of file bindable.hpp.

References assert_bindable(), and trusted_for().

Referenced by welder::carriages::basic_carriage< carriages::marker_resolution >::bind_members(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_namespace(), and welder::carriages::basic_carriage< carriages::marker_resolution >::bind_variable().

◆ assert_signature_bindable()

template<caster_oracle B, std::meta::info Fn, lang L, class Reg = welded_registration>

void welder::assert_signature_bindable ( )

consteval

Assert every parameter type and the (non-void) return type of Fn binds.

So the function/method/operator/constructor can round-trip through the target language. A constructor has no return type.

Template Parameters

B	the rod.
Fn	a reflection of the callable.
L	the target language.

Definition at line 259 of file bindable.hpp.

References assert_bindable(), and welder::detail::assert_params_bindable().

Referenced by assert_callable_bindable().

◆ bindable()

template<caster_oracle B, class T, lang L, class Reg = welded_registration>

bool welder::bindable ( )

consteval

Is T bindable to language L under backend B?

(public spelling.)

Template Parameters

B	the rod.
T	the type to test.
L	the target language.
Reg	the registration oracle: which class/enum types count as registered. Defaults to welder::welded_registration (welded ⇒ registered); the carriage passes its resolution so, e.g., tack welding accepts the types its own greedy pass registers.

Definition at line 210 of file bindable.hpp.

References welder::detail::bindable().

Referenced by assert_bindable(), and welder::carriages::basic_carriage< carriages::marker_resolution >::bind_nested_types().

◆ cleandoc()

std::string welder::cleandoc ( std::string_view text )

consteval

Normalize a docstring the way Python's inspect.cleandoc (PEP 257) does, so a multiline doc/returns can be indented to line up with the surrounding C++ source without that indentation reaching the target language's docstring.

Three steps, matching the Python convention users of the bindings expect:

strip leading whitespace from the first line (it typically abuts the opening R"( or the annotation call);
remove the whitespace common to every subsequent non-blank line (relative indentation — an indented example block — is preserved);
drop leading and trailing blank lines.

A single-line docstring is returned unchanged. Tabs are treated as single characters (not expanded to tab stops): indent doc text with spaces, as C++ source is indented generally.

Parameters

text	the raw docstring text.

Returns: the cleaned text (may be empty if the input was all whitespace).

Definition at line 45 of file doc.hpp.

Referenced by annotation_text_of().

◆ doc()

template<size_type N>

detail::doc_spec< N > welder::doc ( const char(&) s[N] )

consteval

Attach a docstring to a namespace, class, function, or function parameter.

Backends surface it in the target language (e.g. a Python __doc__, with parameter docs folded into the function's docstring). Reading the text back is the reflection layer's job (<welder/doc.hpp>).

Usage: [[=welder::doc("Summary line.")]].

Template Parameters

N	the text length (deduced).

Parameters

s	the docstring text.

Returns: a doc_spec holding the text.

Definition at line 454 of file annotations.hpp.

◆ doc_of()

template<std::meta::info Ent>

const char * welder::doc_of ( )

consteval

The doc text on Ent (a class, namespace, function, or parameter), or nullptr.

A function's own doc is its summary.

Template Parameters

Ent	a reflection of the documented entity.

Definition at line 138 of file doc.hpp.

References annotation_text_of().

Referenced by welder::rods::luacats::rod::add_field(), welder::rods::nanobind::rod< DocStyle >::add_field(), welder::rods::pybind11::rod< DocStyle >::add_field(), welder::rods::luacats::rod::add_variable(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_enum(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_namespace(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_nested_enum(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_nested_type(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_type(), welder::rods::luacats::build_overload(), function_docstring(), welder::rods::luacats::rod::generate(), and param_docs().

◆ excluded_for()

bool welder::excluded_for	(	std::meta::info	member,
		lang	L )

consteval

Does member carry an exclude mark covering language L?

Parameters

member	a reflection of the member to test.
L	the target language.

Returns: true iff an exclude mark applies to L (a mark with mask 0 covers all languages).

Definition at line 172 of file reflect.hpp.

References lang_bit().

Referenced by member_bound().

◆ function_docstring()

template<std::meta::info Fn, doc_style Style>

std::string welder::function_docstring ( )

The complete docstring for function Fn under Style.

Its own doc summary with its parameter docs and returns folded in. Empty when the function carries no documentation at all, so a backend can skip emitting it.

Template Parameters

Fn	a reflection of the function.
Style	the docstring style (a doc_style); the caller picks one that fits its target language.

Returns: the assembled docstring, or empty if undocumented.

Definition at line 276 of file doc.hpp.

References doc_of(), param_docs(), and return_doc_of().

Referenced by welder::rods::nanobind::rod< DocStyle >::_def_function(), and welder::rods::pybind11::rod< DocStyle >::_def_function().

◆ included_for()

bool welder::included_for	(	std::meta::info	member,
		lang	L )

consteval

Does member carry an include mark covering language L?

Parameters

member	a reflection of the member to test.
L	the target language.

Returns: true iff an include mark applies to L (a mark with mask 0 covers all languages).

Definition at line 188 of file reflect.hpp.

References lang_bit().

Referenced by member_bound().

◆ is_nested_type()

bool welder::is_nested_type ( std::meta::info type )

consteval

Is type declared at class scope — a nested (member) type?

Parameters

type	a reflection of a class/enum type.

Returns: true iff the immediately enclosing scope is a class.

Definition at line 105 of file carriage.hpp.

Referenced by welder::carriages::greedy_resolution< WeldProtected >::counts_as_registered(), welder::carriages::marker_resolution::counts_as_registered(), and welder::detail::scoped_registration< Resolution, Scope >::counts_as_registered().

◆ keep_alive()

detail::keep_alive_spec welder::keep_alive	(	unsigned	nurse,
		unsigned	patient )

consteval

Keep the call entity patient alive at least until nurse is collected.

Maps to pybind11 keep_alive<Nurse, Patient> / nanobind keep_alive<Nurse, Patient>; indices are 0 = return value, 1 = first argument (a method's implicit this), 2 = second, … Repeatable — attach several to declare several dependencies. Ignored by backends without the concept (the Lua rods).

Usage: [[=welder::keep_alive(1, 2)]] — keep argument 2 alive as long as the receiver (this) lives.

Parameters

nurse	the keeper whose collection bounds the dependency.
patient	the dependant kept alive until nurse is collected.

Returns: a keep_alive_spec carrying the two indices.

Definition at line 635 of file annotations.hpp.

◆ lang_bit()

unsigned welder::lang_bit ( lang l )

consteval

The single-language bit for l within a language mask.

Languages are tracked as bits in a mask so a spec can name an arbitrary subset. A value past the mask width is diagnosed at compile time (mint user languages with welder::user_lang, which cannot go out of range).

Parameters

l	the language.

Returns: 1u << index-of(l).

Exceptions

diag::lang_out_of_mask_range (a constant-evaluation error) for a value past the mask width — instead of an opaque shift overflow.

Definition at line 41 of file annotations.hpp.

Referenced by alias_welded_for(), excluded_for(), included_for(), lang_mask(), member_bound(), protected_welded(), welder::detail::return_policy_mask(), return_policy_of(), trusted_for(), welder::detail::weld_as_mask(), weld_as_of(), and welded_for().

◆ lang_mask()

template<class... Ls>

unsigned welder::lang_mask ( Ls... ls )

consteval

The mask naming the languages ls.

Template Parameters

Ls	the language enum types (deduced).

Parameters

ls	the languages to combine.

Returns: the OR of each language's bit; 0 for an empty pack — which, on an exclude/include/trust spec, is the sentinel meaning "all welded languages".

Definition at line 56 of file annotations.hpp.

References lang_bit().

Referenced by welder::detail::exclude_spec::operator()(), welder::detail::include_spec::operator()(), welder::detail::only_spec::operator()(), welder::detail::trust_bindable_spec::operator()(), welder::detail::weld_protected_spec::operator()(), and weld().

◆ member_alias_marks_admissible()

bool welder::member_alias_marks_admissible ( std::meta::info mem )

consteval

May the annotations on member type-alias mem appear there?

A member alias participates by the member rules (the outer's policy plus the alias's own marks) with the bindability gate as the register-or-skip arbiter — so weld_as and the participation marks (exclude / include / only) are meaningful on it. Everything else is not: weld (participation never reads it — nested registration follows the outer), policy / weld_protected (they belong on the target type), trust_bindable / return_policy / keep_alive / doc / returns / tparam (no surface they could apply to). Those are diagnosed rather than silently ignored. Non-welder annotations are not welder's business and pass.

Parameters

mem	a reflection of the member alias to check.

Returns: true iff mem carries only admissible welder annotations.

Definition at line 109 of file reflect.hpp.

Referenced by welder::carriages::basic_carriage< carriages::marker_resolution >::bind_nested_types().

◆ member_bound()

bool welder::member_bound	(	std::meta::info	member,
		lang	L,
		policy_kind	pol )

consteval

The core decision a backend asks for each member: does member bind for language L under policy pol?

Parameters

member	a reflection of the member to resolve.
L	the target language.
pol	the enclosing type's reflection policy.

Returns: excluded ⇒ false; else an only mark ⇒ true iff it names L (under either policy — only is also the opt-in); else automatic ⇒ true; else (opt_in) ⇒ true iff explicitly included.

Exceptions

diag::bare_mark_only (a constant-evaluation error) on an uncalled [[=welder::mark::only]] — it must name the languages.

Definition at line 276 of file reflect.hpp.

References automatic, excluded_for(), included_for(), and lang_bit().

◆ name_of()

template<std::meta::info Ent, lang L, class Style, ent_kind K>

const char * welder::name_of ( )

consteval

The final bound name of Ent (a K-kind entity) for language L under name style Style.

A [[=welder::weld_as]] override wins and is used verbatim (it never flows through Style); otherwise Ent's identifier is reshaped by Style's hook for kind K. The result has static storage, so both the driver and the rods feed it straight to their frameworks. This is the single place a bound name is decided — the driver uses it for class/enum/submodule names, each rod for its members.

Template Parameters

Ent	a reflection of the entity to name.
L	the target language.
Style	the name style (a welder::naming::name_style).
K	which of Style's per-kind hooks to apply.

Returns: the bound name, in static storage.

Definition at line 294 of file naming.hpp.

References class_, enum_, enumerator, field, function, method, static_method, variable, and weld_as_of().

Referenced by welder::rods::luabridge::rod::add_enumerator(), welder::rods::luacats::rod::add_enumerator(), welder::rods::nanobind::rod< DocStyle >::add_enumerator(), welder::rods::pybind11::rod< DocStyle >::add_enumerator(), welder::rods::sol2::rod::add_enumerator(), welder::rods::luabridge::rod::add_field(), welder::rods::luacats::rod::add_field(), welder::rods::nanobind::rod< DocStyle >::add_field(), welder::rods::pybind11::rod< DocStyle >::add_field(), welder::rods::sol2::rod::add_field(), welder::rods::luabridge::rod::add_method(), welder::rods::luacats::rod::add_method(), welder::rods::nanobind::rod< DocStyle >::add_method(), welder::rods::pybind11::rod< DocStyle >::add_method(), welder::rods::sol2::rod::add_method(), welder::rods::luabridge::rod::add_static_method(), welder::rods::luacats::rod::add_static_method(), welder::rods::nanobind::rod< DocStyle >::add_static_method(), welder::rods::pybind11::rod< DocStyle >::add_static_method(), welder::rods::sol2::rod::add_static_method(), welder::detail::alias_bound_name(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_namespace(), and name_of_or().

◆ name_of_or()

template<std::meta::info Ent, lang L, class Style, ent_kind K>

const char * welder::name_of_or ( const char * override_ )

constexpr

Resolve a bound name with a call-site override: override_ wins verbatim, nullptr falls back to name_of.

This is the form the driver and every rod use to honor the optional trailing name on weld_type / weld_function / weld_variable / weld_namespace_as_submodule. It exists because the fallback must be lazy: an entity with no identifier — a class/function template instantiation like Box<int> — can only be named by a weld_as or by the call-site override, and a bare override_ ? override_ : name_of<…>() would still constant-evaluate the consteval name_of (and hard-error on identifier_of) even when the override is present. Here the name_of fallback is compiled only when the entity is statically nameable; otherwise a missing override throws at binding time (it cannot be a compile-time diagnostic — whether the runtime pointer is null is unknowable there).

Template Parameters

Ent	a reflection of the entity to name.
L	the target language.
Style	the name style (a welder::naming::name_style).
K	which of Style's per-kind hooks to apply.

Parameters

override_ the verbatim call-site name, or nullptr for the resolved one.

Returns: the bound name, in static storage (or override_, whose lifetime the caller owns).

Exceptions

std::invalid_argument when the entity has neither an identifier nor a weld_as for L and override_ is nullptr.

Definition at line 343 of file naming.hpp.

References name_of(), and weld_as_of().

Referenced by welder::rods::luabridge::rod::add_function(), welder::rods::luacats::rod::add_function(), welder::rods::nanobind::rod< DocStyle >::add_function(), welder::rods::pybind11::rod< DocStyle >::add_function(), welder::rods::sol2::rod::add_function(), welder::rods::luabridge::rod::add_variable(), welder::rods::luacats::rod::add_variable(), welder::rods::nanobind::rod< DocStyle >::add_variable(), welder::rods::pybind11::rod< DocStyle >::add_variable(), welder::rods::sol2::rod::add_variable(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_enum(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_namespace_as_submodule(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_nested_enum(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_nested_type(), and welder::carriages::basic_carriage< carriages::marker_resolution >::bind_type().

◆ names_template_specialization()

bool welder::names_template_specialization ( std::meta::info mem )

consteval

Is mem a namespace-scope alias naming a class-template specialization — the one way an instantiation can enter a namespace sweep?

members_of(ns) enumerates the class template, never its instantiations; a namespace-scope using IntRing = Ring<int>; is therefore welder's vehicle for welding one: the alias supplies both the target-language name (its identifier) and — for text-emitting rods — the C++ spelling of the otherwise unnameable specialization (has_identifier is false on Ring<int> itself).

Parameters

mem	a reflection of a namespace member.

Returns: true iff mem is a type alias whose target is a class-template specialization.

Definition at line 43 of file reflect.hpp.

Referenced by welder::carriages::basic_carriage< carriages::marker_resolution >::bind_namespace(), and welder::detail::sole_alias_of_target().

◆ param_docs()

template<std::meta::info Fn>

auto welder::param_docs ( )

consteval

The parameter docs of function Fn, in declaration order.

Names and texts use static storage, so the array (and spans over it) stay valid at runtime.

Template Parameters

Fn	a reflection of the function.

Returns: an array of detail::param_doc, one per parameter, in declaration order.

Definition at line 227 of file doc.hpp.

References doc_of().

Referenced by welder::rods::luacats::arg_list(), welder::rods::luacats::emit_params(), welder::rods::luacats::fun_signature(), and function_docstring().

◆ policy_of()

policy_kind welder::policy_of ( std::meta::info type )

consteval

The reflection policy declared on type, defaulting to automatic.

Parameters

type	a reflection of the type to inspect.

Returns: the type's policy annotation, or policy_kind::automatic if none.

Definition at line 132 of file reflect.hpp.

References automatic.

Referenced by welder::detail::aggregate_initializable(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_members(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_namespace(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_nested_types(), welder::carriages::basic_carriage< carriages::marker_resolution >::emit_enumerators(), welder::detail::function_overload_set(), welder::detail::method_overload_set(), welder::detail::namespace_has_bindable(), welder::detail::namespace_has_bound(), welder::detail::nested_type_registered(), welder::detail::operator_overload_set(), and welder::detail::registered_by_member_alias().

◆ protected_welded()

bool welder::protected_welded	(	std::meta::info	type,
		lang	L )

consteval

Does type admit its protected members for language L — i.e.

does it carry a policy::weld_protected annotation covering L?

Read off the member's declaring class (so a flattened non-welded base admits its own protected members, consistent with how its marks and policy resolve), and — like every annotation — read through a class-template instantiation from the template's declaration. Repeated annotations union. This is only the default arbitration: a resolution with a protected_participates hook replaces it (see the carriage's member_access_admitted). Private members are never admitted, under any resolution.

Parameters

type	a reflection of the declaring class.
L	the target language.

Returns: true iff a weld_protected annotation applies to L (mask 0 covers all languages).

Definition at line 155 of file reflect.hpp.

References lang_bit().

Referenced by welder::carriages::greedy_resolution< WeldProtected >::protected_participates(), and welder::carriages::marker_resolution::protected_participates().

◆ public_bases()

std::vector< std::meta::info > welder::public_bases ( std::meta::info type )

consteval

The types of the public base classes of type.

Private/protected bases are an implementation detail and never participate in a binding. Backends decide how to treat a public base: typically, a base that is itself welded for the target language maps to native inheritance in that backend, while a non-welded base has its members flattened into the derived binding.

Parameters

type	a reflection of the derived type.

Returns: the reflected types of type's public direct bases, in declaration order.

Definition at line 307 of file reflect.hpp.

Referenced by welder::rods::sol2::rod::_collect_welded_bases(), welder::detail::aggregate_initializable(), welder::carriages::basic_carriage< carriages::marker_resolution >::bind_members(), and welder::detail::collect_native_bases().

◆ return_doc_of()

template<std::meta::info Fn>

const char * welder::return_doc_of ( )

consteval

The returns text on function Fn (documentation of its return value), or nullptr.

A distinct spec type, so it does not collide with the summary doc.

Template Parameters

Fn	a reflection of the function.

Definition at line 148 of file doc.hpp.

References annotation_text_of().

Referenced by welder::rods::luacats::build_overload(), and function_docstring().

◆ return_policy()

template<class... Args>

detail::return_policy_spec welder::return_policy ( Args... args )

consteval

Force a return-value policy on a callable, optionally scoped to one or more languages.

The rv_kind is the last argument; zero or more lang markers precede it. With no marker the policy covers every welded language; with one or several it is scoped to those — repeat the annotation for a different policy per language. Backends without an explicit policy knob (the Lua rods) ignore it, but a reference-category policy on a by-value return is a hard error for every language (it would reference a temporary).

[[=welder::return_policy(welder::rv::reference_internal)]] // all languages

[[=welder::return_policy(welder::lang::py, welder::rv::take_ownership)]] // Python only

welder::rv::reference_internal

constexpr rv_kind reference_internal

Definition annotations.hpp:570

welder::rv::take_ownership

constexpr rv_kind take_ownership

Definition annotations.hpp:566

welder::lang::py

@ py

Python (via the pybind11 and nanobind backends).

Definition lang.hpp:43

welder::return_policy

consteval detail::return_policy_spec return_policy(Args... args)

Force a return-value policy on a callable, optionally scoped to one or more languages.

Definition annotations.hpp:615

Template Parameters

Args	the leading lang markers then the trailing rv_kind (deduced).

Parameters

args	the language markers (if any) followed by the policy.

Returns: a return_policy_spec carrying the mask of the named languages and the kind.

Definition at line 615 of file annotations.hpp.

References welder::detail::return_policy_kind(), and welder::detail::return_policy_mask().

◆ return_policy_of()

rv_kind welder::return_policy_of	(	std::meta::info	fn,
		lang	L )

consteval

The return-value policy declared on callable fn for language L.

Reads fn's return_policy annotations, honoring the first one whose mask covers L (a mask of 0 covers all languages). Absent any, the policy is rv_kind::automatic — the rod's default, so an unannotated callable binds exactly as before. A rod with an explicit policy knob (the Python backends) translates the result; the Lua rods ignore it (ownership is structural).

Parameters

fn	a reflection of the function/method/operator.
L	the target language.

Returns: the resolved policy, or rv_kind::automatic if none applies to L.

Definition at line 229 of file reflect.hpp.

References automatic, and lang_bit().

Referenced by welder::rods::nanobind::rod< DocStyle >::_def_function(), welder::rods::pybind11::rod< DocStyle >::_def_function(), and validate_return_policy().

◆ returns()

template<size_type N>

detail::return_doc_spec< N > welder::returns ( const char(&) s[N] )

consteval

Document a function's return value.

Usage: [[=welder::returns("what the call yields")]] on a function.

Template Parameters

N	the text length (deduced).

Parameters

s	the return-value documentation.

Returns: a return_doc_spec holding the text.

Definition at line 467 of file annotations.hpp.

◆ tparam()

template<size_type N, size_type M>

detail::tparam_spec< N, M > welder::tparam	(	const char(&)	name[N],
		const char(&)	text[M] )

consteval

Document a template parameter (repeatable, ordered).

Usage: [[=welder::tparam("T", "what T is")]] on a class/function template.

Template Parameters

N	the parameter-name length (deduced).
M	the text length (deduced).

Parameters

name	the template parameter's name, matching the declaration.
text	its documentation.

Returns: a tparam_spec pairing the name with the text.

Definition at line 482 of file annotations.hpp.

◆ tparam_count()

template<std::meta::info Ent>

size_type welder::tparam_count ( )

consteval

How many tparam annotations Ent carries.

They are repeatable and keep declaration order, unlike the single-shot doc/returns specs.

Template Parameters

Ent	a reflection of the entity.

Returns: the count of tparam annotations.

Definition at line 169 of file doc.hpp.

◆ tparam_docs()

template<std::meta::info Ent>

auto welder::tparam_docs ( )

consteval

The template-parameter docs declared on Ent via [[=welder::tparam("T","…")]], in annotation order.

Note: P2996 refuses annotations_of on an uninstantiated template, so on gcc-16 these read off a concrete entity — in practice an instantiation, which inherits the governing declaration's annotations (see tests/core/template_annotations.cpp). The Doxygen filter reads the same annotations textually, so the C++ docs need no instantiation.

Template Parameters

Ent	a reflection of the entity.

Returns: an array of detail::tparam_doc, one per tparam annotation, in order.

Definition at line 193 of file doc.hpp.

◆ trusted_for()

bool welder::trusted_for	(	std::meta::info	member,
		lang	L )

consteval

Does member carry a trust_bindable mark covering language L?

The user's vouch that the member's type is registered/convertible outside welder's view, so the bindability gate should trust it. See <welder/annotations.hpp>.

Parameters

member	a reflection of the member to test.
L	the target language.

Returns: true iff a trust_bindable mark applies to L (mask 0 covers all languages).

Definition at line 208 of file reflect.hpp.

References lang_bit().

Referenced by assert_callable_bindable(), and assert_member_bindable().

◆ validate_return_policy()

template<std::meta::info Fn, lang L>

void welder::validate_return_policy ( )

consteval

Reject a return_policy on Fn (for language L) that contradicts Fn's return type.

A reference-category policy (reference / reference_internal) promises the target a view into a live C++ object; on a by-value (prvalue) return there is no such object — only a temporary — so the view would dangle. This is a contradiction in any language, so every rod (Python and Lua alike) runs the check at its per-overload bind site. Anything the framework could plausibly honor passes; only the dangling case is diagnosed.

Template Parameters

Fn	a reflection of the callable being bound.
L	the target language.

Exceptions

diag::dangling_return_policy (a constant-evaluation error) on the contradiction.

Definition at line 253 of file reflect.hpp.

References reference, reference_internal, and return_policy_of().

Referenced by welder::rods::luabridge::rod::_add_function(), welder::rods::luabridge::rod::_add_static_function(), welder::rods::nanobind::rod< DocStyle >::_def_function(), welder::rods::pybind11::rod< DocStyle >::_def_function(), welder::rods::sol2::rod::_register_named(), and welder::rods::sol2::rod::_register_operator().

◆ weld()

template<class... Ls>

detail::weld_spec welder::weld ( Ls... ls )

consteval

Build a weld annotation naming the target languages.

Usage: [[=welder::weld(welder::lang::py, welder::lang::lua)]].

Template Parameters

Ls	the language enum types (deduced).

Parameters

ls	the target languages this entity is exposed to.

Returns: a weld_spec carrying the language mask.

Definition at line 389 of file annotations.hpp.

References lang_mask().

◆ weld_as() [1/2]

template<class... Args>

auto welder::weld_as ( Args &&... args )

consteval

Force a verbatim target name, optionally scoped to one or more languages.

The verbatim name is the last argument; zero or more lang markers precede it. With no marker the name covers every welded language; with one or several it is scoped to those. Repeat the annotation to give an entity a different verbatim name per language.

[[=welder::weld_as("do_thing")]]                          // all languages
[[=welder::weld_as(welder::lang::py, "do_thing")]]        // Python only
[[=welder::weld_as(welder::lang::py, welder::lang::lua, "do_thing")]] // both

Template Parameters

Args	the leading lang markers then the const char[N] name (deduced).

Parameters

args	the language markers (if any) followed by the verbatim name.

Returns: a weld_as_spec carrying the mask of the named languages and the name.

Definition at line 549 of file annotations.hpp.

References welder::detail::weld_as_mask(), and welder::detail::weld_as_name().

◆ weld_as() [2/2]

template<size_type N>

detail::weld_as_spec< N > welder::weld_as ( const char(&) s[N] )

consteval

Force s as the target name in every welded language.

The bare, all-languages form of weld_as — the common case, spelled as its own overload (like welder::weld() with no languages) so a plain [[=welder::weld_as("do_thing")]] needs none of the variadic marker machinery. A single string argument is more specialized than the variadic form below, so it is the one chosen here.

Template Parameters

N	the name length including the terminator (deduced).

Parameters

s	the verbatim name.

Returns: a weld_as_spec with mask 0 (all languages).

Definition at line 500 of file annotations.hpp.

◆ weld_as_of()

template<std::meta::info Ent, lang L>

const char * welder::weld_as_of ( )

consteval

The verbatim weld_as name forced on Ent for language L, or nullptr.

Scans Ent's annotations for a detail::weld_as_spec covering L (a mask of 0 covers all languages); the first match wins. The returned string has static storage (define_static_string), so it is usable at runtime.

Template Parameters

Ent	a reflection of the entity to read.
L	the target language.

Returns: the forced name, or nullptr if Ent carries no weld_as for L.

Definition at line 262 of file naming.hpp.

References lang_bit().

Referenced by welder::detail::alias_bound_name(), name_of(), and name_of_or().

◆ welded_for()

bool welder::welded_for	(	std::meta::info	type,
		lang	L )

consteval

Is type welded for language L — i.e.

does it carry a matching weld annotation?

Parameters

type	a reflection of the type to test.
L	the target language.

Returns: true iff type's weld annotation lists L.

Definition at line 26 of file reflect.hpp.

References lang_bit().

Referenced by welder::rods::sol2::rod::_collect_welded_bases(), alias_welded_for(), welder::detail::collect_native_bases(), welder::carriages::marker_resolution::counts_as_registered(), welder::welded_registration::counts_as_registered(), welder::detail::entity_bound(), welder::carriages::marker_resolution::is_native_base(), welder::carriages::marker_resolution::member_participates(), and welder::carriages::marker_resolution::participates().

Variable Documentation

◆ trust_bindable

template<class T>

bool welder::trust_bindable = false

inlineconstexpr

The type-level trust customization point: specialize to true to trust T wherever it appears (member, parameter, return, container element, …).

A plain bool, so it trusts T for every language at once. Usage (at namespace scope, before binding a type that uses T):

template <> inline constexpr bool welder::trust_bindable<Foo> = true;

welder::trust_bindable

constexpr bool trust_bindable

The type-level trust customization point: specialize to true to trust T wherever it appears (member,...

Definition annotations.hpp:429

Template Parameters

T	the type to trust everywhere. See welder::detail::trust_bindable_spec for the per-member granularity.

Definition at line 429 of file annotations.hpp.

Referenced by welder::detail::bindable().

◆ user_lang

template<unsigned char Slot>

lang welder::user_lang {static_cast<lang>(16 + Slot)}

inlineconstexpr

A user-defined language: the Slot-th identity from the mask's user range (bit 16 + Slot) — for binding a language welder does not ship, without touching welder.

Constrained so it can never collide with a welder-shipped language and never exceeds the mask width.

Mint it once, in one place — the application that instantiates the rod — and spell both the annotations and the rod's language from that single constant, so the two can never disagree:

inline constexpr welder::lang ruby{welder::user_lang<0>};
 
struct [[=welder::weld(ruby)]] Gem { ... };
 
rods_ruby::rod<ruby>   // a third-party rod's injectable language parameter

Two third-party rods that both default to the same slot are re-pointed the same way — pass each a distinct user_lang at the instantiation site.

Template Parameters

Slot	the user-range slot, 0–15.

Definition at line 69 of file lang.hpp.

Namespaces

Classes

Concepts

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

◆ carriage

◆ size_type

◆ stitch_welding_carriage

◆ tack_welding_carriage

Enumeration Type Documentation

◆ ent_kind

◆ lang

◆ policy_kind

◆ rv_kind

Function Documentation

◆ alias_marks_admissible()

◆ alias_welded_for()

◆ annotation_text_of()

◆ assert_bindable()

◆ assert_callable_bindable()

◆ assert_member_bindable()

◆ assert_signature_bindable()

◆ bindable()

◆ cleandoc()

◆ doc()

◆ doc_of()

◆ excluded_for()

◆ function_docstring()

◆ included_for()

◆ is_nested_type()

◆ keep_alive()

◆ lang_bit()

◆ lang_mask()

◆ member_alias_marks_admissible()

◆ member_bound()

◆ name_of()

◆ name_of_or()

◆ names_template_specialization()

◆ param_docs()

◆ policy_of()

◆ protected_welded()

◆ public_bases()

◆ return_doc_of()

◆ return_policy()

◆ return_policy_of()

◆ returns()

◆ tparam()

◆ tparam_count()

◆ tparam_docs()

◆ trusted_for()

◆ validate_return_policy()

◆ weld()

◆ weld_as() [1/2]

◆ weld_as() [2/2]

◆ weld_as_of()

◆ welded_for()

Variable Documentation

◆ trust_bindable

◆ user_lang