Dark-Alex-17/bash-tui-toolkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add examples to documentation

Browse Source
This commit is contained in:
Timo Reymann
2023-02-15 18:12:31 +01:00
parent 9de87a6acd
commit 294cfb1b58
6 changed files with 176 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/modules/Logging.md
+21
View File
@@ -15,10 +15,23 @@ Parse log level from text representation to level number
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
@@ -27,6 +40,14 @@ Parse log level from text representation to level number
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
docs/modules/Prompts.md
+74 -2
View File
@@ -21,9 +21,18 @@ Prompt for text
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 promptint to text
* **$1** (string): Phrase for prompting to text
#### Output on stdout
@@ -33,6 +42,13 @@ Prompt for text
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
@@ -47,6 +63,14 @@ 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
@@ -62,6 +86,14 @@ 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
@@ -76,6 +108,16 @@ Inspired by https://unix.stackexchange.com/questions/146570/arrow-key-enter-menu
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 promptint to text
@@ -86,7 +128,15 @@ it also allows deleting input
### editor
Open default 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
@@ -101,6 +151,16 @@ Open default editor
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
@@ -114,10 +174,22 @@ returns with 0
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
docs/modules/User-Feedback.md
+12
View File
@@ -15,6 +15,12 @@ Display error message in stderr, prefixed by check emoji
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
@@ -23,6 +29,12 @@ Display error message in stderr, prefixed by check emoji
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
src/logging.sh
+19 -5
View File
@@ -12,22 +12,36 @@ LOG_DEBUG=0
#
# @arg $1 string Log level to parse
# @stdout numeric log level
# @set LOG_LEVEL the global log level to use in the script
# @example
# # Parse lower case log level
# parse_log_level "info"
# @example
# # Parse upper case log level
# parse_log_level "ERROR"
parse_log_level() {
local level="$1"
local parsed
case "${level}" in
info | INFO) echo $LOG_INFO; ;;
debug | DEBUG) echo $LOG_DEBUG; ;;
warn | WARN) echo $LOG_WARN; ;;
error | ERROR) echo $LOG_ERROR; ;;
*) echo -1; ;;
info | INFO) parsed=$LOG_INFO; ;;
debug | DEBUG) parsed=$LOG_DEBUG; ;;
warn | WARN) parsed=$LOG_WARN; ;;
error | ERROR) parsed=$LOG_ERROR; ;;
*) parsed=-1; ;;
esac
export LOG_LEVEL="${parsed}"
}
# @description Log output on a given level, checks if $LOG_LEVEL, if not set defaults to INFO
# @arg $1 number Numeric log level
# @arg $2 string Message to output
# @stdout Formatted log message with ANSI color codes
# @example
# # 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"
log() {
local level="$1"
local message="$2"
src/prompts.sh
+46 -4
View File
@@ -63,9 +63,15 @@ _contains() {
}
# @description Prompt for text
# @arg $1 string Phrase for promptint to text
# @stdout Text as provided by user
# @arg $1 string Phrase for prompting to text
# @stderr Instructions for user
# @stdout Text as provided by user
# @example
# # Raw input without validation
# text=$(input "Please enter something and confirm with enter")
# @example
# # Input with validation
# text=$(with_validate 'input "Please enter at least one character and confirm with enter"' validate_present)
input() {
_prompt_text "$1"; echo -en "\e[36m\c" >&2
read -r text
@@ -76,6 +82,9 @@ input() {
# @arg $1 string Phrase for promptint to text
# @stdout 0 for no, 1 for yes
# @stderr Instructions for user
# @example
# confirmed=$(confirm "Should it be?")
# if [ "$confirmed" = "0" ]; then echo "No?"; else echo "Yes!"; fi
confirm() {
_prompt_text "$1 (y/N)"
echo -en "\e[36m\c " >&2
@@ -104,6 +113,10 @@ confirm() {
# @arg $2 array List of options (max 256)
# @stdout selected index (0 for opt1, 1 for opt2 ...)
# @stderr Instructions for user
# @example
# options=("one" "two" "three" "four")
# option=$(list "Select one item" "${options[@]}")
# echo "Your choice: ${options[$option]}"
list() {
_prompt_text "$1 "
@@ -141,11 +154,13 @@ list() {
esac
done
echo -en "\n"
# cursor position back to normal
_cursor_to "${lastrow}"
_cursor_blink_on
echo "${selected}"
echo "${selected}"
}
# @description Render a text based list of options, where multiple can be selected by the
@@ -155,6 +170,10 @@ list() {
# @arg $2 array List of options (max 256)
# @stdout selected index (0 for opt1, 1 for opt2 ...)
# @stderr Instructions for user
# @example
# options=("one" "two" "three" "four")
# checked=$(checkbox "Select one or more items" "${options[@]}")
# echo "Your choices: ${checked}"
checkbox() {
_prompt_text "$1"
local opts; opts=("${@:2}")
@@ -217,6 +236,13 @@ checkbox() {
# @arg $1 string Phrase for promptint to text
# @stdout password as written by user
# @stderr Instructions for user
# @example
# # 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)
# @example
# # Password ith no validation
# pass=$(password "Enter password to use")
password() {
_prompt_text "$1"
echo -en "\e[36m" >&2
@@ -240,10 +266,14 @@ password() {
echo "${password}"
}
# @description Open default editor
# @description Open default editor ($EDITOR) if none is set falls back to vi
# @arg $1 string Phrase for promptint to text
# @stdout Text as input by user in input
# @stderr Instructions for user
# @example
# # Open default editor
# text=$(editor "Please enter something in the editor")
# echo -e "You wrote:\n${text}"
editor() {
tmpfile=$(mktemp)
_prompt_text "$1"
@@ -264,6 +294,13 @@ editor() {
# @arg #2 function validation callback (this is called once for exit code and once for status code)
# @stdout Value collected by evaluating prompt
# @stderr Instructions for user
# @example
# # Using builtin is present validator
# text=$(with_validate 'input "Please enter something and confirm with enter"' validate_present)
# @example
# # 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)
with_validate() {
while true; do
local val; val="$(eval "$1")"
@@ -279,6 +316,11 @@ with_validate() {
# @description Validate a prompt returned any value
# @arg $1 value to validate
# @stdout error message for user
# @exitcode 0 String is at least 1 character long
# @exitcode 1 There was no input given
# @example
# # text input with validation
# text=$(with_validate 'input "Please enter something and confirm with enter"' validate_present)
validate_present() {
if [ "$1" != "" ]; then return 0; else echo "Please specify the value"; return 1; fi
}
src/user_feedback.sh
+4
View File
@@ -4,12 +4,16 @@
# @description Display error message in stderr, prefixed by check emoji
# @arg $1 string Error message to display
# @example
# show_error "Oh snap, that went horribly wrong"
show_error() {
echo -e "\e[91;1m\u2718 $1" >&2
}
# @description Display success message in stderr, prefixed by cross emoji
# @arg $1 string Success message to display
# @example
# show_success "There it is! World peace."
show_success() {
echo -e "\e[92;1m\u2714 $1" >&2
}