MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
FactoryTable.hpp
Go to the documentation of this file.
1#pragma once
2
8
10
11/**
12 * @brief Attribute names a document owns on an instance.
13 *
14 * A table skips the two names and every attribute beginning with the prefix
15 * when it decodes a placement, so a factory never lists them. The driver
16 * reads the prefixed attributes itself.
17 */
18inline constexpr std::string_view reserved_id_attribute { "id" };
19inline constexpr std::string_view reserved_template_attribute { "template" };
20inline constexpr std::string_view reserved_prefix { "mf:" };
21
22/**
23 * @brief The child element of an instance that attaches an action to an event.
24 *
25 * A table skips it when it decodes a placement. The driver reads it.
26 */
27inline constexpr std::string_view reserved_action_element { "on" };
28
29/**
30 * @class FactoryTable
31 * @brief Named factories that turn a template's factory element and an instance into placed Forma elements, as a plain value.
32 *
33 * A table is a plain value. It holds only what its builder registers, and
34 * nothing is pre-registered or privileged: a host, a library or a user each
35 * build their own and combine them with merge(). A factory is a
36 * preparation that decodes everything and returns a Placer, so a document can
37 * be checked completely before anything is placed.
38 *
39 * Source is any element type with a Reflect::RecordAccess specialization and
40 * value semantics, so the same table serves XML, a script or any other
41 * document tree.
42 *
43 * Two ways to register:
44 * - expose_typed: described input and placement types. The factory also gets
45 * a bulk path that decodes its inputs once and makes one element per row of
46 * typed placements.
47 * - expose_placement: any placement at all, with any number of elements,
48 * composed primitives or bindings, onto the Surface it is given.
49 *
50 * Errors name the row of the failing element.
51 *
52 * Usage:
53 * @code
54 * FactoryTable<IO::XmlElementView> mine;
55 * mine.expose_typed<float>("dial", dial_input, dial_placement, make_dial, dial_initial);
56 * FactoryTable<IO::XmlElementView> shared;
57 * std::string error;
58 * shared.merge(mine, "studio.", error);
59 * @endcode
60 */
61template <typename Source, typename Access = Reflect::RecordAccess<Source>>
63public:
64 /**
65 * @brief Places one prepared element, or several, onto a Surface.
66 *
67 * May be run more than once. Returns the id of the element the instance is
68 * anchored on, or nullopt with an error. A placement of several elements
69 * returns the one the others belong with.
70 */
71 using Placer = std::function<std::optional<uint32_t>(Surface&, std::string&)>;
72
73 /** @brief Decodes a factory element and an instance into a Placer, or nullopt with an error. */
74 using Instantiator = std::function<std::optional<Placer>(
75 const Source&, const Source&, std::string&)>;
76
77 /** @brief Decodes a factory element and typed placement rows into one Placer per row. */
78 using BulkInstantiator = std::function<std::optional<std::vector<Placer>>(
79 const Source&, const Kakshya::CompositeArray&, std::string&)>;
80
81 /**
82 * @brief Register a whole placement.
83 *
84 * The Instantiator returns a Placer that receives the Surface. It may place
85 * any number of elements, run composed primitives, or create bindings.
86 * Registering an existing name replaces it.
87 */
88 void expose_placement(std::string name, Instantiator instantiator)
89 {
90 m_bulk.erase(name);
91 m_factories.insert_or_assign(name, std::move(instantiator));
92 }
93
94 /**
95 * @brief Expose a factory whose inputs and placement are described types.
96 *
97 * The inputs are read from the factory element and the placement from the
98 * instance, both strictly through their described members. The document's own
99 * attribute names are skipped on the placement. Initial state and the
100 * post-placement hook receive the decoded values, so one factory serves a
101 * single instance and a bulk placement alike.
102 *
103 * @param input Binding for the factory element.
104 * @param placement Binding for the instance.
105 * @param factory Callable (const Input&, const Placement&, error) returning
106 * std::optional of Geometry::Form of T.
107 * @param initial Callable (const Input&, const Placement&, error) returning
108 * std::optional of T, or a pointer to a member of Input or Placement whose
109 * value is the initial state.
110 * @param placed Optional hook called with the decoded values and the placed Tend.
111 */
112 template <typename T, Reflect::Described Input, Reflect::Described Placement,
113 typename Factory, typename Initial>
114 void expose_typed(std::string name,
117 Factory factory, Initial initial,
118 std::type_identity_t<std::function<void(const Input&, const Placement&, Tend<T>&)>> placed = {})
119 {
121 placement.ignore_prefix(std::string(reserved_prefix));
122 placement.ignore_child(std::string(reserved_action_element));
123
124 using Maker = std::function<std::optional<Placer>(
125 const Input&, const Placement&, std::string&)>;
126
127 Maker maker = [factory = std::move(factory), initial = std::move(initial),
128 placed = std::move(placed)](
129 const Input& decoded_input, const Placement& decoded_placement,
130 std::string& error) -> std::optional<Placer> {
131 auto geometry = std::invoke(factory, decoded_input, decoded_placement, error);
132 if (!geometry) {
133 if (error.empty())
134 error = "could not create the geometry";
135 return std::nullopt;
136 }
137 std::optional<T> value;
138 if constexpr (std::is_member_object_pointer_v<Initial>) {
139 if constexpr (std::is_invocable_v<Initial, const Input&>)
140 value = static_cast<T>(std::invoke(initial, decoded_input));
141 else
142 value = static_cast<T>(std::invoke(initial, decoded_placement));
143 } else {
144 value = std::invoke(initial, decoded_input, decoded_placement, error);
145 }
146 if (!value) {
147 if (error.empty())
148 error = "could not create the initial state";
149 return std::nullopt;
150 }
151 std::function<void(Tend<T>&)> after;
152 if (placed) {
153 after = [placed, decoded_input, decoded_placement](Tend<T>& tend) {
154 placed(decoded_input, decoded_placement, tend);
155 };
156 }
157 return make_placer<T>(std::move(*geometry), std::move(*value), std::move(after));
158 };
159
160 Instantiator single = [input, placement, maker](
161 const Source& factory_element, const Source& instance,
162 std::string& error) -> std::optional<Placer> {
163 uint64_t where {};
164 const auto decoded_input = input.read(factory_element, error, &where);
165 if (!decoded_input) {
166 error = located(where, error);
167 return std::nullopt;
168 }
169 const auto decoded_placement = placement.read(instance, error, &where);
170 if (!decoded_placement) {
171 error = located(where, error);
172 return std::nullopt;
173 }
174 auto placer = maker(*decoded_input, *decoded_placement, error);
175 if (!placer)
176 error = located(Access::location(instance), error);
177 return placer;
178 };
179
180 BulkInstantiator bulk = [input, maker](
181 const Source& factory_element, const Kakshya::CompositeArray& rows,
182 std::string& error) -> std::optional<std::vector<Placer>> {
183 uint64_t where {};
184 const auto decoded_input = input.read(factory_element, error, &where);
185 if (!decoded_input) {
186 error = located(where, error);
187 return std::nullopt;
188 }
189 const auto placements = IO::records_of<Placement>(rows, error);
190 if (!placements) {
191 error = located(Access::location(factory_element), error);
192 return std::nullopt;
193 }
194
195 std::vector<Placer> placers;
196 placers.reserve(placements->size());
197 for (const Placement& decoded_placement : *placements) {
198 auto placer = maker(*decoded_input, decoded_placement, error);
199 if (!placer) {
200 error = located(Access::location(factory_element), error);
201 return std::nullopt;
202 }
203 placers.push_back(std::move(*placer));
204 }
205 return placers;
206 };
207
208 m_factories.insert_or_assign(name, std::move(single));
209 m_bulk.insert_or_assign(name, std::move(bulk));
210 }
211
212 /**
213 * @brief Add every factory of another table under a name prefix.
214 * @param prefix Prepended to each name; empty keeps the names.
215 * @param error Receives the first colliding name when false is returned.
216 * @param replace True to overwrite existing names instead of failing.
217 * @return True on success. A failed merge leaves this table unchanged.
218 */
219 bool merge(const FactoryTable& other, std::string_view prefix,
220 std::string& error, bool replace = false)
221 {
222 if (!m_factories.merge_prefixed(other.m_factories, prefix, error, replace))
223 return false;
224 for (const auto& entry : other.m_factories) {
225 const std::string target = std::string(prefix) + entry.first;
226 const auto bulk = other.m_bulk.find(entry.first);
227 if (bulk != other.m_bulk.end()) {
228 m_bulk.insert_or_assign(target, bulk->second);
229 } else {
230 m_bulk.erase(target);
231 }
232 }
233 return true;
234 }
235
236 /** @brief Whether a factory of this name is registered. */
237 [[nodiscard]] bool contains(std::string_view name) const
238 {
239 return m_factories.find(name) != m_factories.end();
240 }
241
242 /** @brief Registered names in sorted order. */
243 [[nodiscard]] std::vector<std::string> names() const
244 {
245 std::vector<std::string> result;
246 for (const auto& entry : m_factories)
247 result.push_back(entry.first);
248 return result;
249 }
250
251 /** @brief The factory of this name, or nullptr. */
252 [[nodiscard]] const Instantiator* find(std::string_view name) const
253 {
254 const auto found = m_factories.find(name);
255 return found == m_factories.end() ? nullptr : &found->second;
256 }
257
258 /** @brief The bulk path of this name, or nullptr when it was not registered with expose_typed. */
259 [[nodiscard]] const BulkInstantiator* find_bulk(std::string_view name) const
260 {
261 const auto found = m_bulk.find(name);
262 return found == m_bulk.end() ? nullptr : &found->second;
263 }
264
265 /** @brief The message prefixed with the row it concerns. */
266 [[nodiscard]] static std::string located(uint64_t row, std::string_view message)
267 {
268 return Reflect::located_message(row, message);
269 }
270
271private:
272 template <typename T>
273 static Placer make_placer(Geometry::Form<T> form, T initial,
274 std::function<void(Tend<T>&)> after)
275 {
276 return [form = std::move(form), initial = std::move(initial),
277 after = std::move(after)](Surface& surface, std::string& error) -> std::optional<uint32_t> {
278 Tend<T> tend {
279 .form = form,
280 .initial = initial,
281 };
282 tend.place(surface);
283 if (!tend.result) {
284 error = "could not place the element";
285 return std::nullopt;
286 }
287 if (after)
288 after(tend);
289 return tend.result->element.id;
290 };
291 }
292
295};
296
297}
Illustrative geometry functions for common Mapped use cases.
Owns a sequence of values that share a CompositeLayout.
const_iterator end() const noexcept
Definition FlatMap.hpp:27
const_iterator find(const K &key) const
The entry for key, or end() when absent.
Definition FlatMap.hpp:32
Map kept as one sorted vector, cheap to copy.
Definition FlatMap.hpp:21
std::function< std::optional< std::vector< Placer > >( const Source &, const Kakshya::CompositeArray &, std::string &)> BulkInstantiator
Decodes a factory element and typed placement rows into one Placer per row.
std::vector< std::string > names() const
Registered names in sorted order.
Memory::FlatMap< std::string, BulkInstantiator, std::less<> > m_bulk
void expose_placement(std::string name, Instantiator instantiator)
Register a whole placement.
const BulkInstantiator * find_bulk(std::string_view name) const
The bulk path of this name, or nullptr when it was not registered with expose_typed.
static std::string located(uint64_t row, std::string_view message)
The message prefixed with the row it concerns.
std::function< std::optional< Placer >( const Source &, const Source &, std::string &)> Instantiator
Decodes a factory element and an instance into a Placer, or nullopt with an error.
static Placer make_placer(Geometry::Form< T > form, T initial, std::function< void(Tend< T > &)> after)
std::function< std::optional< uint32_t >(Surface &, std::string &)> Placer
Places one prepared element, or several, onto a Surface.
bool merge(const FactoryTable &other, std::string_view prefix, std::string &error, bool replace=false)
Add every factory of another table under a name prefix.
bool contains(std::string_view name) const
Whether a factory of this name is registered.
const Instantiator * find(std::string_view name) const
The factory of this name, or nullptr.
void expose_typed(std::string name, Reflect::RecordBinding< Input, Source, Access > input, Reflect::RecordBinding< Placement, Source, Access > placement, Factory factory, Initial initial, std::type_identity_t< std::function< void(const Input &, const Placement &, Tend< T > &)> > placed={})
Expose a factory whose inputs and placement are described types.
Memory::FlatMap< std::string, Instantiator, std::less<> > m_factories
Named factories that turn a template's factory element and an instance into placed Forma elements,...
Named owner of a (Window, Layer, Context) triple: the Forma canvas.
Definition Surface.hpp:121
RecordBinding & ignore(std::initializer_list< std::string_view > names)
Leave these attributes to other readers of the same element.
std::optional< Input > read(const Source &source, std::string &error, uint64_t *error_location=nullptr) const
Decode the source element into a new Input.
RecordBinding & ignore_prefix(std::string prefix)
Leave every attribute whose name begins with a prefix to other readers.
RecordBinding & ignore_child(std::string child_name)
Leave every child element of this name to another reader.
Bind described attributes and configured child collections of a source element.
A type whose generated sidecar defines Generated::Description<T>::members().
Definition Describe.hpp:86
std::optional< std::vector< T > > records_of(const Kakshya::CompositeArray &rows, std::string &error)
Decode every row of a typed Composite array into values.
void error(Component component, Context context, std::source_location location, std::string_view message)
Log an error message and optionally throw an exception.
constexpr std::string_view reserved_action_element
The child element of an instance that attaches an action to an event.
constexpr std::string_view reserved_id_attribute
Attribute names a document owns on an instance.
constexpr std::string_view reserved_prefix
constexpr std::string_view reserved_template_attribute
std::string located_message(uint64_t location, std::string_view message)
A diagnostic message prefixed with the location of the element it concerns.
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