bindable.hpp

Go to the documentation of this file.

#pragma once
#include <array>
#include <concepts>
#include <cstddef>
#include <meta>
#include <type_traits>
#include <utility>
 
// The STL templates named in the element-wise wrapper table below must be
// complete/visible so `^^std::vector` & friends resolve.
#include <deque>
#include <list>
#include <map>
#include <memory>
#include <expected>
#include <optional>
#include <set>
#include <span>
#include <string>
#include <tuple>
#include <unordered_map>
#include <unordered_set>
#include <variant>
#include <vector>
 
#include <welder/bind_traits.hpp> // param_types (for signature asserts)
#include <welder/concepts.hpp>    // caster_oracle (the backend leaf test)
#include <welder/reflect.hpp>     // welded_for

 
namespace welder::inline v0 {

struct welded_registration {
    static consteval bool counts_as_registered(std::meta::info type, lang L) {
        return welder::welded_for(type, L);
    }
};
 
namespace detail {

template <caster_oracle B, class T, lang L, class Reg>
consteval bool bindable();

struct wrapper_spec {
    std::meta::info tmpl;  
    std::size_t values;    
};

consteval std::array<wrapper_spec, 18> stl_wrappers() {
    return {{
        {^^std::vector, 1},        {^^std::list, 1},
        {^^std::deque, 1},         {^^std::set, 1},
        {^^std::multiset, 1},      {^^std::unordered_set, 1},
        {^^std::unordered_multiset, 1},
        {^^std::map, 2},           {^^std::multimap, 2},
        {^^std::unordered_map, 2}, {^^std::unordered_multimap, 2},
        {^^std::optional, 1},      {^^std::shared_ptr, 1},
        {^^std::unique_ptr, 1},    {^^std::pair, 2},
        {^^std::array, 1},         {^^std::tuple, 0},
        {^^std::variant, 0},
    }};
}

consteval long wrapper_value_count(std::meta::info type) {
    if (!std::meta::has_template_arguments(type))
        return -1;
    const std::meta::info tmpl{std::meta::template_of(type)};
    for (const wrapper_spec& w : stl_wrappers())
        if (w.tmpl == tmpl)
            return w.values != 0 ? static_cast<long>(w.values)
                                 : static_cast<long>(
                                       std::meta::template_arguments_of(type).size());
    return -1;
}

template <std::meta::info Type, std::size_t N>
consteval std::array<std::meta::info, N> leading_args() {
    std::array<std::meta::info, N> out{};
    std::size_t i{0};
    for (auto arg : std::meta::template_arguments_of(Type)) {
        if (i == N)
            break;
        out[i++] = arg;
    }
    return out;
}

consteval bool is_expected_specialization(std::meta::info type) {
    return std::meta::has_template_arguments(type) &&
           std::meta::template_of(type) == ^^std::expected;
}

consteval std::meta::info expected_value_arg(std::meta::info type) {
    return std::meta::template_arguments_of(type)[0];
}

consteval bool is_span_specialization(std::meta::info type) {
    return std::meta::has_template_arguments(type) &&
           std::meta::template_of(type) == ^^std::span;
}

consteval std::meta::info span_element_arg(std::meta::info type) {
    return std::meta::template_arguments_of(type)[0];
}

template <caster_oracle B, lang L, class Reg, auto Args, std::size_t... I>
consteval bool args_bindable(std::index_sequence<I...>) {
    return (bindable<B, typename [:Args[I]:], L, Reg>() && ...);
}

template <caster_oracle B, class T, lang L, class Reg>
consteval bool bindable() {
    // Strip cv/ref/pointer so the STL-wrapper table below sees the bare
    // specialization (a parameter may arrive as `const std::vector<Foo>&`).
    // dealias because remove_* are alias templates: their reflection is an alias
    // carrying neither template arguments nor annotations — the underlying type
    // does. remove_cvref handles the ref+cv combo, then remove_pointer, then a
    // final remove_cv for a pointee's constness (`const Foo*` -> `Foo`).
    constexpr std::meta::info u{std::meta::dealias(
        ^^std::remove_cv_t<std::remove_pointer_t<std::remove_cvref_t<T>>>)};
    if constexpr (welder::trust_bindable<typename [:u:]>) {
        // Type-level escape hatch: the user vouches this type is registered /
        // convertible outside welder's view. Checked first, and on every recursion
        // level, so trusting `Foo` also clears `Foo*`, `const Foo&` and
        // `std::vector<Foo>` (whose element recurses back to a trusted `Foo`).
        return true;
    } else {
        constexpr long values{wrapper_value_count(u)};
        if constexpr (values >= 0) {
            constexpr auto args{leading_args<u, static_cast<std::size_t>(values)>()};
            return args_bindable<B, L, Reg, args>(
                std::make_index_sequence<args.size()>{});
        } else if constexpr (B::template has_native_caster<typename [:u:]>) {
            return true;
        } else if constexpr (is_expected_specialization(u)) {
            // A rod that maps the error branch onto the target language's
            // exception channel never converts E at all, so only the VALUE
            // argument has to bind. Placed AFTER the native-caster check on
            // purpose: a rod whose framework converts the whole expected
            // wholesale — a hand-written pybind11/nanobind caster for a
            // project's `Result<T>` — still wins, so this widening cannot
            // change what the Python rods already accept.
            //
            // `std::expected<void, E>` carries no value at all: it is a pure
            // effect that can fail, so there is nothing to convert and it always
            // binds. (The gate never sees a bare `void` return — only this
            // wrapper can put one in a value position.)
            if constexpr (std::meta::dealias(expected_value_arg(u)) == ^^void)
                return true;
            else
                return bindable<B, typename [:expected_value_arg(u):], L, Reg>();
        } else if constexpr (is_span_specialization(u)) {
            // Element-wise, but checked here rather than from the table so a rod
            // whose framework casts the whole span keeps winning (see
            // is_span_specialization). Whether a span may appear in RETURN
            // position at all is the rod's call, not the gate's.
            return bindable<B, typename [:span_element_arg(u):], L, Reg>();
        } else if constexpr (std::meta::is_union_type(u)) {
            // Unions never bind — not even welded ones (no sweep registers
            // them; see assert_bindable's union diagnostic for why and for
            // the remedies). This branch sits AFTER the trust and
            // native-caster checks on purpose: a user who hand-registers a
            // union with the backend (pybind11/nanobind both allow it) can
            // still vouch for it via the trust hatches or a self-contained
            // caster.
            return false;
        } else {
            return Reg::counts_as_registered(u, L);
        }
    }
}

template <class T>
consteval bool mentions_union();

template <auto Args, std::size_t... I>
consteval bool args_mention_union(std::index_sequence<I...>) {
    return (mentions_union<typename [:Args[I]:]>() || ...);
}

template <class T>
consteval bool mentions_union() {
    constexpr std::meta::info u{std::meta::dealias(
        ^^std::remove_cv_t<std::remove_pointer_t<std::remove_cvref_t<T>>>)};
    if constexpr (std::meta::is_union_type(u)) {
        return true;
    } else {
        constexpr long values{wrapper_value_count(u)};
        if constexpr (values >= 0) {
            constexpr auto args{leading_args<u, static_cast<std::size_t>(values)>()};
            return args_mention_union<args>(
                std::make_index_sequence<args.size()>{});
        } else {
            return false;
        }
    }
}
 
} // namespace detail

template <caster_oracle B, class T, lang L, class Reg = welded_registration>
consteval bool bindable() {
    return detail::bindable<B, T, L, Reg>();
}

template <caster_oracle B, class T, lang L, class Reg = welded_registration>
consteval void assert_bindable() {
    constexpr bool ok{bindable<B, T, L, Reg>()};
    // Two mutually exclusive asserts so a union-caused failure names the real
    // remedy (std::variant) instead of the generic "weld it" — welding a
    // union is itself a hard error.
    static_assert(
        ok || !detail::mentions_union<T>(),
        "welder: this surface names a UNION, and unions do not bind — C++ has "
        "no way to observe which member is active, so generated accessors "
        "would read inactive members (undefined behavior). Use std::variant "
        "instead (converted natively by every rod), or expose safe accessor "
        "functions; otherwise mark::exclude the member that uses it. To "
        "hand-register the union with the backend yourself, vouch for it via "
        "welder::trust_bindable. The offending type is the template argument "
        "of this assert_bindable<B, T, L> instantiation.");
    static_assert(
        ok || detail::mentions_union<T>(),
        "welder: cannot bind this C++ type to the target language. Weld it with "
        "[[=welder::weld(...)]], or register a backend type converter for it; "
        "otherwise mark::exclude the member that uses it. The offending type is "
        "the template argument of this assert_bindable<B, T, L> instantiation.");
}
 
namespace detail {

template <caster_oracle B, std::meta::info Fn, lang L, class Reg, std::size_t... I>
consteval void assert_params_bindable(std::index_sequence<I...>) {
    static constexpr auto params{param_types<Fn>()};
    (assert_bindable<B, typename [:params[I]:], L, Reg>(), ...);
}
 
} // namespace detail

template <caster_oracle B, std::meta::info Fn, lang L,
          class Reg = welded_registration>
consteval void assert_signature_bindable() {
    // Guard n != 0: param_types<Fn> materializes a std::array<info, n>, and
    // std::array<info, 0>::operator[] is not consteval (it must not be
    // instantiated for a parameterless function).
    constexpr std::size_t n{std::meta::parameters_of(Fn).size()};
    if constexpr (n != 0)
        detail::assert_params_bindable<B, Fn, L, Reg>(std::make_index_sequence<n>{});
    if constexpr (!std::meta::is_constructor(Fn)) {
        using R = [:std::meta::return_type_of(Fn):];
        if constexpr (!std::is_void_v<R>)
            assert_bindable<B, R, L, Reg>();
    }
}
 
// --- member-aware asserts (honor the trust_bindable member mark) -------------
//
// The driver uses these at each emission site: they run the bindability gate on a
// member's type / a callable's signature *unless* the member carries a
// [[=welder::mark::trust_bindable]] mark for L, in which case the user has vouched
// for the type and the gate is skipped. (The type-level trust_bindable<T> point is
// folded into bindable() itself, above, so it needs no per-site handling.)

template <caster_oracle B, std::meta::info Member, lang L,
          class Reg = welded_registration>
consteval void assert_member_bindable() {
    if constexpr (!welder::trusted_for(Member, L))
        assert_bindable<B, typename [:std::meta::type_of(Member):], L, Reg>();
}

template <caster_oracle B, std::meta::info Fn, lang L,
          class Reg = welded_registration>
consteval void assert_callable_bindable() {
    if constexpr (!welder::trusted_for(Fn, L))
        assert_signature_bindable<B, Fn, L, Reg>();
}

template <caster_oracle B, std::meta::info Fn, lang L,
          class Reg = welded_registration>
consteval void assert_setter_bindable() {
    if constexpr (!welder::trusted_for(Fn, L)) {
        constexpr std::size_t n{std::meta::parameters_of(Fn).size()};
        if constexpr (n != 0)
            detail::assert_params_bindable<B, Fn, L, Reg>(
                std::make_index_sequence<n>{});
    }
}
 
namespace detail {

template <caster_oracle B, std::meta::info Fn, std::meta::info Type, lang L,
          class Reg, std::size_t... I>
consteval void assert_operands(std::index_sequence<I...>) {
    static constexpr auto params{param_types<Fn>()};
    (
        [] {
            if constexpr (std::meta::dealias(std::meta::remove_cvref(
                              params[I])) != std::meta::dealias(Type))
                assert_bindable<B, typename [:params[I]:], L, Reg>();
        }(),
        ...);
}
 
} // namespace detail

template <caster_oracle B, std::meta::info Fn, std::meta::info Type, lang L,
          class Reg = welded_registration>
consteval void assert_operands_bindable() {
    if constexpr (!welder::trusted_for(Fn, L)) {
        constexpr std::size_t n{std::meta::parameters_of(Fn).size()};
        if constexpr (n != 0)
            detail::assert_operands<B, Fn, Type, L, Reg>(
                std::make_index_sequence<n>{});
    }
}
 
} // namespace welder