//! Assembler parser pass.

use std::mem;

use std::fmt;

use std::lang::alloc;

use std::lang::strings;

use std::lang::parser;

use std::lang::gen;

use std::collections::dict;

use std::arch::rv64::encode;

use std::arch::rv64;

use std::arch::rv64::atomics;

use super::emit;

use super::scanner;

/// Parsed memory operand with base register and signed byte offset.

record MemOperand: Copy {

    /// Base register inside the memory operand parentheses.

    base: gen::Reg,

    /// Signed byte offset preceding the base register.

    offset: i32,

}

/// Parse assembler source into the supplied assembler state.

export fn parseProgram 'parse (a: &mut super::Assembler 'parse) throws (super::Error) {

    advance(a);

    while a.scan.current.kind <> scanner::TokenKind::Eof {

        try parseItem(a);

    }

}

/// Align `value` upward to `alignment`, returning nil on u32 overflow.

fn checkedAlignUp(value: u32, alignment: u32) -> ?u32 {

    let padding = alignment - 1;

    if value > parser::U32_MAX - padding {

        return nil;

    }

    return mem::alignUp(value, alignment);

}

/// Advance the parser by one token, preserving the previous token.

fn advance 'parse (a: &mut super::Assembler 'parse) {

    set a.scan.previous = a.scan.current;

    set a.scan.current = scanner::next(&mut a.scan, a.pool);

}

/// Consume the current token when it has `kind`.

fn consume 'parse (a: &mut super::Assembler 'parse, kind: scanner::TokenKind) -> bool {

    if a.scan.current.kind == kind {

        advance(a);

        return true;

    }

    return false;

}

/// Create an error at the current token.

fn fail 'parse (a: &super::Assembler 'parse, message: *[u8]) -> super::Error {

    return super::Error::Invalid { offset: a.scan.current.offset, message };

}

/// Create an error at `tok`.

fn failOnToken(tok: scanner::Token, message: *[u8]) -> super::Error {

    return super::Error::Invalid { offset: tok.offset, message };

}

/// Require that a data directive appears while assembling the data section.

fn expectDataSection 'parse (a: &super::Assembler 'parse, tok: scanner::Token) throws (super::Error) {

    if a.section <> super::Section::Data {

        throw failOnToken(tok, "data directive is only valid in the data section");

    }

}

/// Consume `kind` or throw `message` at the current token.

fn expect 'parse (a: &mut super::Assembler 'parse, kind: scanner::TokenKind, message: *[u8]) throws (super::Error) {

    if not consume(a, kind) {

        throw fail(a, message);

    }

}

/// Consume `kind` and return the consumed token.

fn expectToken 'parse (a: &mut super::Assembler 'parse, kind: scanner::TokenKind, message: *[u8]) -> scanner::Token throws (super::Error) {

    try expect(a, kind, message);

    return a.scan.previous;

}

/// Require that the current item has reached its semicolon terminator.

fn expectTerminator 'parse (a: &super::Assembler 'parse, message: *[u8]) throws (super::Error) {

    if a.scan.current.kind <> scanner::TokenKind::Semicolon {

        throw fail(a, message);

    }

}

/// Require that `value` fits in i32.

fn expectI32Value 'parse (a: &super::Assembler 'parse, value: i64, message: *[u8]) -> i32 throws (super::Error) {

    if value < -super::I32_MIN_MAGNITUDE or value > super::I32_MAX_VALUE {

        throw fail(a, message);

    }

    return value as i32;

}

/// Require that `value` fits in a signed 12-bit immediate field.

fn expectSmallImmValue 'parse (a: &super::Assembler 'parse, value: i64) -> i32 throws (super::Error) {

    if not encode::isSmallImm64(value) {

        throw fail(a, "immediate out of range");

    }

    return value as i32;

}

/// Define a label at the current text or data offset.

fn defineSymbol 'parse (a: &mut super::Assembler 'parse, name: *[u8], tok: scanner::Token) throws (super::Error) {

    if dict::get(&a.symbolMap, name) <> nil {

        throw failOnToken(tok, "duplicate label");

    }

    emit::defineSymbol(a, name);

}

/// Emit a parsed integer data value after applying source-level range checks.

fn emitDataValue 'parse (a: &mut super::Assembler 'parse, value: i64, width: super::DataWidth) throws (super::Error) {

    match width {

        case super::DataWidth::Word =>

            try emit::emitDataValue(a, (try expectI32Value(a, value, "word literal out of range")) as i64, width),

        case super::DataWidth::Dword =>

            try emit::emitDataValue(a, value, width),

    }

}

/// Parse a possibly scoped name from one or more `::`-separated segments.

fn parseScopedName 'parse (

    a: &mut super::Assembler 'parse,

    kind: scanner::TokenKind,

    message: *[u8],

    trimPrefix: u32

) -> *[u8] throws (super::Error) {

    let first = try expectToken(a, kind, message);

    let start = first.offset + trimPrefix;

    let mut end = first.offset + first.source.len;

    while consume(a, scanner::TokenKind::ColonColon) {

        let segment = try expectToken(a, scanner::TokenKind::Ident, "expected identifier after `::`");

        set end = segment.offset + segment.source.len;

    }

    let source = &a.scan.source[start..end];

    return strings::intern(a.pool, source);

}

/// Parse a bare symbol name.

fn parseSymbolName 'parse (a: &mut super::Assembler 'parse) -> *[u8] throws (super::Error) {

    return try parseScopedName(a, scanner::TokenKind::Ident, "expected symbol name", 0);

}

/// Return `true` when [`tok`] is any label token form.

fn isLabel(tok: scanner::TokenKind) -> bool {

    return tok == scanner::TokenKind::Label or tok == scanner::TokenKind::QuotedLabel;

}

/// Parse the contents of a quoted label token, decoding escapes as needed.

fn parseQuotedLabelName 'parse (a: &mut super::Assembler 'parse) -> *[u8] throws (super::Error) {

    let tok = try expectToken(a, scanner::TokenKind::QuotedLabel, "expected label name");

    let rawStart = super::LABEL_SIGIL_LEN + super::QUOTE_DELIM_LEN;

    let raw = &tok.source[rawStart..tok.source.len - super::QUOTE_DELIM_LEN];

    let mut storage: *mut [u8] = &mut [];

    unsafe {

        set storage = try alloc::allocSlice(a.arena, 1, 1, raw.len) catch {

            panic "asm: out of memory allocating quoted label";

        } as *mut [u8];

    }

    let len = fmt::unescapeString(raw, storage);

    return strings::intern(a.pool, &storage[..len]);

}

/// Parse a label reference or definition name.

fn parseLabelName 'parse (a: &mut super::Assembler 'parse) -> *[u8] throws (super::Error) {

    if a.scan.current.kind == scanner::TokenKind::QuotedLabel {

        return try parseQuotedLabelName(a);

    }

    return try parseScopedName(a, scanner::TokenKind::Label, "expected label name", super::LABEL_SIGIL_LEN);

}

/// Parse a directive name without its leading `.`.

fn parseDirectiveName 'parse (a: &mut super::Assembler 'parse) -> *[u8] throws (super::Error) {

    let name = try expectToken(a, scanner::TokenKind::Directive, "expected directive name");

    return &name.source[super::DIRECTIVE_SIGIL_LEN..];

}

/// Parse one top-level assembler item.

fn parseItem 'parse (a: &mut super::Assembler 'parse) throws (super::Error) {

    match a.scan.current.kind {

        case scanner::TokenKind::Ident => {

            let tok = a.scan.current;

            let name = try parseSymbolName(a);

            try parseInstruction(a, name, tok);

            try expect(a, scanner::TokenKind::Semicolon, "expected `;` after instruction");

        }

        case scanner::TokenKind::Number => {

            let tok = a.scan.current;

            advance(a);

            throw failOnToken(tok, "unexpected number at top level");

        }

        case scanner::TokenKind::Label, scanner::TokenKind::QuotedLabel => {

            let tok = a.scan.current;

            let name = try parseLabelName(a);

            try defineSymbol(a, name, tok);

        }

        case scanner::TokenKind::Directive => {

            let tok = a.scan.current;

            let name = try parseDirectiveName(a);

            try parseDirective(a, name, tok);

            try expect(a, scanner::TokenKind::Semicolon, "expected `;` after directive");

        }

        else => throw fail(a, "expected label, instruction, or directive"),

    }

}

/// Find `name` in a sorted descriptor table.

fn findSortedNameIndex(name: *[u8], len: u32, getName: fn(u32) -> *[u8]) -> ?u32 {

    let mut left: u32 = 0;

    let mut right: u32 = len;

    while left < right {

        let mid = left + ((right - left) / 2);

        let cmp = mem::cmp(name, getName(mid));

        match cmp {

            case -1 => set right = mid,

            case  1 => set left = mid + 1,

            else => return mid,

        }

    }

    return nil;

}

/// Adapter used by [`findSortedNameIndex`] to read an instruction mnemonic.

fn instructionNameAt(index: u32) -> *[u8] {

    return super::INSTRUCTIONS[index].name;

}

/// Adapter used by [`findSortedNameIndex`] to read a directive name.

fn directiveNameAt(index: u32) -> *[u8] {

    return super::DIRECTIVES[index].name;

}

/// Adapter used by [`findSortedNameIndex`] to read a register name.

fn registerNameAt(index: u32) -> *[u8] {

    return super::REGISTERS[index].name;

}

/// Adapter used by [`findSortedNameIndex`] to read a CSR name.

fn csrNameAt(index: u32) -> *[u8] {

    return super::CSRS[index].name;

}

/// Look up the operand parser and encoder for an instruction mnemonic.

fn lookupInstruction(name: *[u8]) -> ?super::InstructionEncoder {

    let index = findSortedNameIndex(name, super::INSTRUCTIONS.len, instructionNameAt) else {

        return nil;

    };

    return super::INSTRUCTIONS[index].encoder;

}

/// Classify a directive name.

fn classifyDirective(name: *[u8]) -> ?super::DirectiveKind {

    let index = findSortedNameIndex(name, super::DIRECTIVES.len, directiveNameAt) else {

        return nil;

    };

    return super::DIRECTIVES[index].kind;

}

/// Look up a percent-prefixed register name after the `%` has been removed.

fn lookupRegister(name: *[u8]) -> ?gen::Reg {

    let index = findSortedNameIndex(name, super::REGISTERS.len, registerNameAt) else {

        return nil;

    };

    return super::REGISTERS[index].reg;

}

/// Look up a CSR name.

fn lookupCsr(name: *[u8]) -> ?u32 {

    let index = findSortedNameIndex(name, super::CSRS.len, csrNameAt) else {

        return nil;

    };

    return super::CSRS[index].csr;

}

/// Parse an instruction after its mnemonic has already been consumed.

fn parseInstruction 'parse (a: &mut super::Assembler 'parse, name: *[u8], tok: scanner::Token) throws (super::Error) {

    if a.section <> super::Section::Text {

        throw failOnToken(tok, "instructions are only valid in the text section");

    }

    if let format = atomics::parse(name) {

        let rd = try parseRegister(a);

        let mut rs2 = rv64::ZERO;

        if format.operation <> 2 {

            set rs2 = try parseRegister(a);

        }

        let memory = try parseMemory(a);

        if memory.offset <> 0 {

            throw fail(a, "atomic memory offset must be zero");

        }

        try emit::emitText(a, atomics::encode(atomics::Instruction { format, rd, rs1: memory.base, rs2 }));

        return;

    }

    let form = lookupInstruction(name) else {

        throw failOnToken(tok, "unknown instruction");

    };

    match form {

        case super::InstructionEncoder::Fence => return try parseFence(a),

        case super::InstructionEncoder::NoOperand { enc } => {

            if a.scan.current.kind <> scanner::TokenKind::Semicolon {

                throw fail(a, "unexpected operand");

            }

            try emit::emitText(a, enc());

            return;

        }

        case super::InstructionEncoder::Li => return try parseLi(a),

        case super::InstructionEncoder::La => return try parseLa(a),

        case super::InstructionEncoder::RR { enc } => return try parseRR(a, enc),

        case super::InstructionEncoder::RRR { enc } => return try parseRRR(a, enc),

        case super::InstructionEncoder::RRI { enc } => return try parseRRI(a, enc),

        case super::InstructionEncoder::Shift { enc } =>

            return try parseShift(a, enc, super::SHIFT_LIMIT, "shift amount out of range"),

        case super::InstructionEncoder::WordShift { enc } =>

            return try parseShift(a, enc, super::WORD_SHIFT_LIMIT, "word shift amount out of range"),

        case super::InstructionEncoder::Load { enc } => return try parseLoad(a, enc),

        case super::InstructionEncoder::Store { enc } => return try parseStore(a, enc),

        case super::InstructionEncoder::Branch { op } => return try parseBranch(a, op),

        case super::InstructionEncoder::BranchZero { op } => return try parseBranchZero(a, op),

        case super::InstructionEncoder::Jal => return try parseJal(a),

        case super::InstructionEncoder::Jump { rd } => return try parseJ(a, rd),

        case super::InstructionEncoder::RdCsr { enc } => return try parseRdCsr(a, enc),

        case super::InstructionEncoder::CsrRs1 { enc } => return try parseCsrRs1(a, enc),

        case super::InstructionEncoder::Csrrw => return try parseCsrrw(a),

        case super::InstructionEncoder::Csrsi => return try parseCsrsi(a),

        case super::InstructionEncoder::Upper { enc } => return try parseUpper(a, enc),

    }

}

/// Parse the `li` pseudo-instruction.

fn parseLi 'parse (a: &mut super::Assembler 'parse) throws (super::Error) {

    let rd = try parseRegister(a);

    let value = try parseValue(a);

    if encode::isSmallImm64(value) {

        try emit::emitText(a, encode::addi(rd, rv64::ZERO, value as i32));

        return;

    }

    let imm = try expectI32Value(a, value, "li immediate out of range");

    let split = rv64::emit::splitImm(imm);

    try emit::emitText(a, encode::lui(rd, split.hi));

    try emit::emitText(a, encode::addi(rd, rd, split.lo));

}

/// Parse the `la` pseudo-instruction.

fn parseLa 'parse (a: &mut super::Assembler 'parse) throws (super::Error) {

    let rd = try parseRegister(a);

    let target = try parseLabelName(a);

    let index = a.textLen;

    try emit::recordTextFixup(a, target, super::FixupInfo::Addr { rd, index }, 2);

}

/// Parse a CSR read-like instruction with destination register then CSR.

fn parseRdCsr 'parse (a: &mut super::Assembler 'parse, enc: fn(gen::Reg, u32) -> u32) throws (super::Error) {

    let rd = try parseRegister(a);

    let csr = try parseCsr(a);

    try emit::emitText(a, enc(rd, csr));

}

/// Parse a CSR write-like instruction with CSR then source register.

fn parseCsrRs1 'parse (a: &mut super::Assembler 'parse, enc: fn(u32, gen::Reg) -> u32) throws (super::Error) {

    let csr = try parseCsr(a);

    let rs1 = try parseRegister(a);

    try emit::emitText(a, enc(csr, rs1));

}

/// Parse `csrrw`.

fn parseCsrrw 'parse (a: &mut super::Assembler 'parse) throws (super::Error) {

    let rd = try parseRegister(a);

    let csr = try parseCsr(a);

    let rs1 = try parseRegister(a);

    try emit::emitText(a, encode::csrrw(rd, csr, rs1));

}

/// Parse a CSR immediate instruction.

fn parseCsrsi 'parse (a: &mut super::Assembler 'parse) throws (super::Error) {

    let csr = try parseCsr(a);

    let imm = try parseValue(a);

    if imm < 0 or imm >= super::CSR_IMM_LIMIT {

        throw fail(a, "CSR immediate out of range");

    }

    try emit::emitText(a, encode::csrsi(csr, imm as u32));

}

/// Parse a two-register instruction.

fn parseRR 'parse (a: &mut super::Assembler 'parse, enc: fn(gen::Reg, gen::Reg) -> u32) throws (super::Error) {

    let rd = try parseRegister(a);

    let rs = try parseRegister(a);

    try emit::emitText(a, enc(rd, rs));

}

/// Parse a three-register instruction.

fn parseRRR 'parse (a: &mut super::Assembler 'parse, enc: fn(gen::Reg, gen::Reg, gen::Reg) -> u32) throws (super::Error) {

    let rd = try parseRegister(a);

    let rs1 = try parseRegister(a);

    let rs2 = try parseRegister(a);

    try emit::emitText(a, enc(rd, rs1, rs2));

}

/// Parse a register-register-immediate instruction.

fn parseRRI 'parse (a: &mut super::Assembler 'parse, enc: fn(gen::Reg, gen::Reg, i32) -> u32) throws (super::Error) {

    let rd = try parseRegister(a);

    let rs1 = try parseRegister(a);

    let imm = try parseSmallImm(a);

    try emit::emitText(a, enc(rd, rs1, imm));

}

/// Parse a shift-immediate instruction and enforce its RV64 shift bound.

fn parseShift 'parse (

    a: &mut super::Assembler 'parse,

    enc: fn(gen::Reg, gen::Reg, i32) -> u32,

    limit: i32,

    message: *[u8]

) throws (super::Error) {

    let rd = try parseRegister(a);

    let rs1 = try parseRegister(a);

    let shamt64 = try parseValue(a);

    if shamt64 < 0 {

        throw fail(a, "shift amount must be non-negative");

    }

    if shamt64 >= limit as i64 {

        throw fail(a, message);

    }

    let shamt = shamt64 as i32;

    try emit::emitText(a, enc(rd, rs1, shamt));

}

/// Parse a load instruction with a memory operand.

fn parseLoad 'parse (a: &mut super::Assembler 'parse, enc: fn(gen::Reg, gen::Reg, i32) -> u32) throws (super::Error) {

    let rd = try parseRegister(a);

    let memop = try parseMemory(a);

    try emit::emitText(a, enc(rd, memop.base, memop.offset));

}

/// Parse a store instruction with a memory operand.

fn parseStore 'parse (a: &mut super::Assembler 'parse, enc: fn(gen::Reg, gen::Reg, i32) -> u32) throws (super::Error) {

    let rs2 = try parseRegister(a);

    let memop = try parseMemory(a);

    try emit::emitText(a, enc(rs2, memop.base, memop.offset));

}

/// Parse a two-register branch instruction.

fn parseBranch 'parse (a: &mut super::Assembler 'parse, op: super::BranchOp) throws (super::Error) {

    let rs1 = try parseRegister(a);

    let rs2 = try parseRegister(a);

    try parseBranchLabel(a, op, rs1, rs2);

}

/// Parse an optional label operand.

fn parseOptionalLabel 'parse (a: &mut super::Assembler 'parse) -> ?*[u8] throws (super::Error) {

    if not isLabel(a.scan.current.kind) {

        return nil;

    }

    return try parseLabelName(a);

}

/// Parse a branch target as either a label fixup or immediate offset.

fn parseBranchLabel 'parse (a: &mut super::Assembler 'parse, op: super::BranchOp, rs1: gen::Reg, rs2: gen::Reg) throws (super::Error) {

    let index = a.textLen;

    if let target = try parseOptionalLabel(a) {

        try emit::recordTextFixup(a, target, super::FixupInfo::Branch { op, rs1, rs2, index }, 1);

        return;

    }

    let imm = try parseBranchImm(a);

    try emit::emitText(a, emit::encodeBranch(op, rs1, rs2, imm));

}

/// Parse a branch-to-zero pseudo-instruction.

fn parseBranchZero 'parse (a: &mut super::Assembler 'parse, op: super::BranchOp) throws (super::Error) {

    let rs = try parseRegister(a);

    try parseBranchLabel(a, op, rs, rv64::ZERO);

}

/// Parse `jal` with an explicit destination register.

fn parseJal 'parse (a: &mut super::Assembler 'parse) throws (super::Error) {

    let rd = try parseRegister(a);

    try parseJ(a, rd);

}

/// Parse a jump target for `jal` or a jump pseudo-instruction.

fn parseJ 'parse (a: &mut super::Assembler 'parse, rd: gen::Reg) throws (super::Error) {

    let index = a.textLen;

    if let target = try parseOptionalLabel(a) {

        try emit::recordTextFixup(a, target, super::FixupInfo::Jal { rd, index }, 1);

        return;

    }

    let imm = try parseJumpImm(a);

    try emit::emitText(a, encode::jal(rd, imm));

}

/// Parse an upper-immediate instruction.

fn parseUpper 'parse (a: &mut super::Assembler 'parse, enc: fn(gen::Reg, i32) -> u32) throws (super::Error) {

    let rd = try parseRegister(a);

    let imm64 = try parseValue(a);

    if imm64 < 0 or imm64 > super::UPPER_IMM_MAX_VALUE {

        throw fail(a, "upper immediate out of range");

    }

    try emit::emitText(a, enc(rd, imm64 as i32));

}

/// Parse a directive after its name has already been consumed.

fn parseDirective 'parse (a: &mut super::Assembler 'parse, name: *[u8], tok: scanner::Token) throws (super::Error) {

    let directive = classifyDirective(name) else {

        throw failOnToken(tok, "unknown directive");

    };

    match directive {

        case super::DirectiveKind::Text => {

            try expectTerminator(a, "unexpected operand");

            set a.section = super::Section::Text;

            return;

        }

        case super::DirectiveKind::Data => {

            try expectTerminator(a, "unexpected operand");

            set a.section = super::Section::Data;

            return;

        }

        case super::DirectiveKind::Align =>

            return try parseAlignDirective(a),

        case super::DirectiveKind::Ascii => {

            try expectDataSection(a, tok);

            return try parseStringDirective(a);

        }

        case super::DirectiveKind::Byte => {

            try expectDataSection(a, tok);

            return try parseByteDirective(a);

        }

        case super::DirectiveKind::Constant =>

            return try parseConstantDirective(a),

        case super::DirectiveKind::Dword => {

            try expectDataSection(a, tok);

            return try parseIntDirective(a, super::DataWidth::Dword);

        }

        case super::DirectiveKind::Export =>

            return try parseExportDirective(a),

        case super::DirectiveKind::Space => {

            try expectDataSection(a, tok);

            return try parseSpaceDirective(a);

        }

        case super::DirectiveKind::Word => {

            try expectDataSection(a, tok);

            return try parseIntDirective(a, super::DataWidth::Word);

        }

    }

}

/// Parse a `.constant` directive.

fn parseConstantDirective 'parse (a: &mut super::Assembler 'parse) throws (super::Error) {

    let name = try parseSymbolName(a);

    let value = try expectI32Value(a, try parseExpr(a), "constant out of range");

    dict::insert(&mut a.constMap, name, value);

}

/// Parse a `.export` directive.

fn parseExportDirective 'parse (a: &mut super::Assembler 'parse) throws (super::Error) {

    let name = try parseLabelName(a);

    dict::insert(&mut a.exportMap, name, 1);

    if let idx = dict::get(&a.symbolMap, name) {

        set a.symbols[idx as u32].isExported = true;

    }

}

/// Parse a `.space` directive.

fn parseSpaceDirective 'parse (a: &mut super::Assembler 'parse) throws (super::Error) {

    let count = try parseValue(a);

    if count < 0 {

        throw fail(a, "space size must be non-negative");

    }

    // The data section grows on demand; only reject sizes that cannot be

    // represented as a section offset.

    if count > super::U32_MAX_VALUE - a.dataLen as i64 {

        throw super::Error::DataOverflow;

    }

    for _ in 0..count as u32 {

        try emit::emitByte(a, 0);

    }

}

/// Parse an `.align` directive for the current section.

fn parseAlignDirective 'parse (a: &mut super::Assembler 'parse) throws (super::Error) {

    let amount64 = try parseValue(a);

    if amount64 <= 0 {

        throw fail(a, "alignment must be positive");

    }

    if amount64 > super::U32_MAX_VALUE {

        throw fail(a, "alignment out of range");

    }

    let amount = amount64 as u32;

    if (amount & (amount - 1)) <> 0 {

        throw fail(a, "alignment must be a power of two");

    }

    match a.section {

        case super::Section::Text => {

            if amount % rv64::INSTR_SIZE as u32 <> 0 {

                throw fail(a, "text alignment must be a multiple of 4");

            }

            let bytes = a.textLen * rv64::INSTR_SIZE as u32;

            let aligned = checkedAlignUp(bytes, amount) else {

                throw super::Error::TextOverflow;

            };

            let words = (aligned - bytes) / rv64::INSTR_SIZE as u32;

            try emit::emitTextPadding(a, words);

        }

        case super::Section::Data => {

            let aligned = checkedAlignUp(a.dataLen, amount) else {

                throw super::Error::DataOverflow;

            };

            for _ in a.dataLen..aligned {

                try emit::emitByte(a, 0);

            }

        }

    }

}

/// Parse a `.byte` directive.

fn parseByteDirective 'parse (a: &mut super::Assembler 'parse) throws (super::Error) {

    loop {

        if a.scan.current.kind == scanner::TokenKind::Char {

            let ch = parseCharLiteral(a.scan.current) else {

                throw fail(a, "invalid char literal");

            };

            try emit::emitByte(a, ch);

            advance(a);

        } else {

            let value = try parseValue(a);

            if value < 0 or value > super::U8_MAX_VALUE {

                throw fail(a, "byte literal out of range");

            }

            try emit::emitByte(a, value as u8);

        }

        if not consume(a, scanner::TokenKind::Comma) {

            return;

        }

    }

}

/// Parse a fixed-width integer data directive.

fn parseIntDirective 'parse (a: &mut super::Assembler 'parse, width: super::DataWidth) throws (super::Error) {

    loop {

        if isLabel(a.scan.current.kind) {

            let target = try parseLabelName(a);

            try emit::recordDataFixup(a, target, width);

        } else if a.scan.current.kind == scanner::TokenKind::Char {

            let ch = parseCharLiteral(a.scan.current) else {

                throw fail(a, "invalid char literal");

            };

            advance(a);

            try emitDataValue(a, ch as i64, width);

        } else {

            try emitDataValue(a, try parseValue(a), width);

        }

        if not consume(a, scanner::TokenKind::Comma) {

            return;

        }

    }

}

/// Parse a `.ascii` string literal list.

fn parseStringDirective 'parse (a: &mut super::Assembler 'parse) throws (super::Error) {

    loop {

        let literal = try expectToken(a, scanner::TokenKind::String, "expected string literal");

        try emit::emitDecodedString(a, literal.source);

        if not consume(a, scanner::TokenKind::Comma) {

            return;

        }

    }

}

/// Parse and resolve a register operand.

fn parseRegister 'parse (a: &mut super::Assembler 'parse) -> gen::Reg throws (super::Error) {

    let tok = try expectToken(a, scanner::TokenKind::Register, "expected register");

    let reg = lookupRegister(&tok.source[1..]) else {

        throw super::Error::Invalid { offset: tok.offset, message: "unknown register" };

    };

    return reg;

}

/// Parse a simple signed immediate or constant value.

fn parseValue 'parse (a: &mut super::Assembler 'parse) -> i64 throws (super::Error) {

    if consume(a, scanner::TokenKind::Minus) {

        return -(try parseValuePrimary(a));

    }

    return try parseValuePrimary(a);

}

/// Parse the primary form used by simple immediate values.

fn parseValuePrimary 'parse (a: &mut super::Assembler 'parse) -> i64 throws (super::Error) {

    if a.scan.current.kind == scanner::TokenKind::Number {

        return try parseInteger(a);

    }

    if a.scan.current.kind == scanner::TokenKind::Ident {

        return try parseConstantValue(a);

    }

    throw fail(a, "expected number or constant");

}

/// Parse an additive constant expression.

fn parseExpr 'parse (a: &mut super::Assembler 'parse) -> i64 throws (super::Error) {

    let mut value = try parseExprMul(a);

    while a.scan.current.kind == scanner::TokenKind::Plus or a.scan.current.kind == scanner::TokenKind::Minus {

        let op = a.scan.current.kind;

        advance(a);

        let rhs = try parseExprMul(a);

        if op == scanner::TokenKind::Plus {

            set value += rhs;

        } else {

            set value -= rhs;

        }

    }

    return value;

}

/// Parse multiplicative expression operators.

fn parseExprMul 'parse (a: &mut super::Assembler 'parse) -> i64 throws (super::Error) {

    let mut value = try parseExprUnary(a);

    while a.scan.current.kind == scanner::TokenKind::Star or a.scan.current.kind == scanner::TokenKind::Slash {

        let op = a.scan.current.kind;

        advance(a);

        let rhs = try parseExprUnary(a);

        if op == scanner::TokenKind::Star {

            set value *= rhs;

        } else {

            if rhs == 0 {

                throw fail(a, "division by zero");

            }

            set value /= rhs;

        }

    }

    return value;

}

/// Parse unary expression operators.

fn parseExprUnary 'parse (a: &mut super::Assembler 'parse) -> i64 throws (super::Error) {

    if consume(a, scanner::TokenKind::Minus) {

        return -(try parseExprUnary(a));

    }

    if consume(a, scanner::TokenKind::Plus) {

        return try parseExprUnary(a);

    }

    return try parseExprPrimary(a);

}

/// Parse expression atoms.

fn parseExprPrimary 'parse (a: &mut super::Assembler 'parse) -> i64 throws (super::Error) {

    if consume(a, scanner::TokenKind::LParen) {

        let value = try parseExpr(a);

        try expect(a, scanner::TokenKind::RParen, "expected `)`");

        return value;

    }

    if a.scan.current.kind == scanner::TokenKind::Number {

        return try parseInteger(a);

    }

    if a.scan.current.kind == scanner::TokenKind::Ident {

        return try parseConstantValue(a);

    }

    throw fail(a, "expected expression");

}

/// Parse and resolve a named assembler constant.

fn parseConstantValue 'parse (a: &mut super::Assembler 'parse) -> i64 throws (super::Error) {

    let name = try parseSymbolName(a);

    let value = dict::get(&a.constMap, name) else {

        throw super::Error::Invalid { offset: a.scan.previous.offset, message: "undefined constant" };

    };

    return value as i64;

}

/// Parse and resolve a CSR operand.

fn parseCsr 'parse (a: &mut super::Assembler 'parse) -> u32 throws (super::Error) {

    let name = try parseSymbolName(a);

    let csr = lookupCsr(name) else {

        throw super::Error::Invalid { offset: a.scan.previous.offset, message: "unknown CSR" };

    };

    return csr;

}

/// Parse an offset(base) memory operand.

fn parseMemory 'parse (a: &mut super::Assembler 'parse) -> MemOperand throws (super::Error) {

    let mut offset: i32 = 0;

    if a.scan.current.kind <> scanner::TokenKind::LParen {

        set offset = try expectSmallImmValue(a, try parseValue(a));

    }

    try expect(a, scanner::TokenKind::LParen, "expected `(`");

    let base = try parseRegister(a);

    try expect(a, scanner::TokenKind::RParen, "expected `)`");

    return MemOperand { base, offset };

}

/// Parse an immediate value that fits in a signed 12-bit field.

fn parseSmallImm 'parse (a: &mut super::Assembler 'parse) -> i32 throws (super::Error) {

    return try expectSmallImmValue(a, try parseValue(a));

}

/// Parse and validate a branch immediate.

fn parseBranchImm 'parse (a: &mut super::Assembler 'parse) -> i32 throws (super::Error) {

    let value = try expectI32Value(a, try parseValue(a), "branch immediate out of range");

    if not encode::isBranchImm(value) {

        throw fail(a, "branch immediate out of range");

    }

    return value;

}

/// Parse and validate a jump immediate.

fn parseJumpImm 'parse (a: &mut super::Assembler 'parse) -> i32 throws (super::Error) {

    let value = try expectI32Value(a, try parseValue(a), "jump immediate out of range");

    if not encode::isJumpImm(value) {

        throw fail(a, "jump immediate out of range");

    }

    return value;

}

/// Parse an integer token as an i64.

fn parseInteger 'parse (a: &mut super::Assembler 'parse) -> i64 throws (super::Error) {

    let tok = try expectToken(a, scanner::TokenKind::Number, "expected number");

    let value = parseIntegerText(tok.source) else {

        throw failOnToken(tok, "invalid integer literal");

    };

    return value;

}

/// Parse integer literal text as an i64.

fn parseIntegerText(text: *[u8]) -> ?i64 {

    if text.len == 0 {

        return nil;

    }

    let negative = text[0] == '-';

    let magnitudeText = &text[1..] if negative or text[0] == '+' else text;

    let literal = try fmt::parseInt(magnitudeText) catch {

        return nil;

    };

    if negative {

        if literal.magnitude > parser::I64_MIN_MAGNITUDE {

            return nil;

        }