Decodal/doc/manual/source/language/materialization-and-errors.md

Materialization and Errors

A normal evaluation result may retain constraints, default values, functions, and other abstract values. Materialization converts an evaluation result into concrete data that can be passed outside Decodal.

Materialization rules

Materialization performs the following work:

• Evaluate required fields.
• Apply default to abstract ranges that have no explicit value.
• Verify that concrete values and selected defaults satisfy their constraints.
• Reject Unknown and other unresolved ranges without a default.
• Reject unapplied functions and other values that cannot be represented as data.

Service = {
    host = String;
    port = Int default 8080;
};

Materializing Service directly fails because host has neither a concrete value nor a default.

Config = {
    host = "localhost";
} as Service;

Materializing Config produces the following data:

{
    host = "localhost";
    port = 8080;
}

A default is not selected for a field that has an explicit value.

Diagnostics

Errors are returned as diagnostics, not ordinary values. Expressions cannot branch on a diagnostic's kind or contents.

Representative diagnostics include:

• Syntax errors
• Unresolved identifiers or fields
• Type mismatches and constraint violations
• Conflicts in & or default
• Dependency cycles
• Import failures
• Match failures
• Materialization failures

A diagnostic identifies the relevant DCDL source span. When several expressions conflict, it also points to the related fields, constraints, values, and defaults. If a structured import value has no source span, the diagnostic identifies the stable key supplied by the host and the logical value path.

Fallback

A match with no matching arm and no fallback arm produces a diagnostic.

match value {
    >= 10: "large";
}

Decodal does not provide general-purpose try / catch, optional imports, or optional field access for catching diagnostics. Use default for a missing-value fallback and match for branching over a finite set of values.