README
¶
Easy Date/Time Formats with Duration Spans
Returns one or two *time.Time pointers, one for the first second for given time, and a bounding second of the end of the duration (second after last second). This allows easy checks for give times within that duration.
+20m - in 20 minutes
+1h - in an hour
-2.5d - two and half days ago
.h - this hour
.d - today (this day)
t - tomorrow
y - yesterday
ly - last year
nw - next week
nm - next month
lw - last week
lmon - last monday
ly+4w - last year for four weeks (24 days)
See the test data for hundreds of examples and the PEG grammar for specifics.
Motivation
When using a mobile device the only characters available on the default keyboard are alpha-numeric and the comma (,) and period (.). While it is only a minor convenience to shift to the character keyboard why not create a set of formats that worth with the least amount of trouble. Therefore, these formats use the shortest, best format possible to convey the most common references to dates and times.
This also makes these time formats particularly useful to add to applications with a terse command-line interface.
TODO
- Add the
dtimecommand (with tab completion) to go with the package.
See Also
TJ Holowaychuk's go-naturaldate Package
TJ's go-naturaldate package came out while I was developing this one. I noted his use of PEG and reworked the internals of my package to also use it.
TJ's package is far better for conversational UIs.
Mine started with emphasis on the least amount of typing possible and no spaces so that queries can easily be added as singular command-line arguments.
Mine also comes with the dtime command for easy integration into shell scripts or while editing files with vi/m using "wand" syntax (!!,!},!G}.
I also focus mostly on time spans rather than specific dates.
Andrew Snodgrass' PEG Golang Package
This PEG package is truly amazing. My days of writing ABNF are likely over.
Design Decisions
-
Lowercase for all. Since the primary motivation is efficiency both in inputting and parsing I decided to keep everything to lowercase which a few exceptions where uppercase has a different meaning.
-
Just one. No need for more than one way to refer to things. Easier to memorize.
Documentation
¶
Overview ¶
Package dtime enables easy human input of times, dates, and durations. It also includes many convenience functions for rouding time duration boundaries as is frequently needed for scheduling and time-based search applications.
Pointers to time.Time are used throughout the package since <nil> is usually a more desirable zero value than that for time.Time without a pointer. */
Index ¶
- Constants
- Variables
- func AprilOf(t *time.Time) *time.Time
- func AugustOf(t *time.Time) *time.Time
- func DayOf(t *time.Time) *time.Time
- func DayOfWeek(t *time.Time, day string) *time.Time
- func DecemberOf(t *time.Time) *time.Time
- func FebruaryOf(t *time.Time) *time.Time
- func FridayOf(t *time.Time) *time.Time
- func HourOf(t *time.Time) *time.Time
- func JanuaryOf(t *time.Time) *time.Time
- func JulyOf(t *time.Time) *time.Time
- func JuneOf(t *time.Time) *time.Time
- func MarchOf(t *time.Time) *time.Time
- func MayOf(t *time.Time) *time.Time
- func MinuteOf(t *time.Time) *time.Time
- func MondayOf(t *time.Time) *time.Time
- func MonthOf(t *time.Time) *time.Time
- func MonthOfYear(t *time.Time, month string) *time.Time
- func NextHourOf(t *time.Time) *time.Time
- func NovemberOf(t *time.Time) *time.Time
- func OctoberOf(t *time.Time) *time.Time
- func Pretty(pretty bool) func(*spanParser) error
- func SameTimeInAprilOf(t *time.Time) *time.Time
- func SameTimeInAugustOf(t *time.Time) *time.Time
- func SameTimeInDecemberOf(t *time.Time) *time.Time
- func SameTimeInFebruaryOf(t *time.Time) *time.Time
- func SameTimeInJanuaryOf(t *time.Time) *time.Time
- func SameTimeInJulyOf(t *time.Time) *time.Time
- func SameTimeInJuneOf(t *time.Time) *time.Time
- func SameTimeInMarchOf(t *time.Time) *time.Time
- func SameTimeInMayOf(t *time.Time) *time.Time
- func SameTimeInMonthOfYear(t *time.Time, month string) *time.Time
- func SameTimeInNovemberOf(t *time.Time) *time.Time
- func SameTimeInOctoberOf(t *time.Time) *time.Time
- func SameTimeInSeptemberOf(t *time.Time) *time.Time
- func SameTimeOnDayOfWeek(t *time.Time, day string) *time.Time
- func SameTimeOnFridayOf(t *time.Time) *time.Time
- func SameTimeOnMondayOf(t *time.Time) *time.Time
- func SameTimeOnSaturdayOf(t *time.Time) *time.Time
- func SameTimeOnSundayOf(t *time.Time) *time.Time
- func SameTimeOnThursdayOf(t *time.Time) *time.Time
- func SameTimeOnTuesdayOf(t *time.Time) *time.Time
- func SameTimeOnWednesdayOf(t *time.Time) *time.Time
- func SaturdayOf(t *time.Time) *time.Time
- func SeptemberOf(t *time.Time) *time.Time
- func Span(s string) (first *time.Time, last *time.Time)
- func SundayOf(t *time.Time) *time.Time
- func ThursdayOf(t *time.Time) *time.Time
- func Today() *time.Time
- func Tomorrow() *time.Time
- func TuesdayOf(t *time.Time) *time.Time
- func Until(fn func(*time.Time) *time.Time, t *time.Time) time.Duration
- func WednesdayOf(t *time.Time) *time.Time
- func WeekOf(t *time.Time) *time.Time
- func YearOf(t *time.Time) *time.Time
- func Yesterday() *time.Time
Examples ¶
Constants ¶
Variables ¶
var DefaultTime *time.Time
DefaultTime can be set instead of time.Now().
Functions ¶
func DayOf ¶
DayOf returns the start of the given day.
Example ¶
package main
import (
"fmt"
"time"
"github.com/rwxrob/bonzai/dtime"
)
func main() {
t, _ := time.Parse("2006-01-02 15:04:05 -0700", "2020-05-13 14:34:56 -0500")
fmt.Println(dtime.DayOf(&t))
}
Output: 2020-05-13 00:00:00 -0500 -0500
func DayOfWeek ¶
DayOfWeek returns the day of the week passed rounded to the beginning of the weekday indicated.
Example ¶
package main
import (
"fmt"
"time"
"github.com/rwxrob/bonzai/dtime"
)
func main() {
then, _ := time.Parse("2006-01-02 15:04 -0700", "2020-05-13 14:34 -0500")
fmt.Println(then)
fmt.Println(dtime.DayOfWeek(&then, "tue"))
fmt.Println(dtime.DayOfWeek(&then, "fri"))
again, _ := time.Parse("2006-01-02 15:04 -0700", "2020-05-11 14:34 -0500")
fmt.Println(again)
fmt.Println(dtime.DayOfWeek(&again, "tue"))
fmt.Println(dtime.DayOfWeek(&again, "fri"))
}
Output: 2020-05-13 14:34:00 -0500 -0500 2020-05-12 00:00:00 -0500 -0500 2020-05-15 00:00:00 -0500 -0500 2020-05-11 14:34:00 -0500 -0500 2020-05-12 00:00:00 -0500 -0500 2020-05-15 00:00:00 -0500 -0500
func DecemberOf ¶
DecemberOf returns the beginning of the first day of December of the given year.
func FebruaryOf ¶
FebruaryOf returns the beginning of the first day of February of the given year.
func FridayOf ¶
FridayOf returns the Friday of the week passed as time rounded to the beginning of the day.
func HourOf ¶
HourOf returns the start of the given hour.
Example ¶
package main
import (
"fmt"
"time"
"github.com/rwxrob/bonzai/dtime"
)
func main() {
t, _ := time.Parse("2006-01-02 15:04:05 -0700", "2020-05-13 14:34:56 -0500")
fmt.Println(dtime.HourOf(&t))
}
Output: 2020-05-13 14:00:00 -0500 -0500
func MinuteOf ¶
MinuteOf returns the start of the given minute.
Example ¶
package main
import (
"fmt"
"time"
"github.com/rwxrob/bonzai/dtime"
)
func main() {
t, _ := time.Parse("2006-01-02 15:04:05 -0700", "2020-05-13 14:34:56 -0500")
fmt.Println(dtime.MinuteOf(&t))
}
Output: 2020-05-13 14:34:00 -0500 -0500
func MondayOf ¶
MondayOf returns the Monday of the week passed as time rounded to the beginning of the day.
func MonthOf ¶
MonthOf returns the start of the month.
Example ¶
package main
import (
"fmt"
"time"
"github.com/rwxrob/bonzai/dtime"
)
func main() {
t, _ := time.Parse("2006-01-02 15:04:05 -0700", "2020-05-13 14:34:56 -0500")
fmt.Println(dtime.MonthOf(&t))
}
Output: 2020-05-01 00:00:00 -0500 -0500
func MonthOfYear ¶
MonthOfYear returns the beginning of the first day of the specified month of the given year.
func NextHourOf ¶
NextHourOf returns the start of the given hour.
func NovemberOf ¶
NovemberOf returns the beginning of the first day of November of the given year.
func SameTimeInAprilOf ¶
SameTimeInAprilOf returns the exact same month day and time but for the month of April instead.
func SameTimeInAugustOf ¶
SameTimeInAugustOf returns the exact same month day and time but for the month of August instead.
func SameTimeInDecemberOf ¶
SameTimeInDecemberOf returns the exact same month day and time but for the month of December instead.
func SameTimeInFebruaryOf ¶
SameTimeInFebruaryOf returns the exact same month day and time but for the month of February instead.
func SameTimeInJanuaryOf ¶
SameTimeInJanuaryOf returns the exact same month day and time but for the month of January instead.
func SameTimeInJulyOf ¶
SameTimeInJulyOf returns the exact same month day and time but for the month of July instead.
func SameTimeInJuneOf ¶
SameTimeInJuneOf returns the exact same month day and time but for the month of June instead.
func SameTimeInMarchOf ¶
SameTimeInMarchOf returns the exact same month day and time but for the month of March instead.
func SameTimeInMayOf ¶
SameTimeInMayOf returns the exact same month day and time but for the month of May instead.
func SameTimeInMonthOfYear ¶
SameTimeInMonthOfYear returns the exact same month day and time but for the specified month instead.
func SameTimeInNovemberOf ¶
SameTimeInNovemberOf returns the exact same month day and time but for the month of November instead.
func SameTimeInOctoberOf ¶
SameTimeInOctoberOf returns the exact same month day and time but for the month of October instead.
func SameTimeInSeptemberOf ¶
SameTimeInSeptemberOf returns the exact same month day and time but for the month of September instead.
func SameTimeOnDayOfWeek ¶
SameTimeOnDayOfWeek returns the day of the week passed rounded to the beginning of the week day indicated.
func SameTimeOnFridayOf ¶
SameTimeOnFridayOf returns the exact same time but on the Friday of the week indicated. For beginning of day use without SameTimeOn.
func SameTimeOnMondayOf ¶
SameTimeOnMondayOf returns the exact same time but on the Monday of the week indicated. For beginning of day use without SameTimeOn.
func SameTimeOnSaturdayOf ¶
SameTimeOnSaturdayOf returns the exact same time but on the Saturday of the week indicated. For beginning of day use without SameTimeOn.
func SameTimeOnSundayOf ¶
SameTimeOnSundayOf returns the exact same time but on the Sunday of the week indicated. For beginning of day use without SameTimeOn.
func SameTimeOnThursdayOf ¶
SameTimeOnThursdayOf returns the exact same time but on the Thursday of the week indicated. For beginning of day use without SameTimeOn.
func SameTimeOnTuesdayOf ¶
SameTimeOnTuesdayOf returns the exact same time but on the Tuesday of the week indicated. For beginning of day use without SameTimeOn.
func SameTimeOnWednesdayOf ¶
SameTimeOnWednesdayOf returns the exact same time but on the Wednesday of the week indicated. For beginning of day use without SameTimeOn.
func SaturdayOf ¶
SaturdayOf returns the Saturday of the week passed as time rounded to the beginning of the day.
func SeptemberOf ¶
SeptemberOf returns the beginning of the first day of September of the given year.
func Span ¶
Span parses the htime format string and returns one or two time pointers. The first is the start time, the second is the last time. If a date and time are detected in the string the first is set. If the offset is detected in the string the second will be set. If no date and time are detected DefaultTime or time.Now() is assumed.
Spans the main function in this package and provides a minimal format for entering date and time information in a practical way. It's primary use case is when a user needs to enter such data quickly and regularly from the command line or into mobile and other devices where human input speed is limited to what can be tapped out on the screen. The characters used in the formatting only characters that appear on most default keyboards without shifting or switching to symbolic input. The package provides no method of specifying timezone, which falls out of the scope of this package. All times are therefore assumed to be local. For a precise specification of the format see the htime.peg file included with the package source code.
func SundayOf ¶
SundayOf returns the Sunday of the week passed as time rounded to the beginning of the day.
func ThursdayOf ¶
ThursdayOf returns the Thursday of the week passed as time rounded to the beginning of the day.
func TuesdayOf ¶
TuesdayOf returns the Tuesday of the week passed as time rounded to the beginning of the day.
func Until ¶
Until takes a time and a function that takes a time and returns a time and converts the result into a duration offset between them. Returns nil if unable to determine. This is useful when a duration is needed for any of the functions in this package that match that signature. The duration is positive or negative depending on the relation between the times.
func WednesdayOf ¶
WednesdayOf returns the Wednesday of the week passed as time rounded to the beginning of the day.
func WeekOf ¶
WeekOf returns the start of the given week.
Example ¶
package main
import (
"fmt"
"time"
"github.com/rwxrob/bonzai/dtime"
)
func main() {
t, _ := time.Parse("2006-01-02 15:04:05 -0700", "2020-05-13 14:34:56 -0500")
fmt.Println(dtime.WeekOf(&t))
}
Output: 2020-05-11 00:00:00 -0500 -0500
Types ¶
This section is empty.
Source Files