kaish_kernel/interpreter.rs
1//! Interpreter module for kaish.
2//!
3//! This module provides expression evaluation, variable scope management,
4//! and the structured result type (`$?`) that every command returns.
5//!
6//! # Architecture
7//!
8//! The interpreter is built in layers:
9//!
10//! - **ExecResult**: The structured result of every command, accessible as `$?`
11//! - **Scope**: Variable bindings with nested frames and path resolution
12//! - **Evaluator**: Reduces expressions to values
13//!
14//! # Command Substitution
15//!
16//! `$(pipeline)` expressions are executed by the async evaluator in the kernel
17//! (`kernel.rs`), which resolves them to literal values before any synchronous
18//! expression evaluation runs. The sync [`eval_expr`] evaluator therefore never
19//! sees a `CommandSubst` node; encountering one is a loud error, not a silent
20//! empty string.
21//!
22//! # Example
23//!
24//! ```
25//! use kaish_kernel::interpreter::{Scope, eval_expr};
26//! use kaish_kernel::ast::{Expr, Value};
27//!
28//! let mut scope = Scope::new();
29//! scope.set("X", Value::Int(42));
30//!
31//! let expr = Expr::VarRef(kaish_kernel::ast::VarPath::simple("X"));
32//! let result = eval_expr(&expr, &mut scope).unwrap();
33//! assert_eq!(result, Value::Int(42));
34//! ```
35
36mod control_flow;
37mod eval;
38mod result;
39mod scope;
40
41pub use control_flow::ControlFlow;
42pub use eval::{eval_expr, expand_tilde, is_collection, numeric_compare, resolve_default, resolve_length, scalar_test_operand_error, strip_leading_tabs, structured_boundary_error, structured_export_error, value_defaults_on_emptiness, values_equal, value_to_bool, value_to_exit_code, value_length, value_to_string, value_to_string_with_tilde, value_to_text_sink, value_to_text_sink_named, values_to_text_sink_named, EvalError, EvalResult, Evaluator, HeredocAssembler};
43pub use result::{apply_output_format, hex_dump, json_to_value, json_to_value_no_envelope, value_to_json, EntryType, ExecResult, OutputData, OutputFormat, OutputNode, OutputPayload};
44pub use scope::{PathError, Scope};
45// Crate-internal: the reduced sync evaluator (scheduler/pipeline.rs) reuses the
46// resolver error-message shape without widening the public API.
47pub(crate) use eval::format_path;