sheet_core/error.rs
1//! Typed, exhaustive error taxonomy for formula reference extraction.
2//!
3//! Following the estate's error discipline (see `wire-kit`): the enum is
4//! deliberately **exhaustive** (no `#[non_exhaustive]`) — callers match every
5//! variant, and a new variant is a semver-minor event by design. Extraction
6//! is total: malformed formulas yield one of these variants, never a panic.
7
8use alloc::string::String;
9use core::fmt;
10
11/// Everything that can go wrong while extracting references from a formula.
12#[derive(Debug, Clone, PartialEq, Eq)]
13pub enum GraphError {
14 /// The formula text was empty or held nothing but the leading `=`.
15 EmptyFormula,
16 /// A string literal (`"…"`) was opened but never closed. Bytes inside a
17 /// string literal are not scanned for references, so an unterminated
18 /// literal poisons the rest of the formula.
19 UnterminatedString {
20 /// Byte offset of the opening `"`.
21 position: usize,
22 },
23 /// A quoted sheet name (`'My Sheet'!A1`) was opened but never closed.
24 UnterminatedQuote {
25 /// Byte offset of the opening `'`.
26 position: usize,
27 },
28 /// An explicit sheet qualifier (`Sheet1!`, `'My Sheet'!`) was not
29 /// followed by a parseable cell reference. Unlike unqualified junk —
30 /// which the lenient scanner skips — a qualifier is explicit user
31 /// intent, so its failure is reported.
32 InvalidReference {
33 /// Byte offset of the malformed reference.
34 position: usize,
35 /// The offending text (up to 32 bytes, truncated with `…`).
36 text: String,
37 },
38 /// A column name would exceed the crate's coordinate space (`u32`
39 /// column index, 0-based). Practical grids are far smaller; this guards
40 /// pathological input like `AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA1`.
41 ColumnOverflow {
42 /// Byte offset of the column name.
43 position: usize,
44 /// The offending column letters.
45 text: String,
46 },
47 /// A row number would exceed the crate's coordinate space (`u32` row
48 /// index, 0-based; row numbers are 1-based in `A1` notation).
49 RowOverflow {
50 /// Byte offset of the row digits.
51 position: usize,
52 /// The offending digits.
53 text: String,
54 },
55 /// A range reference would expand to more than
56 /// [`crate::refs::RANGE_CELL_CAP`] individual cells (e.g. a
57 /// whole-column `A:A` reference). The per-cell dependency model
58 /// requires materializing every cell in a range; refusing beats
59 /// silently allocating millions of edges. Pass an explicit bounded
60 /// range instead.
61 RangeTooLarge {
62 /// Normalized upper-left corner of the range (inclusive).
63 start: (u32, u32),
64 /// Normalized lower-right corner of the range (inclusive).
65 end: (u32, u32),
66 /// Number of cells the range covers.
67 cells: u64,
68 },
69}
70
71impl fmt::Display for GraphError {
72 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
73 match self {
74 GraphError::EmptyFormula => write!(f, "formula is empty"),
75 GraphError::UnterminatedString { position } => {
76 write!(f, "unterminated string literal at byte {position}")
77 }
78 GraphError::UnterminatedQuote { position } => {
79 write!(f, "unterminated quoted sheet name at byte {position}")
80 }
81 GraphError::InvalidReference { position, text } => {
82 write!(f, "invalid cell reference at byte {position}: {text:?}")
83 }
84 GraphError::ColumnOverflow { position, text } => {
85 write!(
86 f,
87 "column {text:?} at byte {position} exceeds u32 coordinate space"
88 )
89 }
90 GraphError::RowOverflow { position, text } => {
91 write!(
92 f,
93 "row {text:?} at byte {position} exceeds u32 coordinate space"
94 )
95 }
96 GraphError::RangeTooLarge { start, end, cells } => write!(
97 f,
98 "range ({},{}):({},{}) covers {cells} cells, above the expansion cap",
99 start.0, start.1, end.0, end.1
100 ),
101 }
102 }
103}
104
105impl core::error::Error for GraphError {}
106
107#[cfg(test)]
108mod tests {
109 #![allow(
110 clippy::unwrap_used,
111 clippy::expect_used,
112 clippy::panic,
113 clippy::indexing_slicing
114 )]
115
116 use super::GraphError;
117 use alloc::{format, string::String};
118
119 #[test]
120 fn display_is_informative_and_total() {
121 let cases = [
122 GraphError::EmptyFormula,
123 GraphError::UnterminatedString { position: 3 },
124 GraphError::UnterminatedQuote { position: 5 },
125 GraphError::InvalidReference {
126 position: 8,
127 text: String::from("1A"),
128 },
129 GraphError::ColumnOverflow {
130 position: 1,
131 text: String::from("ZZZZ"),
132 },
133 GraphError::RowOverflow {
134 position: 2,
135 text: String::from("99999"),
136 },
137 GraphError::RangeTooLarge {
138 start: (0, 0),
139 end: (9, 9),
140 cells: 100,
141 },
142 ];
143 for e in cases {
144 let s = format!("{e}");
145 assert!(!s.is_empty(), "{e:?} rendered empty");
146 }
147 }
148}