Crate tvix_eval

tvix-eval implements the evaluation of the Nix programming language in Tvix.

It is designed to allow users to use Nix as a versatile language for different use-cases.

This module exports the high-level functions and types needed for evaluating Nix code and interacting with the language’s data structures.

Nix has several language features that make use of impurities (such as reading from the NIX_PATH environment variable, or interacting with files). These features are optional and the API of this crate exposes functionality for controlling how they work.

Re-exports

• pub use builtin_macros;

Modules

• builtins
  This module implements the builtins exposed in the Nix language.
• chunk 🔒
• compiler 🔒
  This module implements a compiler for compiling the rnix AST representation to Tvix bytecode.
• errors 🔒
• generators
  This module implements generator logic for the VM. Generators are functions used during evaluation which can suspend their execution during their control flow, and request that the VM do something.
• io 🔒
  Interface for injecting I/O-related functionality into tvix-eval.
• nix_search_path 🔒
• observer
  Implements traits for things that wish to observe internal state changes of tvix-eval.
• opcode 🔒
  This module implements the instruction set running on the abstract machine implemented by tvix.
• pretty_ast 🔒
  Pretty-printed format for the rnix AST representation.
• source 🔒
  This module contains utilities for dealing with the codemap that needs to be carried across different compiler instantiations in an evaluation.
• spans 🔒
  Utilities for dealing with span tracking in the compiler and in error reporting.
• systems 🔒
• upvalues 🔒
  This module encapsulates some logic for upvalue handling, which is relevant to both thunks (delayed computations for lazy-evaluation) as well as closures (lambdas that capture variables from the surrounding scope).
• value 🔒
  This module implements the backing representation of runtime values in the Nix language.
• vm 🔒
  This module implements the abstract/virtual machine that runs Tvix bytecode.
• warnings 🔒
  Implements warnings that are emitted in cases where code passed to Tvix exhibits problems that the user could address.

Macros

• arithmetic_op
  This module provides macros which are used in the implementation of the VM for the implementation of repetitive operations. This macro simplifies the implementation of arithmetic operations, correctly handling the behaviour on different pairings of number types.
• cmp_op
  This macro simplifies the implementation of comparison operations.
• lifted_pop

Structs

• BuilderBuiltins 🔒
• Builtin
  Represents a single built-in function which directly executes Rust code that operates on a Nix value.
• CoercionKind
  Describes what input types are allowed when coercing a Value to a string
• CompilationOutput
  Represents the result of compiling a piece of Nix code. If compilation was successful, the resulting bytecode can be passed to the VM.
• DummyIO
  Dummy implementation of EvalIO, can be used in contexts where IO is not available but code should “pretend” that it is.
• Error
• EvalWarning
• Evaluation
  An Evaluation represents how a piece of Nix code is evaluated. It can be instantiated and configured directly, or it can be accessed through the various simplified helper methods available below.
• EvaluationBuilder
  Builder for building an Evaluation.
• EvaluationResult
  Result of evaluating a piece of Nix code. If evaluation succeeded, a value will be present (and potentially some warnings!). If evaluation failed, errors will be present.
• NixAttrs
• NixContext
  Nix context strings representation in Tvix. This tracks a set of different kinds of string dependencies that we can come across during manipulation of our language primitives, mostly strings. There’s some simple algebra of context strings and how they propagate w.r.t. primitive operations, e.g. concatenation, interpolation and other string operations.
• NixList
• NixString
  Nix string values
• SourceCode
  Tracks all source code in a Tvix evaluation for accurate error reporting.
• StdIO
  Implementation of EvalIO that simply uses the equivalent standard library functions, i.e. does local file-IO.

Enums

• BuilderGlobals 🔒
• CatchableErrorKind
  “CatchableErrorKind” errors – those which can be detected by builtins.tryEval.
• ErrorKind
• EvalMode
  Specification for how to handle top-level values returned by evaluation
• FileType
  Types of files as represented by builtins.readFileType and builtins.readDir in Nix.
• NixContextElement
• Value
• WarningKind

Traits

• AddContext
• EvalIO
  Represents all possible filesystem interactions that exist in the Nix language, and that need to be executed somehow.

Functions

• compile
• parse_compile_internal 🔒
  Internal helper function for common parsing & compilation logic between the public functions.
• prepare_globals
  Prepare the full set of globals available in evaluated code. These are constructed from the set of builtins supplied by the caller, which are made available globally under the builtins identifier.
• pretty_print_expr

Type Aliases

• EvalResult
• GlobalsMap
  The map of globally available functions and other values that should implicitly be resolvable in the global scope.