ternaria_isa/

asm.rs

//! A small text assembler.
//!
//! Mnemonics and operand shapes are read from [`TABLE`] rather
//! than from a list kept here, so the two cannot disagree. Adding an
//! instruction to the `isa!` block makes it assemblable with no change here.
//!
//! # Syntax
//!
//! ```text
//! ; comments start with ; or #
//! start:                      ; a label
//!     addi r1, r0, 10         ; registers are r-13 .. r13
//! loop:
//!     addi r1, r1, -1
//!     br3  r1, loop           ; a label operand becomes a relative offset
//!     halt
//! ```
//!
//! A label used as an immediate resolves to the offset in instructions from
//! the instruction referencing it. See [`ImmUnit`](crate::ImmUnit) for the
//! units each instruction uses. Operands are separated by commas, whitespace,
//! or both.
//!
//! # Named constants
//!
//! `.equ NAME, VALUE` binds a name to an absolute value. This is the difference
//! between an equate and a label: a label resolves to an offset from the
//! instruction that names it, an equate resolves to the value itself.
//!
//! ```text
//! .equ CONSOLE_BASE, -19683
//!     addi r1, r0, CONSOLE_BASE
//! ```
//!
//! A name used as an immediate may carry a displacement: `BLOCK_WINDOW+1` is
//! one more than the value of `BLOCK_WINDOW`. Only a single literal offset is
//! accepted; this is not an expression language.
//!
//! Directives occupy no space in the program. A name may not be both an equate
//! and a label. Device addresses are the main use: a crate that defines a
//! device can emit the matching `.equ` lines so guest programs and the host
//! agree by construction rather than by a literal copied into both.
//!
//! # Absolute label references
//!
//! `@label` resolves to the tryte address of a label rather than the distance
//! to it. A trap vector needs this, since the handler's location must not
//! depend on where the instruction naming it happens to sit.
//!
//! ```text
//!     addi r1, r0, @handler
//!     csrw r1, TVEC
//! ```
//!
//! The address is measured from the base the program is assembled for, which
//! is zero unless [`assemble_at`] is given another.
//!
//! # br3 and its two targets
//!
//! `br3` reaches two targets from one immediate, mirrored about the branch: it
//! adds the immediate when the register is positive and subtracts it when the
//! register is negative. Two forms are accepted.
//!
//! ```text
//! br3 rs1, label              ; label is the POSITIVE target
//! br3 rs1, neg_lbl, pos_lbl   ; both named; the assembler checks the mirror
//! ```
//!
//! The one-label form suits a loop, where the label is behind the branch and
//! only the positive case is reachable. The two-label form suits dispatch on
//! [`Opcode::Cmp3`], and fails at assembly time if the
//! targets are not mirrored rather than branching the wrong way at runtime.
//!
//! Where the targets cannot be mirrored, use `brn` and `brp`, which take one
//! target each over the full immediate range.

use crate::{Format, IMM_MAX, Imm, Instruction, Opcode, REG_MAX, Reg, TABLE};
use std::collections::BTreeMap;
use std::fmt;

/// What went wrong, and where.
#[derive(Clone, PartialEq, Eq, Debug)]
pub struct AsmError {
    /// Source line number, counting from 1.
    pub line: usize,
    /// What went wrong.
    pub kind: AsmErrorKind,
}

/// The kinds of assembly failure.
#[derive(Clone, PartialEq, Eq, Debug)]
pub enum AsmErrorKind {
    /// No instruction has this mnemonic.
    UnknownMnemonic(String),
    /// Wrong number of operands for the instruction's format.
    WrongOperandCount {
        /// The instruction.
        mnemonic: &'static str,
        /// How many it needs.
        expected: usize,
        /// How many it got.
        got: usize,
    },
    /// An operand that should have been a register was not.
    BadRegister(String),
    /// An operand that should have been an immediate or label was not.
    BadImmediate(String),
    /// A label operand that never appears as a definition.
    UndefinedLabel(String),
    /// The same label defined twice.
    DuplicateLabel(String),
    /// The two `br3` targets are not mirrored about the branch.
    Br3NotMirrored {
        /// Instruction index of the negative target.
        neg: i64,
        /// Instruction index of the negative target that would be reached.
        reachable: i64,
        /// Instruction index of the positive target.
        pos: i64,
    },
    /// The same name given to two `.equ` directives, or to an `.equ` and a
    /// label.
    DuplicateEquate(String),
    /// An `.equ` directive whose operands are not a name and a number.
    BadEquate(String),
    /// A resolved offset or literal does not fit twelve trits.
    ImmediateOutOfRange {
        /// The value that did not fit.
        value: i64,
    },
}

impl fmt::Display for AsmError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "line {}: ", self.line)?;
        match &self.kind {
            AsmErrorKind::UnknownMnemonic(m) => write!(f, "unknown instruction {m:?}"),
            AsmErrorKind::WrongOperandCount {
                mnemonic,
                expected,
                got,
            } => {
                write!(f, "{mnemonic} takes {expected} operand(s), found {got}")
            }
            AsmErrorKind::BadRegister(t) => {
                write!(f, "expected a register like r0 or r-13, found {t:?}")
            }
            AsmErrorKind::BadImmediate(t) => write!(f, "expected a number or label, found {t:?}"),
            AsmErrorKind::UndefinedLabel(l) => write!(f, "undefined label {l:?}"),
            AsmErrorKind::DuplicateLabel(l) => write!(f, "label {l:?} defined twice"),
            AsmErrorKind::DuplicateEquate(n) => write!(f, "name {n:?} defined twice"),
            AsmErrorKind::BadEquate(t) => {
                write!(f, "expected `.equ NAME, VALUE`, found {t:?}")
            }
            AsmErrorKind::Br3NotMirrored {
                neg,
                reachable,
                pos,
            } => write!(
                f,
                "br3 targets must be mirrored about the branch: with the \
                 positive target at instruction {pos}, the negative branch \
                 reaches {reachable}, not {neg}. Use brn and brp for targets \
                 that cannot be mirrored."
            ),
            AsmErrorKind::ImmediateOutOfRange { value } => {
                write!(f, "immediate {value} does not fit 12 trits (+/-{IMM_MAX})")
            }
        }
    }
}

impl std::error::Error for AsmError {}

/// An assembled program.
#[derive(Clone, PartialEq, Eq, Debug, Default)]
pub struct Program {
    /// The instructions, in order.
    pub instructions: Vec<Instruction>,
    /// Label name to instruction index.
    pub labels: BTreeMap<String, usize>,
    /// Name to value, from `.equ` directives.
    pub equates: BTreeMap<String, i64>,
}

/// How many operands a format takes.
const fn operand_count(f: Format) -> usize {
    match f {
        Format::R => 3,
        Format::I => 3,
        Format::U => 2,
        Format::B => 2,
        Format::J => 2,
        Format::N => 0,
    }
}

/// Strips comments and surrounding whitespace.
fn clean(line: &str) -> &str {
    let cut = line.find([';', '#']).unwrap_or(line.len());
    line[..cut].trim()
}

/// Splits operands on commas and whitespace.
fn operands(s: &str) -> Vec<&str> {
    s.split([',', ' ', '\t'])
        .map(str::trim)
        .filter(|t| !t.is_empty())
        .collect()
}

fn parse_reg(tok: &str, line: usize) -> Result<Reg, AsmError> {
    let err = || AsmError {
        line,
        kind: AsmErrorKind::BadRegister(tok.to_string()),
    };
    let rest = tok
        .strip_prefix('r')
        .or_else(|| tok.strip_prefix('R'))
        .ok_or_else(err)?;
    let n: i64 = rest.parse().map_err(|_| err())?;
    if n < -(REG_MAX as i64) || n > REG_MAX as i64 {
        return Err(err());
    }
    Reg::new(n as i8).ok_or_else(err)
}

/// Splits a trailing `+k` or `-k` off an operand.
///
/// Only one displacement is accepted and it must be a literal, so this is an
/// offset from a name rather than an expression language. Anything more
/// belongs in the program's own arithmetic, where it can be seen.
fn split_displacement(tok: &str, line: usize) -> Result<(&str, i64), AsmError> {
    // Skip position 0 so that a negative literal is not split into nothing.
    let cut = tok
        .rfind(['+', '-'])
        // Position 0 is a sign on a literal, not a displacement.
        .filter(|i| *i > 0);
    let Some(cut) = cut else {
        return Ok((tok, 0));
    };
    let (name, rest) = tok.split_at(cut);
    let sign = if rest.starts_with('-') { -1 } else { 1 };
    let magnitude: i64 = rest[1..].parse().map_err(|_| AsmError {
        line,
        kind: AsmErrorKind::BadImmediate(tok.to_string()),
    })?;
    Ok((name, sign * magnitude))
}

/// The text after `.equ`, if the line is an `.equ` directive.
fn equate_body(text: &str) -> Option<&str> {
    let rest = text
        .strip_prefix(".equ")
        .or_else(|| text.strip_prefix(".EQU"))?;
    // Reject `.equations`: the directive must be a whole word.
    if rest.is_empty() || rest.starts_with([' ', '\t']) {
        Some(rest.trim())
    } else {
        None
    }
}

/// Parses the name and value of an `.equ` directive.
fn parse_equate(body: &str, line: usize) -> Result<(String, i64), AsmError> {
    let err = || AsmError {
        line,
        kind: AsmErrorKind::BadEquate(body.to_string()),
    };
    let toks = operands(body);
    if toks.len() != 2 {
        return Err(err());
    }
    let name = toks[0];
    if !name.starts_with(|c: char| c.is_ascii_alphabetic() || c == '_')
        || !name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
    {
        return Err(err());
    }
    let value: i64 = toks[1].parse().map_err(|_| err())?;
    Ok((name.to_string(), value))
}

fn lookup(mnemonic: &str) -> Option<Opcode> {
    TABLE
        .iter()
        .find(|e| e.mnemonic.eq_ignore_ascii_case(mnemonic))
        .map(|e| e.opcode)
}

/// Assembles source text.
///
/// Two passes. The first records where each label lands; the second emits
/// instructions and resolves label references. One pass is insufficient because
/// a forward branch names a label defined later.
pub fn assemble(source: &str) -> Result<Program, AsmError> {
    assemble_at(source, 0)
}

/// Assembles source that will be loaded at tryte address `base`.
///
/// `base` is what an absolute label reference resolves against. A program
/// loaded at the reset vector uses zero, which is what [`assemble`] passes.
pub fn assemble_at(source: &str, base: i64) -> Result<Program, AsmError> {
    // Pass one: label positions, measured in instructions, and `.equ` values.
    // Directives occupy no space, so they do not advance the index.
    let mut labels: BTreeMap<String, usize> = BTreeMap::new();
    let mut equates: BTreeMap<String, i64> = BTreeMap::new();
    let mut index = 0usize;
    for (n, raw) in source.lines().enumerate() {
        let line = n + 1;
        let mut text = clean(raw);
        if let Some(rest) = equate_body(text) {
            let (name, value) = parse_equate(rest, line)?;
            if equates.insert(name.clone(), value).is_some() {
                return Err(AsmError {
                    line,
                    kind: AsmErrorKind::DuplicateEquate(name),
                });
            }
            continue;
        }
        // A line may carry a label and an instruction: `loop: addi r1, r1, -1`
        while let Some(colon) = text.find(':') {
            let name = text[..colon].trim().to_string();
            if labels.insert(name.clone(), index).is_some() {
                return Err(AsmError {
                    line,
                    kind: AsmErrorKind::DuplicateLabel(name),
                });
            }
            text = text[colon + 1..].trim();
        }
        if !text.is_empty() {
            index += 1;
        }
    }

    // A name that is both an equate and a label would resolve two ways.
    if let Some(name) = labels.keys().find(|k| equates.contains_key(*k)) {
        return Err(AsmError {
            line: 0,
            kind: AsmErrorKind::DuplicateEquate(name.clone()),
        });
    }

    // Pass two: emit.
    let mut program = Program {
        instructions: Vec::new(),
        labels,
        equates,
    };
    let mut index = 0usize;
    for (n, raw) in source.lines().enumerate() {
        let line = n + 1;
        let mut text = clean(raw);
        if equate_body(text).is_some() {
            continue;
        }
        while let Some(colon) = text.find(':') {
            text = text[colon + 1..].trim();
        }
        if text.is_empty() {
            continue;
        }

        let (mnemonic, rest) = match text.find([' ', '\t']) {
            Some(i) => (&text[..i], &text[i..]),
            None => (text, ""),
        };
        let op = lookup(mnemonic).ok_or_else(|| AsmError {
            line,
            kind: AsmErrorKind::UnknownMnemonic(mnemonic.to_string()),
        })?;
        let fmt = op.format();
        let toks = operands(rest);
        let want = operand_count(fmt);
        let br3_pair = op == Opcode::Br3 && toks.len() == 3;
        if toks.len() != want && !br3_pair {
            return Err(AsmError {
                line,
                kind: AsmErrorKind::WrongOperandCount {
                    mnemonic: op.mnemonic(),
                    expected: want,
                    got: toks.len(),
                },
            });
        }

        // Resolves a token that may be a decimal literal or a label. A label
        // becomes the offset in instructions from this instruction.
        let imm_of = |tok: &str| -> Result<Imm, AsmError> {
            // A name may carry a small displacement: `BLOCK_WINDOW+1`. Device
            // registers sit one tryte apart, and writing the neighbour as a
            // literal reintroduces exactly the drift named constants remove.
            let (tok, displacement) = split_displacement(tok, line)?;
            let value: i64 = if let Ok(v) = tok.parse::<i64>() {
                v
            } else if let Some(name) = tok.strip_prefix('@') {
                // The address of a label rather than the distance to it. A
                // trap vector needs this: the handler's location does not
                // depend on where the instruction naming it happens to sit.
                let &target = program.labels.get(name).ok_or(AsmError {
                    line,
                    kind: AsmErrorKind::UndefinedLabel(name.to_string()),
                })?;
                base + target as i64 * crate::WORD_TRYTES
            } else if let Some(&v) = program.equates.get(tok) {
                // An equate is an absolute value, unlike a label.
                v
            } else if let Some(&target) = program.labels.get(tok) {
                target as i64 - index as i64
            } else if tok.starts_with(|c: char| c.is_ascii_alphabetic() || c == '_') {
                return Err(AsmError {
                    line,
                    kind: AsmErrorKind::UndefinedLabel(tok.to_string()),
                });
            } else {
                return Err(AsmError {
                    line,
                    kind: AsmErrorKind::BadImmediate(tok.to_string()),
                });
            };
            let value = value + displacement;
            Imm::new(value as i32)
                .filter(|_| value.abs() <= IMM_MAX as i64)
                .ok_or(AsmError {
                    line,
                    kind: AsmErrorKind::ImmediateOutOfRange { value },
                })
        };

        // br3 reaches two targets from one immediate, mirrored about the
        // branch. Naming both lets the assembler check the mirror holds
        // instead of silently emitting a branch that goes the wrong way.
        if br3_pair {
            let rs1 = parse_reg(toks[0], line)?;
            let resolve = |tok: &str| -> Result<i64, AsmError> {
                program.labels.get(tok).map(|i| *i as i64).ok_or(AsmError {
                    line,
                    kind: AsmErrorKind::UndefinedLabel(tok.to_string()),
                })
            };
            let neg = resolve(toks[1])?;
            let pos = resolve(toks[2])?;
            let here = index as i64;
            let reachable = 2 * here - pos;
            if neg != reachable {
                return Err(AsmError {
                    line,
                    kind: AsmErrorKind::Br3NotMirrored {
                        neg,
                        reachable,
                        pos,
                    },
                });
            }
            let offset = pos - here;
            let imm = Imm::new(offset as i32)
                .filter(|_| offset.abs() <= IMM_MAX as i64)
                .ok_or(AsmError {
                    line,
                    kind: AsmErrorKind::ImmediateOutOfRange { value: offset },
                })?;
            program.instructions.push(Instruction::b(op, rs1, imm));
            index += 1;
            continue;
        }

        let instr = match fmt {
            Format::R => Instruction::r(
                op,
                parse_reg(toks[0], line)?,
                parse_reg(toks[1], line)?,
                parse_reg(toks[2], line)?,
            ),
            Format::I => Instruction::i(
                op,
                parse_reg(toks[0], line)?,
                parse_reg(toks[1], line)?,
                imm_of(toks[2])?,
            ),
            Format::U => Instruction::u(op, parse_reg(toks[0], line)?, parse_reg(toks[1], line)?),
            Format::B => Instruction::b(op, parse_reg(toks[0], line)?, imm_of(toks[1])?),
            Format::J => Instruction::j(op, parse_reg(toks[0], line)?, imm_of(toks[1])?),
            Format::N => Instruction::n(op),
        };

        program.instructions.push(instr);
        index += 1;
    }

    Ok(program)
}

/// Disassembles a run of instructions, one per line, with indices.
pub fn disassemble(instructions: &[Instruction]) -> String {
    instructions
        .iter()
        .enumerate()
        .map(|(i, ins)| format!("{i:>4}  {ins}"))
        .collect::<Vec<_>>()
        .join("\n")
}

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

    #[test]
    fn assembles_every_format() {
        let src = "
            nop
            add  r1, r2, r3
            addi r4, r0, -100
            neg  r5, r6
            br3  r7, 4
            jal  r8, -2
            halt
        ";
        let p = assemble(src).unwrap();
        assert_eq!(p.instructions.len(), 7);
        assert_eq!(p.instructions[1].to_string(), "add r1, r2, r3");
        assert_eq!(p.instructions[2].to_string(), "addi r4, r0, -100");
        assert_eq!(p.instructions[4].to_string(), "br3 r7, 4");
    }

    #[test]
    fn labels_resolve_to_relative_instruction_offsets() {
        let src = "
        top:
            addi r1, r0, 3
        loop:
            addi r1, r1, -1
            br3  r1, loop
            jal  r0, top
            halt
        ";
        let p = assemble(src).unwrap();
        assert_eq!(p.labels["top"], 0);
        assert_eq!(p.labels["loop"], 1);
        // br3 sits at index 2 and targets index 1, so the offset is -1.
        assert_eq!(p.instructions[2].imm.value(), -1);
        // jal sits at index 3 and targets index 0, so -3.
        assert_eq!(p.instructions[3].imm.value(), -3);
    }

    #[test]
    fn a_label_may_share_a_line_with_an_instruction() {
        let p = assemble("loop: addi r1, r1, -1\n      br3 r1, loop").unwrap();
        assert_eq!(p.labels["loop"], 0);
        assert_eq!(p.instructions.len(), 2);
        assert_eq!(p.instructions[1].imm.value(), -1);
    }

    #[test]
    fn comments_and_blank_lines_are_ignored() {
        let p = assemble("; leading\n\n  nop  # trailing\n\n; done\n").unwrap();
        assert_eq!(p.instructions.len(), 1);
    }

    #[test]
    fn round_trips_through_the_disassembler() {
        let src = "add r1, r-2, r13\naddi r0, r5, 265720\nneg r7, r-13\nhalt";
        let p = assemble(src).unwrap();

        // Assemble -> disassemble -> assemble must reach the same instruction.
        // Comparing the instructions, not just the count, is the point: an
        // earlier version of this test only checked that something parsed,
        // which would have passed even if the text said the wrong thing.
        for instr in &p.instructions {
            let text = instr.to_string();
            let again = assemble(&text).unwrap();
            assert_eq!(again.instructions.len(), 1, "{text}");
            assert_eq!(&again.instructions[0], instr, "{text}");
        }

        // The indexed listing is one line per instruction.
        assert_eq!(
            disassemble(&p.instructions).lines().count(),
            p.instructions.len()
        );
    }

    #[test]
    fn errors_carry_line_numbers() {
        let e = assemble("nop\nfrobnicate r1, r2, r3").unwrap_err();
        assert_eq!(e.line, 2);
        assert!(matches!(e.kind, AsmErrorKind::UnknownMnemonic(_)));

        let e = assemble("add r1, r2").unwrap_err();
        assert!(matches!(
            e.kind,
            AsmErrorKind::WrongOperandCount {
                expected: 3,
                got: 2,
                ..
            }
        ));

        let e = assemble("add r1, r2, x9").unwrap_err();
        assert!(matches!(e.kind, AsmErrorKind::BadRegister(_)));

        let e = assemble("br3 r1, nowhere").unwrap_err();
        assert!(matches!(e.kind, AsmErrorKind::UndefinedLabel(_)));

        let e = assemble("a: nop\na: nop").unwrap_err();
        assert!(matches!(e.kind, AsmErrorKind::DuplicateLabel(_)));

        let e = assemble("addi r1, r0, 300000").unwrap_err();
        assert!(matches!(e.kind, AsmErrorKind::ImmediateOutOfRange { .. }));

        let e = assemble("add r1, r2, r99").unwrap_err();
        assert!(matches!(e.kind, AsmErrorKind::BadRegister(_)));
    }

    /// The assembler reads mnemonics from TABLE, so every instruction in the
    /// set must be assemblable without the assembler knowing about it.
    #[test]
    fn every_table_entry_is_reachable_by_mnemonic() {
        for entry in TABLE {
            assert_eq!(lookup(entry.mnemonic), Some(entry.opcode));
        }
    }
}

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

    /// A single label names the positive target. The negative branch reaches
    /// its mirror, which is why a forward label cannot serve as an error exit
    /// for a negative value; that case wants brn.
    #[test]
    fn a_single_label_names_the_positive_target() {
        let p = assemble("        br3 r1, ahead\n        halt\nahead:  halt").unwrap();
        assert_eq!(p.instructions[0].imm.value(), 2);
        // Positive reaches index 2. Negative reaches index -2, not index 2.
    }

    /// The loop idiom: the label is behind, so only the positive case is taken.
    #[test]
    fn a_backward_label_is_the_loop_idiom() {
        let p = assemble("loop:   addi r1, r1, -1\n        br3 r1, loop\n        halt").unwrap();
        assert_eq!(p.instructions[1].imm.value(), -1);
    }

    /// A numeric offset still works, since it states the mirror explicitly.
    #[test]
    fn a_numeric_offset_is_accepted() {
        let p = assemble("br3 r1, 4\nhalt").unwrap();
        assert_eq!(p.instructions[0].imm.value(), 4);
    }

    #[test]
    fn mirrored_targets_assemble() {
        // less at 0, branch at 2, greater at 4: mirrored about the branch.
        let src = "
less:   halt
        halt
        br3  r1, less, greater
        halt
greater: halt
        ";
        let p = assemble(src).unwrap();
        assert_eq!(p.labels["less"], 0);
        assert_eq!(p.labels["greater"], 4);
        assert_eq!(p.instructions[2].imm.value(), 2);
    }

    #[test]
    fn unmirrored_targets_are_rejected_with_both_positions() {
        // less at 0, branch at 1, greater at 3: the negative branch would
        // reach -1, not 0.
        let src = "
less:   halt
        br3  r1, less, greater
        halt
greater: halt
        ";
        let e = assemble(src).unwrap_err();
        assert_eq!(
            e.kind,
            AsmErrorKind::Br3NotMirrored {
                neg: 0,
                reachable: -1,
                pos: 3
            }
        );
        assert!(e.to_string().contains("mirrored"), "{e}");
    }

    #[test]
    fn brn_and_brp_take_ordinary_labels() {
        let src = "
        brn  r1, less
        brp  r1, greater
        halt
less:   halt
greater: halt
        ";
        let p = assemble(src).unwrap();
        // brn at 0 targets index 3, brp at 1 targets index 4.
        assert_eq!(p.instructions[0].imm.value(), 3);
        assert_eq!(p.instructions[1].imm.value(), 3);
    }

    #[test]
    fn an_equate_resolves_to_its_value_not_an_offset() {
        // The distinction from a label: `here` is two instructions ahead of
        // the first addi, while BASE is -19683 wherever it is used.
        let p = assemble(
            "
            .equ BASE, -19683
                addi r1, r0, BASE
                addi r2, r0, here
            here:
                halt
            ",
        )
        .unwrap();
        assert_eq!(p.instructions[0].imm.value(), -19683);
        assert_eq!(p.instructions[1].imm.value(), 1);
        assert_eq!(p.equates["BASE"], -19683);
    }

    #[test]
    fn directives_do_not_occupy_program_space() {
        let p = assemble(
            "
            .equ A, 1
            .equ B, 2
            start:
                addi r1, r0, A
                halt
            ",
        )
        .unwrap();
        assert_eq!(p.instructions.len(), 2);
        assert_eq!(p.labels["start"], 0);
    }

    #[test]
    fn a_name_cannot_be_both_an_equate_and_a_label() {
        let e = assemble(".equ dup, 1\ndup:\n halt").unwrap_err();
        assert_eq!(e.kind, AsmErrorKind::DuplicateEquate("dup".into()));
    }

    #[test]
    fn an_equate_defined_twice_is_rejected() {
        let e = assemble(".equ A, 1\n.equ A, 2\nhalt").unwrap_err();
        assert_eq!(e.kind, AsmErrorKind::DuplicateEquate("A".into()));
    }

    #[test]
    fn a_malformed_equate_is_rejected() {
        for src in [".equ A", ".equ A, B", ".equ 1, 2", ".equ A, 1, 2"] {
            assert!(
                matches!(
                    assemble(src).map(|_| ()).unwrap_err().kind,
                    AsmErrorKind::BadEquate(_)
                ),
                "{src}"
            );
        }
    }

    #[test]
    fn a_mnemonic_beginning_with_the_directive_text_is_not_a_directive() {
        // `.equ` must be a whole word, so `.equipment` is not swallowed.
        let e = assemble(".equipment").unwrap_err();
        assert!(matches!(e.kind, AsmErrorKind::UnknownMnemonic(_)), "{e:?}");
    }

    #[test]
    fn an_undefined_name_is_still_an_error() {
        let e = assemble("addi r1, r0, MISSING").unwrap_err();
        assert_eq!(e.kind, AsmErrorKind::UndefinedLabel("MISSING".into()));
    }

    #[test]
    fn a_name_may_carry_a_displacement() {
        let p = assemble(
            "
            .equ WINDOW, 5
                addi r1, r0, WINDOW
                addi r2, r0, WINDOW+1
                addi r3, r0, WINDOW-2
            ",
        )
        .unwrap();
        assert_eq!(p.instructions[0].imm.value(), 5);
        assert_eq!(p.instructions[1].imm.value(), 6);
        assert_eq!(p.instructions[2].imm.value(), 3);
    }

    #[test]
    fn a_displacement_does_not_break_a_negative_literal() {
        let p = assemble("addi r1, r0, -19683\nhalt").unwrap();
        assert_eq!(p.instructions[0].imm.value(), -19683);
    }

    #[test]
    fn a_label_may_carry_a_displacement() {
        // A branch that means "two past the label", which a dispatch table
        // needs and which no arithmetic in the program can express.
        let p = assemble("here:\n addi r1, r0, 0\n jal r0, here+1\n halt").unwrap();
        assert_eq!(p.instructions[1].imm.value(), 0, "here is -1 away, plus 1");
    }

    #[test]
    fn a_malformed_displacement_is_rejected() {
        assert!(matches!(
            assemble(".equ A, 1\naddi r1, r0, A+x").unwrap_err().kind,
            AsmErrorKind::BadImmediate(_)
        ));
    }
}