datepicker

An fzf-like tool to interactively select a date in a provided format

git clone https://git.8pit.net/datepicker.git

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