Enum Value 

pub enum Value {
    I64(i64),
    BigInt(Rc<BigInt>),
    Symbol(Text),
    Str(Text),
    Unit,
    List(Vector<Value>),
    Closure {
        id: u64,
        code: Rc<Lambda>,
        applied: u8,
        env: Env,
    },
    Map(HashTrieMap<Value, Value>),
    Builtin {
        op: Builtin,
        args: Vec<Value>,
    },
    HostFn {
        code: Rc<HostFn>,
        args: Box<[Value]>,
    },
    Module(EnvRef),
    Iota {
        home: EnvRef,
        index: u32,
    },
    Object(Rc<ObjectData>),
}

A runtime value.

Variants

I64(i64)

Machine-word integer: the canonical representation for any integer fitting in i64. Stored inline to avoid allocation on common arithmetic paths. The invariant “an integer is Value::BigInt iff it does not fit i64” ensures well-defined equality and hashing.

BigInt(Rc<BigInt>)

Arbitrary-precision integer for magnitudes outside i64. Stored behind an Rc to keep Value width small and make cloning a refcount bump. Always |n| > i64::MAX per the canonical invariant.

Symbol(Text)

A symbol literal (stored without the leading dot) as owned Text. Rendered with a leading dot.

Str(Text)

An owned, immutable UTF-8 string (Text). Equality and order follow Rust’s &str (lexicographic byte order). Rendered quoted and re-escaped.

Unit

The unit value (). A nullary variant that does not widen Value. Distinct from the empty list.

List(Vector<Value>)

A runtime list backed by an immutable rpds::Vector (O(log n) access, cheap structural-sharing clone/append). The empty list is a List of arity zero, not Unit.

Closure

A closure capturing its environment over shared code. id is a per-runtime unique identity minted at creation; closures compare by identity rather than structure. code is the Lambda (patterns and body); applied tracks bound parameters, so remaining ones are code.head[applied..]. Partial application extends env and increments applied without re-allocating the Lambda.

Fields

id: u64

code: Rc<Lambda>

applied: u8

env: Env

Map(HashTrieMap<Value, Value>)

An immutable, persistent, unordered map from keys to values, backed by rpds::HashTrieMap. Keys are identified by structural value equality. See docs/elly-spec.md § maps.

Builtin

A partially-applied builtin: a native __… operation and its gathered arguments. Invoked when args.len() reaches the op’s arity.

Fields

op: Builtin

args: Vec<Value>

HostFn

A partially-applied host function: a callback provided by the embedder (HostFn) and its gathered arguments. This is the primary FFI boundary in the calling direction.

It is a Value rather than an Expr so it retains meaning regardless of the context it is handed. Identity is the Rc pointer plus applied arguments.

Applied arguments use Box<[Value]> instead of Vec to keep Value width at four words, as pinned by tests/sizes.rs. Both are one allocation per curried step.

Fields

code: Rc<HostFn>

args: Box<[Value]>

Module(EnvRef)

A module instance: the module’s Module terminal. The value is the terminal itself, ensuring the module’s code and its instantiation environment are linked. Applying a symbol materializes the item. Identity is the Rc pointer.

Iota

An iota: an atomic identity declared with const. Equal only to itself. Identity is the pair (instance, position), where home is the instance’s Module terminal and index is the position in ModuleData::iota_names. Derived upon reference; two references to the same iota of one instance are equal.

Fields

home: EnvRef

index: u32

Object(Rc<ObjectData>)

An object: a payload plus the prototype module defining its type (see ObjectData). Built by the __new leaf of the owning module. Applying a symbol dispatches the name by materializing it from the prototype and applying it to the object. Compared by payload contents and prototype identity.

Implementations

impl Value

pub fn from_bigint(n: BigInt) -> Value

Builds an integer value from a BigInt, demoting to Value::I64 if it fits. This maintains the canonical invariant that a BigInt is used only when the value does not fit i64, ensuring consistent equality and hashing.

pub fn from_bigint_ref(n: &BigInt) -> Value

from_bigint for a BigInt reference. Demotion to i64 is decided before cloning to avoid unnecessary allocations for literals fitting in i64.

pub fn host_fn( name: impl Into<Text>, arity: usize, f: impl Fn(&[Value], &Ctx) -> Result<Value, Raised> + 'static, ) -> Value

Creates a Value::HostFn from a callback. Unapplied, so the first argument begins the currying process. Panics on arity == 0.

pub fn list(elems: impl IntoIterator<Item = Value>) -> Value

Creates a list value from its elements. Hides the backing rpds::Vector to avoid version/feature mismatches between the core and the host.

pub fn map(entries: impl IntoIterator<Item = (Value, Value)>) -> Value

Creates a map value from its entries; later entries overwrite equal keys. Hides rpds implementation details.

pub fn list_items(&self) -> Option<impl ExactSizeIterator<Item = &Value>>

Returns the elements of a list value, or None otherwise. Hides rpds implementation details.

pub fn remaining_arity(&self) -> Option<usize>

Returns the number of arguments a function-shaped value needs before it runs. None for non-functions, including applicable values like lists or modules (which use projection, not calls).

Runners use this to detect under-application (see docs/done/2026-08-14_elly-run.md).

pub fn module_data(&self) -> Option<&Rc<ModuleData>>

Returns the ModuleData of a Value::Module, or None. A module value holds the Module terminal; this provides access to the item table without matching the environment shape.

pub fn object_data(&self) -> Option<&Rc<ObjectData>>

Returns the ObjectData of a Value::Object, or None. Provides access to the payload and prototype.

pub fn to_display(&self) -> String

Returns a human-readable rendering for golden tests.

Trait Implementations

impl Clone for Value

fn clone(&self) -> Value

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Value

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

Formats the value using the given formatter.

impl Eq for Value

impl Hash for Value

A Hash consistent with structural PartialEq. A per-variant discriminant prevents collisions between different types (e.g. symbol .0 and integer 0). Map keys hash order-independently by summing the hash of entries.

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Value

Structural value equality used by __eq. Data compares structurally (integers mathematically, symbols/strings by text, lists elementwise, maps by content); callables compare by identity (builtins by operation and arguments, closures by unique id). Different variants are never equal. Total order is not defined; < / > only compare Int / Str.

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.