snix_eval/upvalues.rs
1//! This module encapsulates some logic for upvalue handling, which is
2//! relevant to both thunks (delayed computations for lazy-evaluation)
3//! as well as closures (lambdas that capture variables from the
4//! surrounding scope).
5//!
6//! The upvalues of a scope are whatever data are needed at runtime
7//! in order to resolve each free variable in the scope to a value.
8//! "Upvalue" is a term taken from Lua.
9
10use std::ops::Index;
11
12use crate::{opcode::UpvalueIdx, Value};
13
14/// Structure for carrying upvalues of an UpvalueCarrier. The
15/// implementation of this struct encapsulates the logic for
16/// capturing and accessing upvalues.
17///
18/// Nix's `with` cannot be used to shadow an enclosing binding --
19/// like Rust's `use xyz::*` construct, but unlike Javascript's
20/// `with (xyz)`. This means that Nix has two kinds of identifiers,
21/// which can be distinguished at compile time:
22///
23/// - Static identifiers, which are bound in some enclosing scope by
24/// `let`, `name:` or `{name}:`
25/// - Dynamic identifiers, which are not bound in any enclosing
26/// scope
27#[derive(Clone, Debug)]
28pub struct Upvalues {
29 /// The upvalues of static identifiers. Each static identifier
30 /// is assigned an integer identifier at compile time, which is
31 /// an index into this Vec.
32 static_upvalues: Vec<Value>,
33
34 /// The upvalues of dynamic identifiers, if any exist. This
35 /// consists of the value passed to each enclosing `with val;`,
36 /// from outermost to innermost.
37 with_stack: Option<Vec<Value>>,
38}
39
40impl Upvalues {
41 pub fn with_capacity(count: usize) -> Self {
42 Upvalues {
43 static_upvalues: Vec::with_capacity(count),
44 with_stack: None,
45 }
46 }
47
48 /// Push an upvalue at the end of the upvalue list.
49 pub fn push(&mut self, value: Value) {
50 self.static_upvalues.push(value);
51 }
52
53 /// Set the captured with stack.
54 pub fn set_with_stack(&mut self, with_stack: Vec<Value>) {
55 self.with_stack = Some(with_stack);
56 }
57
58 pub fn with_stack(&self) -> Option<&Vec<Value>> {
59 self.with_stack.as_ref()
60 }
61
62 pub fn with_stack_len(&self) -> usize {
63 match &self.with_stack {
64 None => 0,
65 Some(stack) => stack.len(),
66 }
67 }
68
69 /// Resolve deferred upvalues from the provided stack slice,
70 /// mutating them in the internal upvalue slots.
71 pub fn resolve_deferred_upvalues(&mut self, stack: &[Value]) {
72 for upvalue in self.static_upvalues.iter_mut() {
73 if let Value::DeferredUpvalue(update_from_idx) = upvalue {
74 *upvalue = stack[update_from_idx.0].clone();
75 }
76 }
77 }
78}
79
80impl Index<UpvalueIdx> for Upvalues {
81 type Output = Value;
82
83 fn index(&self, index: UpvalueIdx) -> &Self::Output {
84 &self.static_upvalues[index.0]
85 }
86}