time/format_description/parse/
ast.rs

Help
1//! AST for parsing format descriptions.
2
3use alloc::boxed::Box;
4use alloc::string::String;
5use alloc::vec::Vec;
6use core::iter;
7
8use super::{lexer, unused, Error, Location, Spanned, SpannedValue, Unused};
9use crate::internal_macros::bug;
10
11/// One part of a complete format description.
12pub(super) enum Item<'a> {
13    /// A literal string, formatted and parsed as-is.
14    ///
15    /// This should never be present inside a nested format description.
16    Literal(Spanned<&'a [u8]>),
17    /// A sequence of brackets. The first acts as the escape character.
18    ///
19    /// This should never be present if the lexer has `BACKSLASH_ESCAPE` set to `true`.
20    EscapedBracket {
21        /// The first bracket.
22        _first: Unused<Location>,
23        /// The second bracket.
24        _second: Unused<Location>,
25    },
26    /// Part of a type, along with its modifiers.
27    Component {
28        /// Where the opening bracket was in the format string.
29        _opening_bracket: Unused<Location>,
30        /// Whitespace between the opening bracket and name.
31        _leading_whitespace: Unused<Option<Spanned<&'a [u8]>>>,
32        /// The name of the component.
33        name: Spanned<&'a [u8]>,
34        /// The modifiers for the component.
35        modifiers: Box<[Modifier<'a>]>,
36        /// Whitespace between the modifiers and closing bracket.
37        _trailing_whitespace: Unused<Option<Spanned<&'a [u8]>>>,
38        /// Where the closing bracket was in the format string.
39        _closing_bracket: Unused<Location>,
40    },
41    /// An optional sequence of items.
42    Optional {
43        /// Where the opening bracket was in the format string.
44        opening_bracket: Location,
45        /// Whitespace between the opening bracket and "optional".
46        _leading_whitespace: Unused<Option<Spanned<&'a [u8]>>>,
47        /// The "optional" keyword.
48        _optional_kw: Unused<Spanned<&'a [u8]>>,
49        /// Whitespace between the "optional" keyword and the opening bracket.
50        _whitespace: Unused<Spanned<&'a [u8]>>,
51        /// The items within the optional sequence.
52        nested_format_description: NestedFormatDescription<'a>,
53        /// Where the closing bracket was in the format string.
54        closing_bracket: Location,
55    },
56    /// The first matching parse of a sequence of items.
57    First {
58        /// Where the opening bracket was in the format string.
59        opening_bracket: Location,
60        /// Whitespace between the opening bracket and "first".
61        _leading_whitespace: Unused<Option<Spanned<&'a [u8]>>>,
62        /// The "first" keyword.
63        _first_kw: Unused<Spanned<&'a [u8]>>,
64        /// Whitespace between the "first" keyword and the opening bracket.
65        _whitespace: Unused<Spanned<&'a [u8]>>,
66        /// The sequences of items to try.
67        nested_format_descriptions: Box<[NestedFormatDescription<'a>]>,
68        /// Where the closing bracket was in the format string.
69        closing_bracket: Location,
70    },
71}
72
73/// A format description that is nested within another format description.
74pub(super) struct NestedFormatDescription<'a> {
75    /// Where the opening bracket was in the format string.
76    pub(super) _opening_bracket: Unused<Location>,
77    /// The items within the nested format description.
78    pub(super) items: Box<[Item<'a>]>,
79    /// Where the closing bracket was in the format string.
80    pub(super) _closing_bracket: Unused<Location>,
81    /// Whitespace between the closing bracket and the next item.
82    pub(super) _trailing_whitespace: Unused<Option<Spanned<&'a [u8]>>>,
83}
84
85/// A modifier for a component.
86pub(super) struct Modifier<'a> {
87    /// Whitespace preceding the modifier.
88    pub(super) _leading_whitespace: Unused<Spanned<&'a [u8]>>,
89    /// The key of the modifier.
90    pub(super) key: Spanned<&'a [u8]>,
91    /// Where the colon of the modifier was in the format string.
92    pub(super) _colon: Unused<Location>,
93    /// The value of the modifier.
94    pub(super) value: Spanned<&'a [u8]>,
95}
96
97/// Parse the provided tokens into an AST.
98pub(super) fn parse<
99    'item: 'iter,
100    'iter,
101    I: Iterator<Item = Result<lexer::Token<'item>, Error>>,
102    const VERSION: usize,
103>(
104    tokens: &'iter mut lexer::Lexed<I>,
105) -> impl Iterator<Item = Result<Item<'item>, Error>> + 'iter {
106    validate_version!(VERSION);
107    parse_inner::<_, false, VERSION>(tokens)
108}
109
110/// Parse the provided tokens into an AST. The const generic indicates whether the resulting
111/// [`Item`] will be used directly or as part of a [`NestedFormatDescription`].
112fn parse_inner<
113    'item,
114    I: Iterator<Item = Result<lexer::Token<'item>, Error>>,
115    const NESTED: bool,
116    const VERSION: usize,
117>(
118    tokens: &mut lexer::Lexed<I>,
119) -> impl Iterator<Item = Result<Item<'item>, Error>> + '_ {
120    validate_version!(VERSION);
121    iter::from_fn(move || {
122        if NESTED && tokens.peek_closing_bracket().is_some() {
123            return None;
124        }
125
126        let next = match tokens.next()? {
127            Ok(token) => token,
128            Err(err) => return Some(Err(err)),
129        };
130
131        Some(match next {
132            lexer::Token::Literal(Spanned { value: _, span: _ }) if NESTED => {
133                bug!("literal should not be present in nested description")
134            }
135            lexer::Token::Literal(value) => Ok(Item::Literal(value)),
136            lexer::Token::Bracket {
137                kind: lexer::BracketKind::Opening,
138                location,
139            } => {
140                if version!(..=1) {
141                    if let Some(second_location) = tokens.next_if_opening_bracket() {
142                        Ok(Item::EscapedBracket {
143                            _first: unused(location),
144                            _second: unused(second_location),
145                        })
146                    } else {
147                        parse_component::<_, VERSION>(location, tokens)
148                    }
149                } else {
150                    parse_component::<_, VERSION>(location, tokens)
151                }
152            }
153            lexer::Token::Bracket {
154                kind: lexer::BracketKind::Closing,
155                location: _,
156            } if NESTED => {
157                bug!("closing bracket should be caught by the `if` statement")
158            }
159            lexer::Token::Bracket {
160                kind: lexer::BracketKind::Closing,
161                location: _,
162            } => {
163                bug!("closing bracket should have been consumed by `parse_component`")
164            }
165            lexer::Token::ComponentPart {
166                kind: _, // whitespace is significant in nested components
167                value,
168            } if NESTED => Ok(Item::Literal(value)),
169            lexer::Token::ComponentPart { kind: _, value: _ } => {
170                bug!("component part should have been consumed by `parse_component`")
171            }
172        })
173    })
174}
175
176/// Parse a component. This assumes that the opening bracket has already been consumed.
177fn parse_component<
178    'a,
179    I: Iterator<Item = Result<lexer::Token<'a>, Error>>,
180    const VERSION: usize,
181>(
182    opening_bracket: Location,
183    tokens: &mut lexer::Lexed<I>,
184) -> Result<Item<'a>, Error> {
185    validate_version!(VERSION);
186    let leading_whitespace = tokens.next_if_whitespace();
187
188    let Some(name) = tokens.next_if_not_whitespace() else {
189        let span = match leading_whitespace {
190            Some(Spanned { value: _, span }) => span,
191            None => opening_bracket.to_self(),
192        };
193        return Err(Error {
194            _inner: unused(span.error("expected component name")),
195            public: crate::error::InvalidFormatDescription::MissingComponentName {
196                index: span.start.byte as _,
197            },
198        });
199    };
200
201    if *name == b"optional" {
202        let Some(whitespace) = tokens.next_if_whitespace() else {
203            return Err(Error {
204                _inner: unused(name.span.error("expected whitespace after `optional`")),
205                public: crate::error::InvalidFormatDescription::Expected {
206                    what: "whitespace after `optional`",
207                    index: name.span.end.byte as _,
208                },
209            });
210        };
211
212        let nested = parse_nested::<_, VERSION>(whitespace.span.end, tokens)?;
213
214        let Some(closing_bracket) = tokens.next_if_closing_bracket() else {
215            return Err(Error {
216                _inner: unused(opening_bracket.error("unclosed bracket")),
217                public: crate::error::InvalidFormatDescription::UnclosedOpeningBracket {
218                    index: opening_bracket.byte as _,
219                },
220            });
221        };
222
223        return Ok(Item::Optional {
224            opening_bracket,
225            _leading_whitespace: unused(leading_whitespace),
226            _optional_kw: unused(name),
227            _whitespace: unused(whitespace),
228            nested_format_description: nested,
229            closing_bracket,
230        });
231    }
232
233    if *name == b"first" {
234        let Some(whitespace) = tokens.next_if_whitespace() else {
235            return Err(Error {
236                _inner: unused(name.span.error("expected whitespace after `first`")),
237                public: crate::error::InvalidFormatDescription::Expected {
238                    what: "whitespace after `first`",
239                    index: name.span.end.byte as _,
240                },
241            });
242        };
243
244        let mut nested_format_descriptions = Vec::new();
245        while let Ok(description) = parse_nested::<_, VERSION>(whitespace.span.end, tokens) {
246            nested_format_descriptions.push(description);
247        }
248
249        let Some(closing_bracket) = tokens.next_if_closing_bracket() else {
250            return Err(Error {
251                _inner: unused(opening_bracket.error("unclosed bracket")),
252                public: crate::error::InvalidFormatDescription::UnclosedOpeningBracket {
253                    index: opening_bracket.byte as _,
254                },
255            });
256        };
257
258        return Ok(Item::First {
259            opening_bracket,
260            _leading_whitespace: unused(leading_whitespace),
261            _first_kw: unused(name),
262            _whitespace: unused(whitespace),
263            nested_format_descriptions: nested_format_descriptions.into_boxed_slice(),
264            closing_bracket,
265        });
266    }
267
268    let mut modifiers = Vec::new();
269    let trailing_whitespace = loop {
270        let Some(whitespace) = tokens.next_if_whitespace() else {
271            break None;
272        };
273
274        // This is not necessary for proper parsing, but provides a much better error when a nested
275        // description is used where it's not allowed.
276        if let Some(location) = tokens.next_if_opening_bracket() {
277            return Err(Error {
278                _inner: unused(
279                    location
280                        .to_self()
281                        .error("modifier must be of the form `key:value`"),
282                ),
283                public: crate::error::InvalidFormatDescription::InvalidModifier {
284                    value: String::from("["),
285                    index: location.byte as _,
286                },
287            });
288        }
289
290        let Some(Spanned { value, span }) = tokens.next_if_not_whitespace() else {
291            break Some(whitespace);
292        };
293
294        let Some(colon_index) = value.iter().position(|&b| b == b':') else {
295            return Err(Error {
296                _inner: unused(span.error("modifier must be of the form `key:value`")),
297                public: crate::error::InvalidFormatDescription::InvalidModifier {
298                    value: String::from_utf8_lossy(value).into_owned(),
299                    index: span.start.byte as _,
300                },
301            });
302        };
303        let key = &value[..colon_index];
304        let value = &value[colon_index + 1..];
305
306        if key.is_empty() {
307            return Err(Error {
308                _inner: unused(span.shrink_to_start().error("expected modifier key")),
309                public: crate::error::InvalidFormatDescription::InvalidModifier {
310                    value: String::new(),
311                    index: span.start.byte as _,
312                },
313            });
314        }
315        if value.is_empty() {
316            return Err(Error {
317                _inner: unused(span.shrink_to_end().error("expected modifier value")),
318                public: crate::error::InvalidFormatDescription::InvalidModifier {
319                    value: String::new(),
320                    index: span.shrink_to_end().start.byte as _,
321                },
322            });
323        }
324
325        modifiers.push(Modifier {
326            _leading_whitespace: unused(whitespace),
327            key: key.spanned(span.shrink_to_before(colon_index as _)),
328            _colon: unused(span.start.offset(colon_index as _)),
329            value: value.spanned(span.shrink_to_after(colon_index as _)),
330        });
331    };
332
333    let Some(closing_bracket) = tokens.next_if_closing_bracket() else {
334        return Err(Error {
335            _inner: unused(opening_bracket.error("unclosed bracket")),
336            public: crate::error::InvalidFormatDescription::UnclosedOpeningBracket {
337                index: opening_bracket.byte as _,
338            },
339        });
340    };
341
342    Ok(Item::Component {
343        _opening_bracket: unused(opening_bracket),
344        _leading_whitespace: unused(leading_whitespace),
345        name,
346        modifiers: modifiers.into_boxed_slice(),
347        _trailing_whitespace: unused(trailing_whitespace),
348        _closing_bracket: unused(closing_bracket),
349    })
350}
351
352/// Parse a nested format description. The location provided is the the most recent one consumed.
353fn parse_nested<'a, I: Iterator<Item = Result<lexer::Token<'a>, Error>>, const VERSION: usize>(
354    last_location: Location,
355    tokens: &mut lexer::Lexed<I>,
356) -> Result<NestedFormatDescription<'a>, Error> {
357    validate_version!(VERSION);
358    let Some(opening_bracket) = tokens.next_if_opening_bracket() else {
359        return Err(Error {
360            _inner: unused(last_location.error("expected opening bracket")),
361            public: crate::error::InvalidFormatDescription::Expected {
362                what: "opening bracket",
363                index: last_location.byte as _,
364            },
365        });
366    };
367    let items = parse_inner::<_, true, VERSION>(tokens).collect::<Result<_, _>>()?;
368    let Some(closing_bracket) = tokens.next_if_closing_bracket() else {
369        return Err(Error {
370            _inner: unused(opening_bracket.error("unclosed bracket")),
371            public: crate::error::InvalidFormatDescription::UnclosedOpeningBracket {
372                index: opening_bracket.byte as _,
373            },
374        });
375    };
376    let trailing_whitespace = tokens.next_if_whitespace();
377
378    Ok(NestedFormatDescription {
379        _opening_bracket: unused(opening_bracket),
380        items,
381        _closing_bracket: unused(closing_bracket),
382        _trailing_whitespace: unused(trailing_whitespace),
383    })
384}
time/format_description/parse/ast.rs

time/format_description/parse/
ast.rs
