Refocus manual on public language usage

doc/manual/souce/language/materialization-and-errors.md

@@ -1,37 +1,34 @@
 # materialize とエラー
 
-通常の評価では、制約や default を含む中間値が残ることがある。
-外部へデータとして出力する段階では、materialize を行う。
+通常の評価結果には constraint、`default`、function などが残り得る。
+materialize は評価結果を外部へ渡せる concrete data に変換する。
 
-## materialize の責務
+## materialize の規則
 
-materialize は以下を行う。
+materialize は次の処理を行う。
 
-- 必要なフィールドを評価する。
-- 明示値がない abstract value に default を適用する。
-- 採用された値が制約を満たすか検証する。
-- default を持たない未解決の abstract value をエラーにする。
-- 未適用の関数など、データとして出力できない値をエラーにする。
-
-## 例
+- 必要な field を評価する。
+- 明示値のない abstract range に `default` を適用する。
+- concrete value と採用した `default` が constraint を満たすか検証する。
+- `default` のない `Unknown` や他の未解決 range を拒否する。
+- 未適用の function など、data に変換できない値を拒否する。
 
 ```dcdl
-MyConfig = {
+Service = {
     host = String;
     port = Int default 8080;
 };
 ```
 
-`MyConfig` を materialize すると、`host` は具体値も default もないためエラーになる。
-`port` は `8080` が採用される。
+`Service` をそのまま materialize すると、`host` に concrete value も `default` もないため失敗する。
 
 ```dcdl
-Config = MyConfig & {
+Config = {
     host = "localhost";
-};
+} as Service;
 ```
 
-`Config` を materialize すると以下になる。
+`Config` を materialize すると次の data になる。
 
 ```dcdl
 {
@@ -40,46 +37,31 @@ Config = MyConfig & {
 }
 ```
 
-## default の適用
+明示値がある field では `default` は採用されない。
 
-`default` は materialize 時にのみ fallback として採用される。
+## Diagnostics
 
-```text
-Abstract {
-  constraints: [Int]
-  default: 8080
-}
-```
+エラーは通常の値ではなく diagnostic として返される。
+式は diagnostic の種類や内容に基づいて分岐できない。
 
-この abstract value を materialize すると、`8080` が採用され、`Int` を満たすか検証される。
+代表的な diagnostic は次の通りである。
 
-明示値がある場合、default は採用しない。
-明示値は concrete value として表現され、default を保持しない。
+- syntax error
+- unresolved identifier または field
+- type mismatch と constraint violation
+- `&` または `default` の conflict
+- cycle dependency
+- import failure
+- match failure
+- materialization failure
 
-```text
-Concrete(Int(9000))
-```
+diagnostic は問題のある DCDL source span を示す。
+複数の式が conflict した場合は、関係する field、constraint、value、`default` の位置も示される。
+structured import の値に source span がない場合は、host が返した stable key と logical value path が示される。
 
-この値の最終値は `9000` である。
+## Fallback
 
-## エラー分類
-
-代表的なエラー:
-
-- 構文エラー
-- 未定義識別子
-- 型不一致
-- 制約違反
-- `&` の conflict
-- `default` の conflict
-- 循環依存
-- import 失敗
-- match の非網羅による失敗
-- materialize 不能な値の出力
-
-## match の失敗
-
-`match` に fallback 分岐がなく、どの分岐にも一致しなかった場合はエラーになる。
+`match` に fallback arm がなく、どの arm にも一致しない場合は diagnostic になる。
 
 ```dcdl
 match value {
@@ -87,13 +69,5 @@ match value {
 }
 ```
 
-`value` が `10` 未満であれば失敗する。
-
-## エラーは値ではない
-
-エラーは runtime value ではなく diagnostic として扱う。
-通常の式はエラー内容に基づいて分岐できない。
-
-汎用 `try / catch` は core には含めない。
-fallback は `default` と `match` で表現する。
-optional import や optional field access は core には含めない。
+Decodal は diagnostic を捕捉する汎用 `try / catch`、optional import、optional field access を提供しない。
+値がない場合の fallback は `default`、有限の値分岐は `match` で表現する。