Chronograph is a group of four command line programs that implement functions found in a chronograph watch.
The programs are:
alarm - alarm clock
clock - time-of-day clock
stopwatch - stopwatch with pause, reset, and lap functions
timer - countdown timer
All of the programs are written in Go and use Cgo. They were developed on Linux and may work on macOS, but not on Windows.
In the example commands, $ is used to indicate a shell prompt.
$ go build alarm.go
$ go build clock.go
$ go build stopwatch.go
$ go build timer.go
or if you have GNU make installed:
$ make
$ clock
$ stopwatch
$ timer 10s
$ alarm <clock_time>
See the manual pages (included below) for details.
The included Makefile contains rules for installing the programs and manual pages. Set the variables BINDIR and MANDIR in Makefile appropriately before running one of
make install
and/or
make install-man
to install the programs and/or manual pages, respectively.
The distribution includes shell scripts alarm-gui, clock-gui, stopwatch-gui, and timer-gui as examples of how to run the programs within a virtual terminal so they act more like GUI apps. They all depend on konsole(1) for the virtual terminal. You will need to modify the scripts if you want to use another virtual terminal.
ALARM(1) User Commands ALARM(1)
NAME
alarm - alarm clock
SYNOPSIS
alarm time
DESCRIPTION
alarm(1) is a command line alarm clock. It displays the time of day
until reaching the specified time.
ARGUMENTS
The argument specifies the time that alarm exits. The following formats
may be used:
Exactly on the hour:
3pm
3PM
15
Exactly on the minute:
3:04pm
3:04PM
15:04
Exactly on the second:
3:04:05pm
3:04:05PM
15:04:05
EXAMPLES
An alarm set to play an mp3 (with the command aplay alarmbell.mp3) at
2:30 pm (14:30):
alarm 2:30pm && aplay alarmbell.mp3
An alarm set to print "hello, world" at 9 pm (21:00):
alarm 21:00 && echo "hello, world"
Reminder to feed the cat at 10am:
alarm 10am && echo feed the cat
EXIT VALUES
0 Normal command exit (reached alarm time)
1 Quit by user (with q or Q key)
2 Quit by Control-C or SIGKILL
3 Error (bad arguments)
When using alarm in loop in a shell script, use this code to have the
script exit when alarm is interrupted, either with a q or Q keypress,
or a Control-C or SIGKILL from another source:
alarm 1pm
# exit if interrupted
if [ $? -ne 0 ]
then
exit 1
fi
The following causes the shell script to exit if it receives an inter‐
rupt signal (Control-C), but if the user types a q or Q, alarm will
quit early, and the loop inside the shell script will continue to exe‐
cute:
alarm 2pm
# ignore user quit with q or Q key,
# but exit if interrupted with SIGKILL (Control-C)
if [ $? -eq 2 ]
then
exit 1
fi
BUGS
The time is always shown with a 24-hour clock, even when the alarm is
set with a 12-hour clock.
AUTHOR
Jay Ts (http://jayts.com)
COPYRIGHT
Copyright 2019 Jay Ts
Released under the GNU Public License, version 3.0 (GPLv3)
(http://www.gnu.org/licenses/gpl.html)
Jay Ts June 2019 ALARM(1)
CLOCK(1) User Commands CLOCK(1)
NAME
clock - clock
SYNOPSIS
clock
DESCRIPTION
clock(1) is a command-line clock. It displays the running wall clock
time and is accurate to about 1/10 second.
Type a ´q´, ´Q´, or Control-C to exit.
ARGUMENTS
None.
EXIT VALUES
1 Quit by user (with q key)
2 Quit by Control-C or SIGKILL
3 Error (bad arguments)
BUGS
The time is always shown with a 24-hour clock.
AUTHOR
Jay Ts (http://jayts.com)
COPYRIGHT
Copyright 2019 Jay Ts
Released under the GNU Public License, version 3.0 (GPLv3)
(http://www.gnu.org/licenses/gpl.html)
Jay Ts June 2019 CLOCK(1)
STOPWATCH(1) User Commands STOPWATCH(1)
NAME
stopwatch - stopwatch
SYNOPSIS
stopwatch [-p]
DESCRIPTION
stopwatch(1) is a stopwatch that runs in a virtual terminal.
It is controlled with keys on the keyboard as follows:
SPACE, p, P
Pause/restart the stopwatch.
l, L
Lap Timer. The current timing is printed, and counting continues on the following line.
r, R
Reset. Works only while paused.
q, Q, e, E, Ctrl-C, Ctrl-D, Enter/Return
Stop the stopwatch and exit.
ARGUMENTS
When the -p option is specified, the stopwatch starts in the paused
state.
EXIT VALUES
1 Quit by user (with q key)
2 Quit by Control-C or SIGKILL
3 Error (bad arguments)
AUTHOR
Jay Ts (http://jayts.com)
COPYRIGHT
Copyright 2019 Jay Ts
Released under the GNU Public License, version 3.0 (GPLv3)
(http://www.gnu.org/licenses/gpl.html)
Jay Ts June 2019 STOPWATCH(1)
TIMER(1) User Commands TIMER(1)
NAME
timer - countdown timer
SYNOPSIS
timer duration
DESCRIPTION
timer(1) is a countdown timer.
While the timer is running, the remaining time is displayed. The com‐
mand exits when the time remaining reaches 0.
ARGUMENTS
The argument specifies the duration. Some examples of valid arguments
follows:
5s Five seconds
22.9s Twenty-two and 9/10 seconds
179s 179 seconds (or two minutes and 59 seconds)
7m Seven minutes
32m30s 32½ minutes
1h45m One hour and 45 minutes
2h56m4s Two hours, 56 minutes, and 4 seconds
5h Five hours
100h One hundred hours
EXAMPLES
Pause for 5 seconds, showing the countdown:
timer 5s
After 2 minutes and 30 seconds, play an mp3 (with the command aplay
alarmbell.mp3):
timer 2m30s && aplay alarmbell.mp3
Print "hello, world" after waiting 21 minutes:
timer 21m && echo "hello, world"
EXIT VALUES
0 Normal command exit (timer reached 0)
1 Quit by user (with q key)
2 Quit by Control-C or SIGKILL
3 Error (bad arguments)
When using timer in loop in a shell script, use this code to have the
script exit when the timer is interrupted, either with a q or Q key‐
press, or a Control-C or SIGKILL from another source:
timer 600s
# exit if interrupted
if [ $? -ne 0 ]
then
exit 1
fi
The following causes the shell script to exit if it receives an inter‐
rupt signal (Control-C), but if the user types a q or Q, timer will
quit early, and the loop inside the shell script will continue to exe‐
cute:
timer 600s
# ignore user quit with q or Q key,
# but exit if interrupted with SIGKILL (Control-C)
if [ $? -eq 2 ]
then
exit 1
fi
BUGS
The time is always shown with a 24-hour clock, even when the duration
is set with a 12-hour clock.
AUTHOR
Jay Ts (http://jayts.com)
COPYRIGHT
Copyright 2019 Jay Ts
Released under the GNU Public License, version 3.0 (GPLv3)
(http://www.gnu.org/licenses/gpl.html)
Jay Ts June 2019 TIMER(1)