datemath

README

go-datemath

This library provides support for parsing datemath expressions compatibly with Elasticsearch datemath expressions. These are useful for allowing users to specify, and for encoding, relative dates. Examples:

• now+15m: 15 minutes from now
• now-1w+1d: one day after on week ago
• 2015-05-05T00:00:00||+1M: one month after 2019-05-05

These expressions will seem familiar if you have used Grafana or Kibana.

Example usage:

expr, _ := datemath.Parse("now-15m")
fmt.Println(t.Time(datemath.WithNow(now)))

See package documentation for usage and more examples.

Development / Contributing

See CONTRIBUTING.md.

Documentation

Overview

Package datemath provides an expression language for relative dates based on Elasticsearch's date math.

This package is useful for letting end-users describe dates in a simple format similar to Grafana and Kibana and for persisting them as relative dates.

The expression starts with an anchor date, which can either be "now", or an ISO8601 date string ending with ||. This anchor date can optionally be followed by one or more date math expressions, for example:

now+1h	Add one hour
now-1d	Subtract one day
now/d	Round down to the nearest day

The supported time units are:

y  Years
fy Fiscal years (by default same as a regular year, use WithStartOfFiscalYear to override)
Q  Annual quarters
fQ Fiscal quarters (by default same as a regular annual quarter, use WithStartOfFiscalYear to override)
M  Months
w  Weeks
d  Days
b  Business Days (excludes Saturday and Sunday by default, use WithBusinessDayFunc to override)
h  Hours
H  Hours
m  Minutes
s  Seconds

Compatibility with Elasticsearch datemath

This package aims to be a superset of Elasticsearch's expressions. That is, any datemath expression that is valid for Elasticsearch should evaluate in the same way here.

In addition to the expressions supported by Elasticsearch, this package also supports business days, annual quarters, and fiscal years/quarters.

Index

• func ParseAndEvaluate(s string, opts ...func(*Options)) (time.Time, error)
• func WithBusinessDayFunc(fn func(time.Time) bool) func(*Options)
• func WithLocation(l *time.Location) func(*Options)
• func WithNow(now time.Time) func(*Options)
• func WithRoundUp(b bool) func(*Options)
• func WithStartOfFiscalYear(t time.Time) func(*Options)
• func WithStartOfWeek(day time.Weekday) func(*Options)
• type Expression
  • func MustParse(s string) Expression
  • func Parse(s string) (Expression, error)
  • func (e Expression) MarshalJSON() ([]byte, error)
  • func (e Expression) String() string
  • func (e Expression) Time(opts ...func(*Options)) time.Time
  • func (e *Expression) UnmarshalJSON(data []byte) error
• type Options

Examples

• Parse

Functions

func ParseAndEvaluate

func ParseAndEvaluate(s string, opts ...func(*Options)) (time.Time, error)

ParseAndEvaluate is a convience wrapper to parse and return the time that the expression represents

func WithBusinessDayFunc

func WithBusinessDayFunc(fn func(time.Time) bool) func(*Options)

WithBusinessDayFunc use the given fn to check if a day is a business day

func WithLocation

func WithLocation(l *time.Location) func(*Options)

WithLocation uses the given location as the timezone of the date if unspecified

func WithNow

func WithNow(now time.Time) func(*Options)

WithNow use the given time as "now"

func WithRoundUp

func WithRoundUp(b bool) func(*Options)

WithRoundUp sets the rounding of time to the end of the period instead of the beginning

func WithStartOfFiscalYear

func WithStartOfFiscalYear(t time.Time) func(*Options)

WithStartOfFiscalYear sets the beginning of the fiscal year. The year is ignored.

func WithStartOfWeek

func WithStartOfWeek(day time.Weekday) func(*Options)

WithStartOfWeek uses the given weekday as the start of the week

Types

type Expression

type Expression struct {
	// contains filtered or unexported fields
}

Expression represents a parsed datemath expression

func MustParse

func MustParse(s string) Expression

MustParse is the same as Parse() but panic's on error

func Parse

func Parse(s string) (Expression, error)

Parse parses the datemath expression which can later be evaluated

Example

now, _ := time.Parse(time.RFC3339, "2014-05-30T20:21:35.123Z")

expressions := []string{
	"now-15m",
	"now/w",
	"now+1M",
	"2014-05-31||+1M/w",
}

for _, expression := range expressions {
	t, err := datemath.Parse(expression)
	if err != nil {
		panic(err)
	}
	fmt.Println(t.Time(datemath.WithNow(now)))
}

Output:

2014-05-30 20:06:35.123 +0000 UTC
2014-05-26 00:00:00 +0000 UTC
2014-06-30 20:21:35.123 +0000 UTC
2014-06-30 00:00:00 +0000 UTC

func (Expression) MarshalJSON

func (e Expression) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface

It serializes as the string expression the Expression was created with

func (Expression) String

func (e Expression) String() string

String returns a the string used to create the expression

func (Expression) Time

func (e Expression) Time(opts ...func(*Options)) time.Time

Time evaluate the expression with the given options to get the time it represents

func (*Expression) UnmarshalJSON

func (e *Expression) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface

Parses the datemath expression from a JSON string

type Options

type Options struct {
	// Use this this time as "now"
	// Default is `time.Now()`
	Now time.Time

	// Use this location if there is no timezone in the expression
	// Defaults to time.UTC
	Location *time.Location

	// Use this weekday as the start of the week
	// Defaults to time.Monday
	StartOfWeek time.Weekday

	// Rounding to period should be done to the end of the period
	// Defaults to false
	RoundUp bool

	StartOfFiscalYear time.Time

	BusinessDayFunc func(time.Time) bool
}

Options represesent configurable behavior for interpreting the datemath expression