README
¶
Window Language Parser (in Go)
A window is a term from the time series domain. It is a period of time. This package allows to define windows in plain text and then convert them to Go structures.
Playground
Run a tool from window folder to try recognition of your input, here are a few examples:
$ go run main.go "within 30 days and 2 minutes and 3 nanoseconds"
Window resolved at: 2022-05-07, 17:36:53.163478476 +05
You defined a sliding window of 30 day(s) 2 minute(s) 0.000000003 seconds(s)
$ go run main.go --timezone="Europe/Moscow" "from yesterday to today"
Your Using time.Local set to location=Europe/Moscow MSK
Window resolved at: 2022-05-07, 15:38:50.736614500 MSK
Left Bound: 2022-05-06, 23:59:59.999999999 MSK
Right Bound: 2022-05-07, 00:00:00.000000000 MSK
Syntax
A windows can be defined by its left and right bounds: FROM a TO b (you can use different delimiters). Bounds are time
points (as precise as we want).
This package does not distinguish included/excluded bounds. A time point can be absolute or relative. Relative to what?
There are two options: relative to the other point or to the NOW point.
For convenience a few delimiters are supported: FROM/SINCE, UNTIL/TO/BEFORE and WITHIN.
Types
Supported window bound types:
- absolute bound (ex:
9:00 am 22 June, 2022) - relative to the other bound (ex:
6 days BEFORE 1 September 2022) - relative to now (ex:
1 may 1992 UNTIL today)
| Type | Left Bound Keywords | Right Bound Keyword | Formats |
|---|---|---|---|
| Absolute | FROM, SINCE |
TO, BEFORE, UNTIL |
Many formats are supported, see araddon/dateparse |
| Relative To Now |
x AGO/BEFORE/ or x LATER/AFTER/AHEAD where "x" is a combination of number unit (and number unit)*
units: nanosecond, microsecond, millisecond, second, minute, hour, day, week, month Also possible more sophisitcated queries: last X or next Y
|
||
| Relative To Another Bound | WITHIN |
WITHIN |
number unit (and number unit)* |
Absolute
Absolute bound is specified as a date-time string in one of the supported formats (which is many). Ideally it should support anything you can type for a date-time. Of course it does not, but it supports a lot. See https://github.com/araddon/dateparse which does the absolute datetime parsing.
Relative To Another Bound
This bound is specified as a period that is applied to another bound. The format is simple: number unit (like 1 day)
. And you can add as many as you need: 1 minute and 32 seconds.
Relative To Now
This window bound is defined relatively to the current point in time. It can be expressed in 2 ways: as an interval in the past or as a point in the past. Let's review them. Window bound relative to Now:
- a point. Ex:
2 days and 1 second agoor2 hours later. Under the hood this specification is converted to a duration and subtracted from (added to) the Now time. - an interval. Ex:
last weekornext year. This is a window by itself. It has two bounds. Depending on where this specification is used one of the bounds is picked as a result. Consider this specFROM last week UNTIL yesterday. "Last week" is used in the left bound definition, so the left bound of the "last week" is picked as a bound. Contrary "yesterday" also has two bounds and the right bound is assumed as a result of evaluation.
Examples
Combining these types we can specify a window in 9 ways:
| Left Bound | Right Bound | Example |
|---|---|---|
| Absolute | Absolute |
FROM 1 January 1991 TO 31 December 1991
|
| Absolute | Relative To Another Bound |
FROM May 8, 2009 5:57:51 PM WITHIN 365 days
|
| Absolute | Relative To Now |
FROM Mon Jan 02 15:04:05 -0700 2006 TO now
FROM oct 7, 1970 UNTIL last week
|
| Relative To Another Bound | Absolute |
1 day TO 1332151919
WITHIN 365 days BEFORE 12 Feb 2006 19:17
|
| Relative To Another Bound | Relative To Another Bound |
A special case for a window that only has duration, starts at any point in time.
Called **"Sliding Window"**.
WITHIN 60 DAYS or simply 1 week
|
| Relative To Another Bound | Relative To Now |
WITHIN 7 days UNTIL yesterday
1 second 3 nanoseconds UNTIL today
|
| Relative To Now | Absolute | FROM 7 years ago TO 2014-12-16 06:20:00 UTC |
| Relative To Now | Relative To Another Bound |
FROM 7 years ago UNTIL last week
2 days ago TO next week
FROM next week TO 7 days LATER
|
| Relative To Now | Relative To Now | FROM last year TO this year |
How To Use
// go get github.com/lezhnev74/window-spec
windowQuery := "30 days"
winSpec, err := Start(windowQuery) // convert the text to a specification data structure
if err != nil {
fatal(err)
}
w := winSpec.ResolveAt(time.Now()) // resolve specification relatively to a given time
Documentation
¶
Index ¶
Constants ¶
const ( STATE_LEFT_BOUND = iota // parse left bound STATE_RIGHT_BOUND // parse right bound STATE_VALIDATE // parsing is over, validate the result STATE_FINISH // all is good, stop the parsing )
Variables ¶
This section is empty.
Functions ¶
func GetPeriodWords ¶
func GetPeriodWords() []string
GetPeriodWords returns a list of possible predefined words that can be used in the bound definition relative to now ex: "last X" or "next Y"
func GetShortWords ¶
func GetShortWords() []string
GetShortWords returns a list of possible predefined words that can be used in the bound definition relative to now as is
func MapUnitToDuration ¶
Types ¶
type Recognizer ¶
type Recognizer struct {
// contains filtered or unexported fields
}
type Specification ¶
type Specification struct {
// contains filtered or unexported fields
}
Specification contains left/right bounds for a window that can be resolved to absolute time when needed
func MakeSpecification ¶
func MakeSpecification(leftBound, rightBound any) Specification
func Start ¶
func Start(text string) (s Specification, e error)
Source Files
Directories