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