timediff

README

🌳 timediff - a tool for calculating clock time differences

Install

Prebuilt executable

Download the latest release for your platform from the releases page, put it somewhere in your PATH. If you're running bash as your shell, you can also enable command tab completion by following the instruction in the tab completion section.

Every release is signed with gpg, the public key of which can be found here.

Bonzai style.

This command can be installed as a standalone program or composed into a Bonzai command tree.

Standalone

go install github.com/morngrar/timediff/cmd/timediff@latest

Composed

package z

import (
	Z "github.com/rwxrob/bonzai/z"
	timediff "github.com/morngrar/timediff"
)

var Cmd = &Z.Cmd{
	Name:     `z`,
	Commands: []*Z.Cmd{help.Cmd, timediff.Cmd},
}

Tab Completion

To activate bash completion just use the complete -C option from your .bashrc or command line. There is no messy sourcing required. All the completion is done by the program itself.

complete -C timediff timediff

If you don't have bash or tab completion check use the shortcut commands instead.

Embedded Documentation

All documentation (like manual pages) has been embedded into the source code of the application. See the source or run the program with help to access it.

Other Examples

• https://github.com/rwxrob/z - the one that started it all

Documentation

Overview

Package timediff provides the Bonzai command branch of the same name.

Index

• Variables
• func ParseTime(s string) (float64, error)

Examples

• ParseTime

Variables

var Cmd = &Z.Cmd{

	Name:      `timediff`,
	Summary:   `a tool for aiding in time reporting`,
	Version:   `v0.2.5`,
	Copyright: `Copyright 2023 Svein-Kåre Bjørnsen`,
	License:   `Apache-2.0`,
	Source:    `git@github.com:morngrar/timediff.git`,
	Issues:    `github.com/morngrar/timediff/issues`,

	Commands: []*Z.Cmd{

		help.Cmd, conf.Cmd, vars.Cmd,

		Sub,
	},

	Description: `
        {{aka}} is a toolchain for simple calculation of clock time differences.
        see the help of each subcommand separately for usage info.
		`,
}

Cmd provides a Bonzai branch command that can be composed into Bonzai trees or used as a standalone with light wrapper (see cmd/).

var Sub = &Z.Cmd{
	Name:    `subtract`,
	Usage:   `[START_TIME END_TIME | COMMAND]`,
	Aliases: []string{"s"},
	Summary: `subtracts two times and prints the number of hours between them`,
	Description: `
		The {{aka}} command either takes a subcommand or two arguments and
		executes its primary function. The only subcommand that is currently
		supported is this help.

		In regards to the primary function, the the first of the arguments is
		START_TIME and the second is END_TIME. The command prints the
		real-valued difference in hours between them.

		The format of the times is expected to be in 24-hour format, where the
		time 8 AM can be written in the following ways:

		    08:00 
		    8:00 
		    8.00 
		    8

		*NOTE*: If START_TIME is **higher** than END_TIME the command assumes
		that the START_TIME was during the previous day. Thus the difference
		will never be negative.  
	`,

	Commands: []*Z.Cmd{help.Cmd},
	Call: func(x *Z.Cmd, args ...string) error {
		if len(args) < 2 || len(args) > 2 {
			return x.UsageError()
		}

		var err error

		startTime := args[0]
		endTime := args[1]

		startTimeHours, err := ParseTime(startTime)
		if err != nil {
			return fmt.Errorf("Error parsing START_TIME: '%w'", err)
		}
		endTimeHours, err := ParseTime(endTime)
		if err != nil {
			return fmt.Errorf("Error parsing END_TIME: '%w'", err)
		}

		diff := endTimeHours - startTimeHours
		if diff < 0 {
			firstDay := 24 - startTimeHours
			diff = firstDay + endTimeHours
		}

		fmt.Printf("%.2f hours\n", diff)

		return nil
	},
}

Functions

func ParseTime

func ParseTime(s string) (float64, error)

ParseTime converts a time of day represented as a string from hours or hours and minutes into a scalar float representing the hours into the day.

It takes a string containing a point in time in the format of 24-hour clock hours with minutes being optional. The separator between hours and minutes can be either a colon or a period, and seconds are not supported. The returned value is a `float64` representing the added hours and minutes as hours.

As an example, the time 8 AM can be expressed in the following supported ways:

8
8:00
08:00
8.00
08:00

The function wraps and returns any transitive errors, and also generates an error if the time expression is invalid.

Example

var t float64
var err error

t, err = ParseTime("8")
if err != nil {
	log.Printf("Error parsing time: %s", err)
}
fmt.Println(t)

t, err = ParseTime("8:00")
if err != nil {
	log.Printf("Error parsing time: %s", err)
}
fmt.Println(t)

t, err = ParseTime("08:00")
if err != nil {
	log.Printf("Error parsing time: %s", err)
}
fmt.Println(t)

t, err = ParseTime("08.00")
if err != nil {
	log.Printf("Error parsing time: %s", err)
}
fmt.Println(t)

t, err = ParseTime("8.00")
if err != nil {
	log.Printf("Error parsing time: %s", err)
}
fmt.Println(t)

t, err = ParseTime("8.30")
if err != nil {
	log.Printf("Error parsing time: %s", err)
}
fmt.Println(t)

t, err = ParseTime("8.45")
if err != nil {
	log.Printf("Error parsing time: %s", err)
}
fmt.Println(t)

Output:

8
8
8
8
8
8.5
8.75