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}