Expand description
🕗 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
- A
dd/mm/yyyy
style date. - e.g.
22/4/1991 5:25 PM
,22/4/1991 at 5:25 PM
,22/4/1991 15:28
. - Represents a particular day of the month, which can range from 1 to 31.
- Represents a specific duration of time that is not anchored at any particular point in time.
- Represents a minute of the hour, which can range from 0 to 60.
- Represents a positive integer, stored as a
u64
. - A simple representation of the time, e.g.
13:07
or5:07 PM
. - Represents a range of two valid PointInTimes that together define the start and end of some defined period of time.
- Represents a year, which can be any valid
u16
.
Enums
- Represents either AM or PM
- Represents an hour of the day in either 12-hour or 24-hour format.
- Represents a particular month of the year, which can range from 1-12
- Corresponds with a named relative time, such as “now”, “today”, “tomorrow”, etc.
- 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”).
- 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..
- Combined with “next” or “after” to denote specific RelativeTimes.
- Enumerates the various types of relative times that can be paired with a Duration.
- The top-level entry-point for the timelang AST.
- Represents particular units of time, such as hours, minutes, etc.