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 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.org100[formatTime]: https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime101[RFC 1123]: https://datatracker.ietf.org/doc/html/rfc1123102[tmux]: https://tmux.github.io103[fzf preview]: https://manpages.debian.org/unstable/fzf/fzf.1.en.html#PREVIEW_WINDOW