Struct Env 

pub struct Env(/* private fields */);

Evaluation environment — flattened binding map with structural sharing.

Internally an Rc<EnvInner>, so cloning is always O(1) (refcount bump). child() clones the FxHashMap (O(1) structural sharing) instead of building a parent chain. bind() uses Rc::make_mut for copy-on-write: if the Rc is shared, only then does it clone the inner data.

Implementations

impl Env

pub fn new() -> Self

Create a root environment with no bindings.

pub fn child(&self) -> Self

Create a child environment that inherits from this one.

O(1) — the FxHashMap clone is structural sharing (refcount bump on internal tree nodes), not a deep copy.

pub fn with_scope(self, value: Value) -> Self

Attach a with scope to this environment.

If the value is a thunk that’s ALREADY evaluated (OnceCell cache hit), pre-populate the with-scope cache immediately. This avoids creating deferred WithIdent thunks when the fixpoint is already resolved — critical for the overlay chain where multiple stages access the same fixpoint through different with self; scopes.

pub fn bind(&mut self, name: String, value: Value)

Bind a name to a value in this environment’s own scope.

Uses copy-on-write: if the inner Rc is shared, clones the inner data before mutating.

pub fn bind_many(&mut self, pairs: impl IntoIterator<Item = (String, Value)>)

Bind many names in ONE copy-on-write step: a single Rc::make_mut on the inner env, then N inserts on the owned map — instead of N successive bind() calls each re-borrowing + re-make_mut-ing self.0.

Byte-identical to calling bind once per pair in the same order (same intern, same insert sequence, same final HAMT) — a byte-SAFE RedundantWrite-class optimization: it removes intermediate re-borrows, not any observable value. Consumed by pattern-lambda binding (bind_param), where an N-formal pattern otherwise pays N make_mut refcount checks.

pub fn eval_file(&self) -> Option<&PathBuf>

Get the eval_file for this environment.

pub fn set_eval_file(&mut self, file: Option<PathBuf>)

Set the eval_file for this environment.

pub fn source_id(&self) -> u32

The source_id of the parse tree this env belongs to (0 = top level).

pub fn set_source_id(&mut self, id: u32)

Set the source_id for this environment (called by eval_with_file for an imported parse tree).

pub fn binding_count(&self) -> usize

Number of direct bindings in this environment (debug).

pub fn binding_names_preview(&self, n: usize) -> Vec<String>

First N binding names (debug).

pub fn with_scope_count(&self) -> usize

Number of with scopes (debug).

pub fn lookup_lexical(&self, name: &str) -> Option<Value>

Lookup in LEXICAL scope only (no with-scopes). Used by maybe_thunk to avoid forcing with-scope fixpoints during attrset construction.

pub fn lookup_lexical_sym(&self, sym: Symbol) -> Option<Value>

Lookup in LEXICAL scope only, by pre-interned Symbol — the Symbol-keyed sibling of lookup_lexical.

Probes ONLY the lexical bindings map (the first thing lookup_fast does, by the same Symbol) — never the with-chain. The ENV-RESOLVE M0 fast path uses this: a Resolution::Lexical{sym} reference probes here directly with its precomputed Symbol; on a hit the returned value is byte-identical to lookup_fast’s (same map, same Symbol); on a miss the caller falls back to today’s exact runtime path.

pub fn lookup_with_cache_only(&self, name: &str) -> Option<Value>

Look up a name using ONLY with-scope caches (no forcing). Returns Some if the name is in a cached with-scope, None otherwise. Used by maybe_thunk to resolve with-scope idents without forcing fixpoints.

pub fn innermost_with_scope( &self, ) -> Option<(Rc<RefCell<Option<NixAttrs>>>, Value)>

Get the innermost with-scope’s cache and value for creating WithIdent thunks. Returns None if there are no with-scopes.

pub fn lookup(&self, name: &str) -> Option<Value>

Lookup matching Nix semantics:

1. Probe the flattened binding map (single O(log32 n) lookup). Any explicit let/rec/function-arg binding wins over every with scope.
2. If no lexical binding matched, iterate with_scopes in reverse order (innermost first). So with X; with Y; x finds x in Y if Y has it, otherwise in X.

pub fn lookup_fresh(&self, name: &str) -> Option<Value>

Cache-BYPASSING with-scope lookup: force each with-scope value FRESH (through the full thunk chain) and check for name, refreshing the per-scope cache on the way. A force that errors (a mid-fixpoint blackhole or a with (throw …); … namespace) is caught and the scope skipped.

This exists ONLY for the last-ditch retry on the about-to-throw UndefinedVar path (see the WithIdent force): the normal cache-first [lookup_fast] can trust a stale mid-fixpoint PARTIAL cached for a scope (e.g. f self before makeScope merged callPackage into self) and skip it; a fresh force sees the now-completed scope. Never call this on a hot path — it re-forces every scope.

pub fn lookup_fast(&self, sym: Symbol, name: &str) -> Option<Value>

Lookup by pre-interned Symbol + string name. Avoids re-interning.

pub fn lookup_sym(&self, sym: Symbol) -> Option<Value>

Look up a binding by pre-interned Symbol.

Same semantics as lookup but skips the intern() call — for use when the caller has already cached the symbol (e.g. via intern_cached).

Trait Implementations

impl Clone for Env

fn clone(&self) -> Env

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Env

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Env

fn default() -> Env

Returns the “default value” for a type.