Time expressions

There are two types of time expressions recognized by Modbot: duration expressions such as 10.5h and date/time expressions such as Sep 29 9pm EST.

Duration

A duration expression is defined as one or more pairs of a number and a unit.

• A number must be non-negative, and may contain decimals.
• Recognized units are y(ears), mo(nths), w(eeks), d(ays), h(ours), m(inutes), and s(econds). Multiple abbreviations are accepted for most units, e.g. hours may also be expressed as h, hr, or hrs.

Fields

• seconds: Seconds are the smallest duration unit. A minute is 60 seconds, and an hour is 3600 seconds. Hours, minutes, and seconds are unaffected by the context of the current date and time.
• days: A week is defined as 7 days. By default, a day is equivalent to 24 hours. However, if added onto a date/time with a timezone that uses daylight savings, the time will be kept as close as possible to the provided context. Fractional days are multiplied by 24 hours.
  • e.g. March 1 9pm EST + 30d = March 31 9pm EDT
  • e.g. 1.5d = 1d 12h
  • e.g. 1.5w = 10.5d = 10d 12h
• months: A year is defined as 12 months. The day and time will be kept as close as possible to the provided context. Fractional months are multiplied by 30 days.
  • e.g. March 1 9pm EST + 1mo = April 1 9pm EDT (+31 days)
  • e.g. 1.5mo = 1mo 15d
  • e.g. 1.5y = 18mo

Date/time

A date/time expression is defined as a date, time, and time zone. Not all fields must be defined, but fields may not contradict each other or be defined more than once.

Fields

• Date: year, month, day, dayOfWeek, relativeDate A date may be defined in one or more of the following ways:
  • yyyy-mm-dd: e.g. 2021-09-29.
  • Month and day (with optional year): e.g. March 1 or 30th April 2021. A month must follow or be followed by a day, and vice versa. A month and a day must be included if a year is defined.
  • A relative date: One of today, tomorrow, or yesterday.
  • A day of the week: e.g. Friday or Sun. If no other date fields are defined, the nearest future matching date (excluding the current date) will be selected.
    • e.g. Sun 19 Sep + Tue = Tue 21 Sep (+2 days)
    • e.g. Fri 10 Sep + Fri = Fri 17 Sep (+7 days)
  • If omitted, the date defaults to the nearest future/present date with the provided time and time zone.
    • e.g. 1 Sep 9pm + 11pm = 1 Sep 11pm (date = today)
    • e.g. 1 Sep 9pm + 3am = 2 Sep 3am (date = tomorrow)
  • All date elements must be non-contradictory. e.g. tomorrow Sunday September 29 will error if Sept 29 is not a Sunday, or if tomorrow is not Sept 29.
• Time: hour, minute, second, period
  • h(:mm(:ss)) (am/pm): A colon-separated time of day. Minutes, seconds, and period (i.e. AM/PM indicator) are optional. The period may be space-separated from the hour. If the period is omitted, the time is interpretted as a 24-hour time.
    • e.g. 9pm = 9 pm = 9:00 pm = 21:00 = 21:00:00
    • e.g. 12am = 12 am = 12:00 am = 0:00 = 00:00:00
  • If omitted, the time defaults to the current time of day in the provided time zone.
• Time zone: zone
  • Various abbreviations: A set of abbreviations is defined in the resource timezones.yml. e.g. ET, EST, and EDT all translate to America/New_York, which respects daylight savings.
  • If omitted, the time zone defaults to UTC.