Module Json

A materialized JSON value.

Notes:

• .number uses Float.
• Encoding .number(Float.NaN), .number(Float.Inf), or .number(Float.NegInf) produces JSON null.
• Object keys are normalized through BoxMap.Readonly, so duplicate source keys and original key order are not preserved.

Human-readable JSON parse/decode errors.

A reusable parser from a materialized Json value into a typed value.

A Format<a> exposes a single .parse operation that returns .ok value on success or .err! on mismatch.

A reusable parser specialized to JSON objects.

Use Json.Object(...) to lift an ObjectFormat<a> into a full Format<a>.

Runs two object formats against the same object and returns both results.

The result shape is (right) left, so Json.Field("age", Json.Number)->Json.And(Json.Field("name", Json.String)) returns (String) Float.

Both object formats return non-linear values because either side may need to be discarded if the other side fails.

Parses a JSON boolean.

Decodes JSON text into a materialized Json value.

Parses an empty object. Ignores any fields, does not fail if fields are present.

Encodes a Json value into compact JSON text.

Tests two Json values for structural equality.

Object key order does not matter, because objects are normalized through BoxMap.Readonly.

Parses a required object field with the given format.

For example, Json.Field("name", Json.String) accepts an object whose "name" field is a JSON string.

Parses a JSON array with the given item format.

The item type must be non-linear because earlier parsed items may need to be discarded if a later item fails to parse.

Matches exactly one JSON value.

Applies a pure mapping function to a successful parse result.

Use Json.Map when parsing cannot fail once the underlying format succeeds. Use Json.Then for fallible post-processing.

Matches JSON null.

Parses a JSON number.

Parses a JSON object with the given object format.

Parses an optional object field with the given format.

Missing fields produce .ok .none!. Present fields must parse successfully.

Accepts JSON null as .ok .none!, otherwise parses with the given format and wraps the result in .some.

Parses a JSON string.

Parses tagged JSON objects by matching one field against literal JSON tags.

The first argument selects the field to inspect. Each branch provides a tag literal, an object format, and a mapper into the result type. Tags are compared with Json.Equals, so they may be strings, numbers, booleans, or null, not just strings.

type Command = either {
  .sleep Float,
  .say String,
}

def CommandFormat = Json.Tagged("operation", *(
  (.string "sleep", Json.Field("seconds", Json.Number)) box [seconds] .sleep seconds,
  (.string "say", Json.Field("message", Json.String)) box [message] .say message,
))

Applies a fallible post-processing step to a successful parse result.

The mapping function returns .ok value to accept the parsed result or .err! to reject it.

Tries multiple formats in order and returns the first successful result.

Each branch may parse to its own intermediate type before mapping into the shared result type.

type Answer = either {
  .yes!,
  .text String,
}

def AnswerFormat = Json.Union(*(
  (Json.Literal(.string "yes")) box [!] .yes!,
  (Json.String) box [text] .text text,
))