std/src/prelude/runtime.nv - main - nv-lang/nova

std/src/prelude/runtime.nv
107 строк5 KB
Evgeniy Golovin
docs(endocs): перевод ///-комментариев prelude на английский
31 июл 2026, 19:10
31 июл 2026, 19:102085649
// std/prelude/runtime.nv — runtime functions: panic, exit, assert, print, println.
// Все declarations — `extern "nova" fn` (zero imports), dispatch через codegen
// special-case в emit_c.rs.

module prelude.runtime

// ──────────────────────────────────────────────────────────────────────────
// Runtime functions
// ──────────────────────────────────────────────────────────────────────────

/// Aborts the fiber with a message. Inside a fiber it is routed through
/// the nearest handler, on the main flow with a test frame — to the
/// test-runner, without a supervisor — aborts the process. `-> never`
/// lets panic be a branch without a value (e.g., `?? panic(...)`).
#stable(since = "0.1")
extern "nova" fn panic(msg str) -> never

/// Aborts the whole process with an exit code and a message. Not
/// caught by a handler. In tests it is routed through the test-runner
/// so that one test does not kill the whole run.
#stable(since = "0.1")
extern "nova" fn exit(code int, msg str) -> never

/// Marker for logically unreachable code. Fires only if an invariant is
/// broken — the compiler cannot itself prove unreachability.
/// Semantically identical to `panic("unreachable: ${reason}")`, but
/// expresses the intent: "this point must never be reached".
///
/// **When to use:**
/// - After a `match` over a full enumeration (when the compiler does not
///   infer exhaustiveness — e.g. with guards)
/// - In a default branch for a case excluded by an invariant above
/// - As a placeholder for an impossible parameter combination
///
/// **When not to use:**
/// - A TODO stub — that is `panic("todo")`
/// - Validation of user input — that is `Fail[E]` via `throw`
///
/// Works in expression position in any if/match, e.g.
/// `let x = if cond { compute() } else { unreachable("inv broken") }`.
#stable(since = "0.1")
// extern "nova" (not a Nova body) — lowers in codegen's special-case to
// C concat helpers, avoiding StringBuilder dependency under #no_prelude.
extern "nova" fn unreachable(reason str) -> never

/// Runtime condition check. Fails with an auto-generated message
/// (the condition text via display) if `cond == false`. Always-on:
/// also fires in release builds.
///
/// Format: `<file>:<line>: assert failed: <expr>` (without msg) or
/// `<file>:<line>: assert failed: <msg> (<expr>)` (with msg).
///
/// Both forms via arity overload: `assert(cond)` — no message,
/// `assert(cond, msg)` — msg is printed before the expression in parens.
#stable(since = "0.1")
extern "nova" fn assert(cond bool) -> ()
#stable(since = "0.1")
extern "nova" fn assert(cond bool, msg str) -> ()

/// Prints all arguments to stdout without a separator and without a
/// trailing newline. Accepts heterogeneous args (int / str / bool / f64 / mixed).
///
/// # Examples
/// ```nova
/// print("hello")              // → "hello"
/// print("x = ", 42)           // → "x = 42"
/// print("a=", 1, " b=", true) // → "a=1 b=true"
/// ```
#stable(since = "0.1")
extern "nova" fn print(...items []any) -> ()

/// Prints all arguments to stdout + a trailing newline ('\n'). Identical
/// to `print(...)`, plus a line feed at the end.
///
/// # Examples
/// ```nova
/// println("hello")                                  // → "hello\n"
/// println(factorial(5).to_str())                     // → "120\n"
/// println("count=", n, " total=", sum)              // mixed-type ok
/// ```
#stable(since = "0.1")
extern "nova" fn println(...items []any) -> ()

/// Suppressed errors that accompanied the last caught error.
/// A cleanup failure during propagation does NOT replace the primary —
/// the primary is handed to the catcher as-is (typed catching via
/// `with Fail[Primary]` works, the effect does NOT become `Fail[MultiError]`);
/// the suppressed errors stay "in the pocket"; the accessor retrieves them after catching.
///
/// Returns `[]any` in chronological order of failures (first-failed
/// first); each element is `any`, narrowed via `is T` / `.try_as[T]()`.
/// An empty array = cleanup did not fail (pocket empty). The pocket is
/// reset on each fresh `throw` and filled at catching time, so it does
/// not leak between unrelated catches.
///
/// # Examples
/// ```nova
/// mut primary_code = 0
/// with Fail[DbErr] = effect Fail[DbErr] { fail(e) -> never { primary_code = e.code } } {
///     do_tx()            // the body threw DbErr; @cleanup threw Cleanup2
/// }
/// for s in suppressed() {          // == [Cleanup2]
///     if s is Cleanup2 { Log.warn("cleanup failed") }
/// }
/// ```
#stable(since = "0.1")
extern "nova" fn suppressed() -> []any