when

when

when is a natural language date/time parser with pluggable rules and merge strategies

Examples

• tonight at 11:10 pm
• at Friday afternoon
• the deadline is next tuesday 14:00
• drop me a line next wednesday at 2:25 p.m
• it could be done at 11 am past tuesday

Check EN rules and tests of them, for more examples.

Russian event phrases

The bundled when.RU parser is deterministic and rule-based. It does not use LLMs, network requests, external APIs, or background services.

base := time.Date(2026, time.June, 1, 10, 0, 0, 0, time.UTC)
res, err := when.RU.Parse("завтра в 7", base)
// res.Time == 2026-06-02 07:00:00 +0000 UTC

Supported Russian examples include:

• relative days: сегодня, завтра, послезавтра, вчера, позавчера;
• literal 24-hour time without a day-part: в 5 -> 05:00, в 17 -> 17:00;
• day of month without month: 7 числа, 7-го числа, 7-го в 5;
• dates without year: 7 июня, 07.06, 7/06, with optional time such as 7 июня в 5 or 07.06 в 17:30;
• relative deadlines: через неделю, через 2 недели, в течение 5 минут, через полтора часа;
• day periods: в полдень -> 12:00, в полночь -> 00:00, ночью -> 02:00 by default.

Ambiguity policy is explicit:

• в 5 is always 05:00; the parser does not guess morning or evening intent.
• 7 числа chooses the nearest not-passed calendar day. If the current month has no such day, the parser checks following months until it finds one.
• 7 июня, 07.06, and 07/06 choose the nearest not-passed calendar date. If it already passed this year, the next valid year is used.
• explicitly past phrases such as вчера, позавчера, and в прошлый понедельник remain past.
• calendar units use calendar arithmetic: через день means next calendar day, while через 24 часа means an exact 24-hour duration. This matters across DST transitions.
• month and year offsets clamp to the end of the target month, for example 2026-01-31 + 1 месяц -> 2026-02-28.

Needed rule not found? Open an issue with the case and it will be added asap.

How it works

Usually, there are several rules added to the parser's instance for checking. Each rule has its own borders - length and offset in provided string. Meanwhile, each rule yields only the first match over the string. So, the library checks all the rules and extracts a cluster of matched rules which have distance between each other less or equal to options.Distance, which is 5 by default. For example:

on next wednesday at 2:25 p.m.
   └──────┬─────┘    └───┬───┘
       weekday      hour + minute

So, we have a cluster of matched rules - "next wednesday at 2:25 p.m." in the string representation.

After that, each rule is applied to the context. In order of definition or in match order, if options.MatchByOrder is set to true(which it is by default). Each rule could be applied with given merge strategy. By default, it's an Override strategy. The other strategies are not implemented yet in the rules. Pull requests are welcome.

Supported Languages

• EN - English
• RU - Russian
• BR - Brazilian Portuguese
• ZH - Chinese
• NL - Dutch

Install

The project follows the official release workflow. It is recommended to refer to this resource for detailed information on the process.

To install the latest version:

$ go get github.com/aagolovanov/when@latest

Usage

w := when.New(nil)
w.Add(en.All...)
w.Add(common.All...)

text := "drop me a line in next wednesday at 2:25 p.m"
r, err := w.Parse(text, time.Now())
if err != nil {
	// an error has occurred
}
if  r == nil {
 	// no matches found
}

fmt.Println(
	"the time",
	r.Time.String(),
	"mentioned in",
	text[r.Index:r.Index+len(r.Text)],
)

Distance Option

w := when.New(nil)
w.Add(en.All...)
w.Add(common.All...)

text := "February 23, 2019 | 1:46pm"

// With default distance (5):
// February 23, 2019 | 1:46pm
//            └───┬───┘
//           distance: 9 (1:46pm will be ignored)

r, _ := w.Parse(text, time.Now())
fmt.Printf(r.Time.String())
// "2019-02-23 09:21:21.835182427 -0300 -03"
// 2019-02-23 (correct)
//   09:21:21 ("wrong")

// With custom distance (10):
w.SetOptions(&rules.Options{
	Distance:     10,
	MatchByOrder: true})

r, _ = w.Parse(text, time.Now())
fmt.Printf(r.Time.String())
// "2019-02-23 13:46:21.559521554 -0300 -03"
// 2019-02-23 (correct)
//   13:46:21 (correct)

LICENSE

http://www.apache.org/licenses/LICENSE-2.0