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 nownow-1w+1d: one day after on week ago2015-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 M Months w Weeks d Days 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.
Currently the package does not support expressions outside of those also considered valid by Elasticsearch, but this may change in the future to include additional functionality.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ParseAndEvaluate ¶
ParseAndEvaluate is a convience wrapper to parse and return the time that the expression represents
func WithLocation ¶
WithLocation uses the given location as the timezone of the date if unspecified
func WithStartOfWeek ¶
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
}
Options represesent configurable behavior for interpreting the datemath expression
Source Files