Crate timelang

🕗 Timelang

Timelang is a simple DSL (Domain Specific Language) for representing human-readable time-related expressions including specific date/times, relative expressions like “3 hours from now”, time ranges, and durations.

Getting Started

To use timelang, you should take a look at TimeExpression, which is the top-level entry point of the AST, or some of the more specific types like Duration, PointInTime, and TimeRange.

All nodes in timelang impl FromStr as well as syn::parse::Parse which is used for the internal parsing logic. The standard Display impl is used on all node types as the preferred means of outputting them to a string.

Note that for the moment, only years, months, weeks, days, hours, and minutes are supported in timelang, but seconds and more might be added later. Generally better than minute resolution is not needed in many of the common use-cases for timelang.

Examples

The following are all examples of valid expressions in timelang:

• now (RelativeTime)
• tomorrow (RelativeTime)
• next tuesday (RelativeTime)
• day after tomorrow (RelativeTime)
• the day before yesterday (RelativeTime)
• 20/4/2021 (Date)
• 11:21 AM (Time)
• 15/6/2022 at 3:58 PM (DateTime / PointInTime::Absolute)
• 2 hours, 37 minutes (Duration)
• 5 years, 2 months, 3 weeks and 11 minutes (Duration)
• 7 days ago (RelativeTime)
• 2 years and 10 minutes from now (RelativeTime)
• 5 days, 3 weeks, 6 minutes after 15/4/2025 at 9:27 AM (RelativeTime)
• from 1/1/2023 at 14:07 to 15/1/2023 (TimeRange)
• from 19/3/2024 at 10:07 AM to 3 months 2 days after 3/9/2027 at 5:27 PM (TimeRange)
• 2 days and 14 hours after the day after tomorrow (RelativeTime)

Context Free Grammar

Here is a rough CFG (Context Free Grammar) for timelang:

S → TimeExpression
TimeExpression → PointInTime | TimeRange | Duration
PointInTime → AbsoluteTime | RelativeTime
TimeRange → 'from' PointInTime 'to' PointInTime
Duration → Number TimeUnit ((','? 'and')? Number TimeUnit)*
AbsoluteTime → Date | DateTime
RelativeTime → Duration TimeDirection | NamedRelativeTime | 'next' RelativeTimeUnit | 'last' RelativeTimeUnit
NamedRelativeTime → 'now' | 'today' | 'tomorrow' | 'yesterday' | 'day after tomorrow' | 'the day after tomorrow' | 'day before yesterday' | 'the day before yesterday'
Date → DayOfMonth '/' Month '/' Year
DateTime → Date ('at')? Time
Time → Hour ':' Minute AmPm?
Hour → Number
Minute → Number
Month → Number
DayOfMonth → Number
Year → Number
AmPm → 'AM' | 'PM'
TimeUnit → 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'years'
TimeDirection → 'after' AbsoluteTime | 'before' AbsoluteTime | 'after' NamedRelativeTime | 'before' NamedRelativeTime | 'before' 'next' RelativeTimeUnit | 'before' 'last' RelativeTimeUnit | 'after' 'next' RelativeTimeUnit | 'after' 'last' RelativeTimeUnit | 'ago' | 'from now'
RelativeTimeUnit → 'week' | 'month' | 'year' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sunday'
Number → [Any positive integer value]

It is worth noting that this CFG is slightly more permissive than the actual timelang grammar, particularly when it comes to validating the permitted number ranges for various times.

Notes

• At the moment syn is used for parsing. This will likely be swapped out for a TBD parsing crate, but it was easy to quickly get this off the ground using syn. Whatever new crate we use will hopefully allow us to make timelang compatible with no std.
• Timelang is unambiguous, meaning there is exactly one tree representation for all possible timelang sentences. If you can come up with an ambiguous sentence, please let us know by submitting a GitHub issue!

Structs

• Date
  A dd/mm/yyyy style date.
• DateTime
  e.g. 22/4/1991 5:25 PM, 22/4/1991 at 5:25 PM, 22/4/1991 15:28.
• DayOfMonth
  Represents a particular day of the month, which can range from 1 to 31.
• Duration
  Represents a specific duration of time that is not anchored at any particular point in time.
• Minute
  Represents a minute of the hour, which can range from 0 to 60.
• Number
  Represents a positive integer, stored as a u64.
• Time
  A simple representation of the time, e.g. 13:07 or 5:07 PM.
• TimeRange
  Represents a range of two valid PointInTimes that together define the start and end of some defined period of time.
• Year
  Represents a year, which can be any valid u16.

Enums

• AbsoluteTime
  Represents an absolute/fixed point in time, such as a Date or DateTime.
• AmPm
  Represents either AM or PM
• Hour
  Represents an hour of the day in either 12-hour or 24-hour format.
• Month
  Represents a particular month of the year, which can range from 1-12
• NamedRelativeTime
  Corresponds with a named relative time, such as “now”, “today”, “tomorrow”, etc.
• PointInTime
  Represents a specific point in time, which could either be an AbsoluteTime (corresponding with a particular Date or DateTime), or a RelativeTime (corresponding with an offset from some AbsoluteTime or “now”).
• RelativeTime
  Represents a specific point in time offset by some known duration or period, such as “tomorrow”, “now”, “next tuesday”, “3 days after 2/5/2028 at 7:11 PM” etc..
• RelativeTimeUnit
  Combined with “next” or “after” to denote specific RelativeTimes.
• TimeDirection
  Enumerates the various types of relative times that can be paired with a Duration.
• TimeExpression
  The top-level entry-point for the timelang AST.
• TimeUnit
  Represents particular units of time, such as hours, minutes, etc.