Struct Aether 

pub struct Aether { /* private fields */ }

Main Aether engine struct

Implementations

impl Aether

pub fn new() -> Self

Create a new Aether engine instance

For DSL embedding: IO operations are disabled by default for security. Use with_permissions() or with_all_permissions() to enable IO.

For CLI usage: The command-line tool uses with_all_permissions() by default.

pub fn with_permissions(permissions: IOPermissions) -> Self

Create a new Aether engine with custom IO permissions

pub fn with_all_permissions() -> Self

Create a new Aether engine with all IO permissions enabled

pub fn with_stdlib() -> Result<Self, String>

Create a new Aether engine with standard library preloaded

This creates an engine with all permissions and automatically loads all standard library modules (string_utils, array_utils, validation, datetime, testing).

pub fn load_stdlib_module(&mut self, module_name: &str) -> Result<(), String>

Load a specific standard library module

Available modules: “string_utils”, “array_utils”, “validation”, “datetime”, “testing”

pub fn load_all_stdlib(&mut self) -> Result<(), String>

Load all standard library modules

pub fn with_limits(self, limits: ExecutionLimits) -> Self

Create a new Aether engine with execution limits

pub fn set_limits(&mut self, limits: ExecutionLimits)

Set execution limits

pub fn limits(&self) -> &ExecutionLimits

Get current execution limits

pub fn with_stdlib_string_utils(self) -> Result<Self, String>

Load string utilities module (chainable)

pub fn with_stdlib_array_utils(self) -> Result<Self, String>

Load array utilities module (chainable)

pub fn with_stdlib_validation(self) -> Result<Self, String>

Load validation module (chainable)

pub fn with_stdlib_datetime(self) -> Result<Self, String>

Load datetime module (chainable)

pub fn with_stdlib_testing(self) -> Result<Self, String>

Load testing framework module (chainable)

pub fn with_stdlib_set(self) -> Result<Self, String>

Load set data structure module (chainable)

pub fn with_stdlib_queue(self) -> Result<Self, String>

Load queue data structure module (chainable)

pub fn with_stdlib_stack(self) -> Result<Self, String>

Load stack data structure module (chainable)

pub fn with_stdlib_heap(self) -> Result<Self, String>

Load heap data structure module (chainable)

pub fn with_stdlib_sorting(self) -> Result<Self, String>

Load sorting algorithms module (chainable)

pub fn with_stdlib_json(self) -> Result<Self, String>

Load JSON processing module (chainable)

pub fn with_stdlib_csv(self) -> Result<Self, String>

Load CSV processing module (chainable)

pub fn with_stdlib_functional(self) -> Result<Self, String>

Load functional programming utilities module (chainable)

pub fn with_stdlib_cli_utils(self) -> Result<Self, String>

Load CLI utilities module (chainable)

pub fn with_stdlib_text_template(self) -> Result<Self, String>

Load text template engine module (chainable)

pub fn with_stdlib_regex_utils(self) -> Result<Self, String>

Load regex utilities module (chainable)

pub fn eval(&mut self, code: &str) -> Result<Value, String>

Evaluate Aether code and return the result

pub fn eval_report(&mut self, code: &str) -> Result<Value, ErrorReport>

Evaluate Aether code and return a structured error report on failure.

This is intended for integrations that need machine-readable diagnostics.

pub fn take_trace(&mut self) -> Vec<String>

Drain the in-memory TRACE buffer.

This is designed for DSL-safe debugging: scripts call TRACE(...) to record values, and the host application reads them out-of-band via this method.

pub fn clear_trace(&mut self)

Clear the TRACE buffer without returning it.

pub fn trace_records(&self) -> Vec<TraceEntry>

Get all structured trace entries (Stage 3.2)

Returns a vector of structured trace entries with levels, categories, timestamps, etc.

pub fn trace_by_level(&self, level: TraceLevel) -> Vec<TraceEntry>

Filter trace entries by level (Stage 3.2)

Example

let error_traces = engine.trace_by_level(crate::runtime::TraceLevel::Error);

pub fn trace_by_category(&self, category: &str) -> Vec<TraceEntry>

Filter trace entries by category (Stage 3.2)

Example

let api_traces = engine.trace_by_category("api_call");

pub fn trace_by_label(&self, label: &str) -> Vec<TraceEntry>

Filter trace entries by label (Stage 3.2)

Example

let slow_traces = engine.trace_by_label("slow_request");

pub fn trace_filter(&self, filter: &TraceFilter) -> Vec<TraceEntry>

Apply complex filter to trace entries (Stage 3.2)

Example

use crate::runtime::{TraceFilter, TraceLevel};
use std::time::Instant;

let filter = TraceFilter::new()
    .with_min_level(TraceLevel::Warn)
    .with_category("api".to_string());
let filtered = engine.trace_filter(&filter);

pub fn trace_stats(&self) -> TraceStats

Get trace statistics (Stage 3.2)

Returns statistics about trace entries, including counts by level and category.

pub fn set_trace_buffer_size(&mut self, _size: usize)

Set TRACE buffer size (Stage 3.2)

Note: This method is a placeholder for future implementation. Currently, the buffer size is fixed at 1024 entries.

pub fn set_module_resolver(&mut self, resolver: Box<dyn ModuleResolver>)

Configure the module resolver used for Import/Export.

By default (DSL embedding), the resolver is disabled for safety.

pub fn push_import_base(&mut self, module_id: String, base_dir: Option<PathBuf>)

Push a base directory context for resolving relative imports.

This is typically used by a file-based runner (CLI) before calling eval().

pub fn pop_import_base(&mut self)

Pop the most recent base directory context.

pub fn eval_file(&mut self, path: impl AsRef<Path>) -> Result<Value, String>

Evaluate an Aether script from a file path.

This is a convenience wrapper that:

• reads the file
• pushes an import base context (module_id = canonical path; base_dir = parent dir)
• evaluates the code
• pops the import base context

Note: this does not enable any module resolver. For DSL safety, module loading remains disabled unless you explicitly call set_module_resolver(...).

pub fn eval_file_report( &mut self, path: impl AsRef<Path>, ) -> Result<Value, ErrorReport>

Evaluate an Aether script from a file path, returning a structured error report on failure.

pub fn set_global(&mut self, name: &str, value: Value)

Set a global variable from the host application without using eval().

This is useful when you already have Rust-side data and want to inject it as Value into the script environment.

pub fn reset_env(&mut self)

Reset the runtime environment (variables/functions) while keeping built-ins registered.

Note: this clears anything that was introduced via eval() (including stdlib code).

pub fn with_isolated_scope<R>( &mut self, f: impl FnOnce(&mut Aether) -> Result<R, String>, ) -> Result<R, String>

Run a closure inside an isolated child scope.

All variables/functions you inject or define inside the closure will be dropped when it returns, while the outer environment is preserved.

This is designed for the “DSL host” scenario: inject Rust data + load per-request Aether functions (e.g. from DB) + run the script, without cross-request pollution.

pub fn cache_stats(&self) -> CacheStats

获取缓存统计信息

pub fn clear_cache(&mut self)

清空缓存

pub fn set_optimization( &mut self, constant_folding: bool, dead_code: bool, tail_recursion: bool, )

设置优化选项

Trait Implementations

impl Default for Aether

fn default() -> Self

Returns the “default value” for a type.