@cella-lang/cpp 0.1.202610121721 → 0.1.202610130445

package/CHANGES.md

@@ -5,6 +5,29 @@
 
 ## 未發佈
 
+- 標準庫的 Int 名字改進 `Int` namespace（`add_int` → `Int.add`、`ltInt` → `Int.blt`、`addIntF` → `Int.addFast`…），套件的原始碼與產生的項都寫完整名稱。對照表見 cella-lang 的變更紀錄。
+  - 穩定定義（`docs/stable-defs.json`）的內容雜湊因此改變（引用的名字變了，內容不變）：`cpp.NonZero`、`cpp.add`、`cpp.div`、`cpp.eq`、`cpp.inRangeB`、`cpp.le`、`cpp.lt`、`cpp.minOf`、`cpp.mul`、`cpp.neg`、`cpp.rem`、`cpp.sub`、`cpp.toC`、`cpp.toInt_add`、`cpp.toInt_div`、`cpp.toInt_mul`、`cpp.toInt_neg`、`cpp.toInt_rem`、`cpp.toInt_sub`。
+- `cpp.Exc` 多一個建構子 `objExc 類別鏈 訊息 節點 位置`：其他語言的例外物件（`@cella-lang/python` 使用者的例外類別：類別與祖先由近到遠、物件在堆上的位置）；`excNode`、`excJson`（type 是鏈的第一個）跟著支援。對 `Exc` 做窮盡 match 的程式要多一個分支。
+- `stopNode` 對未接住的例外回報例外帶著的節點（`namedExc` 的；C++ 的例外不帶，照舊是空字串）。
+- **不相容**：`Debugger` 的 `showGlobals`、`showFrame` 多收環境：`showGlobals : E -> V -> String`、`showFrame : String -> E -> V -> String`（變數可能指向環境裡的東西，例如 Python 的 list 在堆上）。
+- `cpp.Exc` 多一個建構子 `namedExc 型別名 訊息 節點`：其他語言的例外（`@cella-lang/python` 的 `ZeroDivisionError` 等），帶丟出它的節點；`excJson` 印成 `{"type", "what", "node"}`。`Thr`、`sTry`、`sCallT`、除錯器的 `terminated` 原樣適用。對 `Exc` 做窮盡 match 的程式要多一個分支。
+- **不相容**：記憶體（`GMem`）的執行用表示改成 GArr：配置是 `alloc 格子(GArr) 活著 heap 唯讀`、記憶體是 `mem 配置(GArr)`。`new`、`*p` 讀寫、`delete` 都是 O(log n)：瀏覽器（node）上 10⁵ 個配置的建立、讀出、delete 約 0.3 秒（之前 10⁴ 次 `new` 1 秒、平方成長）。
+  - 規格仍是串列的觀點：`allocCells a`（格子）、`memAllocs m`（現在是 `List (Maybe (GAlloc A))`）。快速路徑 `blockOf`、`cellAt`、`allocLen`、`memUpd` 有證明與規格相等（`blockOfSpec`、`cellAtSpec`、`allocLenSpec`、`memUpdSpec`、`storeAtCells`）。
+  - 由串列建配置用 `allocL 格子 活著 heap 唯讀`（`allocLCells`）；改一個配置用 `memUpd m b f`（取代 `mem (updBlock (memAllocs m) b f)`）；`storeAt` 對任意元素型別、`killA` 是 delete／離開作用域。
+  - 新的引理：`addAllocBlock`、`derefNew`、`blockUpd`、`storeDerefB`（寫了之後可讀）、`storeKeepsWritableB`（寫一格不改變哪些格子寫得進去）、`readM`／`derefA`／`deleteA`（`load`、`derefB`、`deleteB` 找到配置之後的那一段）。
+  - 記憶體的章節搬到 vector 之後（定義的名字不變）。
+- **不相容**：`GArr`（vector、陣列）的執行用表示改成固定深度的二元 trie：建構子 `arr 樹 深度 大小 版本 損壞點 容量`（原本 `arr 元素串列 版本 損壞點 容量`）。讀寫是 O(log n)：瀏覽器（node）上 10⁶ 次讀寫約 3 秒（之前 10⁵ 次約 170 秒、平方成長）。規格仍是元素串列 `gElems a`（= `elems`），讀寫、push、pop 的快速路徑（`gNth`、`gSetRaw`、`gPushRaw`、`gPopRaw`）都有證明與規格相等（`gNthSpec`、`gSetRawElems`、`gPushElems`、`gPopElems`……）。直接對 `arr` 做 match 或寫 `arr` 的程式要改用 `gElems`／`gFrom 串列 版本 損壞點 容量`；整個 `GArr` 的等式（之前由串列的等式直接得到）改述元素的等式。`gFill`、`zeros`、`uninit` 一格一格接，不先建串列（10⁴ 格以上在瀏覽器不再用完堆疊）。
+- 二維陣列參數的視圖 `GFull2`：`g2Get`／`g2Set` 直接走 trie（O(log r + log c)，之前每次攤平整個外層）；新的 `g2Row`、`g2RowFull`、`full2Set`、`rowsFullSetNth`、`rowsFullNthL`、`rowAtB`、`rowOf`。**不相容**：拿掉 `g2GetL`、`g2SetL`、`lengthG2SetL`、`rowsFullSet`（只在證明視圖保持時用到）。
+- **不相容**：直譯器的狀態改成三層 `cpp.St E V`（`io`、`env`、`vars`；`mkSt io env vars`）：`env` 是程式所處的環境（`@cella-lang/arduino` 放硬體，一般程式是 `Unit`），學生的變數仍然只在 `vars`。`Debugger` 多 `env0`、`showEnv`；`dbgEnv` 給宿主讀環境（JSON）。除錯器的函數都對 `E` 參數化。
+- `byCompute b slow` 的 `slow` 改成 `Unit -> b = true`（延遲的證明包成函數）：嚴格求值的後端（WasmGC、VM）不再把範圍引理算出來——之前 `wrap` 的每次呼叫成本和數值成正比，數到 10 萬的迴圈 77 秒，現在約 0.2 秒。
+- **不相容**：`cpp.Flow` 的 `ret` 帶狀態：`ret 值 狀態`（return 那一刻的狀態；`returnS`、`retT`、`throwS` 照舊）。呼叫回到呼叫端時因此拿得到被呼叫者的狀態：小步語意的 `sCall`／`sCallT` 的 `leave` 改成 `S -> S -> Maybe R -> S`（存下的狀態、被呼叫者結束時的狀態、回傳值），被呼叫者裡的輸入輸出與全域修改不再遺失；`sCallT` 的 `restore saved t` 的 t 是丟出那一刻被呼叫者的狀態。狀態只有一份：`Thr R` 是 `thrown e | done v`（原本 `Thr S R` 的 `thrown e s`），`Jump R` 是 `jTo l | jRet v`。對 `ret`／`thrown`／`jTo` 做 match 或寫出期望值的程式要補上狀態；`uncaughtB`、`thrownState` 照舊。
+- 小步語意的 `try`：`cpp.sTry body h`（`h : Exc -> Maybe (CStmt …)`，接得住就給 handler）；丟出的例外走 return 通道，被最近接得住的 `sTry` 接住，接不住就往外傳，到最外層仍是 `thrown` 就是未接住（`std::terminate`）。會丟例外的程式裡的呼叫用 `cpp.sCallT enter body leave restore`：例外穿出呼叫，帶的狀態換成 `restore saved s`（呼叫端看到的樣子）。小步執行與指稱語意的一致性證明涵蓋這兩者。底層建構子是 `sTryC`（新）與 `sCallC`（新增第四個欄位 `unwind`：哪些回傳值不由呼叫吸收）、框架 `kTry`（新）與 `kCall`（同樣多一個欄位）。
+- **不相容**：`sCall`／`sCallT` 前面多兩個參數 `fn site`（函式定義的節點、發出呼叫的節點（呼叫運算式）），`sCallC`／`kCall` 多這兩個欄位。
+- 除錯器的變數：`cpp.frames mainFn cur x`（每層 `DFrame`：`dfFn`、`dfAt`、`dfSt`）、`setFrame n f x`；值的字串 `showValC`（整數、`'a'`、`true`）、`showStrC`、`showListC`（`{1, 2, 3}`）；從文字讀回 `parseValC t 文字`，錯誤是 `unreadable` 或 `outOfRange 最小 最大`。
+- 除錯器的宿主介面：`cpp.Debugger V X`（`prog`、`vars0`、`mainFn`、`showGlobals`、`showFrame`、`setField`）與 `dbgInit`、`dbgRun kind 斷點 closed fuel x`、`stopConfOr`、`stopNode`、`stopOut`／`stopErr`、`stopDetail`（未定義行為的 why、未接住的例外，JSON）、`dbgFeed`、`dbgGlobals`、`dbgFrames`、`dbgSetVar`、`eitherErr`；JSON 的 `jsonStr`／`jsonObj`／`jsonArr`。完整的例子 `tests/t_sem_dap.cella`（cella-lang 的 `cella-lang/dap` 用它）。`undefinedAt` 多帶出事前的狀態。
+- 除錯驅動：`cpp.continueRun uncaught closed 斷點 fuel x`、`stepIn`、`stepOver`、`stepOut`（同樣的參數）回 `cpp.Stop`：`atBreakpoint 節點 組態`、`stepped 節點 組態`、`fuelSpent 組態`、`awaitingInput 組態`、`undefinedAt 最近的節點 why`、`terminated 例外 狀態`、`exited 結果`；`thrUncaught` 給 `Thr` 的程式用；`confVars`、`confDepth`。可停的地方是 `sLabel` 的節點。
+- 直譯器（可停的執行）：狀態 `cpp.St V`（`io : IOS`、`vars : V`；`mkSt`）；`cpp.stepIO closed x` 走一步，輸入還沒關閉而這一步讀到目前輸入的結尾（eofbit 由 0 變 1）時回 `needsInput`、不提交，宿主以 `feedConf` 補輸入後從同一個組態重走；`runFed fuel 段落 x` 把輸入分段餵（段用完就是關閉），分段與一次給完結果相同。
+- **不相容**（只影響對建構子做 match 或直接寫 `sCallC`／`kCall`／`callAfter`／`callU`／`callUC` 的程式）：上面的欄位。`sCall` 的寫法不變（回傳值一律由呼叫吸收）。
 - 標準庫的定理改名（帶底線的改 lowerCamel，規則見 cella-lang 的 CHANGES）：套件內的使用處一起改，名字與意思不變；`stable-defs.json` 裡雜湊改變的：`cpp.toInt_add`、`cpp.toInt_mul`、`cpp.toInt_sub`。
 - **不相容**：定理與前置條件改證 `a = b`（原本是路徑 `≡`）：`InRange` 的欄位是 `inRangeB bits v = true`、`NonZero b` 是 `isZeroInt (toInt b) = false`、`toInt_add` 等證 `=`，迴圈、記憶體、switch 的條件也是。名字不變；前置條件照舊寫 `refl` 或具名的洞，洞的型別照寫的印（`cpp.InRange 32 (…)`）。需要路徑的地方改寫 `Eq.toPath (…)`；範圍證明唯一改用 `DecEq.uip`（hlevel）。`stable-defs.json` 裡雜湊改變的 16 個：`cpp.InRange`、`cpp.NonZero`、`cpp.isPropInRange`、`cpp.lit`、`cpp.maxInt32`、`cpp.minInt32`、`cpp.mkCong`、`cpp.mkInj`、`cpp.toC`、`cpp.toInt_add`、`cpp.toInt_div`、`cpp.toInt_inj`、`cpp.toInt_mul`、`cpp.toInt_neg`、`cpp.toInt_rem`、`cpp.toInt_sub`。
 - 標準庫 `int` 的定理改證 `a = b`：套件內需要路徑的地方改寫 `Eq.toPath (…)`（過渡）；`twosModRange` 的前提直接收 `=`。用到的定義雜湊改變，意思不變；`stable-defs.json` 裡是 `cpp.toInt_add`、`cpp.toInt_sub`、`cpp.toInt_mul`。