diff --git a/1.8.4/docs/docs/Compatibility.md b/1.8.4/docs/docs/Compatibility.md new file mode 100644 index 0000000..006dd14 --- /dev/null +++ b/1.8.4/docs/docs/Compatibility.md @@ -0,0 +1,30 @@ +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 | ✔️ +| Ubuntu | 24 | Tilix | 5 | ✔️ +| Ubuntu | 24 | Ghostty | 5 | ✔️ +| Alpine | 3 | n/a | 5 | ✔️ +| MacOS | Monterey | iTerm | 3 | ✔️ +| MacOS | Monterey | iTerm2 | 3 | ✔️ +| MacOS | Sequoia | iTerm | 3 | ✔️ +| MacOS | Sequoia | iTerm2 | 5 | ✔️ +| MacOS | Sequoia | Ghostty | 5 | ✔️ +| Windows | 10 | Windows Terminal | 4 | ✔️ +| Windows | 10 | Git Bash | 4 | ✔️ +| Windows | 10 | Hyper | 4 | ✔️ +| Windows | 11 | Git Bash | 4 | ✔️ +| Windows | 11 | Windows Terminal | 4 | ✔️ diff --git a/1.8.4/docs/docs/README.md b/1.8.4/docs/docs/README.md new file mode 120000 index 0000000..e892330 --- /dev/null +++ b/1.8.4/docs/docs/README.md @@ -0,0 +1 @@ +docs/index.md \ No newline at end of file diff --git a/1.8.4/docs/docs/index.md b/1.8.4/docs/docs/index.md new file mode 100644 index 0000000..5dee5d3 --- /dev/null +++ b/1.8.4/docs/docs/index.md @@ -0,0 +1,13 @@ +bash-tui-toolkit +=== + +Toolkit to create interactive and shiny terminal UIs using plain bash builtins + +## Contents + +- [Compatibility](./Compatibility) +- Available Modules + - [Logging](./modules/Logging.md) + - [Platform Helpers](./modules/Platform-Helpers.md) + - [Prompts](./modules/Prompts.md) + - [User Feedback](./modules/User-Feedback.md) \ No newline at end of file diff --git a/1.8.4/docs/docs/modules/Logging.md b/1.8.4/docs/docs/modules/Logging.md new file mode 100755 index 0000000..d4ad87d --- /dev/null +++ b/1.8.4/docs/docs/modules/Logging.md @@ -0,0 +1,59 @@ +# Logging + +Provide logging helpers for structured logging + +## Overview + +Parse log level from text representation to level number + +## Index + +* [parse_log_level](#parse_log_level) +* [log](#log) + +### parse_log_level + +Parse log level from text representation to level number + +#### Example + +```bash +# Parse lower case log level +parse_log_level "info" +# Parse upper case log level +parse_log_level "ERROR" +``` + +#### Arguments + +* **$1** (string): Log level to parse + +#### Variables set + +* **LOG_LEVEL** (the): global log level to use in the script + +#### Output on stdout + +* numeric log level + +### log + +Log output on a given level, checks if $LOG_LEVEL, if not set defaults to INFO + +#### Example + +```bash +# Log a message on info level +log "$LOG_INFO" "this is a info message" +log "LOG_DEBUG" "i am only visible when \$LOG_LEVEL is debug" +``` + +#### Arguments + +* **$1** (number): Numeric log level +* **$2** (string): Message to output + +#### Output on stdout + +* Formatted log message with ANSI color codes + diff --git a/1.8.4/docs/docs/modules/Platform-Helpers.md b/1.8.4/docs/docs/modules/Platform-Helpers.md new file mode 100755 index 0000000..eed35fd --- /dev/null +++ b/1.8.4/docs/docs/modules/Platform-Helpers.md @@ -0,0 +1,47 @@ +# Platform-Helpers + +Platform specific helpers + +## Overview + +Detect the OS the script is running on + +## Index + +* [detect_os](#detect_os) +* [get_opener](#get_opener) +* [open_link](#open_link) + +### detect_os + +Detect the OS the script is running on + +#### Output on stdout + +* solaris | macos | linux | bsd | windows | unknown + +### get_opener + +Get opener command for platform + +#### Output on stdout + +* Command that can be used, if it is not supported returns an empty string + +### open_link + +Open a link using the default opener, if it is not possible/supported or an error occurs simply prints the url with instructions + +#### Arguments + +* **$1** (Link): to open + +#### Exit codes + +* **1**: Failed to open link +* **0**: Opened link using util + +#### Output on stdout + +* Instructions in case link can not be opened + diff --git a/1.8.4/docs/docs/modules/Prompts.md b/1.8.4/docs/docs/modules/Prompts.md new file mode 100644 index 0000000..d594d53 --- /dev/null +++ b/1.8.4/docs/docs/modules/Prompts.md @@ -0,0 +1,219 @@ +# Prompts + +Inquirer.js inspired prompts + +## Overview + +Prompt for text + +## Index + +* [input](#input) +* [confirm](#confirm) +* [list](#list) +* [checkbox](#checkbox) +* [password](#password) +* [editor](#editor) +* [with_validate](#with_validate) +* [range](#range) +* [validate_present](#validate_present) + +### input + +Prompt for text + +#### Example + +```bash +# Raw input without validation +text=$(input "Please enter something and confirm with enter") +# Input with validation +text=$(with_validate 'input "Please enter at least one character and confirm with enter"' validate_present) +``` + +#### Arguments + +* **$1** (string): Phrase for prompting to text + +#### Output on stdout + +* Text as provided by user + +### confirm + +Show confirm dialog for yes/no + +#### Example + +```bash +confirmed=$(confirm "Should it be?") +if [ "$confirmed" = "0" ]; then echo "No?"; else echo "Yes!"; fi +``` + +#### Arguments + +* **$1** (string): Phrase for promptint to text + +#### Output on stdout + +* 0 for no, 1 for yes + +### list + +Renders a text based list of options that can be selected by the +user using up, down and enter keys and returns the chosen option. +Inspired by https://unix.stackexchange.com/questions/146570/arrow-key-enter-menu/415155#415155 + +#### Example + +```bash +options=("one" "two" "three" "four") +option=$(list "Select one item" "${options[@]}") +echo "Your choice: ${options[$option]}" +``` + +#### Arguments + +* **$1** (string): Phrase for promptint to text +* **$2** (array): List of options (max 256) + +#### Output on stdout + +* selected index (0 for opt1, 1 for opt2 ...) + +### checkbox + +Render a text based list of options, where multiple can be selected by the +user using up, down and enter keys and returns the chosen option. +Inspired by https://unix.stackexchange.com/questions/146570/arrow-key-enter-menu/415155#415155 + +#### Example + +```bash +options=("one" "two" "three" "four") +checked=$(checkbox "Select one or more items" "${options[@]}") +echo "Your choices: ${checked}" +``` + +#### Arguments + +* **$1** (string): Phrase for promptint to text +* **$2** (array): List of options (max 256) + +#### Output on stdout + +* selected index (0 for opt1, 1 for opt2 ...) + +### password + +Show password prompt displaying stars for each password character letter typed +it also allows deleting input + +#### Example + +```bash +# Password prompt with custom validation +validate_password() { if [ ${#1} -lt 10 ];then echo "Password needs to be at least 10 characters"; exit 1; fi } +pass=$(with_validate 'password "Enter random password"' validate_password) +# Password ith no validation +pass=$(password "Enter password to use") +``` + +#### Arguments + +* **$1** (string): Phrase for prompting to text + +#### Output on stdout + +* password as written by user + +### editor + +Open default editor ($EDITOR) if none is set falls back to vi + +#### Example + +```bash +# Open default editor +text=$(editor "Please enter something in the editor") +echo -e "You wrote:\n${text}" +``` + +#### Arguments + +* **$1** (string): Phrase for promptint to text + +#### Output on stdout + +* Text as input by user in input + +### with_validate + +Evaluate prompt command with validation, this prompts the user for input till the validation function +returns with 0 + +#### Example + +```bash +# Using builtin is present validator +text=$(with_validate 'input "Please enter something and confirm with enter"' validate_present) +# Using custom validator e.g. for password +validate_password() { if [ ${#1} -lt 10 ];then echo "Password needs to be at least 10 characters"; exit 1; fi } +pass=$(with_validate 'password "Enter random password"' validate_password) +``` + +#### Arguments + +* **$1** (string): Prompt command to evaluate until validation is successful +* **$2** (function): validation callback (this is called once for exit code and once for status code) + +#### Output on stdout + +* Value collected by evaluating prompt + +### range + +Display a range dialog that can incremented and decremented using the arrow keys + +#### Example + +```bash +# Range with negative min value +value=$(range -5 0 5) +``` + +#### Arguments + +* **$1** (string): Phrase for prompting to text +* **$2** (int): Minimum selectable value +* **$3** (int): Default selected value +* **$4** (int): Maximum value of the select + +#### Output on stdout + +* Selected value using arrow keys + +### validate_present + +Validate a prompt returned any value + +#### Example + +```bash +# text input with validation +text=$(with_validate 'input "Please enter something and confirm with enter"' validate_present) +``` + +#### Arguments + +* **$1** (value): to validate + +#### Exit codes + +* **0**: String is at least 1 character long +* **1**: There was no input given + +#### Output on stdout + +* error message for user + diff --git a/1.8.4/docs/docs/modules/User-Feedback.md b/1.8.4/docs/docs/modules/User-Feedback.md new file mode 100755 index 0000000..0e0653c --- /dev/null +++ b/1.8.4/docs/docs/modules/User-Feedback.md @@ -0,0 +1,41 @@ +# User-Feedback + +Provides useful colored outputs for user feedback on actions + +## Overview + +Display error message in stderr, prefixed by check emoji + +## Index + +* [show_error](#show_error) +* [show_success](#show_success) + +### show_error + +Display error message in stderr, prefixed by check emoji + +#### Example + +```bash +show_error "Oh snap, that went horribly wrong" +``` + +#### Arguments + +* **$1** (string): Error message to display + +### show_success + +Display success message in stderr, prefixed by cross emoji + +#### Example + +```bash +show_success "There it is! World peace." +``` + +#### Arguments + +* **$1** (string): Success message to display +