Dextrin.Schema.Reader (Dextrin v0.3.0)

Copy Markdown View Source

Which schema a decoded struct is read with, given the version it was written with and the versions loaded (DXN.md §4.8). Shared by the text and binary decoders, so both answer every case the same way.

  • No version, or the latest loaded: read with the latest, exactly.
  • Newer than anything loaded: read against the latest. Text matches fields by name; binary assumes positions are unchanged, drops the items beyond the reader's own and leaves missing optional fields absent. A newer version that reordered or removed fields is misread, without an error whenever the types agree -- the documented risk of reading forward.
  • Older and loaded: read with that version's own schema and handed to the materializer, which upgrades it. Without a materializer it is refused, schema/no-materializer: reading old data as if it were the latest would be a guess.
  • Older and not loaded: refused, schema/unknown-version, even with a materializer, which would receive no field names.

What is built from the fields (B4): the schema's materializer, when one is registered, is called for every struct of its schema, whatever the version, as materializer.(name, version, fields) -- version being the one the fields were read with, fields a map keyed by field-name string. It upgrades, builds the application's own value, refines and validates; its result is checked against the latest schema, and a refusal or a result the latest schema rejects is schema/materializer. Without a materializer the latest version comes back as a Dextrin.Struct at that version, its fields in the schema's order, which is written back exactly as it was read. Nested structs are built first, so a materializer sees its fields' structs finished.

Summary

Functions

fields of the struct name, written at version (nil when it says none), read against registry.

Functions

read(registry, name, version, fields, extra \\ [])

fields of the struct name, written at version (nil when it says none), read against registry.

Answers {:ok, value, registry}, {:unknown, registry} when name has no schema at all -- the struct stays opaque -- or {:error, error} with a Dextrin.Error carrying the DXN.md §5 category where there is one, or a message the caller wraps as a schema violation.