74 lines
2.1 KiB
Markdown
74 lines
2.1 KiB
Markdown
# 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.
|
|
|
|
```dcdl
|
|
Service = {
|
|
host = String;
|
|
port = Int default 8080;
|
|
};
|
|
```
|
|
|
|
Materializing `Service` directly fails because `host` has neither a concrete value nor a `default`.
|
|
|
|
```dcdl
|
|
Config = {
|
|
host = "localhost";
|
|
} as Service;
|
|
```
|
|
|
|
Materializing `Config` produces the following data:
|
|
|
|
```dcdl
|
|
{
|
|
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.
|
|
|
|
```dcdl
|
|
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.
|