Struct EvalState 

pub struct EvalState { /* private fields */ }

Implementations

impl EvalState

pub fn new<'a>( store: Store, lookup_path: impl IntoIterator<Item = &'a str>, ) -> Result<Self>

Creates a new EvalState with basic configuration.

For more options, use EvalStateBuilder.

pub unsafe fn raw_ptr(&self) -> *mut EvalState

Returns a raw pointer to the raw Nix C API EvalState.

Safety

The caller must ensure that the pointer is not used beyond the lifetime of this EvalState.

pub fn store(&self) -> &Store

Returns a reference to the Store that’s used for instantiation, import from derivation, etc.

pub fn weak_ref(&self) -> EvalStateWeak

Creates a weak reference to this EvalState.

pub fn eval_from_string(&mut self, expr: &str, path: &str) -> Result<Value>

Parses and evaluates a Nix expression expr.

Expressions can contain relative paths such as ./. that are resolved relative to the given path.

Examples

use nix_bindings_store::store::Store;
use nix_bindings_expr::value::Value;
use std::collections::HashMap;

let v: Value = es.eval_from_string("42", ".")?;
assert_eq!(es.require_int(&v)?, 42);

pub fn force(&mut self, v: &Value) -> Result<()>

Forces evaluation of a value to weak head normal form.

Converts thunks to their evaluated form. Does not modify already-evaluated values.

Does not perform deep evaluation of nested structures.

See also: Shared Evaluation State

pub fn value_type_unforced(&mut self, value: &Value) -> Option<ValueType>

Returns the type of a value without forcing evaluation.

Returns None if the value is an unevaluated thunk.

Returns Some if the value is already evaluated.

See also: Shared Evaluation State

pub fn value_type(&mut self, value: &Value) -> Result<ValueType>

Returns the type of a value, forcing evaluation if necessary.

Forces evaluation if the value is an unevaluated thunk.

Evaluation may fail, producing an Err.

Guarantees a definitive result if Ok, thanks to the language being pure and lazy.

pub fn require_int(&mut self, v: &Value) -> Result<Int>

Extracts the value from an integer Nix value.

Forces evaluation and verifies the value is an integer.

Returns the integer value if successful, or an Err if evaluation failed or the value is not an integer.

Examples

let store = Store::open(None, HashMap::new())?;
let mut es = EvalState::new(store, [])?;

let value = es.eval_from_string("42", "<example>")?;
let int_val = es.require_int(&value)?;
assert_eq!(int_val, 42);

pub fn require_bool(&mut self, v: &Value) -> Result<bool>

Extracts the value from a boolean Nix value.

Forces evaluation and verifies the value is a boolean.

Returns the boolean value if successful, or an Err if evaluation failed or the value is not a boolean.

pub fn require_list_strict<C>(&mut self, value: &Value) -> Result<C>

where C: FromIterator<Value>,

Extracts all elements from a list Nix value.

Forces evaluation and verifies the value is a list.

Returns the contained values in the specified container type (e.g., Vec, VecDeque, etc.).

This is strict - all list elements will be evaluated.

Examples

let vec: Vec<Value> = es.require_list_strict(&list_value)?;
let deque: VecDeque<Value> = es.require_list_strict(&list_value)?;
let linked_list = es.require_list_strict::<LinkedList<Value>>(&list_value)?;

pub fn require_attrs_names(&mut self, v: &Value) -> Result<Vec<String>>

Evaluate, and require that the Value is a Nix ValueType::AttrSet.

Returns a list of the keys in the attrset.

NOTE: this currently implements its own sorting, which probably matches Nix’s implementation, but is not guaranteed.

pub fn require_attrs_names_unsorted(&mut self, v: &Value) -> Result<Vec<String>>

For when EvalState::require_attrs_names isn’t fast enough.

Only use when it’s ok that the keys are returned in an arbitrary order.

pub fn require_attrs_select( &mut self, v: &Value, attr_name: &str, ) -> Result<Value>

Extracts an attribute value from an attribute set Nix value.

Forces evaluation and verifies the value is an attribute set.

Returns the attribute value if found, or an Err if evaluation failed, the attribute doesn’t exist, or the value is not an attribute set.

pub fn require_attrs_select_opt( &mut self, v: &Value, attr_name: &str, ) -> Result<Option<Value>>

Extracts an optional attribute value from an attribute set Nix value.

Forces evaluation and verifies the value is an attribute set.

Returns Err if evaluation failed or the value is not an attribute set.

Returns Ok(None) if the attribute is not present.

Returns Ok(Some(value)) if the attribute is present.

pub fn require_list_size(&mut self, v: &Value) -> Result<u32>

Returns the number of elements in a list Nix value.

Forces evaluation of the list structure and verifies the value is a list.

Individual elements remain as lazy thunks and are not evaluated.

pub fn require_list_select_idx_strict( &mut self, v: &Value, idx: u32, ) -> Result<Option<Value>>

Extracts an element from a list Nix value by index.

Forces evaluation and verifies the value is a list. Forces evaluation of the selected element, similar to Self::require_attrs_select.

Returns Ok(Some(value)) if the element is found.

Returns Ok(None) if the index is out of bounds.

Returns Err if evaluation failed, the element contains an error (e.g., throw), or the value is not a list.

pub fn new_value_str(&mut self, s: &str) -> Result<Value>

Creates a new string Nix value.

Returns a string value without any string context.

pub fn new_value_int(&mut self, i: Int) -> Result<Value>

Creates a new integer Nix value.

pub fn new_value_thunk( &mut self, name: &str, f: Box<dyn Fn(&mut EvalState) -> Result<Value>>, ) -> Result<Value>

Creates a new thunk Nix value.

The thunk will lazily evaluate to the result of the given Rust function when forced. The Rust function will be called with the current EvalState and must not return a thunk.

The name is shown in stack traces.

pub fn require_string(&mut self, value: &Value) -> Result<String>

Extracts a string value from a string Nix value.

Forces evaluation and verifies the value is a string. Returns the string value if successful, or an Err if evaluation failed or the value is not a string.

NOTE: this will be replaced by two methods, one that also returns the context, and one that checks that the context is empty.

pub fn realise_string( &mut self, value: &Value, is_import_from_derivation: bool, ) -> Result<RealisedString>

Realises a string Nix value with context information.

Forces evaluation, verifies the value is a string, and builds any derivations referenced in the string context if required.

pub fn call(&mut self, f: Value, a: Value) -> Result<Value>

Applies a function to an argument and returns the result.

Forces evaluation of the function application. For a lazy version, see Self::new_value_apply.

pub fn call_multi(&mut self, f: &Value, args: &[Value]) -> Result<Value>

Apply a sequence of function applications.

When argument f is a curried function, this applies each argument in sequence. Equivalent to the Nix expression f arg1 arg2 arg3.

Returns a Value in at least weak head normal form if successful.

Returns an Err

• if f did not evaluate to a function
• if f arg1 had any problems
• if f arg1 did not evaluate to a function (for (f arg1) arg2)
• etc

Examples

let store = Store::open(None, HashMap::new())?;
let mut es = EvalState::new(store, [])?;

// Create a curried function: x: y: x + y
let f = es.eval_from_string("x: y: x + y", "<example>")?;
let arg1 = es.eval_from_string("5", "<example>")?;
let arg2 = es.eval_from_string("3", "<example>")?;

// Equivalent to: (x: y: x + y) 5 3
let result = es.call_multi(&f, &[arg1, arg2])?;
let value = es.require_int(&result)?;
assert_eq!(value, 8);

pub fn new_value_apply(&mut self, f: &Value, a: &Value) -> Result<Value>

Applies a function to an argument lazily, creating a thunk.

Does not force evaluation of the function application. For an eager version, see Self::call.

pub fn new_value_primop(&mut self, primop: PrimOp) -> Result<Value>

Creates a new function Nix value implemented by a Rust function.

This is also known as a “primop” in Nix, short for primitive operation. Most of the builtins.* values are examples of primops, but this function does not affect builtins.

pub fn new_value_attrs<I>(&mut self, attrs: I) -> Result<Value>

where I: IntoIterator<Item = (String, Value)>, I::IntoIter: ExactSizeIterator,

Creates a new attribute set Nix value from an iterator of name-value pairs.

Accepts any iterator that yields (String, Value) pairs and has an exact size. Common usage includes Vec, std::collections::HashMap, and array literals.

Examples

let store = Store::open(None, HashMap::new())?;
let mut es = EvalState::new(store, [])?;
let a = es.new_value_int(1)?;
let b = es.new_value_int(2)?;
let c = es.new_value_int(3)?;
let d = es.new_value_int(4)?;

// From array
let attrs1 = es.new_value_attrs([
    ("x".to_string(), a),
    ("y".to_string(), b)
])?;

// From HashMap
let mut map = HashMap::new();
map.insert("foo".to_string(), c);
map.insert("bar".to_string(), d);
let attrs2 = es.new_value_attrs(map)?;

Trait Implementations

impl Clone for EvalState

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.