Stoic 0.4.1

Stoic 0.4.1 lets a typed schema describe a settings file people edit by hand, with nothing lost on the next write. Lodestar's config now runs on it.

Everything here is additive. 0.4.0 code builds unchanged.

Schema (design/06, "As built: files people edit")

• Clamping. clampingToRange() on a double or integer schema with an inclusive .range brings an out-of-range number to the nearest bound and reports it as a warning ("99999 is out of range, expected a number between 200 and 4000; clamped to 4000").

• Lossy dictionaries. Schema.lossyDictionary(of:valueDoc:) drops each bad entry on its own, with a dropped_entry warning at that entry's path, and keeps the good ones. A settings store writes the dropped entries back on every write, so a typo in one entry is never erased by an unrelated change.

• Documentation. documented(_:) and valueDoc: describe any schema or a dictionary's values in the JSON Schema export.

• Null sections. readingNullAsEmpty() reads a null object as all its defaults, silently, and the null is not written back.

• Normalization. normalizing(_:retired:) is an unversioned, idempotent rewrite of the raw document, applied on every read before decoding:

  • a rename where the new key wins, move, delete and setIfAbsent;
  • an enum remap;
  • custom operations;
  • retired keys, which are skipped on read and never carried on write.

  Nodes it does not touch keep their exact positions.

• JSON Schema export. JSONSchemaOptions adds Draft-07 output and closed objects (additionalProperties: false) whatever the unknown-key policy, plus extra root properties for a file's header keys (SettingsFileHeader.jsonSchemaProperties). Schema.json(jsonSchema:) lets a free-form field carry a fragment of its own into the export. The default options write exactly the 0.4.0 document.

• Messages.

  • .string(.oneOf(...)) suggests the closest choices, as .enumeration does.
  • A repair no longer spells out a composite default.
  • Issue.message includes the repair on warnings too.