docs: Add examples to documentation

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

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

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

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; ;;
+      info | INFO)   parsed=$LOG_INFO; ;;
-      debug | DEBUG) echo $LOG_DEBUG; ;;
+      debug | DEBUG) parsed=$LOG_DEBUG; ;;
-      warn | WARN)   echo $LOG_WARN; ;;
+      warn | WARN)   parsed=$LOG_WARN; ;;
-      error | ERROR) echo $LOG_ERROR; ;;
+      error | ERROR) parsed=$LOG_ERROR; ;;
-      *)             echo -1; ;;
+      *)             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

@@ -63,9 +63,15 @@ _contains() {
 }
 
 # @description Prompt for text
-# @arg $1 string Phrase for promptint to text
+# @arg $1 string Phrase for prompting to text
-# @stdout Text as provided by user
 # @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,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
 }