.TH "PDD" "1" "03 Dec 2022" "Version 1.7" "User Commands"
.SH NAME
pdd \- Tiny date, time difference calculator with timers.
.SH SYNOPSIS
.B pdd [OPTIONS] [KEYWORDS ...]
.SH DESCRIPTION
.B pdd
(python3 date diff) is a small utility to calculate date and time difference. It can also be used as a timer. If no program arguments are specified it shows the current date, time and timezone.
.PP
.B Features
.PP
- easy to use, minimal dependencies
.br
- calculate date and time difference
.br
- add, subtract duration (timeslice) to/from date (time)
.br
- calculate diff from \fItoday\fR and \fInow\fR
.br
- countdown timer with command piggybacking
.br
- custom resolution stopwatch
.br
- non-verbose mode for background timers
.br
- show current date, time and timezone
.br
- follows ISO 8601
.PP
.B Operational notes
.PP
- ISO 8601 format. Month can be specified as month number (e.g. Jan - 1, Dec - 12).
.br
- Time is in 24-hr format.
.br
- The absolute difference is shown. Argument order is ignored.
.br
- The end date is excluded in date difference calculations.
.br
- Hour, minute or second can be omitted. Partial inputs are recognized as \fImm:ss\fR or \fIss\fR.
.br
- The keybind to stop timers is \fICtrl-C\fR.
.SH OPTIONS
.TP
.BI "-h, --help"
Show help text and exit.
.TP
.BI "-d, --date" " yyyy mmm dd [yyyy mmm dd | y m d]"
Calculate date difference.
.TP
.BI "-t, --time" " hh:mm:ss [hh:mm:ss | h:m:s]"
Calculate time difference.
.TP
.BI "--add"
Add a duration or timeslice to date (/today) or time (/now).
.TP
.BI "--sub"
Subtract a duration or timeslice from date (/today) or time (/now).
.TP
.BI "--day" " yyyy mmm dd"
Show the day of the week on a date.
.TP
.BI "-c, --timer" " hh:mm:ss"
Set a countdown timer with duration in hours, minutes and seconds.
.TP
.BI "-r, --run" " command"
Run command when countdown timer reaches 0.
.TP
.BI "-s, --stopwatch" " [resolution]"
Start a custom resolution stopwatch. \fIresolution\fR can range from 1 to 9. Default 3 for millisecond.
.TP
.BI "-q, --quiet"
Quiet mode for a countdown timer or stopwatch to be run in the background. The counter is shown only when \fICtrl-C\fR is pressed.
.SH EXAMPLES
.PP
.IP 1. 4
Calculate diff from \fBtoday\fR:
.PP
.EX
.IP
.B $ pdd 2014 Jan 15
.EE
.PP
.IP 2. 4
Calculate diff from \fBnow\fR:
.PP
.EX
.IP
.B $ pdd 24:00:00
.B $ pdd 0
.EE
.PP
.IP 3. 4
Calculate date diff:
.PP
.EX
.IP
.B $ pdd -d 1983 jul 3 2014 1 15
.EE
.PP
.IP 4. 4
Calculate time diff:
.PP
.EX
.IP
.B $ pdd -t 45:50 6:17:33
.EE
.PP
.IP 5. 4
Show current date, time and timezone:
.PP
.EX
.IP
.B $ pdd
.EE
.PP
.IP 6. 4
Specify time with roll-over:
.PP
.EX
.IP
.B $ pdd -t 5:80:75 6:17:33
.EE
.PP
.IP 7. 4
Add a duration (3 years, 2 months, 1 day) to 28 Feb, 2000:
.PP
.EX
.IP
.B $ pdd -d 2000 FEB 28 3 2 1 --add
.EE
.PP
.IP 8. 4
Add a timeslice (1 hour 2 mins 3 secs) to 23:45:37:
.PP
.EX
.IP
.B $ pdd -t 23:45:37 1:2:3 --add
.EE
.PP
.IP 9. 4
Add a duration (3 years, 2 months, 1 day) to \fBtoday\fR:
.PP
.EX
.IP
.B $ pdd 3 2 1 --add
.EE
.PP
.IP 10. 4
Add a timeslice (1 hour 2 minutes 3 seconds) to \fBnow\fR:
.PP
.EX
.IP
.B $ pdd 1:2:3 --add
.EE
.PP
.IP 11. 4
Subtract a duration (1 day) from 1 Mar, 2000:
.PP
.EX
.IP
.B $ pdd -d 2000 Mar 01 0 0 1 --sub
.EE
.PP
.IP 12. 4
Subtract a timeslice (1 sec) from midnight:
.PP
.EX
.IP
.B $ pdd -t 00:00:00 0:0:1 --sub
.EE
.PP
.IP 13. 4
Subtract a duration (3 years, 2 months, 1 day) from \fBtoday\fR:
.PP
.EX
.IP
.B $ pdd 3 2 1 --sub
.EE
.PP
.IP 14. 4
Subtract a timeslice (1 hour 2 minutes 3 seconds) from \fBnow\fR:
.PP
.EX
.IP
.B $ pdd 1:2:3 --sub
.EE
.PP
.IP 15. 4
Show the day of the week on 15 Jan 2014:
.PP
.EX
.IP
.B $ pdd --day 2014 Jan 15
.EE
.PP
.IP 16. 4
Start a countdown timer or stopwatch in \fBquiet mode\fR in the background:
.PP
.EX
.IP
.B $ pdd -qs &
.B $ pdd -qc 3:0:0 &
.EE
.PP
.IP "" 4
To see the final counter run \fIfg\fR and press \fICtrl-C\fR.
.PP
.IP 17. 4
Run a command when countdown timer reaches 0:
.PP
.EX
.IP
.B $ pdd -c 00:00:5 -r 'ps -aux'
.B $ pdd -c 00:00:5 -r 'notify-send pdd expired'
.EE
.SH AUTHORS
Arun Prakash Jana <engineerarun@gmail.com>
.SH HOME
.I https://github.com/jarun/pdd
.SH REPORTING BUGS
.I https://github.com/jarun/pdd/issues
.SH LICENSE
Copyright \(co 2017 Arun Prakash Jana <engineerarun@gmail.com>
.PP
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
.br
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.