Skip to main content

ifc_step/
location.rs

1//! Lines, columns and short quotes of the source for diagnostics.
2//!
3//! Positions follow `openbim_step::Source::location`: the line counts `\n`
4//! bytes, the column counts the Unicode characters of the line before the
5//! offset, decoding invalid UTF-8 as U+FFFD. [`positions`] answers many
6//! offsets in one forward pass instead of one scan from the start each.
7//! [`SyntaxLocation`] places one failure and quotes the line it is on.
8
9use std::ops::Range;
10
11use std::fmt;
12
13use ifc_model::{ModelError, SourcePosition};
14
15use crate::StepError;
16
17/// Most characters of the source a diagnostic quotes.
18pub(crate) const EXCERPT_CHARS: usize = 120;
19
20/// The positions of `offsets` in `input`, in the order of `offsets`.
21///
22/// An offset past the end is clamped to the end. Within a line the column
23/// carries forward from the previous offset, so many offsets on one long line
24/// cost one pass over it, not one pass each.
25pub(crate) fn positions(input: &[u8], offsets: &[usize]) -> Vec<SourcePosition> {
26    let mut order: Vec<usize> = (0..offsets.len()).collect();
27    order.sort_by_key(|&index| offsets[index]);
28    let mut found = vec![SourcePosition::new(1, 1); offsets.len()];
29    let (mut at, mut line, mut line_start) = (0, 1, 0);
30    // The column at `checkpoint`, 1-based, on the current line.
31    let (mut checkpoint, mut checkpoint_column) = (0, 1);
32    for index in order {
33        let offset = offsets[index].min(input.len());
34        for (step, byte) in input[at..offset].iter().enumerate() {
35            if *byte == b'\n' {
36                line += 1;
37                line_start = at + step + 1;
38                (checkpoint, checkpoint_column) = (line_start, 1);
39            }
40        }
41        at = offset;
42        // Decoding is lossy, so the count of two halves equals the count of
43        // the whole only when the split lies before an ASCII byte (or at
44        // the end); otherwise count from the line start again.
45        if !input.get(checkpoint).is_none_or(u8::is_ascii) {
46            (checkpoint, checkpoint_column) = (line_start, 1);
47        }
48        let column = checkpoint_column
49            + String::from_utf8_lossy(&input[checkpoint..offset])
50                .chars()
51                .count();
52        (checkpoint, checkpoint_column) = (offset, column);
53        found[index] = SourcePosition::new(line, column);
54    }
55    found
56}
57
58/// A quote of the first [`EXCERPT_CHARS`] characters of `range`, line breaks
59/// and tabs as spaces, with `…` when the range goes on.
60pub(crate) fn excerpt_of(input: &[u8], range: Range<usize>) -> String {
61    let end = range.end.min(input.len());
62    let start = range.start.min(end);
63    // Four bytes cover any character; one byte more shows the range goes on.
64    let take = (end - start).min(EXCERPT_CHARS * 4 + 1);
65    let text = String::from_utf8_lossy(&input[start..start + take]);
66    let mut chars = text.chars();
67    let mut quote: String = chars.by_ref().take(EXCERPT_CHARS).map(plain).collect();
68    if chars.next().is_some() || take < end - start {
69        quote.push('…');
70    }
71    quote
72}
73
74/// Line breaks and tabs as a space, so a quote stays on one line.
75pub(crate) fn plain(c: char) -> char {
76    if matches!(c, '\r' | '\n' | '\t') {
77        ' '
78    } else {
79        c
80    }
81}
82
83/// Where a read failed: the byte offset, its line and column and a quote of
84/// the offending line.
85///
86/// The quote is the whole line when it fits in 120 characters.
87/// A longer line is cut to a window of 120 characters around the
88/// offset, with `…` on each cut end. Line breaks and tabs are spaces.
89#[derive(Debug, Clone, PartialEq, Eq)]
90pub struct SyntaxLocation {
91    offset: usize,
92    position: SourcePosition,
93    excerpt: String,
94    excerpt_column: usize,
95}
96
97impl SyntaxLocation {
98    /// The location of byte `offset` in `input`, clamped to its length.
99    #[must_use]
100    pub fn at(input: &[u8], offset: usize) -> Self {
101        let offset = offset.min(input.len());
102        let position = positions(input, &[offset])[0];
103        let line_start = input[..offset]
104            .iter()
105            .rposition(|byte| *byte == b'\n')
106            .map_or(0, |at| at + 1);
107        let line_end = input[offset..]
108            .iter()
109            .position(|byte| *byte == b'\n')
110            .map_or(input.len(), |at| offset + at);
111        let mut line = &input[line_start..line_end];
112        if let Some(rest) = line.strip_suffix(b"\r") {
113            line = rest;
114        }
115        let chars: Vec<char> = String::from_utf8_lossy(line).chars().map(plain).collect();
116        let column = position.column();
117        let (excerpt, excerpt_column) = if chars.len() <= EXCERPT_CHARS {
118            (chars.iter().collect(), column)
119        } else {
120            let start = (column - 1)
121                .saturating_sub(EXCERPT_CHARS / 2)
122                .min(chars.len() - EXCERPT_CHARS);
123            let end = start + EXCERPT_CHARS;
124            let mut text = String::new();
125            if start > 0 {
126                text.push('…');
127            }
128            text.extend(&chars[start..end]);
129            if end < chars.len() {
130                text.push('…');
131            }
132            (text, column - start + usize::from(start > 0))
133        };
134        // A position at the end of the line points one past its last char.
135        let excerpt_column = excerpt_column.min(excerpt.chars().count() + 1);
136        Self {
137            offset,
138            position,
139            excerpt,
140            excerpt_column,
141        }
142    }
143
144    /// The location of a syntax error in `input`; `None` for any other
145    /// error.
146    #[must_use]
147    pub fn locate(input: &[u8], error: &ModelError) -> Option<Self> {
148        match error {
149            ModelError::Syntax { offset, .. } => Some(Self::at(input, *offset)),
150            _ => None,
151        }
152    }
153
154    /// The location of a STEP error that names a byte offset
155    /// ([`StepError::Syntax`], [`StepError::MissingEntityId`],
156    /// [`StepError::RealWithoutDecimalPoint`], [`StepError::DuplicateId`]);
157    /// `None` for any other.
158    #[must_use]
159    pub fn of_step_error(input: &[u8], error: &StepError) -> Option<Self> {
160        match error {
161            StepError::Syntax { offset, .. }
162            | StepError::MissingEntityId { offset }
163            | StepError::RealWithoutDecimalPoint { offset, .. }
164            | StepError::DuplicateId { offset, .. } => Some(Self::at(input, *offset)),
165            _ => None,
166        }
167    }
168
169    /// Byte offset into the input.
170    #[must_use]
171    pub const fn offset(&self) -> usize {
172        self.offset
173    }
174
175    /// Line and column of the offset.
176    #[must_use]
177    pub const fn position(&self) -> SourcePosition {
178        self.position
179    }
180
181    /// The quoted line, or the window of it around the offset.
182    #[must_use]
183    pub fn excerpt(&self) -> &str {
184        &self.excerpt
185    }
186
187    /// 1-based column of the offset within [`SyntaxLocation::excerpt`],
188    /// counted in characters, a leading `…` included.
189    #[must_use]
190    pub const fn excerpt_column(&self) -> usize {
191        self.excerpt_column
192    }
193}
194
195impl fmt::Display for SyntaxLocation {
196    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
197        write!(formatter, "{}: {}", self.position, self.excerpt)
198    }
199}
200
201#[cfg(test)]
202mod tests {
203    use super::*;
204    use openbim_step::{Source, Span};
205
206    fn reference(input: &[u8], offset: usize) -> SourcePosition {
207        let at = Source::new("", input).location(Span::new(offset, offset));
208        SourcePosition::new(at.line, at.column)
209    }
210
211    fn agrees(input: &[u8]) {
212        // Unsorted, repeated and past-the-end offsets on purpose.
213        let mut offsets: Vec<usize> = (0..=input.len() + 2).rev().collect();
214        offsets.push(0);
215        let got = positions(input, &offsets);
216        for (offset, position) in offsets.iter().zip(got) {
217            assert_eq!(position, reference(input, *offset), "offset {offset}");
218        }
219    }
220
221    #[test]
222    fn matches_the_substrate_on_lf() {
223        agrees(b"ab\ncd\n\nef");
224    }
225
226    #[test]
227    fn matches_the_substrate_on_crlf() {
228        agrees(b"ab\r\ncd\r\n#1=X();\r\n");
229    }
230
231    #[test]
232    fn matches_the_substrate_on_multibyte_utf8() {
233        agrees("a\u{e4}\u{20ac}b\n\u{1f600}x\n".as_bytes());
234    }
235
236    #[test]
237    fn matches_the_substrate_on_invalid_utf8() {
238        agrees(b"a\xffb\n\xc3\xe4\n\xe2\x82");
239    }
240
241    #[test]
242    fn many_offsets_on_one_line_agree_with_the_substrate() {
243        // Mixed widths, invalid bytes and a few line breaks, so checkpoints
244        // land before ASCII and before continuation bytes.
245        let mut input = Vec::new();
246        for n in 0..40 {
247            input.extend_from_slice(format!("#{n}=X('a").as_bytes());
248            input.extend_from_slice(["\u{e4}", "\u{20ac}", "\u{1f600}"][n % 3].as_bytes());
249            input.extend_from_slice(if n % 7 == 0 { b"\xff" } else { b"b" });
250            input.extend_from_slice(if n % 13 == 12 { b"');\n" } else { b"');" });
251        }
252        agrees(&input);
253    }
254
255    #[test]
256    fn twenty_thousand_records_on_one_line_are_positioned() {
257        let input: Vec<u8> = (0..20_000)
258            .flat_map(|n| format!("#{n}=X();").into_bytes())
259            .collect();
260        let starts: Vec<usize> = (0..60_000).map(|n| n * input.len() / 60_000).collect();
261        let got = positions(&input, &starts);
262        assert!(got.iter().all(|p| p.line() == 1));
263        assert!(got.windows(2).all(|w| w[0].column() <= w[1].column()));
264        assert_eq!(got[0], SourcePosition::new(1, 1));
265    }
266
267    #[test]
268    fn offset_at_the_end_is_the_last_position() {
269        assert_eq!(positions(b"ab\ncd", &[5]), [SourcePosition::new(2, 3)]);
270        assert_eq!(positions(b"", &[0]), [SourcePosition::new(1, 1)]);
271    }
272
273    #[test]
274    fn excerpt_cuts_at_the_limit_and_flattens_breaks() {
275        assert_eq!(excerpt_of(b"a\r\n\tb", 0..5), "a   b");
276        let long = "x".repeat(300);
277        let quote = excerpt_of(long.as_bytes(), 0..300);
278        assert_eq!(quote.chars().count(), EXCERPT_CHARS + 1);
279        assert!(quote.ends_with('…'));
280        let exact = "y".repeat(EXCERPT_CHARS);
281        assert_eq!(excerpt_of(exact.as_bytes(), 0..EXCERPT_CHARS), exact);
282        assert_eq!(excerpt_of(b"abc", 2..99), "c");
283    }
284}