token_parser/
lib.rs

1#![deny(missing_docs)]
2
3/*!
4Some utilities for parsing some format based on nested lists into arbitrary data structures.
5It's also meant to be used as a backend for parsers.
6**/
7
8use std::path::PathBuf;
9
10use thiserror::Error;
11
12/// A trait required for all contexts being used for token parsing.
13///
14/// By default, only the empty tuple implements it.
15/// It currently does not contain anything by default. It's just there to achieve compatibility with features and to allow more changes without breaking anything.
16pub trait Context {
17    #[cfg(feature = "radix-parsing")]
18    #[inline]
19    /// Specifies the radix if the feature radix parsing is enabled.
20    fn radix(&self) -> u32 {
21        10
22    }
23}
24
25impl Context for () {}
26
27/// A source position with line and column (both 0-based).
28#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
29pub struct Span {
30    /// The line number (0-based).
31    pub line: usize,
32    /// The column number (0-based).
33    pub column: usize,
34}
35
36impl std::fmt::Display for Span {
37    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
38        write!(f, "{}:{}", self.line + 1, self.column + 1)
39    }
40}
41
42/// The kind of error that occurred during token parsing.
43#[derive(Debug, Error)]
44pub enum ErrorKind {
45    /// The sublist contains less elements than expected by a specified amount.
46    #[error("Not enough elements: {0} more expected")]
47    NotEnoughElements(usize),
48
49    /// The sublist contains more elements than expected by a specified amount.
50    #[error("Too many elements: {0} less expected")]
51    TooManyElements(usize),
52
53    /// No list is allowed in this context.
54    #[error("List not allowed")]
55    ListNotAllowed,
56
57    /// No symbol is allowed in this context.
58    #[error("Symbol not allowed")]
59    SymbolNotAllowed,
60
61    /// Error with string parsing.
62    #[error("String parsing error")]
63    StringParsing,
64
65    /// Some specific element is invalid.
66    #[error("Invalid element")]
67    InvalidElement,
68}
69
70/// The error type for token parsing, containing a kind and an optional source position.
71#[derive(Debug)]
72pub struct Error {
73    /// The kind of error.
74    pub kind: ErrorKind,
75    /// The source position where the error occurred, if known.
76    pub span: Option<Span>,
77}
78
79impl std::fmt::Display for Error {
80    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
81        if let Some(span) = self.span {
82            write!(f, "{span}: {}", self.kind)
83        } else {
84            write!(f, "{}", self.kind)
85        }
86    }
87}
88
89impl std::error::Error for Error {}
90
91impl From<ErrorKind> for Error {
92    fn from(kind: ErrorKind) -> Self {
93        Error { kind, span: None }
94    }
95}
96
97impl Error {
98    fn at(self, span: Span) -> Self {
99        Error {
100            kind: self.kind,
101            span: self.span.or(Some(span)),
102        }
103    }
104}
105
106/// The result type for token parsing.
107pub type Result<T> = std::result::Result<T, Error>;
108
109/// Some unit, which represents an intermediate state.
110#[derive(Clone)]
111pub enum Unit {
112    /// The current unit is a single symbol.
113    Symbol(Box<str>, Span),
114    /// The current unit is a parser, which can yield multiple units.
115    Parser(Parser),
116}
117
118impl Unit {
119    /// Returns the source span of this unit.
120    pub fn span(&self) -> Span {
121        match self {
122            Self::Symbol(_, span) => *span,
123            Self::Parser(parser) => parser.span,
124        }
125    }
126
127    /// Returns the symbol, if applicable, as a result type.
128    pub fn symbol(self) -> Result<Box<str>> {
129        if let Self::Symbol(name, _) = self {
130            Ok(name)
131        } else {
132            Err(ErrorKind::ListNotAllowed.into())
133        }
134    }
135
136    /// Returns the parser, if applicable, as a result type.
137    pub fn parser(self) -> Result<Parser> {
138        if let Self::Parser(parser) = self {
139            Ok(parser)
140        } else {
141            Err(ErrorKind::SymbolNotAllowed.into())
142        }
143    }
144
145    /// Replaces all occurrences of a symbol with another symbol, recursively.
146    pub fn substitute(&mut self, variable: &str, value: &str) {
147        match self {
148            Self::Symbol(name, _) => {
149                if name.as_ref() == variable {
150                    *name = value.into();
151                }
152            }
153            Self::Parser(parser) => parser.substitute(variable, value),
154        }
155    }
156}
157
158impl<C: Context> Parsable<C> for Unit {
159    fn parse_symbol(name: Box<str>, span: Span, _context: &C) -> Result<Self> {
160        Ok(Self::Symbol(name, span))
161    }
162
163    fn parse_list(parser: &mut Parser, _context: &C) -> Result<Self> {
164        let form = std::mem::take(&mut parser.form);
165        let span = parser.span;
166        Ok(Self::Parser(Parser {
167            form,
168            count: 0,
169            span,
170        }))
171    }
172}
173
174/// This trait needs to be implemented for every struct which can be parsed using the token parser.
175#[allow(clippy::boxed_local)]
176pub trait Parsable<C: Context>: Sized {
177    /// When a symbol is found by the parser, this will be called.
178    fn parse_symbol(_name: Box<str>, _span: Span, _context: &C) -> Result<Self> {
179        Err(ErrorKind::SymbolNotAllowed.into())
180    }
181
182    /// When a subparser is found by the parser, this will be called.
183    fn parse_list(_parser: &mut Parser, _context: &C) -> Result<Self> {
184        Err(ErrorKind::ListNotAllowed.into())
185    }
186}
187
188fn parse<C: Context, P: Parsable<C>>(unit: Unit, context: &C) -> Result<P> {
189    match unit {
190        Unit::Symbol(name, span) => {
191            Parsable::parse_symbol(name, span, context).map_err(|e| e.at(span))
192        }
193        Unit::Parser(mut parser) => {
194            let span = parser.span;
195            Parsable::parse_list(&mut parser, context).map_err(|e| e.at(span))
196        }
197    }
198}
199
200impl<C: Context, T: Parsable<C>> Parsable<C> for Box<T> {
201    fn parse_symbol(name: Box<str>, span: Span, context: &C) -> Result<Self> {
202        Ok(Self::new(Parsable::parse_symbol(name, span, context)?))
203    }
204
205    fn parse_list(parser: &mut Parser, context: &C) -> Result<Self> {
206        Ok(Self::new(parser.parse_list(context)?))
207    }
208}
209
210impl<C: Context, T: Parsable<C>> Parsable<C> for Vec<T> {
211    fn parse_list(parser: &mut Parser, context: &C) -> Result<Self> {
212        let Parser { form, count, .. } = parser;
213        form.drain(..)
214            .rev()
215            .map(|unit| {
216                *count += 1;
217                parse(unit, context)
218            })
219            .collect()
220    }
221}
222
223impl<C: Context> Parsable<C> for String {
224    fn parse_symbol(name: Box<str>, _span: Span, _context: &C) -> Result<Self> {
225        Ok(name.into())
226    }
227}
228
229impl<C: Context> Parsable<C> for Box<str> {
230    fn parse_symbol(name: Box<str>, _span: Span, _context: &C) -> Result<Self> {
231        Ok(name)
232    }
233}
234
235impl<C: Context> Parsable<C> for PathBuf {
236    fn parse_symbol(name: Box<str>, _span: Span, _context: &C) -> Result<Self> {
237        Ok(name.as_ref().into())
238    }
239}
240
241/// Derives `Parsable` from symbol for types which implement `FromStr`.
242#[macro_export]
243macro_rules! derive_symbol_parsable {
244    ($t:ty) => {
245        impl<C: $crate::Context> $crate::Parsable<C> for $t {
246            fn parse_symbol(name: Box<str>, _span: $crate::Span, _context: &C) -> $crate::Result<Self> {
247                name.parse().map_err(|_| $crate::ErrorKind::StringParsing.into())
248            }
249        }
250    };
251    ($t:ty, $($rest:ty),+) => {
252        derive_symbol_parsable!($t);
253        derive_symbol_parsable!($($rest),+);
254    };
255}
256
257#[cfg(not(feature = "radix-parsing"))]
258mod numbers;
259derive_symbol_parsable!(bool);
260
261/// The token parser to parse the units into wanted types.
262#[derive(Clone)]
263pub struct Parser {
264    form: Vec<Unit>,
265    count: usize,
266    span: Span,
267}
268
269impl Parser {
270    /// Creates a new parser from a list of objects.
271    pub fn new<I: IntoIterator>(form: I) -> Self
272    where
273        I::Item: Into<Unit>,
274    {
275        let mut form: Vec<_> = form.into_iter().map(I::Item::into).collect();
276        form.reverse();
277        Self {
278            form,
279            count: 0,
280            span: Span::default(),
281        }
282    }
283
284    /// Sets the span for this parser (builder pattern).
285    pub fn with_span(mut self, span: Span) -> Self {
286        self.span = span;
287        self
288    }
289
290    /// Returns the source span of this parser.
291    pub fn span(&self) -> Span {
292        self.span
293    }
294
295    /// Returns whether the parser has no remaining elements.
296    pub fn is_empty(&self) -> bool {
297        self.form.is_empty()
298    }
299
300    /// Replaces all occurrences of a symbol with another symbol, recursively.
301    pub fn substitute(&mut self, variable: &str, value: &str) {
302        for unit in &mut self.form {
303            unit.substitute(variable, value);
304        }
305    }
306
307    /// Returns the next unit without parsing it, or `None` if empty.
308    pub fn next_unit(&mut self) -> Option<Unit> {
309        self.count += 1;
310        self.form.pop()
311    }
312
313    /// Tries to parse the next unit as the required type.
314    pub fn parse_next<C: Context, T: Parsable<C>>(&mut self, context: &C) -> Result<T> {
315        self.count += 1;
316        if let Some(token) = self.form.pop() {
317            parse(token, context)
318        } else {
319            Result::Err(Error {
320                kind: ErrorKind::NotEnoughElements(self.count),
321                span: Some(self.span),
322            })
323        }
324    }
325
326    /// Tries to parse the rest of the current list into the required type.
327    /// If not every available token is used, this will be an error.
328    pub fn parse_rest<C: Context, T: Parsable<C>>(&mut self, context: &C) -> Result<T> {
329        let result = self.parse_list(context);
330        let count = self.form.len();
331        if count > 0 {
332            self.form.clear();
333            Err(Error {
334                kind: ErrorKind::TooManyElements(count),
335                span: Some(self.span),
336            })
337        } else {
338            result
339        }
340    }
341
342    /// Tries to parse as many tokens of the current list as needed into the required type.
343    pub fn parse_list<C: Context, T: Parsable<C>>(&mut self, context: &C) -> Result<T> {
344        Parsable::parse_list(self, context)
345    }
346}
347
348impl Iterator for Parser {
349    type Item = Result<Self>;
350
351    fn next(&mut self) -> Option<Result<Self>> {
352        self.count += 1;
353        Some(self.form.pop()?.parser())
354    }
355}
356
357#[cfg(feature = "radix-parsing")]
358/// Contains utilities for radix parsing.
359pub mod radix;
token_parser/lib.rs

token_parser/
lib.rs
