66 lines
3.4 KiB
Markdown
66 lines
3.4 KiB
Markdown
# Variables and Scope (Local/Block Semantics)
|
||
|
||
Status: Stable (Stage‑3 surface for `local`), default strong references.
|
||
|
||
This document defines the variable model used by Hakorune/Nyash and clarifies how locals interact with blocks, memory, and references across VMs (Rust VM, Hakorune VM, LLVM harness).
|
||
|
||
## Local Variables
|
||
|
||
- Syntax: `local name = expr`
|
||
- Scope: Block‑scoped. The variable is visible from its declaration to the end of the lexical block.
|
||
- Redeclaration: Writing `local name = ...` inside a nested block creates a new shadowing binding. Writing `name = ...` without `local` updates the nearest existing binding in an enclosing scope.
|
||
- Mutability: Locals are mutable unless future keywords specify otherwise (e.g., `const`).
|
||
- Lifetime: The variable binding is dropped at block end; any referenced objects live as long as at least one strong reference exists elsewhere.
|
||
|
||
Notes:
|
||
- Stage‑3 gate: Parsing `local` requires Stage‑3 to be enabled (`NYASH_PARSER_STAGE3=1` or equivalent runner profile).
|
||
|
||
## Assignment Resolution (Enclosing Scope Update)
|
||
|
||
Assignment to an identifier resolves as follows:
|
||
|
||
1) If a `local` declaration with the same name exists in the current block, update that binding.
|
||
2) Otherwise, search outward through enclosing blocks and update the first found binding.
|
||
3) If no binding exists in any enclosing scope, it is an error (undeclared variable). Declare it with `local`.
|
||
|
||
This matches intuitive block‑scoped semantics (Lua‑like), and differs from Python where inner blocks do not create a new scope (function scope), and assignment would create a local unless `nonlocal`/`global` is used.
|
||
|
||
## Reference Semantics (Strong/Weak)
|
||
|
||
- Default: Locals hold strong references to boxes/collections. Implementation uses reference counting (strong = ownership) with internal synchronization.
|
||
- Weak references: Use `WeakBox` to hold a non‑owning (weak) reference. Weak refs do not keep the object alive; they can be upgraded to strong at use sites. Intended for back‑pointers and cache‑like links to avoid cycles.
|
||
- Typical guidance:
|
||
- Locals and return values: strong references.
|
||
- Object fields that create cycles (child→parent): weak references.
|
||
|
||
Example (nested block retains object via outer local):
|
||
|
||
```
|
||
local a = null
|
||
{
|
||
local b = new Box(a)
|
||
a = b // outer binding updated; a and b point to the same object
|
||
}
|
||
// leaving the block drops `b` (strong‑count ‑1), but `a` still keeps the object alive
|
||
```
|
||
|
||
## Shadowing vs. Updating
|
||
|
||
- Shadowing: `local x = ...` inside a block hides an outer `x` for the remainder of the inner block. The outer `x` remains unchanged.
|
||
- Updating: `x = ...` without `local` updates the nearest enclosing `x` binding.
|
||
|
||
Prefer clarity: avoid accidental shadowing. If you intentionally shadow, consider naming or comments to clarify intent.
|
||
|
||
## Const/Immutability (Future)
|
||
|
||
- A separate keyword (e.g., `const`) can introduce an immutable local. Semantics: same scoping as `local`, but re‑assignment is a compile error. This does not affect reference ownership (still strong by default).
|
||
|
||
## Cross‑VM Consistency
|
||
|
||
The above semantics are enforced consistently across:
|
||
- Rust VM (MIR interpreter): scope updates propagate to enclosing locals.
|
||
- Hakorune VM/runner: same resolution rules.
|
||
- LLVM harness/EXE: parity tests validate identical exit codes/behavior.
|
||
|
||
See also: quick/integration smokes `scope_assign_vm.sh`, `vm_llvm_scope_assign.sh`.
|