Skip to main content

vihaco_syntax/
statements.rs

1// SPDX-FileCopyrightText: 2026 The vihaco Authors
2// SPDX-License-Identifier: MIT
3
4//! Splitting a block into statements: the line rules of SST.
5//!
6//! A statement ends at the end of its line. It continues onto the next line
7//! only while a `(`, `[`, or `{` is open, like implicit line joining in
8//! Python; there is no `\` continuation and no statement terminator. A comment
9//! runs from `;` to the end of the line, except inside a `"…"` string literal.
10//! Indentation and spacing carry no meaning, and `\r\n` is a newline.
11//!
12//! [`statements`] is a pre-pass: it finds each statement's span in the block
13//! and leaves the statement text untouched, so the derived parsers run over a
14//! slice of the original text and every span they report is a block offset.
15//! A comment inside a bracket-continued statement stays in its slice, where
16//! the trivia of collections and records skips it.
17
18use std::ops::Range;
19
20use crate::spanned::SyntaxError;
21
22/// One statement of a block.
23#[derive(Debug, Clone, PartialEq, Eq)]
24pub struct Statement {
25    /// From the first character of the statement to its last character that
26    /// is not whitespace or a comment, relative to the block.
27    pub span: Range<usize>,
28    /// Whether the statement's brackets are balanced. An unbalanced statement
29    /// has already been reported in [`Statements::errors`] and should not be
30    /// parsed.
31    pub balanced: bool,
32}
33
34/// The statements of a block and its bracket errors.
35#[derive(Debug, Clone, PartialEq, Eq)]
36pub struct Statements {
37    pub statements: Vec<Statement>,
38    /// One error per unclosed bracket, at the bracket.
39    pub errors: Vec<SyntaxError>,
40}
41
42fn closer(open: char) -> char {
43    match open {
44        '(' => ')',
45        '[' => ']',
46        _ => '}',
47    }
48}
49
50/// The offset of the end of the string literal whose opening `"` is at
51/// `start`: just past its closing `"`, or the end of the line if it is not
52/// closed on its line.
53fn string_end(text: &str, start: usize) -> usize {
54    let bytes = text.as_bytes();
55    let mut index = start + 1;
56    while index < bytes.len() {
57        match bytes[index] {
58            b'\\' if bytes.get(index + 1).is_some_and(|b| *b != b'\n') => index += 2,
59            b'"' => return index + 1,
60            b'\n' => return index,
61            _ => index += 1,
62        }
63    }
64    bytes.len()
65}
66
67/// The end of the physical line containing `offset`, excluding the `\n`.
68fn line_end(text: &str, offset: usize) -> usize {
69    text[offset..]
70        .find('\n')
71        .map_or(text.len(), |index| offset + index)
72}
73
74/// Split `text` into statements. `first_line` is the file line of the start
75/// of `text`, used in error messages.
76///
77/// An unclosed bracket is reported as ``unclosed `[` opened at line N``; its
78/// statement is cut at the end of the bracket's line and marked unbalanced,
79/// and splitting resumes on the next line, so the rest of the block is
80/// unaffected. A closing bracket that matches no open bracket is left to the
81/// statement's parser.
82pub fn statements(text: &str, first_line: usize) -> Statements {
83    let line_of = |offset: usize| first_line + text[..offset].matches('\n').count();
84    let mut out = Statements {
85        statements: Vec::new(),
86        errors: Vec::new(),
87    };
88    let mut position = 0;
89    while position < text.len() {
90        // One statement, starting on the physical line at `position`.
91        let mut open: Vec<(char, usize)> = Vec::new();
92        let mut start = None;
93        let mut end = position;
94        let mut balanced = true;
95        let mut index = position;
96        let mut next = text.len();
97        while index < text.len() {
98            let c = text[index..].chars().next().expect("in bounds");
99            match c {
100                '\n' if open.is_empty() => {
101                    next = index + 1;
102                    break;
103                }
104                ';' => {
105                    index = line_end(text, index);
106                    continue;
107                }
108                c if c.is_whitespace() => {
109                    index += c.len_utf8();
110                    continue;
111                }
112                '"' => {
113                    start.get_or_insert(index);
114                    index = string_end(text, index);
115                    end = index;
116                    continue;
117                }
118                '(' | '[' | '{' => open.push((c, index)),
119                ')' | ']' | '}' => {
120                    if let Some(found) = open.iter().rposition(|(open, _)| closer(*open) == c) {
121                        // Brackets opened inside this pair and never closed.
122                        for &(bracket, at) in &open[found + 1..] {
123                            out.errors.push(unclosed(bracket, at, line_of(at)));
124                            balanced = false;
125                        }
126                        open.truncate(found);
127                    }
128                }
129                _ => {}
130            }
131            start.get_or_insert(index);
132            index += c.len_utf8();
133            end = index;
134        }
135        if let Some(&(bracket, at)) = open.first() {
136            // The block ended inside a bracket: report the outermost one, cut
137            // the statement at the end of its line, and resume after it.
138            let cut = line_end(text, at);
139            // Lines after the cut are split again; forget what they reported.
140            out.errors.retain(|error| error.span.start < cut);
141            out.errors.push(unclosed(bracket, at, line_of(at)));
142            end = trim_comment_end(text, start.unwrap_or(at), cut);
143            balanced = false;
144            next = (cut + 1).min(text.len());
145        }
146        if let Some(start) = start {
147            out.statements.push(Statement {
148                span: start..end.max(start),
149                balanced,
150            });
151        }
152        position = next;
153    }
154    out.errors.sort_by_key(|error| error.span.start);
155    out
156}
157
158/// The end of the code between `start` and `limit` on one line: before any
159/// comment and trailing whitespace.
160fn trim_comment_end(text: &str, start: usize, limit: usize) -> usize {
161    let mut index = start;
162    let mut end = start;
163    while index < limit {
164        let c = text[index..].chars().next().expect("in bounds");
165        match c {
166            ';' => break,
167            '"' => {
168                index = string_end(text, index).min(limit);
169                end = index;
170            }
171            c if c.is_whitespace() => index += c.len_utf8(),
172            c => {
173                index += c.len_utf8();
174                end = index;
175            }
176        }
177    }
178    end
179}
180
181fn unclosed(bracket: char, at: usize, line: usize) -> SyntaxError {
182    SyntaxError {
183        span: at..at + 1,
184        message: format!("unclosed `{bracket}` opened at line {line}"),
185        label: format!("this `{bracket}` is never closed"),
186    }
187}
188
189#[cfg(test)]
190mod tests {
191    use super::*;
192
193    fn split(text: &str) -> Vec<&str> {
194        statements(text, 1)
195            .statements
196            .iter()
197            .map(|statement| &text[statement.span.clone()])
198            .collect()
199    }
200
201    #[test]
202    fn statements_end_at_the_end_of_the_line() {
203        assert_eq!(
204            split("  a 1  ; one\n\n\tb ; two\r\n; only a comment\nc"),
205            ["a 1", "b", "c"]
206        );
207    }
208
209    #[test]
210    fn brackets_continue_a_statement() {
211        let text = "x [1, ; first\n  2,\n] y\nz (\n)\n";
212        assert_eq!(split(text), ["x [1, ; first\n  2,\n] y", "z (\n)"]);
213    }
214
215    #[test]
216    fn semicolons_in_strings_are_not_comments() {
217        assert_eq!(split("p \"a ; b\" ; c\n"), ["p \"a ; b\""]);
218        assert_eq!(split("p \"[\" q\nr"), ["p \"[\" q", "r"]);
219    }
220
221    #[test]
222    fn unclosed_brackets_are_reported_and_splitting_recovers() {
223        let text = "a\nb [1,\nc\nd\n";
224        let split = statements(text, 10);
225        let spans: Vec<_> = split
226            .statements
227            .iter()
228            .map(|statement| (&text[statement.span.clone()], statement.balanced))
229            .collect();
230        assert_eq!(
231            spans,
232            [("a", true), ("b [1,", false), ("c", true), ("d", true)]
233        );
234        assert_eq!(split.errors.len(), 1);
235        assert_eq!(split.errors[0].message, "unclosed `[` opened at line 11");
236        assert_eq!(split.errors[0].span, 4..5);
237    }
238
239    #[test]
240    fn mismatched_closers_report_the_inner_bracket() {
241        let split = statements("a { [ }\nb\n", 1);
242        assert_eq!(split.errors[0].message, "unclosed `[` opened at line 1");
243        assert!(!split.statements[0].balanced);
244        assert!(split.statements[1].balanced);
245    }
246}