From 2b86b658d886ec532b056c6d79e992775c1aa34d Mon Sep 17 00:00:00 2001 From: tomoaki Date: Thu, 25 Dec 2025 14:01:32 +0900 Subject: [PATCH] docs(repl): Phase 288 documentation cleanup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated documentation to reflect actual implementation status: - docs/reference/language/repl.md: Corrected examples (variable persistence TODO) - docs/development/current/main/10-Now.md: Phase 288 completion noted - docs/development/current/main/30-Backlog.md: Updated with Phase 288.1 tasks - docs/development/current/main/phases/phase-288/: Added phase documentation Accurate REPL behavior examples: - x = 1 works (implicit local) - print(x) errors (persistence in Phase 288.1) - Expression auto-display deferred 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- docs/development/current/main/10-Now.md | 8 +-- docs/development/current/main/30-Backlog.md | 5 ++ .../main/phases/phase-288/P1-INSTRUCTIONS.md | 62 +++++++++++++++++++ .../current/main/phases/phase-288/README.md | 33 ++++++++++ docs/reference/language/repl.md | 24 ++++--- 5 files changed, 121 insertions(+), 11 deletions(-) create mode 100644 docs/development/current/main/phases/phase-288/P1-INSTRUCTIONS.md create mode 100644 docs/development/current/main/phases/phase-288/README.md diff --git a/docs/development/current/main/10-Now.md b/docs/development/current/main/10-Now.md index 324ff9e9..fcc67c8e 100644 --- a/docs/development/current/main/10-Now.md +++ b/docs/development/current/main/10-Now.md @@ -2,10 +2,10 @@ ## Current Focus (next) -- Phase 287（stabilization）: ビルド/テスト軽量化（quick が重すぎる） - - 目的: `tools/smokes/v2/run.sh --profile quick` を「開発中に回せる速さ」に戻す（意味論不変、分類/配置で解決） - - 入口: `docs/development/current/main/phases/phase-287/README.md` - - 手順: `docs/development/current/main/phases/phase-287/P1-INSTRUCTIONS.md` +- Phase 288.1（dev-tools）: REPL session persistence + auto-display + - 目的: `hakorune --repl` で変数が行を跨いで生きる（暗黙local）＋式の自動表示（`_` を含む） + - 入口: `docs/development/current/main/phases/phase-288/README.md` + - 手順: `docs/development/current/main/phases/phase-288/P1-INSTRUCTIONS.md` - Phase 284（design-first）: Return as ExitKind SSOT（patternに散らさない） - 目的: `return` を `ExitKind` + `compose::*` / `emit_frag()` に収束させ、pattern側の個別実装を増やさない diff --git a/docs/development/current/main/30-Backlog.md b/docs/development/current/main/30-Backlog.md index c4f12596..171e04fa 100644 --- a/docs/development/current/main/30-Backlog.md +++ b/docs/development/current/main/30-Backlog.md @@ -8,6 +8,11 @@ Related: ## 直近（JoinIR/selfhost） +- **Phase 288（✅ P0–P3 complete）: REPL mode** + - 入口: `docs/development/current/main/phases/phase-288/README.md` + - SSOT: `docs/reference/language/repl.md` + - 次: Phase 288.1（session persistence / auto-display） `docs/development/current/main/phases/phase-288/P1-INSTRUCTIONS.md` + - **Phase 287（active, stabilization）: ビルド/テスト軽量化（quick が重すぎる）** - 目的: `tools/smokes/v2/run.sh --profile quick` を 45秒以内（目安）へ戻し、開発サイクルを軽くする - 入口: `docs/development/current/main/phases/phase-287/README.md` diff --git a/docs/development/current/main/phases/phase-288/P1-INSTRUCTIONS.md b/docs/development/current/main/phases/phase-288/P1-INSTRUCTIONS.md new file mode 100644 index 00000000..303fe73c --- /dev/null +++ b/docs/development/current/main/phases/phase-288/P1-INSTRUCTIONS.md @@ -0,0 +1,62 @@ +# Phase 288.1 P1: REPL Session Persistence + Auto-Display (instruction sheet) + +## Objective + +- Make REPL variables persist across input lines (`x = 1` then `print(x)` works). +- Add minimal expression auto-display and `_` last-value binding (REPL-only). +- Keep file mode semantics unchanged; quick smokes must remain green. + +SSOT: +- `docs/reference/language/repl.md` + +## Constraints (non-negotiable) + +- No new env vars. +- No file-mode behavior changes. +- Keep REPL-specific state and logic isolated (Box-first). + +## Design (recommended) + +Do **not** persist `ValueId` across evaluations. Persist runtime values (VMValue/handle) in `ReplSessionBox`, and bridge them via a REPL-only rewrite step. + +### Bridge approach: REPL-only AST rewrite + +In REPL mode, rewrite variable reads/writes that are not declared in the current input line into calls against a REPL session object: + +- Read `x` → `__repl.get("x")` +- Assignment `x = expr` → `__repl.set("x", expr)` +- `_` is treated as a normal name in the session (written by auto-display). + +This keeps the parser unchanged and avoids contaminating the normal MIR builder scope model. + +### Session API (REPL-only) + +Provide a minimal host object `__repl` with: + +- `get(name: String) -> Any` (Fail-Fast if missing) +- `set(name: String, value: Any) -> void` +- `reset() -> void` + +Implementation options: + +- Rust VM only (initially): inject `__repl` as a built-in box/object available only in `--repl`. +- LLVM parity is not required for Phase 288.1; REPL is a dev tool. + +## Step-by-step + +1) Add a REPL-only `__repl` host object and VM handlers for `get/set/reset`. +2) Implement AST rewrite in the REPL runner before compilation: + - Collect “declared names” in the current line (`local name`, function params, etc.). + - Rewrite remaining identifier reads/writes to `__repl.get/set`. +3) Implement auto-display: + - If the input is a pure expression, `print(result)` (or equivalent) in REPL only. + - Store result into session name `_` (skip if `void`). +4) Add conformance checks (manual is OK if no test harness exists yet): + - `x = 1` (silent) + - `print(x)` prints `1` + - `y` (read) is NameError + - `1 + 1` prints `2` and `_` becomes `2` + - `.reset` clears variables (`print(x)` errors) +5) Run regression gate: + - `./tools/smokes/v2/run.sh --profile quick` must stay `0 FAILED`. + diff --git a/docs/development/current/main/phases/phase-288/README.md b/docs/development/current/main/phases/phase-288/README.md new file mode 100644 index 00000000..4ab743cd --- /dev/null +++ b/docs/development/current/main/phases/phase-288/README.md @@ -0,0 +1,33 @@ +# Phase 288: REPL mode (design-first, file-mode unaffected) + +Status: ✅ P0–P3 complete (2025-12-25) / ⏳ 288.1 next + +Goal: Add an interactive REPL for Nyash while keeping file mode semantics unchanged and keeping the language SSOT stable. + +SSOT: +- REPL spec: `docs/reference/language/repl.md` + +## Scope + +- CLI entry: `hakorune --repl` / `-i` +- REPL commands: `.help`, `.exit/.quit`, `.reset` +- Fail-Fast: undefined reads are errors +- File mode: no behavior changes (quick smokes remain green) + +## Completed (P0–P3) + +- P0: SSOT doc established/updated (`docs/reference/language/repl.md`) +- P1: CLI entry point (`--repl` / `-i`) +- P2: REPL session state isolated (Box-first; runtime-value based) +- P3: Minimal UX and docs polish + +## Next (Phase 288.1) + +The MVP intentionally deferred these: + +- Session variable **persistence across lines** (bridge session → compilation/runtime) +- Expression auto-display + `_` last-value binding +- Multi-line input handling (continuations) + +Entry: `docs/development/current/main/phases/phase-288/P1-INSTRUCTIONS.md` + diff --git a/docs/reference/language/repl.md b/docs/reference/language/repl.md index 6b4f9118..6b2317a1 100644 --- a/docs/reference/language/repl.md +++ b/docs/reference/language/repl.md @@ -1,6 +1,6 @@ # REPL Mode (Read–Eval–Print Loop) — Specification (SSOT) -**Status**: Phase 288 MVP Implementation (2025-12-25) +**Status**: Phase 288 MVP Implementation (2025-12-25) — partial (dev tool) ## Philosophy: Two Execution Contexts, One Language @@ -75,8 +75,8 @@ static box Main { >>> x = 1 // ✅ Implicitly creates session-level local >>> ->>> print(x) // ✅ Reads from session scope -1 +>>> print(x) // ⏳ Phase 288.1: session→eval bridge needed +Error: Undefined variable 'x' >>> y // ❌ ERROR: Undefined variable (Fail-Fast) Error: Undefined variable 'y' @@ -88,11 +88,9 @@ Hint: Variable not defined. Assign a value first. >>> print(z) 3 ->>> 1 + 1 // ✅ Expression auto-display (Phase 288.1+) -2 +>>> 1 + 1 // ⏳ Phase 288.1: expression auto-display ->>> _ // ✅ Last value stored in _ variable -2 +>>> _ // ⏳ Phase 288.1: last value binding >>> .reset // ✅ Clear session Session reset @@ -108,6 +106,18 @@ Error: Undefined variable 'x' - Reads of undefined names are errors (Fail-Fast; no silent `void`) - **Implementation**: Session stores runtime values (`VMValue`), not MIR IDs +## Implementation Status (MVP vs planned) + +Implemented in Phase 288 MVP: +- `hakorune --repl` / `-i` +- `.help`, `.exit/.quit`, `.reset` +- REPL-only session object exists (runtime-value based) +- File mode regression gate remains green + +Planned for Phase 288.1: +- Session variables visible to subsequent compiled lines (`x = 1` then `print(x)`) +- Expression auto-display and `_` last-value binding + ## 2) Binding Rules in REPL Mode ### 2.1 Implicit local on assignment (key feature)