Crate timelang

Source
Expand description

§🕗 Timelang

Crates.io docs.rs Build Status MIT License

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:

§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.