when

Documentation

Overview

Package when resolves the time expressions people put in questions.

"what was I working on about five weeks ago" is not a retrieval query with an unusual vocabulary. It is a retrieval query with a filter attached, and the filter is the part that decides the answer. Matching those words against stored text finds nothing, because nobody writes "five weeks ago" in a note — they write "ran the drop test series", on a day that happens to be five weeks back. Resolving the phrase against a clock is the only thing that connects the question to the record.

The parser is deliberately small. It recognises a fixed set of shapes and returns nothing for everything else. A time filter that fires on a phrase the asker did not mean is worse than no filter at all, because it removes context silently — so the bias is heavily toward not matching. Everything it does match is reported to the reader with the dates it resolved to, which turns a wrong guess from something invisible into something correctable.

What it deliberately does not do: absolute dates ("on 4 March"), open-ended comparisons ("before the Pegatron signing"), and anything needing a model. Those are real questions and this is not the place to guess at them.

Index

• type Window
  • func Parse(text string, now time.Time) (Window, bool)
  • func Trailing(unit string, now time.Time) (Window, bool)
  • func (w Window) Contains(ts int64) bool
  • func (w Window) String() string

Types

type Window

type Window struct {
	From, To time.Time
	// Phrase is the words that named it, as the asker wrote them. Kept so the
	// reader can be told what was assumed on their behalf.
	Phrase string
}

A Window is a span of time named by a phrase in a question. From and To are inclusive.

func Parse

func Parse(text string, now time.Time) (Window, bool)

Parse finds the first time expression in text and resolves it against now. The bool is false when there is nothing it recognises, which is the common case and not an error.

func Trailing

func Trailing(unit string, now time.Time) (Window, bool)

Trailing returns the window from now back by one unit — the same shape "ago"/"the last <unit>" resolve to, without a phrase to parse it from. It exists for a caller that already knows the unit it wants (an explicit `since` argument, or a gap-based inference) rather than extracting one from free text.

func (Window) Contains

func (w Window) Contains(ts int64) bool

Contains reports whether a unix timestamp falls inside the window.

Undated material is always inside. Excluding what cannot be measured would mean a note with no recorded time silently disappears the moment anyone asks a question with a date in it, which is the wrong way for a filter to fail.

func (Window) String

func (w Window) String() string

String renders the window as the phrase plus the dates it resolved to, so a reader who meant something else can see that and say so.