- 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.
- 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".
- Assemblers should invalidate themselves as soon as they become "finished".
- For maps and lists, that means the "Finish" methods.
- For maps and lists, that means the "Finish" methods.
- For all the other scalars, the "Assign*" method itself means finished.
- For all the other scalars, the "Assign*" method itself means finished.
...
@@ -22,8 +27,8 @@ overall rules
...
@@ -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).
- 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.
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,
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.
...
@@ -33,8 +38,9 @@ but the caller tries to continue anyway.
- assigning a key with 'AssembleKey':
- assigning a key with 'AssembleKey':
- in case of success: clearly 'AssembleValue' should be ready to use next.
- in case of success: clearly 'AssembleValue' should be ready to use next.
- in case of failure from repeated key:
- in case of failure from repeated key:
- the error must be returned immediately from either the 'NodeAssembler.AssignString' or the 'MapAssembler.Finish' method.
- the error must be returned immediately from either the 'NodeAssembler.AssignString' or the 'MapNodeAssembler.Finish' method.
- note that this implies the `NodeAssembler` returned by `AssembleKey` has some way to refer to the map assembler that spawned it.
- '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.
- 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.)
- (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!)
- (remember to reset any internal flag for expecting 'AssembleValue' to be used next, and decrement any length pointers that were optimistically incremented!)
