hakorune/docs/guides/exception-handling.md

Exception Handling — Postfix catch / cleanup (Stage‑3)

Summary

• Nyash adopts a flatter, postfix-first exception style:
  • There is no try statement in the language spec. Use postfix catch and cleanup instead.
  • catch = handle exceptions from the immediately preceding expression/call.
  • cleanup = always-run finalization (formerly finally), regardless of success or failure.
• This matches the language’s scope unification and keeps blocks shallow and readable.

Spec Clarifications (Stage‑3)

• Acceptance gates and profiles
  • Expression‑postfix: NYASH_PARSER_STAGE3=1 enables expr catch(...) {..} cleanup {..} on calls/chains.
  • Block‑postfix: NYASH_BLOCK_CATCH=1 or Stage‑3 enables { ... } catch(...) {..} cleanup {..} (standalone block statement)。
  • Method‑postfix: NYASH_METHOD_CATCH=1 or Stage‑3 enables method body postfix on the most recent method.
• Cardinality and order
  • Postfix (expr/block/method): at most one catch and at most one cleanup — in this order. A second catch after postfix is a parse error. Multiple cleanup are not allowed.
  • Legacy compatibility: some builds may still accept the historical try { ... } catch ... cleanup ... form, but it is not part of the language spec and will be disabled by default. Prefer postfix forms.
• Binding and chaining
  • Postfix binds to the immediately preceding expression (the last call in a chain) or to the just‑parsed block/method body. It does not extend to the entire statement unless parentheses are used.
  • After constructing the postfix TryCatch, further method chaining on that expression is not accepted.
• Semantics and control‑flow
  • cleanup (finally) always runs, regardless of success/failure of the try part.
  • return inside the try part is deferred until after cleanup executes. This is implemented by the MIR builder as a deferred return slot/jump to the cleanup/exit block.
  • return inside cleanup is disallowed by default; enable with NYASH_CLEANUP_ALLOW_RETURN=1.
  • throw inside cleanup is disallowed by default; enable with NYASH_CLEANUP_ALLOW_THROW=1.
  • break/continue inside cleanup are allowed (no special guard); use with care. Cleanup executes before the loop transfer takes effect.
  • Nested cleanup follows lexical unwinding order (inner cleanup runs before outer cleanup).
  • If no catch is present, thrown exceptions still trigger cleanup, then propagate outward.
• Diagnostics
  • Method‑postfix: duplicate postfix after a method body is a parse error: "duplicate postfix catch/cleanup after method".
  • Block‑postfix: a standalone postfix without a preceding block is a parse error: "catch/cleanup must follow a try block or standalone block".
  • Expression‑postfix: only one catch is accepted at expression level; a second catch triggers a parse error.

Status

• Phase 1: normalization sugar（既存）
  • NYASH_CATCH_NEW=1 でコア正規化パスが有効化。
  • 後置フォームは内部 TryCatch AST に変換され、既存経路で降下。
  • 実行時コストはゼロ（意味論不変）。
• Phase 2（実装済み・Stage‑3ゲート）
  • パーサが式レベルの後置 catch/cleanup を直接受理。
  • ゲート: NYASH_PARSER_STAGE3=1
  • 糖衣正規化はそのまま併存（関数糖衣専用）。キーワード直受理と二重適用はしない設計。

Syntax (postfix)

• Expression-level postfix handlers (Stage‑3):
  • expr catch(Type e) { /* handle */ }
  • expr catch { /* handle (no variable) */ }
  • expr cleanup { /* always-run */ }
  • Combine: expr catch(Type e){...} cleanup{...}
• Method/function calls are just expressions, so postfix applies:
  • call(arg1, arg2) catch(Error e) { log(e) }
  • obj.method(x) cleanup { obj.release() }

Precedence and chaining

• Postfix catch/cleanup binds to the immediately preceding expression (call/chain result), not to the whole statement.
• For long chains, we recommend parentheses to make intent explicit:
  • (obj.m1().m2()) catch { ... }
  • f(a, b) catch { ... } cleanup { ... }
• Parser rule (Stage‑3): postfix attaches once at the end of a call/chain and stops further chaining on that expression.

Diagram (conceptual)

// before (parse)
obj.m1().m2() catch { H } cleanup { C }

// precedence (binding)
obj.m1().[ m2()  ↖ binds to this call ] catch { H } cleanup { C }

// normalization (conceptual AST)
TryCatch {
  try:   [ obj.m1().m2() ],
  catch: [ (type:Any, var:None) -> H ],
  finally: [ C ]
}

Normalization (Phase 1)

• With NYASH_CATCH_NEW=1, postfix sugar is transformed into legacy TryCatch AST:
  • EXPR catch(T e){B} → TryCatch { try_body:[EXPR], catch:[(T,e,B)], finally:None }
  • EXPR cleanup {B} → TryCatch { try_body:[EXPR], catch:[], finally:Some(B) }
  • Multiple catch are ordered top-to-bottom; first matching type handles the error.
  • Combined catch ... cleanup ... expands to a single TryCatch with both blocks.
• Lowering uses the existing builder (cf_try_catch) which already supports cleanup semantics.

Semantics

• catch handles exceptions from the immediately preceding expression only.
• cleanup is always executed regardless of success/failure (formerly finally).
• Multiple catch blocks match by type in order; the first match is taken.
• In loops, break/continue cooperate with cleanup: cleanup is run before leaving the scope.
• Return deferral: A return in the try section defers until after cleanup. return/throw inside cleanup are disabled by default; see env toggles below.

Environment toggles

• NYASH_PARSER_STAGE3=1: Enable Stage‑3 syntax (postfix catch/cleanup for expressions; also gates others by default)
• NYASH_BLOCK_CATCH=1: Allow block‑postfix (independent of Stage‑3 if needed)
• NYASH_METHOD_CATCH=1: Allow method‑postfix (independent of Stage‑3 if needed)
• NYASH_CLEANUP_ALLOW_RETURN=1: Permit return inside cleanup (default: off)
• NYASH_CLEANUP_ALLOW_THROW=1: Permit throw inside cleanup (default: off)

Migration notes

• try is deprecated: prefer postfix catch/cleanup.
• Member-level handlers (computed/once/birth_once/method) keep allowing postfix catch/cleanup (Stage‑3), unchanged.
• Parser acceptance of postfix at expression level will land in Phase 2; until then use the gate for normalization.

Examples

// Postfix catch on a call
do_work() catch(Error e) { env.console.log("error: " + e) }

// Always-run cleanup
open_file(path) cleanup { env.console.log("closed") }

// Combined
connect(url)
  catch(NetworkError e) { env.console.warn(e) }
  cleanup { env.console.log("done") }

// Stage‑3 parser gate quick smoke (direct acceptance)
//   NYASH_PARSER_STAGE3=1 ./target/release/nyash --backend vm \
//     apps/tests/macro/exception/expr_postfix_direct.hako