annotations.hpp

Go to the documentation of this file.

#pragma once
#include <welder/diag.hpp>
#include <welder/lang.hpp>

 
namespace welder::inline v0 {

using size_type = decltype(sizeof(0));
 
// The language identity scheme (lang.hpp: welder-shipped 0–15, user_lang
// 16–31) assumes the mask below spans 32 bits.
static_assert(sizeof(unsigned) >= 4,
              "welder's language mask needs a >= 32-bit unsigned");

consteval unsigned lang_bit(lang l) {
    if (static_cast<unsigned>(l) >= 8 * sizeof(unsigned))
        throw diag::lang_out_of_mask_range{};
    return 1u << static_cast<unsigned>(l);
}

template <class... Ls>
consteval unsigned lang_mask(Ls... ls) {
    return (0u | ... | lang_bit(ls));
}

enum class policy_kind : unsigned char {
    automatic, 
    opt_in,    
};

enum class rv_kind : unsigned char {
    automatic,           
    automatic_reference, 
    take_ownership,      
    copy,                
    move,                
    reference,           
    reference_internal,  
    none,                
};

namespace detail {
 
// --- weld: the type-level annotation declaring target languages -------------

struct weld_spec {
    unsigned mask = 0; 
};
 
// --- policy: how greedily members are reflected -----------------------------

struct policy_spec {
    policy_kind kind = policy_kind::automatic; 
};

struct weld_protected_spec {
    unsigned mask = 0; 

    template <class... Ls>
    consteval weld_protected_spec operator()(Ls... ls) const {
        return weld_protected_spec{lang_mask(ls...)};
    }
};
 
// --- mark: member-level include/exclude -------------------------------------

struct exclude_spec {
    unsigned mask = 0; 

    template <class... Ls>
    consteval exclude_spec operator()(Ls... ls) const {
        return exclude_spec{lang_mask(ls...)};
    }
};

struct include_spec {
    unsigned mask = 0; 

    template <class... Ls>
    consteval include_spec operator()(Ls... ls) const {
        return include_spec{lang_mask(ls...)};
    }
};

struct only_spec {
    unsigned mask = 0; 

    template <class... Ls>
    consteval only_spec operator()(lang first, Ls... rest) const {
        return only_spec{lang_mask(first, rest...)};
    }
};
 
// --- trust_bindable: vouch that a type is representable outside welder's view --

struct trust_bindable_spec {
    unsigned mask = 0; 

    template <class... Ls>
    consteval trust_bindable_spec operator()(Ls... ls) const {
        return trust_bindable_spec{lang_mask(ls...)};
    }
};
 
// --- doc: human-readable documentation --------------------------------------

template <size_type N>
struct fixed_string {
    char data[N]{}; 
    consteval fixed_string(const char (&s)[N]) {
        for (size_type i{0}; i < N; ++i)
            data[i] = s[i];
    }
};

template <size_type N>
struct doc_spec {
    fixed_string<N> text; 
};

template <size_type N>
struct return_doc_spec {
    fixed_string<N> text; 
};

template <size_type N, size_type M>
struct tparam_spec {
    fixed_string<N> name; 
    fixed_string<M> text; 
};
 
// --- weld_as: force an entity's target-language name verbatim ----------------

template <size_type N>
struct weld_as_spec {
    unsigned mask = 0;    
    fixed_string<N> name; 
};
 
// --- return_policy: how a returned object is owned/converted ------------------

struct return_policy_spec {
    unsigned mask = 0;                        
    rv_kind kind = rv_kind::automatic;        
};
 
// --- keep_alive: tie one argument's/return's lifetime to another's -----------

struct keep_alive_spec {
    unsigned nurse = 0;   
    unsigned patient = 0; 
};
 
} // namespace detail
 
// --- weld: the type-level annotation declaring target languages -------------

template <class... Ls>
consteval detail::weld_spec weld(Ls... ls) {
    return detail::weld_spec{lang_mask(ls...)};
}
 
// --- policy: how greedily members are reflected -----------------------------

namespace policy {
inline constexpr detail::policy_spec automatic{policy_kind::automatic}; 
inline constexpr detail::policy_spec opt_in{policy_kind::opt_in};       

inline constexpr detail::weld_protected_spec weld_protected{};
} // namespace policy
 
// --- mark: member-level include/exclude / trust_bindable --------------------

template <class T>
inline constexpr bool trust_bindable = false;

namespace mark {
inline constexpr detail::exclude_spec exclude{};               
inline constexpr detail::include_spec include{};               
inline constexpr detail::only_spec only{};                     
inline constexpr detail::trust_bindable_spec trust_bindable{}; 
} // namespace mark
 
// --- doc: human-readable documentation --------------------------------------

template <size_type N>
consteval detail::doc_spec<N> doc(const char (&s)[N]) {
    return detail::doc_spec<N>{detail::fixed_string<N>{s}};
}

template <size_type N>
consteval detail::return_doc_spec<N> returns(const char (&s)[N]) {
    return detail::return_doc_spec<N>{detail::fixed_string<N>{s}};
}

template <size_type N, size_type M>
consteval detail::tparam_spec<N, M> tparam(const char (&name)[N], const char (&text)[M]) {
    return detail::tparam_spec<N, M>{detail::fixed_string<N>{name}, detail::fixed_string<M>{text}};
}
 
// --- weld_as: force an entity's target-language name verbatim ----------------

template <size_type N>
consteval detail::weld_as_spec<N> weld_as(const char (&s)[N]) {
    return detail::weld_as_spec<N>{0u, detail::fixed_string<N>{s}};
}
 
namespace detail {
// The `weld_as(langs…, "name")` argument list is a run of `lang` markers followed
// by the verbatim name. A parameter pack cannot precede a deduced trailing string
// (the pack would not deduce), so `weld_as` takes one forwarding pack and these two
// helpers walk it: one ORs the leading markers, the other peels down to the name —
// binding the string by reference so its extent N survives (a by-value array decays
// to a pointer and loses its length). No std headers, so the vocabulary stays
// module-exportable.

consteval unsigned weld_as_mask() { return 0u; }
template <size_type N>
consteval unsigned weld_as_mask(const char (&)[N]) { return 0u; }
template <class... Rest>
consteval unsigned weld_as_mask(lang l, Rest&&... rest) {
    return lang_bit(l) | weld_as_mask(static_cast<Rest&&>(rest)...);
}

template <size_type N>
consteval fixed_string<N> weld_as_name(const char (&s)[N]) { return fixed_string<N>{s}; }
template <class... Rest>
consteval auto weld_as_name(lang, Rest&&... rest) {
    return weld_as_name(static_cast<Rest&&>(rest)...);
}
} // namespace detail

template <class... Args>
consteval auto weld_as(Args&&... args) {
    return detail::weld_as_spec{detail::weld_as_mask(static_cast<Args&&>(args)...),
                                detail::weld_as_name(static_cast<Args&&>(args)...)};
}
 
// --- return_policy: how a returned object is owned/converted ------------------

namespace rv {
inline constexpr rv_kind automatic{rv_kind::automatic};                     
inline constexpr rv_kind automatic_reference{rv_kind::automatic_reference}; 
inline constexpr rv_kind take_ownership{rv_kind::take_ownership};           
inline constexpr rv_kind copy{rv_kind::copy};                               
inline constexpr rv_kind move{rv_kind::move};                               
inline constexpr rv_kind reference{rv_kind::reference};                     
inline constexpr rv_kind reference_internal{rv_kind::reference_internal};   
inline constexpr rv_kind none{rv_kind::none};                               
} // namespace rv
 
namespace detail {
// The `return_policy(langs…, kind)` argument list is a run of `lang` markers
// followed by the trailing @ref rv_kind — mirroring `weld_as(langs…, "name")`.
// Two helpers walk the forwarding pack: one ORs the leading markers, the other
// peels down to the kind. No std headers, keeping the vocabulary module-safe.

consteval unsigned return_policy_mask(rv_kind) { return 0u; }
template <class... Rest>
consteval unsigned return_policy_mask(lang l, Rest... rest) {
    return lang_bit(l) | return_policy_mask(rest...);
}

consteval rv_kind return_policy_kind(rv_kind k) { return k; }
template <class... Rest>
consteval rv_kind return_policy_kind(lang, Rest... rest) {
    return return_policy_kind(rest...);
}
} // namespace detail

template <class... Args>
consteval detail::return_policy_spec return_policy(Args... args) {
    return detail::return_policy_spec{detail::return_policy_mask(args...),
                                      detail::return_policy_kind(args...)};
}
 
// --- keep_alive: tie one argument's/return's lifetime to another's -----------

consteval detail::keep_alive_spec keep_alive(unsigned nurse, unsigned patient) {
    return detail::keep_alive_spec{nurse, patient};
}
 
} // namespace welder