time/format_description/parse/
mod.rs

1//! Parser for format descriptions.
2
3use alloc::boxed::Box;
4use alloc::vec::Vec;
5
6pub use self::strftime::{parse_strftime_borrowed, parse_strftime_owned};
7use crate::{error, format_description};
8
9/// A helper macro to make version restrictions simpler to read and write.
10macro_rules! version {
11    ($range:expr) => {
12        $range.contains(&VERSION)
13    };
14}
15
16/// A helper macro to statically validate the version (when used as a const parameter).
17macro_rules! validate_version {
18    ($version:ident) => {
19        let _ = $crate::format_description::parse::Version::<$version>::IS_VALID;
20    };
21}
22
23mod ast;
24mod format_item;
25mod lexer;
26mod strftime;
27
28/// A struct that is used to ensure that the version is valid.
29struct Version<const N: usize>;
30impl<const N: usize> Version<N> {
31    /// A constant that panics if the version is not valid. This results in a post-monomorphization
32    /// error.
33    const IS_VALID: () = assert!(N >= 1 && N <= 2);
34}
35
36/// Parse a sequence of items from the format description.
37///
38/// The syntax for the format description can be found in [the
39/// book](https://time-rs.github.io/book/api/format-description.html).
40///
41/// This function exists for backward compatibility reasons. It is equivalent to calling
42/// `parse_borrowed::<1>(s)`. In the future, this function will be deprecated in favor of
43/// `parse_borrowed`.
44pub fn parse(
45    s: &str,
46) -> Result<Vec<format_description::BorrowedFormatItem<'_>>, error::InvalidFormatDescription> {
47    parse_borrowed::<1>(s)
48}
49
50/// Parse a sequence of items from the format description.
51///
52/// The syntax for the format description can be found in [the
53/// book](https://time-rs.github.io/book/api/format-description.html). The version of the format
54/// description is provided as the const parameter. **It is recommended to use version 2.**
55pub fn parse_borrowed<const VERSION: usize>(
56    s: &str,
57) -> Result<Vec<format_description::BorrowedFormatItem<'_>>, error::InvalidFormatDescription> {
58    validate_version!(VERSION);
59    let mut lexed = lexer::lex::<VERSION>(s.as_bytes());
60    let ast = ast::parse::<_, VERSION>(&mut lexed);
61    let format_items = format_item::parse(ast);
62    Ok(format_items
63        .map(|res| res.and_then(TryInto::try_into))
64        .collect::<Result<_, _>>()?)
65}
66
67/// Parse a sequence of items from the format description.
68///
69/// The syntax for the format description can be found in [the
70/// book](https://time-rs.github.io/book/api/format-description.html). The version of the format
71/// description is provided as the const parameter.
72///
73/// Unlike [`parse`], this function returns [`OwnedFormatItem`], which owns its contents. This means
74/// that there is no lifetime that needs to be handled. **It is recommended to use version 2.**
75///
76/// [`OwnedFormatItem`]: crate::format_description::OwnedFormatItem
77pub fn parse_owned<const VERSION: usize>(
78    s: &str,
79) -> Result<format_description::OwnedFormatItem, error::InvalidFormatDescription> {
80    validate_version!(VERSION);
81    let mut lexed = lexer::lex::<VERSION>(s.as_bytes());
82    let ast = ast::parse::<_, VERSION>(&mut lexed);
83    let format_items = format_item::parse(ast);
84    let items = format_items.collect::<Result<Box<_>, _>>()?;
85    Ok(items.into())
86}
87
88/// Attach [`Location`] information to each byte in the iterator.
89fn attach_location<'item>(
90    iter: impl Iterator<Item = &'item u8>,
91) -> impl Iterator<Item = (&'item u8, Location)> {
92    let mut byte_pos = 0;
93
94    iter.map(move |byte| {
95        let location = Location { byte: byte_pos };
96        byte_pos += 1;
97        (byte, location)
98    })
99}
100
101/// A location within a string.
102#[derive(Clone, Copy)]
103struct Location {
104    /// The zero-indexed byte of the string.
105    byte: u32,
106}
107
108impl Location {
109    /// Create a new [`Span`] from `self` to `other`.
110    const fn to(self, end: Self) -> Span {
111        Span { start: self, end }
112    }
113
114    /// Create a new [`Span`] consisting entirely of `self`.
115    const fn to_self(self) -> Span {
116        Span {
117            start: self,
118            end: self,
119        }
120    }
121
122    /// Offset the location by the provided amount.
123    ///
124    /// Note that this assumes the resulting location is on the same line as the original location.
125    #[must_use = "this does not modify the original value"]
126    const fn offset(&self, offset: u32) -> Self {
127        Self {
128            byte: self.byte + offset,
129        }
130    }
131
132    /// Create an error with the provided message at this location.
133    const fn error(self, message: &'static str) -> ErrorInner {
134        ErrorInner {
135            _message: message,
136            _span: Span {
137                start: self,
138                end: self,
139            },
140        }
141    }
142}
143
144/// A start and end point within a string.
145#[derive(Clone, Copy)]
146struct Span {
147    start: Location,
148    end: Location,
149}
150
151impl Span {
152    /// Obtain a `Span` pointing at the start of the pre-existing span.
153    #[must_use = "this does not modify the original value"]
154    const fn shrink_to_start(&self) -> Self {
155        Self {
156            start: self.start,
157            end: self.start,
158        }
159    }
160
161    /// Obtain a `Span` pointing at the end of the pre-existing span.
162    #[must_use = "this does not modify the original value"]
163    const fn shrink_to_end(&self) -> Self {
164        Self {
165            start: self.end,
166            end: self.end,
167        }
168    }
169
170    /// Obtain a `Span` that ends before the provided position of the pre-existing span.
171    #[must_use = "this does not modify the original value"]
172    const fn shrink_to_before(&self, pos: u32) -> Self {
173        Self {
174            start: self.start,
175            end: Location {
176                byte: self.start.byte + pos - 1,
177            },
178        }
179    }
180
181    /// Obtain a `Span` that starts after provided position to the end of the pre-existing span.
182    #[must_use = "this does not modify the original value"]
183    const fn shrink_to_after(&self, pos: u32) -> Self {
184        Self {
185            start: Location {
186                byte: self.start.byte + pos + 1,
187            },
188            end: self.end,
189        }
190    }
191
192    /// Create an error with the provided message at this span.
193    const fn error(self, message: &'static str) -> ErrorInner {
194        ErrorInner {
195            _message: message,
196            _span: self,
197        }
198    }
199}
200
201/// A value with an associated [`Span`].
202#[derive(Clone, Copy)]
203struct Spanned<T> {
204    /// The value.
205    value: T,
206    /// Where the value was in the format string.
207    span: Span,
208}
209
210impl<T> core::ops::Deref for Spanned<T> {
211    type Target = T;
212
213    fn deref(&self) -> &Self::Target {
214        &self.value
215    }
216}
217
218/// Helper trait to attach a [`Span`] to a value.
219trait SpannedValue: Sized {
220    /// Attach a [`Span`] to a value.
221    fn spanned(self, span: Span) -> Spanned<Self>;
222}
223
224impl<T> SpannedValue for T {
225    fn spanned(self, span: Span) -> Spanned<Self> {
226        Spanned { value: self, span }
227    }
228}
229
230/// The internal error type.
231struct ErrorInner {
232    /// The message displayed to the user.
233    _message: &'static str,
234    /// Where the error originated.
235    _span: Span,
236}
237
238/// A complete error description.
239struct Error {
240    /// The internal error.
241    _inner: Unused<ErrorInner>,
242    /// The error needed for interoperability with the rest of `time`.
243    public: error::InvalidFormatDescription,
244}
245
246impl From<Error> for error::InvalidFormatDescription {
247    fn from(error: Error) -> Self {
248        error.public
249    }
250}
251
252/// A value that may be used in the future, but currently is not.
253///
254/// This struct exists so that data can semantically be passed around without _actually_ passing it
255/// around. This way the data still exists if it is needed in the future.
256// `PhantomData` is not used directly because we don't want to introduce any trait implementations.
257struct Unused<T>(core::marker::PhantomData<T>);
258
259/// Indicate that a value is currently unused.
260fn unused<T>(_: T) -> Unused<T> {
261    Unused(core::marker::PhantomData)
262}
time/format_description/parse/mod.rs

time/format_description/parse/
mod.rs
