diff --git a/.github/images/logo.png b/.github/images/logo.png new file mode 100644 index 0000000..66369ca Binary files /dev/null and b/.github/images/logo.png differ diff --git a/README.md b/README.md index 8e12f3b..7f5ecfb 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,82 @@ bash-tui-toolkit === -[![pre-commit](https://img.shields.io/badge/%E2%9A%93%20%20pre--commit-enabled-success)](https://pre-commit.com/) -[![CircleCI](https://dl.circleci.com/status-badge/img/gh/timo-reymann/bash-tui-toolkit/tree/main.svg?style=shield)](https://dl.circleci.com/status-badge/redirect/gh/timo-reymann/bash-tui-toolkit/tree/main) +[![LICENSE](https://img.shields.io/github/license/timo-reymann/gpg-key-creation-assistant)](https://github.com/timo-reymann/bash-tui-toolkit/blob/main/LICENSE) +[![CircleCI](https://circleci.com/gh/timo-reymann/bash-tui-toolkit.svg?style=shield)](https://app.circleci.com/pipelines/github/timo-reymann/bash-tui-toolkit) +[![GitHub Release](https://img.shields.io/github/v/tag/timo-reymann/bash-tui-toolkit?label=version)](https://github.com/timo-reymann/bash-tui-toolkit/releases) [![Renovate](https://img.shields.io/badge/renovate-enabled-green?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzNjkgMzY5Ij48Y2lyY2xlIGN4PSIxODkuOSIgY3k9IjE5MC4yIiByPSIxODQuNSIgZmlsbD0iI2ZmZTQyZSIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoLTUgLTYpIi8+PHBhdGggZmlsbD0iIzhiYjViNSIgZD0iTTI1MSAyNTZsLTM4LTM4YTE3IDE3IDAgMDEwLTI0bDU2LTU2YzItMiAyLTYgMC03bC0yMC0yMWE1IDUgMCAwMC03IDBsLTEzIDEyLTktOCAxMy0xM2ExNyAxNyAwIDAxMjQgMGwyMSAyMWM3IDcgNyAxNyAwIDI0bC01NiA1N2E1IDUgMCAwMDAgN2wzOCAzOHoiLz48cGF0aCBmaWxsPSIjZDk1NjEyIiBkPSJNMzAwIDI4OGwtOCA4Yy00IDQtMTEgNC0xNiAwbC00Ni00NmMtNS01LTUtMTIgMC0xNmw4LThjNC00IDExLTQgMTUgMGw0NyA0N2M0IDQgNCAxMSAwIDE1eiIvPjxwYXRoIGZpbGw9IiMyNGJmYmUiIGQ9Ik04MSAxODVsMTgtMTggMTggMTgtMTggMTh6Ii8+PHBhdGggZmlsbD0iIzI1YzRjMyIgZD0iTTIyMCAxMDBsMjMgMjNjNCA0IDQgMTEgMCAxNkwxNDIgMjQwYy00IDQtMTEgNC0xNSAwbC0yNC0yNGMtNC00LTQtMTEgMC0xNWwxMDEtMTAxYzUtNSAxMi01IDE2IDB6Ii8+PHBhdGggZmlsbD0iIzFkZGVkZCIgZD0iTTk5IDE2N2wxOC0xOCAxOCAxOC0xOCAxOHoiLz48cGF0aCBmaWxsPSIjMDBhZmIzIiBkPSJNMjMwIDExMGwxMyAxM2M0IDQgNCAxMSAwIDE2TDE0MiAyNDBjLTQgNC0xMSA0LTE1IDBsLTEzLTEzYzQgNCAxMSA0IDE1IDBsMTAxLTEwMWM1LTUgNS0xMSAwLTE2eiIvPjxwYXRoIGZpbGw9IiMyNGJmYmUiIGQ9Ik0xMTYgMTQ5bDE4LTE4IDE4IDE4LTE4IDE4eiIvPjxwYXRoIGZpbGw9IiMxZGRlZGQiIGQ9Ik0xMzQgMTMxbDE4LTE4IDE4IDE4LTE4IDE4eiIvPjxwYXRoIGZpbGw9IiMxYmNmY2UiIGQ9Ik0xNTIgMTEzbDE4LTE4IDE4IDE4LTE4IDE4eiIvPjxwYXRoIGZpbGw9IiMyNGJmYmUiIGQ9Ik0xNzAgOTVsMTgtMTggMTggMTgtMTggMTh6Ii8+PHBhdGggZmlsbD0iIzFiY2ZjZSIgZD0iTTYzIDE2N2wxOC0xOCAxOCAxOC0xOCAxOHpNOTggMTMxbDE4LTE4IDE4IDE4LTE4IDE4eiIvPjxwYXRoIGZpbGw9IiMzNGVkZWIiIGQ9Ik0xMzQgOTVsMTgtMTggMTggMTgtMTggMTh6Ii8+PHBhdGggZmlsbD0iIzFiY2ZjZSIgZD0iTTE1MyA3OGwxOC0xOCAxOCAxOC0xOCAxOHoiLz48cGF0aCBmaWxsPSIjMzRlZGViIiBkPSJNODAgMTEzbDE4LTE3IDE4IDE3LTE4IDE4ek0xMzUgNjBsMTgtMTggMTggMTgtMTggMTh6Ii8+PHBhdGggZmlsbD0iIzk4ZWRlYiIgZD0iTTI3IDEzMWwxOC0xOCAxOCAxOC0xOCAxOHoiLz48cGF0aCBmaWxsPSIjYjUzZTAyIiBkPSJNMjg1IDI1OGw3IDdjNCA0IDQgMTEgMCAxNWwtOCA4Yy00IDQtMTEgNC0xNiAwbC02LTdjNCA1IDExIDUgMTUgMGw4LTdjNC01IDQtMTIgMC0xNnoiLz48cGF0aCBmaWxsPSIjOThlZGViIiBkPSJNODEgNzhsMTgtMTggMTggMTgtMTggMTh6Ii8+PHBhdGggZmlsbD0iIzAwYTNhMiIgZD0iTTIzNSAxMTVsOCA4YzQgNCA0IDExIDAgMTZMMTQyIDI0MGMtNCA0LTExIDQtMTUgMGwtOS05YzUgNSAxMiA1IDE2IDBsMTAxLTEwMWM0LTQgNC0xMSAwLTE1eiIvPjxwYXRoIGZpbGw9IiMzOWQ5ZDgiIGQ9Ik0yMjggMTA4bC04LThjLTQtNS0xMS01LTE2IDBMMTAzIDIwMWMtNCA0LTQgMTEgMCAxNWw4IDhjLTQtNC00LTExIDAtMTVsMTAxLTEwMWM1LTQgMTItNCAxNiAweiIvPjxwYXRoIGZpbGw9IiNhMzM5MDQiIGQ9Ik0yOTEgMjY0bDggOGM0IDQgNCAxMSAwIDE2bC04IDdjLTQgNS0xMSA1LTE1IDBsLTktOGM1IDUgMTIgNSAxNiAwbDgtOGM0LTQgNC0xMSAwLTE1eiIvPjxwYXRoIGZpbGw9IiNlYjZlMmQiIGQ9Ik0yNjAgMjMzbC00LTRjLTYtNi0xNy02LTIzIDAtNyA3LTcgMTcgMCAyNGw0IDRjLTQtNS00LTExIDAtMTZsOC04YzQtNCAxMS00IDE1IDB6Ii8+PHBhdGggZmlsbD0iIzEzYWNiZCIgZD0iTTEzNCAyNDhjLTQgMC04LTItMTEtNWwtMjMtMjNhMTYgMTYgMCAwMTAtMjNMMjAxIDk2YTE2IDE2IDAgMDEyMiAwbDI0IDI0YzYgNiA2IDE2IDAgMjJMMTQ2IDI0M2MtMyAzLTcgNS0xMiA1em03OC0xNDdsLTQgMi0xMDEgMTAxYTYgNiAwIDAwMCA5bDIzIDIzYTYgNiAwIDAwOSAwbDEwMS0xMDFhNiA2IDAgMDAwLTlsLTI0LTIzLTQtMnoiLz48cGF0aCBmaWxsPSIjYmY0NDA0IiBkPSJNMjg0IDMwNGMtNCAwLTgtMS0xMS00bC00Ny00N2MtNi02LTYtMTYgMC0yMmw4LThjNi02IDE2LTYgMjIgMGw0NyA0NmM2IDcgNiAxNyAwIDIzbC04IDhjLTMgMy03IDQtMTEgNHptLTM5LTc2Yy0xIDAtMyAwLTQgMmwtOCA3Yy0yIDMtMiA3IDAgOWw0NyA0N2E2IDYgMCAwMDkgMGw3LThjMy0yIDMtNiAwLTlsLTQ2LTQ2Yy0yLTItMy0yLTUtMnoiLz48L3N2Zz4=)](https://renovatebot.com) +[![pre-commit](https://img.shields.io/badge/%E2%9A%93%20%20pre--commit-enabled-success)](https://pre-commit.com/) -Toolkit to create simple Terminal UIs using plain bash builtins +

+ +
+ Toolkit to create interactive and shiny terminal UIs using plain bash builtins +

-## Goals +## Features + +- clean and standardized API - provide a simple and clear default set of elements to use creating an interactive terminal UI -- be clean and minimalistic +- clean and minimalistic design - zero dependencies to be installed -- parts can be used separately +- parts can be used modular -## Install -1. Download the bundle (entire lib) or single compoennt from [releases](https://github.com/timo-reymann/bash-tui-toolkit/releases) +## Requirements + +- [bash 3+](https://www.gnu.org/software/bash/) + +## Installation + +1. Download the bundle (entire lib) or single compoennt + from [releases](https://github.com/timo-reymann/bash-tui-toolkit/releases) 2. Source the bundle in your script or embed -## Documentation +## Usage + For a list of available modules and their documentation please check the [docs/modules](./docs/modules) folder -## Tested with +For a complete playground demo check [test.sh](./test.sh). -> Since there are some weird combinations/side effects based on the platform you might use there are different side effects that might occur -> -> If you use it on a different platform successfully please create a PR to add a item here :) +## Motivation -| OS | Version of OS | Terminal emulator | Bash Major Version | Works -| :------ | :------------ | :---------------- | :----------------- | :----- -| Ubuntu | 20 | Tilix | 4 | ✔️ -| Ubuntu | 20 | xterm | 4 | ✔️ -| Ubuntu | 22 | Tilix | 5 | ✔️ -| Alpine | 3 | n/a | 5 | ✔️ -| MacOS | Monterey | iTerm | 3 | ✔️ -| MacOS | Monterey | iTerm2 | 3 | ✔️ -| Windows | 10 | Windows Terminal | 4 | ✔️ -| Windows | 10 | Git Bash | 4 | ✔️ -| Windows | 10 | Hyper | 4 | ✔️ +Providing a clean bash UI sometimes becomes a mess and interactivity is hard to achieve especially when it should be +portable. - +The target is to provide a simple-to-use toolkit that can be dropped into any bash script and is compatible no matter +the target system. + +## Documentation + +- [Modules](./docs/modules) - Modules available and their usage +- [Compability table](./docs/Compability.md) - Known combinations of OS/Bash Version/Terminal emulators that work guaranteed + +## Contributing + +I love your input! I want to make contributing to this project as easy and transparent as possible, whether it's: + +- Reporting a bug +- Discussing the current state of the configuration +- Submitting a fix +- Proposing new features +- Becoming a maintainer + +To get started please read the [Contribution Guidelines](./CONTRIBUTING.md). ## Development ### Requirements -- bash 3+ -- docker 19+ -- GNU make -## Generate documentation +- [GNU make](https://www.gnu.org/software/make/) +- [Docker](https://docs.docker.com/get-docker/) +- [pre-commit](https://pre-commit.com/) + +### Build + +``` +make build +``` + +### Update documentation + To update the module documentation you just need to run ```sh @@ -58,16 +86,13 @@ make generate-docs This builds the documentation inside a docker container and updates the repo locally. Afterwards just commit the docs with your code changes -## Build -To combine the script(s) you just need to run -```sh -make build -``` +## Credits -The combined artifacts can be found in `dist/` +- Logo + - Bash logo from [pngegg](https://www.pngegg.com/en/png-pxpgu) + - Toolbox logo from [IconExperience.com](https://www.iconexperience.com/g_collection/icons/?icon=toolbox) ## Alternatives - [kahkhang/Inquirer.sh](https://github.com/kahkhang/Inquirer.sh) - List, Checkbox and Text Input with more advanced validation - diff --git a/docs/Compability.md b/docs/Compability.md new file mode 100644 index 0000000..52124c7 --- /dev/null +++ b/docs/Compability.md @@ -0,0 +1,23 @@ +Compability +=== + +The toolkit is known to work with the following platforms listed below. + +If you feel like an important one is missing feel free to create an issue or PR directly for the file. + +> Since there are some weird combinations/side effects based on the platform you might use there are different side +> effects that might occur +> +> If you use it on a different platform successfully please create a PR to add a item here :) + +| OS | Version of OS | Terminal emulator | Bash Major Version | Works +|:--------|:--------------|:------------------|:-------------------|:------ +| Ubuntu | 20 | Tilix | 4 | ✔️ +| Ubuntu | 20 | xterm | 4 | ✔️ +| Ubuntu | 22 | Tilix | 5 | ✔️ +| Alpine | 3 | n/a | 5 | ✔️ +| MacOS | Monterey | iTerm | 3 | ✔️ +| MacOS | Monterey | iTerm2 | 3 | ✔️ +| Windows | 10 | Windows Terminal | 4 | ✔️ +| Windows | 10 | Git Bash | 4 | ✔️ +| Windows | 10 | Hyper | 4 | ✔️