humantime

README

humantime

Convert English strings related to time to Go time.Time. This package also implements the flags.Value and flag.Getter interfaces for use in a cli context.

Nomenclature

• A "date phrase" is text that represents a date and optionally time, examples:
  • May 8, 2009 5:57:51 PM
  • 3/15/2022
  • yesterday
  • yesterday at 4pm
  • tomorrow at 13:34:32

Supported formats

• since [date phrase]
• until or til [date phrase]
• before [date phrase]
• after [date phrase]
• [date phrase] ago
• from [date phrase] to [date phrase]

Example phrases

• from May 8, 2009 5:57:51 PM to Sep 12, 2021 3:21:22 PM
• 3 days ago
• after yesterday at 4pm

Usage

CLI flag example

  var st, err = NewString2Time(now.Location())
  result, err := st.After("after 3/15/2022")
 
  fmt.Println(result)    // From: 15 Mar 22 00:00 MDT, To: 19 Jul 22 15:02 MDT

Documentation

Index

• Constants
• Variables
• type Humantime
  • func NewString2Time(loc *time.Location) (*Humantime, error)
  • func (st *Humantime) After(input string) (*TimeRange, error)
  • func (st *Humantime) Ago(input string) (*TimeRange, error)
  • func (st *Humantime) Before(input string) (*TimeRange, error)
  • func (st *Humantime) FromTo(input string) (*TimeRange, error)
  • func (st *Humantime) Parse(input string) (*TimeRange, error)
  • func (st *Humantime) Since(input string) (*TimeRange, error)
  • func (st *Humantime) Until(input string) (*TimeRange, error)
• type TimeRange
  • func (v *TimeRange) Get(s string) TimeRange
  • func (v *TimeRange) Set(s string) error
  • func (v TimeRange) String() string

Constants

const AM = `^\dam`

const DateDash = `\d{1,2}-\d{1,2}-\d{2,4}`

const DateSlash = `\d{1,2}/\d{1,2}/\d{2,4}`

const ExactTime = `\d{1,2}:\d{1,2}(:\d{1,2})?` // can detect optional seconds

const PM = `^\dpm`

Variables

var DurationStringToMilli = map[string]int{
	"second":  time.Now().Second(),
	"seconds": time.Now().Second(),
	"minute":  time.Now().Minute(),
	"minutes": time.Now().Minute(),
	"hour":    time.Now().Hour(),
	"hours":   time.Now().Hour(),
	"day":     time.Now().Day(),
	"days":    time.Now().Day(),
	"week":    time.Now().Day() * 7,
	"weeks":   time.Now().Day() * 7,
	"month":   int(time.Now().Month()),
	"months":  int(time.Now().Month()),
	"year":    time.Now().Year(),
	"years":   time.Now().Year(),
}

var DurationWords = map[string]time.Duration{
	"second":  time.Second,
	"seconds": time.Second,
	"minute":  time.Minute,
	"minutes": time.Minute,
	"hour":    time.Hour,
	"hours":   time.Hour,
	"day":     time.Hour * 24,
	"days":    time.Hour * 24,
	"week":    time.Hour * 24 * 7,
	"weeks":   time.Hour * 24 * 7,
	"month":   time.Hour * 24 * 7 * 30,
	"months":  time.Hour * 24 * 7 * 30,
	"year":    time.Second * 31536000,
	"years":   time.Second * 31536000,
}

var TimeSynonyms = map[string]func(*time.Location) time.Time{
	"yesterday": func(loc *time.Location) time.Time {
		var now = time.Now().Add(time.Hour * -24)
		var y, m, d = now.Date()
		return time.Date(y, m, d, 0, 0, 0, 0, loc)
	},
	"today": func(loc *time.Location) time.Time {
		var now = time.Now()
		var y, m, d = now.Date()
		return time.Date(y, m, d, 0, 0, 0, 0, loc)
	},
	"tomorrow": func(loc *time.Location) time.Time {
		var now = time.Now().Add(time.Hour * 24)
		var y, m, d = now.Date()
		return time.Date(y, m, d, 0, 0, 0, 0, loc)
	},
}

Types

type Humantime

type Humantime struct {
	*time.Location
	AMRegex        *regexp.Regexp
	PMRegex        *regexp.Regexp
	DateSlashRegex *regexp.Regexp
	DateDashRegex  *regexp.Regexp
	ExactTimeRegex *regexp.Regexp
}

func NewString2Time

func NewString2Time(loc *time.Location) (*Humantime, error)

NewString2Time is just a constructor

func (*Humantime) After

func (st *Humantime) After(input string) (*TimeRange, error)

After takes a string starting with the word after and parses the remainder as time.Duration, examples: after 3/15/2022 after May 8, 2009 5:57:51 PM after 2am after yesterday after yesterday at 4pm after yesterday at 13:34:32

func (*Humantime) Ago

func (st *Humantime) Ago(input string) (*TimeRange, error)

Ago takes a string starting with the word since and parses the remainder as time.Duration, examples: 3 hours ago 8 days and three hours ago

func (*Humantime) Before

func (st *Humantime) Before(input string) (*TimeRange, error)

Before takes a string starting with the word before and parses the remainder as time.Duration, examples: before 3/15/2022 before May 8, 2009 5:57:51 PM before 2am before tomorrow before tomorrow at 4pm before tomorrow at 13:34:32

func (*Humantime) FromTo

func (st *Humantime) FromTo(input string) (*TimeRange, error)

Ago takes a string starting with the word since and parses the remainder as time.Duration, examples: 3 hours ago 8 days and three hours ago

func (*Humantime) Parse

func (st *Humantime) Parse(input string) (*TimeRange, error)

Parse is the entry point for parsing English input and performs the switching between different phrase types

func (*Humantime) Since

func (st *Humantime) Since(input string) (*TimeRange, error)

Since takes a string starting with the word since and parses the remainder as time.Duration, examples: since 3/15/2022 since May 8, 2009 5:57:51 PM since 2am since yesterday since yesterday at 4pm since yesterday at 13:34:32

func (*Humantime) Until

func (st *Humantime) Until(input string) (*TimeRange, error)

Until takes a string starting with the words until or til and parses the remainder as time.Duration, examples: until 3/15/2022 until May 8, 2009 5:57:51 PM until 2am until tomorrow until tomorrow at 4pm until tomorrow at 13:34:32

type TimeRange

type TimeRange struct {
	From time.Time
	To   time.Time
}

func (*TimeRange) Get

func (v *TimeRange) Get(s string) TimeRange

Get fulfils the flag.Getter interface https://pkg.go.dev/flag#Getter

func (*TimeRange) Set

func (v *TimeRange) Set(s string) error

Set fulfils the flag.Value interface https://pkg.go.dev/flag#Value

func (TimeRange) String

func (v TimeRange) String() string

String fulfils the flag.Value interface https://pkg.go.dev/flag#Value