rsaeb 0.7.0

A no_std + alloc interpreter for A=B ordered rewrite programs.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

//! Structured error types for parsing, input validation, running, and tracing.
//!
//! The interpreter reports errors as structured data first. Human-readable text
//! is kept in formatting implementations, so parser and runtime code construct
//! typed reasons instead of scattering presentation strings across the core.
//!
//! The main domains are:
//!
//! - [`ParseError`] for source syntax and parser allocation failures.
//! - [`RuntimeInputError`] for raw input bytes rejected before execution.
//! - [`RunError`] for execution-time allocation, state-size, and budget
//!   failures.
//! - [`TraceSnapshotError`] and the traced run wrappers for trace
//!   materialization or user callback failures.
//! - [`AebError`] for callers that want a parse/input/run umbrella while still
//!   preserving the structured inner error.
//!
//! ```
//! use rsaeb::error::{AebError, RuntimeInputError};
//! use rsaeb::limits::RuntimeInputByteLimit;
//! use rsaeb::RuntimeInput;
//!
//! fn validate(bytes: &[u8]) -> Result<RuntimeInput, AebError> {
//!     RuntimeInput::validate(bytes, RuntimeInputByteLimit::new(8)).map_err(AebError::from)
//! }
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let Err(error) = validate(&[b'a', 0xff]) else {
//!     return Err("expected invalid input".into());
//! };
//!
//! assert!(matches!(
//!     error,
//!     AebError::Input(RuntimeInputError::NonAscii { column, byte })
//!         if column.get() == 2 && byte.get() == 0xff
//! ));
//! # Ok(())
//! # }
//! ```

mod fmt;
mod parse;
mod run;
mod traced;

use core::error::Error;

pub use crate::allocation::{AllocationContext, AllocationError, AllocationErrorKind};
pub use crate::bytes::{
    NonAsciiCodeByte, NonAsciiInputByte, NonPrintableCodeByte, ReservedSyntaxByte,
};
pub use parse::{
    LeftModifierKind, ParseError, ParseErrorKind, ParseErrorLocation, ParseLimitError, PayloadKind,
    RightActionKind,
};
pub use run::{
    InputColumn, LimitError, RunError, RuntimeInputError, StateLimitContext, StateSizeError,
};
pub use traced::{
    FallibleTraceSnapshotRunError, TraceSnapshotError, TraceSnapshotRunError, TracedRunError,
};

/// Top-level source parsing, input validation, and runtime execution error.
///
/// This wrapper is useful at host boundaries that perform parse, input
/// validation, and execution in one operation. It does not erase the underlying
/// domain: callers can still match the inner [`ParseError`],
/// [`RuntimeInputError`], or [`RunError`] variant.
#[derive(Debug, PartialEq, Eq)]
pub enum AebError {
    /// Source program parse error.
    Parse(ParseError),
    /// Runtime input validation error.
    Input(RuntimeInputError),
    /// Runtime execution error.
    Run(RunError),
}

impl Error for AebError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            Self::Parse(error) => Some(error),
            Self::Input(error) => Some(error),
            Self::Run(error) => Some(error),
        }
    }
}

impl From<ParseError> for AebError {
    fn from(value: ParseError) -> Self {
        Self::Parse(value)
    }
}

impl From<RuntimeInputError> for AebError {
    fn from(value: RuntimeInputError) -> Self {
        Self::Input(value)
    }
}

impl From<RunError> for AebError {
    fn from(value: RunError) -> Self {
        Self::Run(value)
    }
}