0046 - Reading a field of a reflected object goes through one door
Status: accepted
Context
Every reader of the model that walks a &dyn Reflect asks the same few
questions: what text does this field hold, which number, is the flag set, which
nested object, which objects of a repeated field. About forty private functions
answered them, one set per module (text, scalar_f64, flag, objects,
field_object, string_of, number_of…), in energyml-geometry,
energyml-domain, energyml-storage and energyml-build.
The copies did not agree, and the same field therefore read differently depending on which check looked at it:
- a blank string: kept by one copy, dropped by another when empty, by a third when only whitespace;
- a fractional double asked for as an integer: truncated by some, refused by others;
- a string asked for as a number: parsed by one copy, refused by the rest;
- a field of the wrong shape: sometimes
None, sometimes a default.
Decision
- One module,
energyml_core::reflect::fields. It has no native dependency (it builds forwasm32). The private copies are deleted; where a module kept a local name for readability it re-imports the door’s function under that name, never a second implementation. - The policy is stated once, in the module’s documentation:
- absent (no such field, unset, undeclared name) is
None, or an emptyVecfor the plural readers; never zero,falseor the empty string; - a blank string (empty or whitespace only) is absent for the single
textreader; the plural readers keep every element, because in a list the position is the information; - a field of the wrong shape is
None: the strict readers never parse a string as a number, and a double is an integer only when it is finite, whole and in range; - reading a number out of text is a named variant (
number_lexical,integer_lexical,flag_lexical), asked for only where a schema version keeps the value as text; - a caller that must refuse says so: the
require_*readers return a named error,MissingRequiredfor an absent field andTypeMismatchfor a field of another shape, instead of the caller inventing a default.
- absent (no such field, unset, undeclared name) is
- The reflection walks of
identity.rsshare one traversal.collect_refs,nested_objectsandcollect_refs_by_ownerare visitors of a singlewalk(references, kept-verbatim subtrees, entered objects). The dotted path is one buffer, pushed and truncated, not aformat!per field. - An error that names a type borrows it. The geometry readers passed
Box::leaked copies of&'static strtype names to their errors; the names are already'staticand are passed as they are.
Consequences
- A change of policy (what a blank means, what an integer is) is made in one place and applies to every reader.
- A reader that wants the old lenient behaviour on a field kept as text asks for the lexical variant by name; it does not get it by accident.
- Behaviour that changed where the copies disagreed:
textnow drops a blank string in every reader (it used to be kept byintegrity,property,valuesand the geometrywell/parentreaders), and returns the wire text of a non-string scalar in every reader (the geometry andvaluesreaders were string-only);- an integer read from a fractional double is now
None(it was truncated by the geometry,valuesandcrsreaders); a whole double still reads; propertyno longer truncates a non-negative fractional double to a count.
- A new reader of the model does not write a helper: it imports the door.