Skip to main content

vihaco_syntax/
spanned.rs

1// SPDX-FileCopyrightText: 2026 The vihaco Authors
2// SPDX-License-Identifier: MIT
3
4//! Located, error-recovering parsers for `.text` streams and header
5//! declarations.
6//!
7//! [`parse_text`] and [`parse_declarations`] accept exactly the inputs that
8//! [`ParsedModule::parse_section`](crate::ParsedModule::parse_section) and
9//! `HeaderDeclarations` accept, but keep the byte span of every instruction,
10//! symbol definition, and declaration, and keep going after a malformed
11//! statement so that every problem is reported as a human-readable
12//! [`SyntaxError`].
13//!
14//! Both split their block into statements first (see
15//! [`statements`](crate::statements())): one statement per line, continued onto
16//! following lines only inside an open bracket. Each statement is parsed on
17//! its own, so recovery is per line and every bad line is reported once.
18//! Spans are byte ranges relative to the parsed block.
19
20use std::ops::Range;
21
22use chumsky::error::Simple;
23use chumsky::prelude::*;
24use vihaco_parser::Parse;
25
26use crate::Symbol;
27use crate::statements::statements;
28
29/// A parsed value and the byte range of its source text.
30#[derive(Debug, Clone, PartialEq, Eq)]
31pub struct Spanned<T> {
32    pub value: T,
33    pub span: Range<usize>,
34}
35
36/// A located, human-readable syntax error.
37#[derive(Debug, Clone, PartialEq, Eq)]
38pub struct SyntaxError {
39    /// The offending text, relative to the parsed block. May be empty to mark
40    /// a position, such as a missing operand at the end of a line.
41    pub span: Range<usize>,
42    /// What went wrong, for example ``expected an instruction, found `foo` ``.
43    pub message: String,
44    /// A short annotation for the span itself, such as `unknown instruction`.
45    pub label: String,
46}
47
48impl std::fmt::Display for SyntaxError {
49    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
50        f.write_str(&self.message)
51    }
52}
53
54impl std::error::Error for SyntaxError {}
55
56/// A located `.text` stream: instructions in address order, symbol
57/// definitions in source order, and every syntax error.
58///
59/// When [`errors`](Self::errors) is non-empty the other fields hold what could
60/// be recovered: malformed statements are skipped and occupy no address.
61#[derive(Debug, Clone, PartialEq)]
62pub struct ParsedText<I> {
63    /// Each instruction's span covers the instruction, without a symbol
64    /// definition before it on its line or a trailing comment.
65    pub code: Vec<Spanned<I>>,
66    /// Each symbol's span covers its whole `@name:` definition.
67    pub symbols: Vec<Spanned<Symbol>>,
68    pub errors: Vec<SyntaxError>,
69}
70
71/// Located header declarations and every syntax error.
72#[derive(Debug, Clone, PartialEq)]
73pub struct ParsedDeclarations<D> {
74    /// Each declaration's span covers its statement, without a trailing
75    /// comment.
76    pub declarations: Vec<Spanned<D>>,
77    pub errors: Vec<SyntaxError>,
78}
79
80/// The 1-based line and column (counted in characters) of `offset` in `text`.
81pub fn line_column(text: &str, offset: usize) -> (usize, usize) {
82    let before = &text[..offset.min(text.len())];
83    let line_start = before.rfind('\n').map_or(0, |index| index + 1);
84    (
85        before.matches('\n').count() + 1,
86        before[line_start..].chars().count() + 1,
87    )
88}
89
90/// Characters allowed in a symbol name: see [`crate::symbol_definition`].
91pub(crate) fn symbol_name_char(c: char) -> bool {
92    !c.is_whitespace()
93        && !matches!(
94            c,
95            ':' | '@' | ',' | ';' | '(' | ')' | '{' | '}' | '[' | ']' | '"' | '\'' | '`'
96        )
97}
98
99/// The token starting at `offset`, ending at `limit` at the latest: a run of
100/// non-whitespace, non-delimiter characters, or a single delimiter.
101fn token_at(text: &str, offset: usize, limit: usize) -> Range<usize> {
102    let rest = &text[offset..limit.max(offset)];
103    let delimiter = |c: char| matches!(c, ',' | ';' | '(' | ')' | '{' | '}' | '[' | ']');
104    let mut chars = rest.char_indices();
105    match chars.next() {
106        None => offset..offset,
107        Some((_, c)) if delimiter(c) => offset..offset + c.len_utf8(),
108        Some(_) => {
109            let token = &rest[..rest
110                .find(|c: char| c.is_whitespace() || delimiter(c))
111                .unwrap_or(rest.len())];
112            // A record key is reported without its `:`.
113            let token = match token.strip_suffix(':') {
114                Some(key) if !key.is_empty() => key,
115                _ => token,
116            };
117            offset..offset + token.len()
118        }
119    }
120}
121
122/// The first whitespace-delimited word of `text[span]`.
123fn word_at(text: &str, span: &Range<usize>) -> Range<usize> {
124    let rest = &text[span.clone()];
125    span.start..span.start + rest.find(char::is_whitespace).unwrap_or(rest.len())
126}
127
128/// Whether `token` is shaped like a number literal.
129fn numeric(token: &str) -> bool {
130    let digits = token.strip_prefix('-').unwrap_or(token);
131    digits.starts_with(|c: char| c.is_ascii_digit())
132        && digits
133            .chars()
134            .all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '+' | '-'))
135}
136
137/// What kind of statement failed to parse, for wording its error.
138#[derive(Clone, Copy)]
139enum Kind {
140    Instruction,
141    Declaration,
142}
143
144/// Explain why the statement at `statement` failed to parse.
145///
146/// `parses` reports whether a prefix of the statement is a complete statement
147/// by itself, which tells a second statement on the line apart from a
148/// malformed operand.
149fn statement_error<'s>(
150    text: &'s str,
151    statement: Range<usize>,
152    error: &Simple<'_, char>,
153    kind: Kind,
154    parses: impl Fn(&'s str) -> bool,
155) -> SyntaxError {
156    let head = match kind {
157        Kind::Instruction => word_at(text, &statement),
158        Kind::Declaration => token_at(text, statement.start, statement.end),
159    };
160    let head_text = &text[head.clone()];
161    if let Some((prefix, after)) = complete_prefix(text, &statement, &parses) {
162        let (what, label) = match kind {
163            Kind::Instruction => ("instruction", "one instruction per line"),
164            Kind::Declaration => ("declaration", "one declaration per line"),
165        };
166        let span = token_at(text, after, statement.end);
167        return SyntaxError {
168            message: format!(
169                "expected end of line after the {what} `{}`, found `{}`",
170                &text[prefix],
171                &text[span.clone()]
172            ),
173            span,
174            label: label.to_owned(),
175        };
176    }
177    let relative = error.span().into_range();
178    let at = (statement.start + relative.start).min(statement.end);
179    // A value rejected after lexing (such as an overflowing integer) reports
180    // no token but spans the value.
181    let rejected = error.found().is_none() && !relative.is_empty();
182    let rest = &text[at..statement.end];
183    let next = at + rest.len() - rest.trim_start().len();
184
185    if !rejected && next >= statement.end {
186        let end = statement.end;
187        return match kind {
188            Kind::Instruction => SyntaxError {
189                span: end..end,
190                message: format!("expected more operands for `{head_text}`, found end of line"),
191                label: "operand expected here".to_owned(),
192            },
193            Kind::Declaration => SyntaxError {
194                span: end..end,
195                message: format!(
196                    "expected the rest of the `{head_text}` declaration, found end of line"
197                ),
198                label: "declaration is incomplete".to_owned(),
199            },
200        };
201    }
202    if next < head.end {
203        return match kind {
204            Kind::Instruction => SyntaxError {
205                message: format!("expected an instruction, found `{head_text}`"),
206                span: head,
207                label: "unknown instruction".to_owned(),
208            },
209            Kind::Declaration if head_text.starts_with('.') => SyntaxError {
210                message: format!("unknown directive `{head_text}`"),
211                span: head,
212                label: "not a header directive".to_owned(),
213            },
214            Kind::Declaration => SyntaxError {
215                message: format!("expected a header declaration, found `{head_text}`"),
216                span: head,
217                label: "unknown declaration".to_owned(),
218            },
219        };
220    }
221    let token = token_at(text, next, statement.end);
222    let span = if rejected {
223        next..token
224            .end
225            .max((statement.start + relative.end).min(statement.end))
226    } else {
227        token
228    };
229    let found = &text[span.clone()];
230    match (kind, numeric(found)) {
231        (Kind::Instruction, true) => SyntaxError {
232            message: format!("invalid operand `{found}` for `{head_text}`"),
233            span,
234            label: "value out of range or malformed".to_owned(),
235        },
236        (Kind::Instruction, false) => SyntaxError {
237            message: format!("unexpected `{found}` in operands of `{head_text}`"),
238            span,
239            label: "unexpected operand".to_owned(),
240        },
241        (Kind::Declaration, true) => SyntaxError {
242            message: format!("invalid value `{found}` in `{head_text}` declaration"),
243            span,
244            label: "value out of range or malformed".to_owned(),
245        },
246        (Kind::Declaration, false) => SyntaxError {
247            message: format!("unexpected `{found}` in `{head_text}` declaration"),
248            span,
249            label: "unexpected token".to_owned(),
250        },
251    }
252}
253
254/// The longest proper prefix of `statement` that ends before whitespace
255/// (outside string literals) and parses as a complete statement, and the
256/// offset of the text after it.
257fn complete_prefix<'s>(
258    text: &'s str,
259    statement: &Range<usize>,
260    parses: impl Fn(&'s str) -> bool,
261) -> Option<(Range<usize>, usize)> {
262    let line = &text[statement.clone()];
263    let mut boundaries = Vec::new();
264    let mut in_string = false;
265    let mut escaped = false;
266    let mut previous_space = true;
267    for (index, c) in line.char_indices() {
268        if in_string {
269            match (escaped, c) {
270                (true, _) => escaped = false,
271                (false, '\\') => escaped = true,
272                (false, '"') => in_string = false,
273                _ => {}
274            }
275            previous_space = false;
276            continue;
277        }
278        let space = c.is_whitespace();
279        if space && !previous_space {
280            boundaries.push(index);
281        }
282        in_string = c == '"';
283        previous_space = space;
284    }
285    boundaries.into_iter().rev().find_map(|end| {
286        let prefix = statement.start..statement.start + end;
287        let rest = &text[prefix.end..statement.end];
288        let after = prefix.end + rest.len() - rest.trim_start().len();
289        (after < statement.end && parses(&text[prefix.clone()])).then_some((prefix, after))
290    })
291}
292
293/// The error chumsky reports furthest into the statement.
294fn furthest<'a, 'src>(errors: &'a [Simple<'src, char>]) -> Option<&'a Simple<'src, char>> {
295    errors.iter().max_by_key(|error| error.span().start)
296}
297
298/// Parse a `.text` stream, keeping spans and recovering after malformed
299/// statements.
300///
301/// Accepts exactly the streams accepted by
302/// [`ParsedModule::parse_section`](crate::ParsedModule::parse_section): one
303/// statement per line, each an `@name:` symbol definition, an instruction, or
304/// a symbol definition followed by an instruction. A symbol written without
305/// its trailing `:` is reported as an error but still recorded, so later
306/// checks do not report it as missing.
307///
308/// Line numbers in messages count from 1 at the start of `text`; use
309/// [`parse_text_at`] when `text` is part of a larger file.
310pub fn parse_text<'src, I>(text: &'src str) -> ParsedText<I>
311where
312    I: Parse<'src> + 'src,
313{
314    parse_text_at(text, 1)
315}
316
317/// [`parse_text`] for a block that starts on file line `first_line`.
318pub fn parse_text_at<'src, I>(text: &'src str, first_line: usize) -> ParsedText<I>
319where
320    I: Parse<'src> + 'src,
321{
322    let split = statements(text, first_line);
323    let mut parsed = ParsedText {
324        code: Vec::new(),
325        symbols: Vec::new(),
326        errors: split.errors,
327    };
328    let parser = I::parser().then_ignore(end());
329    let parses = |prefix: &'src str| !prefix.is_empty() && !parser.parse(prefix).has_errors();
330    for statement in split.statements {
331        if !statement.balanced {
332            continue;
333        }
334        let mut start = statement.span.start;
335        let end = statement.span.end;
336        if let Some(rest) = text[start..end].strip_prefix('@') {
337            let name_len = rest.find(|c| !symbol_name_char(c)).unwrap_or(rest.len());
338            if name_len == 0 {
339                parsed.errors.push(SyntaxError {
340                    span: start..start + 1,
341                    message: "expected a symbol name after `@`".to_owned(),
342                    label: "symbol definitions are written `@name:`".to_owned(),
343                });
344                continue;
345            }
346            let name = rest[..name_len].to_owned();
347            let colon = rest[name_len..].starts_with(':');
348            let span = start..start + 1 + name_len + usize::from(colon);
349            if !colon {
350                parsed.errors.push(SyntaxError {
351                    span: span.clone(),
352                    message: format!("expected `:` after symbol name `@{name}`"),
353                    label: format!("write `@{name}:` to define this symbol"),
354                });
355            }
356            let Ok(address) = u32::try_from(parsed.code.len()) else {
357                parsed.errors.push(SyntaxError {
358                    span,
359                    message: "instruction stream exceeds u32 address space".to_owned(),
360                    label: String::new(),
361                });
362                continue;
363            };
364            parsed.symbols.push(Spanned {
365                value: Symbol { name, address },
366                span: span.clone(),
367            });
368            if !colon {
369                continue;
370            }
371            let after = &text[span.end..end];
372            start = span.end + after.len() - after.trim_start().len();
373            if start >= end {
374                continue;
375            }
376        }
377        let statement = start..end;
378        match parser.parse(&text[statement.clone()]).into_result() {
379            Ok(value) => parsed.code.push(Spanned {
380                value,
381                span: statement,
382            }),
383            Err(errors) => {
384                if let Some(error) = furthest(&errors) {
385                    parsed.errors.push(statement_error(
386                        text,
387                        statement,
388                        error,
389                        Kind::Instruction,
390                        parses,
391                    ));
392                }
393            }
394        }
395    }
396    parsed.errors.sort_by_key(|error| error.span.start);
397    parsed
398}
399
400/// Parse header declarations, one per statement, keeping spans and
401/// recovering after malformed declarations.
402///
403/// Accepts exactly the headers accepted by `HeaderDeclarations<D>`: one
404/// declaration per line, continued onto following lines only inside an open
405/// bracket, with `;` comments. Line numbers in messages count from 1 at the
406/// start of `text`; use [`parse_declarations_at`] when `text` is part of a
407/// larger file.
408pub fn parse_declarations<'src, D>(text: &'src str) -> ParsedDeclarations<D>
409where
410    D: Parse<'src> + 'src,
411{
412    parse_declarations_at(text, 1)
413}
414
415/// [`parse_declarations`] for a block that starts on file line `first_line`.
416pub fn parse_declarations_at<'src, D>(text: &'src str, first_line: usize) -> ParsedDeclarations<D>
417where
418    D: Parse<'src> + 'src,
419{
420    let split = statements(text, first_line);
421    let mut parsed = ParsedDeclarations {
422        declarations: Vec::new(),
423        errors: split.errors,
424    };
425    let parser = D::parser().then_ignore(end());
426    let parses = |prefix: &'src str| !prefix.is_empty() && !parser.parse(prefix).has_errors();
427    for statement in split.statements {
428        if !statement.balanced {
429            continue;
430        }
431        let span = statement.span;
432        match parser.parse(&text[span.clone()]).into_result() {
433            Ok(value) => parsed.declarations.push(Spanned { value, span }),
434            Err(errors) => {
435                if let Some(error) = furthest(&errors) {
436                    parsed.errors.push(statement_error(
437                        text,
438                        span,
439                        error,
440                        Kind::Declaration,
441                        parses,
442                    ));
443                }
444            }
445        }
446    }
447    parsed.errors.sort_by_key(|error| error.span.start);
448    parsed
449}
450
451#[cfg(test)]
452mod tests;