CountdownTimer.pl version 2.02
A countdown timer, like a kitchen timer for your perfect cup of tea.
I could not find a countdown timer I really liked, so I decided to roll my own.
This is what the output looks like:
$ ./CountdownTimer.pl "1m 30s"
Start time: 2020-10-04 16:45:00
Countdown duration: 1 minute, 30 seconds (90 seconds)
Countdown: 01:25 Finish time: 16:46:30The remaining time on the last output line is updated as time passes.
The timing method is not a simplistic sleep( 1 second ) between updates, but is based either on the real-time clock or on CLOCK_MONOTONIC (a kind of uptime), see option --method further below.
perl CountdownTimer.pl [options] [--] [duration]If no duration is specified, the user will be prompted for one.
The duration is a single command-line argument. If it contains spaces and you are running this script from the shell, you will need to quote the duration so that it gets passed as a single argument.
The maximum duration is 10 years.
Possible duration formats are:
An natural number like 123 is interpreted as a number of seconds.
A digital clock like 1:02 or 01:02 is interpreted as minutes and seconds (62 seconds in this example).
A digital clock like 1:02:03 or 01:02:03 is interpreted as hours, minutes and seconds (3,723 seconds in this example).
A condensed expression like 1m2s (62 seconds in this example).
A rather flexible and tolerant human expression like "2 weeks, 1 days, 8 hour, and 3 minutes and 2 secs", which yields 1,324,982 seconds in this example.
If you want to run some action after the countdown has finished, you can chain commands in your shell like this:
./CountdownTimer.pl '3 seconds' && zenity --info --text 'Countdown finished.'See also script DesktopNotification.sh in the same repository as this one.
You can use script background.sh (also in the same repository as this script) for notification purposes too like this:
background.sh --no-prio --filter-log -- ./CountdownTimer.pl '3 seconds'If you create a desktop icon with the following command, a new console window will open up and prompt you for the timer duration:
/some/path/run-in-new-console.sh --console-title='Countdown Timer' --console-icon=clock -- '/some/path/CountdownTimer.pl && /some/path/DesktopNotification.sh "Countdown finished."'You will find run-in-new-console.sh in the same repository as this script.
-h, --help
Print this help text.
--help-pod
Preprocess and print the POD section. Useful to generate the README.pod file.
--version
Print this tool's name and version number (2.02).
--license
Print the license.
--
Terminate options processing. Useful to avoid confusion between options and filenames that begin with a hyphen ('-'). Recommended when calling this script from another script, where the filename comes from a variable or from user input.
--method=<method name>
The method name can be either monotonic , or real time (realtime and real-time work too). The name is case insensitive. The default is real time.
Each timing method is explained in its own section further below.
--self-test
Runs some internal self-tests.
This is the default timing method, see option --method=<method name> .
A 10-minute countdown started at 14:00 will finish at 14:10.
If you (or something like NTP) decide to adjust the clock in the meantime, perhaps because the clock was runnnig fast, your countdown duration will no longer be the desired 10 minutes.
Clock changes due to sommer time will not affect the countdown duration, because this script uses UTC internally.
If your laptop goes to sleep, this script will pause executing, so, if the countdown expires during the sleep period, the script will not actually exit until the laptop wakes up. Therefore, by allowing your laptop to sleep during a countdown, you risk missing the countdown deadline (you will get notified too late), which will make your black tee unpalatable.
The countdown seconds display will not actually update in sync with the real-time clock seconds, and the countdown finish time will usually fall between real-time clock seconds. This is because I could not find a way to tick this script in sync with the real-time clock.
You can use this timing method with option --method=monotonic .
The script will then use CLOCK_MONOTONIC (a kind of uptime). This means that the countdown timer is not synchronised with the real-time clock, which has advantages and disadvantages:
The countdown timer is not affected by any real-time clock changes.
The ETA (estimated time of arrival) on the progress message does get updated if necessary, but that does not affect the overall countdown duration.
There may still be some external interference with the monotonic clock. For example, the Linux documentation states some differences between CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW in this respect.
The real-time clock is often synchronised over NTP, but the internal monotonic clock is usually not.
Therefore, the accuracy of the countdown timer depends on the accuracy of the internal clock. Clock drifting may become noticeable for long countdown periods.
The countdown seconds display will not update in sync with the real-time clock seconds.
The countdown finish time will usually fall between real-time clock seconds.
The timer will not count whilst the computer is asleep.
Let's say that you are using this script to remind you when your washing machine has finished. If your laptop goes to sleep, you will miss the notification. When the laptop wakes up, it will countinue counting exactly where it was, so the washing machine may have already finished. Even if your laptop slept just 15 minutes, the countdown timer will be delayed by those 15 minutes, which is also not ideal, because your washing machine will not actually be delayed.
This script could switch from CLOCK_MONOTONIC to the Linux-specific CLOCK_BOOTTIME, so that the timer does get adjusted after waking up. That is of course assuming that the script is running on Linux. And if Perl's Time::HiRes module actually supported CLOCK_BOOTTIME. Moreover, it looks like CLOCK_BOOTTIME is only available on the Linux syscall, not even via glibc, further complicating matters. This change would not be enough to wake the computer up should the timer reach zero while asleep. And whether automatically waking up is desirable, is yet another question.
Exit code: 0 on success, some other value on error.
Many things could be improved, like adding built-in visual notifications or using a GUI tool like yad for prompting and progress indication.
Version 1.07 only implemented the monotonic method, and version 2.00 introduced the alternative real time method and made it the default. Therefore, the default timing behaviour has changed between those two versions.
Please send feedback to rdiezmail-tools at yahoo.de
Copyright (C) 2019-2023 R. Diez
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License version 3 as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License version 3 for more details.
You should have received a copy of the GNU Affero General Public License version 3 along with this program. If not, see http://www.gnu.org/licenses/.