datepicker

  1## README
  2
  3An [fzf]-like tool to interactively select a date in a provided format.
  4
  5![Example usage with at(1) job scheduling](https://files.8pit.net/img/datepicker-demo-20250101.gif)
  6
  7### Motivation
  8
  9A variety of command-line utilities ([at], [journalctl], [mpick], [khal], …) allow passing dates in different formats via command-line options.
 10Entering these dates in the required formats manually can be cumbersome and annoying.
 11Inspired by [fzf], this utility allows visually selecting a date interactively through a TUI, thereby easing specification of dates for other command-line utilities.
 12
 13### Status
 14
 15Basic functionally is operational and works.
 16The currently implemented feature set is presently being stabilized and tested, more advanced features (like [fzf-like previews][fzf preview]) may be added in a future version.
 17
 18### Installation
 19
 20If you have a Haskell development environment setup and a compatible GHC version installed, you can install this utility by cloning the repository and running:
 21
 22	$ cabal install
 23
 24Alternatively, if you don't have a Haskell development environment, you can also install this software using [Guix].
 25Guix will automatically install a supported GHC version for you and add the binary to your `$PATH`.
 26In order to install `datepicker` this way run the following command
 27
 28	$ guix time-machine -C channels.scm -- package -f manifest.scm
 29
 30### Tests
 31
 32A test suite is available, it performs several checks on the TUI using [tmux] and requires the `datepicker` binary in your `$PATH`.
 33Once these requirements are satisfied, it can be invoked using:
 34
 35	$ cabal test
 36
 37### Usage Examples
 38
 39By default, `datepicker` requires selection of both a date and a time and prints the selected date in the [RFC 1123] date format.
 40The behavior can be customized using several command-line flags, e.g. the `-f` option allows specification of a different date format.
 41This format must be specified using the format strings supported by the [formatTime] function from Haskell's `time` library.
 42A few example usages are provided below.
 43
 44**at** — Execute a job at a specified time which is selected based on the current year (`-y`):
 45
 46	$ echo "ls ~" | at -m -t "$(datepicker -y -f %0Y%m%d%H%M)"
 47
 48**journalctl** — Select log entries newer than a given date from a span of three months (`-3`):
 49
 50	$ journalctl --since="$(datepicker -3 -f '%Y-%m-%d %H:%M:%S')"
 51
 52**mpick** — Select emails newer than a given date in the current month, skipping time selection (`-d`):
 53
 54	$ mlist ~/mail/INBOX | mpick -t "date >= \"$(datepicker -d -f %Y-%m-%d)\""
 55
 56Refer to the `--help` output for an overview of all supported command-line options.
 57The command-line interface is still subject to change, more options will likely be added in future versions.
 58
 59### Key Bindings
 60
 61Two input views are provided: (1) A date selection view and (2) a time selection view.
 62
 63**Date Selection:**
 64
 65* `Esc` / `q`: Abort selection, exit with non-zero exit status
 66* `Enter`: Confirm selection of focused date
 67* `Up` and `Down`: Change focus to date in previous/next week
 68* `Left` and `Right`: Change focus to previous/next date
 69
 70**Time Selection:**
 71
 72* `Esc` / `q`: Abort selection, exit with non-zero exit status
 73* `Enter`: Confirm selection of specified time
 74	* Note: If the time is invalid, confirming the selection won't be possible
 75	* In a future version, this may cause an error to be emitted
 76* `[0-9]`: Input a new digit at the highlighted location
 77* `Backspace`: Move cursor to previous time digit
 78* `Left` and `Right`: Move cursor to previous/next digit
 79
 80### License
 81
 82This program is free software: you can redistribute it and/or modify it
 83under the terms of the GNU General Public License as published by the
 84Free Software Foundation, either version 3 of the License, or (at your
 85option) any later version.
 86
 87This program is distributed in the hope that it will be useful, but
 88WITHOUT ANY WARRANTY; without even the implied warranty of
 89MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 90Public License for more details.
 91
 92You should have received a copy of the GNU General Public License along
 93with this program. If not, see <https://www.gnu.org/licenses/>.
 94
 95[fzf]: https://github.com/junegunn/fzf
 96[cal]: https://manpages.debian.org/unstable/ncal/cal.1.en.html
 97[at]: https://manpages.debian.org/unstable/at/at.1.en.html
 98[journalctl]: https://manpages.debian.org/unstable/systemd/journalctl.1.en.html#FILTERING_OPTIONS
 99[mpick]: https://manpages.debian.org/unstable/mblaze/mpick.1.en.html#EXAMPLES
100[khal]: https://manpages.debian.org/unstable/khal/khal.1.en.html
101[Guix]: https://guix.gnu.org
102[formatTime]: https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime
103[RFC 1123]: https://datatracker.ietf.org/doc/html/rfc1123
104[tmux]: https://tmux.github.io
105[fzf preview]: https://manpages.debian.org/unstable/fzf/fzf.1.en.html#PREVIEW_WINDOW