Skip to main content

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}