From 294cfb1b583eebb8fe4e861aed8bc63bcc255c67 Mon Sep 17 00:00:00 2001 From: Timo Reymann Date: Wed, 15 Feb 2023 18:12:31 +0100 Subject: [PATCH] docs: Add examples to documentation --- docs/modules/Logging.md | 21 ++++++++++ docs/modules/Prompts.md | 76 ++++++++++++++++++++++++++++++++++- docs/modules/User-Feedback.md | 12 ++++++ src/logging.sh | 24 ++++++++--- src/prompts.sh | 50 +++++++++++++++++++++-- src/user_feedback.sh | 4 ++ 6 files changed, 176 insertions(+), 11 deletions(-) diff --git a/docs/modules/Logging.md b/docs/modules/Logging.md index 44853fe..d4ad87d 100644 --- a/docs/modules/Logging.md +++ b/docs/modules/Logging.md @@ -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 diff --git a/docs/modules/Prompts.md b/docs/modules/Prompts.md index f208b44..611250b 100644 --- a/docs/modules/Prompts.md +++ b/docs/modules/Prompts.md @@ -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 diff --git a/docs/modules/User-Feedback.md b/docs/modules/User-Feedback.md index a953179..0e0653c 100644 --- a/docs/modules/User-Feedback.md +++ b/docs/modules/User-Feedback.md @@ -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 diff --git a/src/logging.sh b/src/logging.sh index bc65b3e..d05da97 100644 --- a/src/logging.sh +++ b/src/logging.sh @@ -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" diff --git a/src/prompts.sh b/src/prompts.sh index c26ddfe..9772401 100644 --- a/src/prompts.sh +++ b/src/prompts.sh @@ -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 } diff --git a/src/user_feedback.sh b/src/user_feedback.sh index e26d8f3..bfdfee8 100644 --- a/src/user_feedback.sh +++ b/src/user_feedback.sh @@ -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 }