Crate snix_eval

Source
Expand description

snix-eval implements the evaluation of the Nix programming language in Snix.

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 Snix 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 snix-eval.
nix_search_path ๐Ÿ”’
observer
Implements traits for things that wish to observe internal state changes of snix-eval.
opcode ๐Ÿ”’
This module implements the instruction set running on the abstract machine implemented by snix.
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 Snix bytecode.
warnings ๐Ÿ”’
Implements warnings that are emitted in cases where code passed to Snix 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.
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. 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 Snix 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.