ferth 0.2.0

A safe, native-sized Forth. no_std compatible.
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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

/// The result type of the inner interpreter.
pub type VmResult<T> = core::result::Result<T, VmError>;

/// An error raised by the inner interpreter.
#[derive(Debug, PartialEq)]
pub enum VmError {
    /// The data stack overflowed.
    StackOverflow,
    /// The data stack underflowed.
    StackUnderflow,
    /// The return stack overflowed.
    ReturnStackOverflow,
    /// The return stack underflowed.
    ReturnStackUnderflow,
    /// The address is out of range.
    AddressOutOfRange(usize),
    /// The address is not aligned to the cell size.
    AddressMisaligned(usize),
    /// Irrecoverable. The opcode is not valid.
    InvalidOpCode(u8),
    /// Attempted to divide by zero.
    DivisionByZero,
    ParsedStringOverflow,
    InvalidEscape(u8),
    /// The memory is too small for the VM state.
    ///
    /// Contains the minimum memory size in bytes.
    MemoryTooSmall(usize),
}

impl core::error::Error for VmError {}

impl core::fmt::Display for VmError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        let w = core::mem::size_of::<usize>() * 2;
        match self {
            Self::StackOverflow => write!(f, "stack overflow"),
            Self::StackUnderflow => write!(f, "stack underflow"),
            Self::ReturnStackOverflow => write!(f, "return stack overflow"),
            Self::ReturnStackUnderflow => write!(f, "return stack underflow"),
            Self::AddressOutOfRange(addr) => {
                write!(f, "address out of range: 0x{:0width$x}", addr, width = w)
            }
            Self::AddressMisaligned(addr) => {
                write!(f, "address misaligned: 0x{:0width$x}", addr, width = w)
            }
            Self::InvalidOpCode(op) => write!(f, "invalid opcode: 0x{op:02x}"),
            Self::DivisionByZero => write!(f, "division by zero"),
            Self::ParsedStringOverflow => write!(f, "parsed string overflow"),
            Self::InvalidEscape(c) => write!(f, "invalid escape: 0x{c:02x}"),
            Self::MemoryTooSmall(n) => write!(f, "memory must be at least {n} bytes"),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn width() -> usize {
        core::mem::size_of::<usize>() * 2
    }

    #[test]
    fn display_stack_overflow() {
        assert_eq!(VmError::StackOverflow.to_string(), "stack overflow");
    }

    #[test]
    fn display_stack_underflow() {
        assert_eq!(VmError::StackUnderflow.to_string(), "stack underflow");
    }

    #[test]
    fn display_return_stack_overflow() {
        assert_eq!(
            VmError::ReturnStackOverflow.to_string(),
            "return stack overflow"
        );
    }

    #[test]
    fn display_return_stack_underflow() {
        assert_eq!(
            VmError::ReturnStackUnderflow.to_string(),
            "return stack underflow"
        );
    }

    #[test]
    fn display_address_out_of_range() {
        let addr = 0xcafe;
        assert_eq!(
            VmError::AddressOutOfRange(addr).to_string(),
            format!("address out of range: 0x{:0width$x}", addr, width = width())
        );
    }

    #[test]
    fn display_address_misaligned() {
        let addr = 0x0003;
        assert_eq!(
            VmError::AddressMisaligned(addr).to_string(),
            format!("address misaligned: 0x{:0width$x}", addr, width = width())
        );
    }

    #[test]
    fn display_invalid_opcode() {
        assert_eq!(
            VmError::InvalidOpCode(0xab).to_string(),
            "invalid opcode: 0xab"
        );
    }

    #[test]
    fn display_division_by_zero() {
        assert_eq!(VmError::DivisionByZero.to_string(), "division by zero");
    }
}