MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
RecordBinding.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "TextBinding.hpp"
4
5namespace MayaFlux::Reflect {
6
7/**
8 * @brief How a record binding reads one source element of a document tree.
9 *
10 * Specialize for each source type. A specialization provides:
11 * name(source), location(source) as a diagnostic position,
12 * attribute(source, name) returning optional text,
13 * for_each_attribute(source, visit) with visit(name, text), and
14 * for_each_child(source, visit) with visit(child). Visitors return false to stop.
15 */
16template <typename Source>
18
19/**
20 * @class RecordBinding
21 * @brief Bind described attributes and configured child collections of a source element.
22 *
23 * Attributes overlay onto the described Input by member name. Required
24 * attributes, ignored attributes and repeated children with shared defaults
25 * are configured on the binding. Any source with a RecordAccess specialization
26 * can be bound.
27 */
28template <Described Input, typename Source,
29 typename Access = RecordAccess<Source>>
31public:
32 RecordBinding& required(std::string name)
33 {
34 m_required.push_back(std::move(name));
35 return *this;
36 }
37
38 /**
39 * @brief Leave these attributes to other readers of the same element.
40 *
41 * Listed names are neither decoded nor rejected. Described members still
42 * decode strictly, so do not list one.
43 */
44 RecordBinding& ignore(std::initializer_list<std::string_view> names)
45 {
46 for (const auto name : names)
47 m_ignored.emplace_back(name);
48 return *this;
49 }
50
51 /**
52 * @brief Leave every attribute whose name begins with a prefix to other readers.
53 *
54 * Like ignore, a matching attribute is neither decoded nor rejected, so a
55 * reader can own a whole family of names without listing each one.
56 */
57 RecordBinding& ignore_prefix(std::string prefix)
58 {
59 m_ignored_prefixes.push_back(std::move(prefix));
60 return *this;
61 }
62
63 /**
64 * @brief Leave every child element of this name to another reader.
65 *
66 * Children that no repeated collection and no ignore names are rejected, so
67 * a reader that shares an element with another one lists the other's
68 * children here.
69 */
70 RecordBinding& ignore_child(std::string child_name)
71 {
72 m_ignored_children.push_back(std::move(child_name));
73 return *this;
74 }
75
76 template <auto Pointer>
77 RecordBinding& repeated(std::string child_name,
78 std::string defaults_name = {},
79 std::string required_item_attribute = {},
80 size_t minimum = 0)
81 {
82 using Values = std::remove_cvref_t<decltype(std::declval<Input&>().*Pointer)>;
83 using Item = typename Values::value_type;
84 static_assert(std::same_as<Values, std::vector<Item>>);
85 static_assert(Described<Item>);
86
87 ChildBinding binding;
88 binding.name = std::move(child_name);
89 binding.defaults_name = std::move(defaults_name);
90 binding.decode = [name = binding.name, defaults_name = binding.defaults_name,
91 required_item_attribute = std::move(required_item_attribute), minimum](
92 Input& input, const Source& source, std::string& error,
93 uint64_t* error_location) {
94 Item defaults {};
95 bool defaults_seen = false;
96 size_t count = 0;
97 auto& values = input.*Pointer;
98 const bool traversed = Access::for_each_child(source, [&](const Source& child) {
99 if (error_location)
100 *error_location = Access::location(child);
101
102 const auto child_name = Access::name(child);
103 if (!defaults_name.empty() && child_name == defaults_name) {
104 if (defaults_seen || count != 0) {
105 error = "<" + defaults_name + "> must appear once before the "
106 + name + " children";
107 return false;
108 }
109 defaults_seen = true;
110 if (!required_item_attribute.empty()
111 && Access::attribute(child, required_item_attribute)) {
112 error = "<" + defaults_name + "> has an unsupported attribute "
113 + required_item_attribute;
114 return false;
115 }
116 if (has_children(child)) {
117 error = "<" + defaults_name + "> may not have children";
118 return false;
119 }
120 return overlay(defaults, child, error);
121 }
122 if (child_name != name)
123 return true;
124 if (!required_item_attribute.empty()
125 && !Access::attribute(child, required_item_attribute)) {
126 error = "<" + label(child) + "> needs a "
127 + required_item_attribute + " attribute";
128 return false;
129 }
130 if (has_children(child)) {
131 error = "<" + name + "> may not have children";
132 return false;
133 }
134 Item item = defaults;
135 if (!overlay(item, child, error))
136 return false;
137 values.push_back(std::move(item));
138 ++count;
139 return true;
140 });
141 if (!traversed)
142 return false;
143 if (count < minimum) {
144 if (error_location)
145 *error_location = Access::location(source);
146 error = "<" + std::string(Access::name(source)) + "> needs at least "
147 + std::to_string(minimum) + " " + name + " children";
148 return false;
149 }
150 return true;
151 };
152 m_children.push_back(std::move(binding));
153 return *this;
154 }
155
156 /**
157 * @brief Decode the source element into a new Input.
158 * @param error_location Receives the position of the failing element when given.
159 */
160 [[nodiscard]] std::optional<Input> read(const Source& source,
161 std::string& error, uint64_t* error_location = nullptr) const
162 {
163 if (error_location)
164 *error_location = Access::location(source);
165 for (const auto& name : m_required) {
166 if (!Access::attribute(source, name)) {
167 error = "<" + label(source) + "> needs a " + name + " attribute";
168 return std::nullopt;
169 }
170 }
171
172 Input input {};
173 const bool overlaid = overlay_text_fields(input,
174 [&](const auto& visit) {
175 return Access::for_each_attribute(source,
176 [&](std::string_view name, std::string_view value) {
177 return is_ignored(name) || visit(name, value);
178 });
179 }, label(source), error);
180 if (!overlaid)
181 return std::nullopt;
182 const bool known_children = Access::for_each_child(source, [&](const Source& child) {
183 const auto child_name = Access::name(child);
184 const bool known = std::ranges::find(m_ignored_children, child_name) != m_ignored_children.end()
185 || std::ranges::any_of(m_children, [&](const ChildBinding& binding) {
186 return child_name == binding.name
187 || (!binding.defaults_name.empty() && child_name == binding.defaults_name);
188 });
189 if (known)
190 return true;
191 if (error_location)
192 *error_location = Access::location(child);
193 error = "<" + std::string(child_name) + "> is not allowed in <"
194 + std::string(Access::name(source)) + ">";
195 return false;
196 });
197 if (!known_children)
198 return std::nullopt;
199 for (const ChildBinding& binding : m_children) {
200 if (!binding.decode(input, source, error, error_location))
201 return std::nullopt;
202 }
203 return input;
204 }
205
206private:
207 template <Described T>
208 static bool overlay(T& target, const Source& source, std::string& error)
209 {
210 return overlay_text_fields(target,
211 [&](const auto& visit) {
212 return Access::for_each_attribute(source, visit);
213 }, label(source), error);
214 }
215
216 static std::string label(const Source& source)
217 {
218 const auto id = Access::attribute(source, "id");
219 return id ? std::string(*id) : std::string(Access::name(source));
220 }
221
222 static bool has_children(const Source& source)
223 {
224 bool found = false;
225 Access::for_each_child(source, [&](const Source&) {
226 found = true;
227 return false;
228 });
229 return found;
230 }
231
233 std::string name;
234 std::string defaults_name;
235 std::function<bool(Input&, const Source&, std::string&, uint64_t*)> decode;
236 };
237
238 [[nodiscard]] bool is_ignored(std::string_view name) const
239 {
240 return std::ranges::find(m_ignored, name) != m_ignored.end()
241 || std::ranges::any_of(m_ignored_prefixes, [name](const std::string& prefix) {
242 return name.starts_with(prefix);
243 });
244 }
245
246 std::vector<std::string> m_required;
247 std::vector<std::string> m_ignored;
248 std::vector<std::string> m_ignored_prefixes;
249 std::vector<std::string> m_ignored_children;
250 std::vector<ChildBinding> m_children;
251};
252
253}
RecordBinding & ignore(std::initializer_list< std::string_view > names)
Leave these attributes to other readers of the same element.
bool is_ignored(std::string_view name) const
static std::string label(const Source &source)
RecordBinding & repeated(std::string child_name, std::string defaults_name={}, std::string required_item_attribute={}, size_t minimum=0)
std::vector< std::string > m_ignored_children
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.
std::vector< std::string > m_required
std::vector< std::string > m_ignored_prefixes
RecordBinding & required(std::string name)
static bool has_children(const Source &source)
static bool overlay(T &target, const Source &source, std::string &error)
std::vector< ChildBinding > m_children
std::vector< std::string > m_ignored
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
void error(Component component, Context context, std::source_location location, std::string_view message)
Log an error message and optionally throw an exception.
std::vector< double > count(std::span< const double > data, size_t n_windows, uint32_t hop_size, uint32_t window_size)
Sample count per window (as double for pipeline uniformity).
Definition Analysis.cpp:506
bool overlay_text_fields(T &target, Fields &&fields, std::string_view label, std::string &error)
Overlay named text values onto a described value.
How a record binding reads one source element of a document tree.
std::function< bool(Input &, const Source &, std::string &, uint64_t *)> decode