feat: add support for TZ="timezone" date spec

Author: yuankunzhang

src/items/builder.rs

@@ -18,6 +18,7 @@ pub(crate) struct DateTimeBuilder {
     time: Option<time::Time>,
     weekday: Option<weekday::Weekday>,
     offset: Option<offset::Offset>,
+    timezone: Option<jiff::tz::TimeZone>,
     relative: Vec<relative::Relative>,
 }
 
@@ -33,6 +34,20 @@ impl DateTimeBuilder {
         self
     }
 
+    /// Sets the timezone rule for the builder.
+    ///
+    /// By default, the builder uses the time zone rules indicated by the `TZ`
+    /// environment variable, or the system default rules if `TZ` is not set.
+    /// This method allows overriding the time zone rules.
+    fn set_timezone(mut self, tz: jiff::tz::TimeZone) -> Result<Self, &'static str> {
+        if self.timezone.is_some() {
+            return Err("timezone rule cannot appear more than once");
+        }
+
+        self.timezone = Some(tz);
+        Ok(self)
+    }
+
     /// Sets a timestamp value. Timestamp values are exclusive to other date/time
     /// items (date, time, weekday, timezone, relative adjustments).
     pub(super) fn set_timestamp(mut self, ts: epoch::Timestamp) -> Result<Self, &'static str> {
@@ -51,7 +66,7 @@ impl DateTimeBuilder {
         Ok(self)
     }
 
-    pub(super) fn set_date(mut self, date: date::Date) -> Result<Self, &'static str> {
+    fn set_date(mut self, date: date::Date) -> Result<Self, &'static str> {
         if self.timestamp.is_some() {
             return Err("timestamp cannot be combined with other date/time items");
         } else if self.date.is_some() {
@@ -62,7 +77,7 @@ impl DateTimeBuilder {
         Ok(self)
     }
 
-    pub(super) fn set_time(mut self, time: time::Time) -> Result<Self, &'static str> {
+    fn set_time(mut self, time: time::Time) -> Result<Self, &'static str> {
         if self.timestamp.is_some() {
             return Err("timestamp cannot be combined with other date/time items");
         } else if self.time.is_some() {
@@ -75,7 +90,7 @@ impl DateTimeBuilder {
         Ok(self)
     }
 
-    pub(super) fn set_weekday(mut self, weekday: weekday::Weekday) -> Result<Self, &'static str> {
+    fn set_weekday(mut self, weekday: weekday::Weekday) -> Result<Self, &'static str> {
         if self.timestamp.is_some() {
             return Err("timestamp cannot be combined with other date/time items");
         } else if self.weekday.is_some() {
@@ -86,7 +101,7 @@ impl DateTimeBuilder {
         Ok(self)
     }
 
-    pub(super) fn set_offset(mut self, timezone: offset::Offset) -> Result<Self, &'static str> {
+    fn set_offset(mut self, timezone: offset::Offset) -> Result<Self, &'static str> {
         if self.timestamp.is_some() {
             return Err("timestamp cannot be combined with other date/time items");
         } else if self.offset.is_some()
@@ -99,10 +114,7 @@ impl DateTimeBuilder {
         Ok(self)
     }
 
-    pub(super) fn push_relative(
-        mut self,
-        relative: relative::Relative,
-    ) -> Result<Self, &'static str> {
+    fn push_relative(mut self, relative: relative::Relative) -> Result<Self, &'static str> {
         if self.timestamp.is_some() {
             return Err("timestamp cannot be combined with other date/time items");
         }
@@ -117,7 +129,7 @@ impl DateTimeBuilder {
     /// If a date is already set but lacks a year, the number is interpreted as
     /// a year. Otherwise, it's interpreted as a time in HHMM, HMM, HH, or H
     /// format.
-    pub(super) fn set_pure(mut self, pure: String) -> Result<Self, &'static str> {
+    fn set_pure(mut self, pure: String) -> Result<Self, &'static str> {
         if self.timestamp.is_some() {
             return Err("timestamp cannot be combined with other date/time items");
         }
@@ -149,7 +161,11 @@ impl DateTimeBuilder {
     }
 
     pub(super) fn build(self) -> Result<Zoned, error::Error> {
-        let base = self.base.unwrap_or(Zoned::now());
+        let base = self.base.unwrap_or(if let Some(tz) = &self.timezone {
+            jiff::Timestamp::now().to_zoned(tz.clone())
+        } else {
+            Zoned::now()
+        });
 
         // If a timestamp is set, we use it to build the `Zoned` object.
         if let Some(ts) = self.timestamp {
@@ -158,11 +174,11 @@ impl DateTimeBuilder {
 
         // If any of the following items are set, we truncate the time portion
         // of the base date to zero; otherwise, we use the base date as is.
-        let mut dt = if self.timestamp.is_none()
-            && self.date.is_none()
+        let mut dt = if self.date.is_none()
             && self.time.is_none()
             && self.weekday.is_none()
             && self.offset.is_none()
+            && self.timezone.is_none()
         {
             base
         } else {
@@ -264,6 +280,7 @@ impl TryFrom<Vec<Item>> for DateTimeBuilder {
                 Item::Weekday(weekday) => builder.set_weekday(weekday)?,
                 Item::Offset(offset) => builder.set_offset(offset)?,
                 Item::Relative(rel) => builder.push_relative(rel)?,
+                Item::TimeZone(tz) => builder.set_timezone(tz)?,
                 Item::Pure(pure) => builder.set_pure(pure)?,
             }
         }

src/items/mod.rs

@@ -25,6 +25,7 @@
 //!  - [`pure`]
 //!  - [`relative`]
 //!  - [`time`]
+//!  - [`timezone`]
 //!  - [`weekday`]
 //!  - [`year`]
 
@@ -36,6 +37,7 @@ mod offset;
 mod pure;
 mod relative;
 mod time;
+mod timezone;
 mod weekday;
 mod year;
 
@@ -67,6 +69,7 @@ enum Item {
     Weekday(weekday::Weekday),
     Relative(relative::Relative),
     Offset(offset::Offset),
+    TimeZone(jiff::tz::TimeZone),
     Pure(String),
 }
 
@@ -196,6 +199,8 @@ fn parse(input: &mut &str) -> ModalResult<DateTimeBuilder> {
 /// > (Timestamp) Such a number cannot be combined with any other date item, as
 /// > it specifies a complete timestamp.
 fn parse_timestamp(input: &mut &str) -> ModalResult<DateTimeBuilder> {
+    let _ = timezone::parse(input);
+
     trace(
         "parse_timestamp",
         terminated(epoch::parse.map(Item::Timestamp), preceded(space, eof)),
@@ -212,12 +217,18 @@ fn parse_timestamp(input: &mut &str) -> ModalResult<DateTimeBuilder> {
 
 /// Parse a sequence of items.
 fn parse_items(input: &mut &str) -> ModalResult<DateTimeBuilder> {
-    let (items, _): (Vec<Item>, _) = trace(
+    let tz = timezone::parse(input).map(Item::TimeZone);
+
+    let (mut items, _): (Vec<Item>, _) = trace(
         "parse_items",
         repeat_till(0.., parse_item, preceded(space, eof)),
     )
     .parse_next(input)?;
 
+    if let Ok(tz) = tz {
+        items.push(tz);
+    }
+
     items.try_into().map_err(|e| expect_error(input, e))
 }
 
@@ -271,6 +282,14 @@ mod tests {
             .to_string()
     }
 
+    #[test]
+    fn test_tmp() {
+        let mut input = r#"TZ="UTC-2:10:20""#;
+        let result = parse(&mut input).unwrap().build().unwrap();
+        let result = result.with_time_zone(jiff::tz::TimeZone::system());
+        println!("result: {result:?}");
+    }
+
     #[test]
     fn date_and_time() {
         assert_eq!(