- That means an error like "repeated key in map" should be returned by the 'NodeAssembler.AssignString' or the 'MapAssembler.Finish' method.
- That means an error like "repeated key in map" should be returned by the key assembler!
- Either 'NodeAssembler.AssignString' should return this (for simple keys on untyped maps, or on structs, etc)...
- ... or 'MapNodeAssembler.Finish' (in the case of complex keys in a typed map).
- Logical integrity checks must be done locally -- recursive types rely on their contained types to report errors, and the recursive type wraps the assemblers of their contained type in order to check and correctly invalidate/rollback the recursive construction.
- Recursive types tend to have a value assembler that wraps the child type's assembler in order to intercept relevant "finish" methods.
- This is generally where that logic integrity check mentioned above is tracked; we need explicit confirmation that it *passes* before the parent's assembly should proceed.
- Implementations may also need this moment to complete any assignment of the child value into position in the parent value. But not all implementations need this -- some will have had all the child assembler effects applying directly to the final memory positions.
- Assemblers should invalidate themselves as soon as they become "finished".
- For maps and lists, that means the "Finish" methods.
- For all the other scalars, the "Assign*" method itself means finished.
...
...
@@ -22,8 +27,8 @@ overall rules
- When misuses of order are detected, these may cause panics (rather than error returns) (not all methods that can be so misused have error returns).
detailed rules and expectations
-------------------------------
detailed rules and expectations for implementers
------------------------------------------------
The expectations in the "happy path" are often clear.
Here are also collected some details of exactly what should happen when an error has been reached,
...
...
@@ -33,8 +38,9 @@ but the caller tries to continue anyway.
- assigning a key with 'AssembleKey':
- in case of success: clearly 'AssembleValue' should be ready to use next.
- in case of failure from repeated key:
- the error must be returned immediately from either the 'NodeAssembler.AssignString' or the 'MapAssembler.Finish' method.
- note that this implies the `NodeAssembler` returned by `AssembleKey` has some way to refer to the map assembler that spawned it.
- the error must be returned immediately from either the 'NodeAssembler.AssignString' or the 'MapNodeAssembler.Finish' method.
- 'AssignString' for any simple keys; 'MapNodeAssembler.Finish' may be relevant in the case of complex keys in a typed map.
- implementers take note: this implies the `NodeAssembler` returned by `AssembleKey` has some way to refer to the map assembler that spawned it.
- no side effect should be visible if 'AssembleKey' is called again next.
- (typically this doesn't require extra code for the string case, but it may require some active zeroing in the complex key case.)
- (remember to reset any internal flag for expecting 'AssembleValue' to be used next, and decrement any length pointers that were optimistically incremented!)
