MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
CallTable.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "ElementHit.hpp"
4#include "FactoryTable.hpp"
5
7
8/**
9 * @brief Attribute of a form element that names the function it calls.
10 *
11 * A call table reads it, the driver skips it, and the function's own
12 * parameter names are the element's other attributes.
13 */
14inline constexpr std::string_view reserved_call_attribute { "call" };
15
16/** @brief Attribute of an element that holds the initial value of its state. */
17inline constexpr std::string_view reserved_state_attribute { "state" };
18
19namespace Detail {
20
21 template <typename F>
23
24 template <typename R, typename... A>
25 struct FunctionTraits<R (*)(A...)> {
26 using Result = R;
27 using Values = std::tuple<std::remove_cvref_t<A>...>;
28 static constexpr size_t count = sizeof...(A);
29 };
30
31 template <typename R, typename... A>
32 struct FunctionTraits<R (*)(A...) noexcept> : FunctionTraits<R (*)(A...)> { };
33
34 template <typename R>
35 struct FormState;
36
37 template <typename T>
38 struct FormState<Geometry::Form<T>> {
39 using type = T;
40 };
41
42 /** A Placer that places a form with an initial state on a Surface and returns its element id. */
43 template <typename Placer, typename State>
44 Placer form_placer(Geometry::Form<State> form, State initial)
45 {
46 return Placer([form = std::move(form), initial = std::move(initial)](
47 Surface& surface, std::string& error) -> std::optional<uint32_t> {
48 Tend<State> tend {
49 .form = form,
50 .initial = initial,
51 };
52 tend.place(surface);
53 if (!tend.result) {
54 error = "could not place the element";
55 return std::nullopt;
56 }
57 return tend.result->element.id;
58 });
59 }
60
61 template <auto Function, typename Source, typename Access, size_t Index, typename Values>
62 bool decode_parameter(const Source& call, Values& values, std::array<bool, std::tuple_size_v<Values>>& given,
63 std::string& error)
64 {
66 using Parameter = std::tuple_element_t<Index, Values>;
67
68 const auto text = Access::attribute(call, Description::parameters[Index]);
69 if (!text)
70 return true;
73 if (!Reflect::TextCodec<Parameter>::decode(*text, std::get<Index>(values), reason)) {
74 error = Reflect::located_message(Access::location(call),
75 "<" + std::string(Access::name(call)) + "> has an invalid " + std::string(Description::parameters[Index])
76 + " of " + std::string(*text));
77 return false;
78 }
79 given[Index] = true;
80 return true;
81 } else {
82 error = Reflect::located_message(Access::location(call),
83 std::string(Description::parameters[Index]) + " of " + std::string(Description::name)
84 + " cannot be written in a document");
85 return false;
86 }
87 }
88
89 /**
90 * Calls a described function with the arguments an element's attributes give by parameter
91 * name. Arguments are the leading parameters, as in C++: a trailing run may be left to the
92 * function's own defaults, which the sidecar's call applies because it calls by name, and a
93 * later parameter cannot be given while an earlier one is skipped.
94 */
95 template <auto Function, typename Source, typename Access>
96 std::optional<typename FunctionTraits<decltype(Function)>::Result> call_described(
97 const Source& call, std::string& error)
98 {
99 using Traits = FunctionTraits<decltype(Function)>;
100 using Result = typename Traits::Result;
101 using Values = typename Traits::Values;
102 using Description = Reflect::Generated::Signature<Function>;
103 constexpr size_t count = Traits::count;
104 constexpr size_t required = Description::required;
105 static_assert(Description::parameters.size() == count, "the sidecar does not describe this function");
106
107 const bool known = Access::for_each_attribute(call, [&](std::string_view name, std::string_view) {
108 if (name == reserved_call_attribute
109 || std::ranges::find(Description::parameters, name) != Description::parameters.end()) {
110 return true;
111 }
112 error = Reflect::located_message(Access::location(call),
113 "<" + std::string(Access::name(call)) + "> has an unsupported attribute " + std::string(name)
114 + " for " + std::string(Description::name));
115 return false;
116 });
117 if (!known)
118 return std::nullopt;
119
120 Values values {};
121 std::array<bool, count> given {};
122 bool decoded = true;
123 [&]<size_t... I>(std::index_sequence<I...>) {
124 ((decoded = decoded && decode_parameter<Function, Source, Access, I>(call, values, given, error)), ...);
125 }(std::make_index_sequence<count> {});
126 if (!decoded)
127 return std::nullopt;
128
129 size_t provided = 0;
130 while (provided < count && given[provided])
131 ++provided;
132 for (size_t i = provided + 1; i < count; ++i) {
133 if (given[i]) {
134 error = Reflect::located_message(Access::location(call),
135 std::string(Description::parameters[i]) + " is given without "
136 + std::string(Description::parameters[provided]));
137 return std::nullopt;
138 }
139 }
140 if (provided < required) {
141 error = Reflect::located_message(Access::location(call),
142 std::string(Description::name) + " needs " + std::string(Description::parameters[provided]));
143 return std::nullopt;
144 }
145
146 std::optional<Result> result;
147 [&]<size_t... N>(std::index_sequence<N...>) {
148 ((provided == required + N
149 ? (result.emplace(Description::template call<required + N>(values)), true)
150 : false)
151 || ...);
152 }(std::make_index_sequence<count - required + 1> {});
153 return result;
154 }
155
156}
157
158/**
159 * @class CallTable
160 * @brief Functions a document calls by name, with the function's own parameter names as attributes.
161 *
162 * A plain value like every table here. Registering a function needs nothing written about it: its
163 * generated Signature sidecar (MF_DESCRIBE_FUNCTION) supplies the parameter names, its own type
164 * supplies their types, and each attribute is decoded with TextCodec. A form element names the
165 * function and gives its arguments, as C++ passes them:
166 *
167 * @code
168 * table.expose_form<&Geometry::horizontal_fader>();
169 * // <element name="volume" state="0.5">
170 * // <form call="horizontal_fader" bounds="-0.5 -0.1 0.5 0.1" handle_w="0.04"/>
171 * // </element>
172 * @endcode
173 *
174 * A function returning a Geometry::Form of T makes an element whose state is a T, written in
175 * the element's state attribute as TextCodec of T reads it, and a T{} when it is absent, as
176 * Tend does.
177 *
178 * @tparam Source Element type with a Reflect::RecordAccess specialization.
179 */
180template <typename Source, typename Access = Reflect::RecordAccess<Source>>
182public:
184
185 /**
186 * @brief Decodes a form element and the element holding it into a Placer, or nullopt with an error.
187 *
188 * The element supplies the state, and the form element its call and arguments. The hit is what
189 * the element's own spatial children say, written after the form's.
190 */
191 using Maker = std::function<std::optional<Placer>(
192 const Source&, const Source&, const ElementHit&, std::string&)>;
193
194 /**
195 * @brief Register a described function that returns a Geometry::Form.
196 * @tparam Function Pointer to the function, such as &Geometry::horizontal_fader.
197 * @param name The name a document calls it by, the function's own name when empty.
198 */
199 template <auto Function>
201 void expose_form(std::string name = {})
202 {
203 using Traits = Detail::FunctionTraits<decltype(Function)>;
205
206 if (name.empty()) {
207 const std::string_view full = Reflect::Generated::Signature<Function>::name;
208 name = std::string(full.substr(full.rfind("::") == std::string_view::npos ? 0 : full.rfind("::") + 2));
209 }
210
211 m_makers.insert_or_assign(std::move(name),
212 Maker([](const Source& call, const Source& element, const ElementHit& hit,
213 std::string& error) -> std::optional<Placer> {
215 if (!form)
216 return std::nullopt;
217
218 State initial {};
219 if (const auto text = Access::attribute(element, reserved_state_attribute)) {
221 if (!Reflect::TextCodec<State>::decode(*text, initial, reason)) {
222 error = Reflect::located_message(Access::location(element),
223 "<" + std::string(Access::name(element)) + "> has an invalid state of " + std::string(*text));
224 return std::nullopt;
225 }
226 }
227
228 apply_hit(*form, hit);
229 return Detail::form_placer<Placer, State>(std::move(*form), std::move(initial));
230 }));
231 }
232
233 /** @brief Add every call of another table under a name prefix. */
234 bool merge(const CallTable& other, std::string_view prefix, std::string& error, bool replace = false)
235 {
236 return m_makers.merge_prefixed(other.m_makers, prefix, error, replace);
237 }
238
239 [[nodiscard]] bool contains(std::string_view name) const
240 {
241 return m_makers.find(name) != m_makers.end();
242 }
243
244 /** @brief Registered names in sorted order. */
245 [[nodiscard]] std::vector<std::string> names() const
246 {
247 std::vector<std::string> result;
248 for (const auto& entry : m_makers)
249 result.push_back(entry.first);
250 return result;
251 }
252
253 /** @brief The maker of this name, or nullptr. */
254 [[nodiscard]] const Maker* find(std::string_view name) const
255 {
256 const auto found = m_makers.find(name);
257 return found == m_makers.end() ? nullptr : &found->second;
258 }
259
260private:
262};
263
264}
bool insert_or_assign(const K &key, V value)
Sets the value for key, adding the entry if it is absent.
Definition FlatMap.hpp:44
Map kept as one sorted vector, cheap to copy.
Definition FlatMap.hpp:21
const Maker * find(std::string_view name) const
The maker of this name, or nullptr.
bool contains(std::string_view name) const
void expose_form(std::string name={})
Register a described function that returns a Geometry::Form.
std::function< std::optional< Placer >( const Source &, const Source &, const ElementHit &, std::string &)> Maker
Decodes a form element and the element holding it into a Placer, or nullopt with an error.
bool merge(const CallTable &other, std::string_view prefix, std::string &error, bool replace=false)
Add every call of another table under a name prefix.
Memory::FlatMap< std::string, Maker, std::less<> > m_makers
typename FactoryTable< Source, Access >::Placer Placer
std::vector< std::string > names() const
Registered names in sorted order.
Functions a document calls by name, with the function's own parameter names as attributes.
std::function< std::optional< uint32_t >(Surface &, std::string &)> Placer
Places one prepared element, or several, onto a Surface.
Named owner of a (Window, Layer, Context) triple: the Forma canvas.
Definition Surface.hpp:121
A function pointer whose generated sidecar defines Generated::Signature<Function>.
Definition Describe.hpp:93
std::optional< typename FunctionTraits< decltype(Function)>::Result > call_described(const Source &call, std::string &error)
Calls a described function with the arguments an element's attributes give by parameter name.
Definition CallTable.hpp:96
Placer form_placer(Geometry::Form< State > form, State initial)
A Placer that places a form with an initial state on a Surface and returns its element id.
Definition CallTable.hpp:44
bool decode_parameter(const Source &call, Values &values, std::array< bool, std::tuple_size_v< Values > > &given, std::string &error)
Definition CallTable.hpp:62
constexpr std::string_view reserved_state_attribute
Attribute of an element that holds the initial value of its state.
Definition CallTable.hpp:17
constexpr std::string_view reserved_call_attribute
Attribute of a form element that names the function it calls.
Definition CallTable.hpp:14
void apply_hit(Geometry::Form< T > &form, const ElementHit &hit)
Write a document's spatial fields after a form's own.
std::string located_message(uint64_t location, std::string_view message)
A diagnostic message prefixed with the location of the element it concerns.
std::tuple< std::remove_cvref_t< A >... > Values
Definition CallTable.hpp:27
The spatial fields a document gives an element, as Element carries them.
A geometry function plus everything its realization requires.
Definition Geometry.hpp:83
Tend & place(Surface &target)
Realize form on target.
Definition Tend.hpp:244
std::optional< Mapped< T > > result
Populated by place(). The real, fully wired element.
Definition Tend.hpp:233
The fourth member of the Collapsible/Scrollable/TextField family, for a bare Form<T> control.
Definition Tend.hpp:220
The parameter names of a described function, which C++ cannot supply itself.
Definition Describe.hpp:52
Conversion of authored text to one value type.
Definition TextCodec.hpp:81