ask/choose/confirm: complete no-TTY support

/close #253

- shellcheckrc: add `SC2059`, and add docs on all the disabled rules
- ask: rewrote for modern conventions, support no-TTY, fix read failures not being output
- ask/choose/confirm: consistent commentary styling
- choose: fix blockquote line being a different color or breaking colors
- confirm: fix and improve the WIP no-TTY support, now complete
- dorothy: prompt for lint upgrade before dev deps, to speed up UX
- echo-clear-lines: rewrote to support all known edge cases
- echo-count-lines: add note that it doesn't wrap
- echo-escape-command: use new `__quote` helped in `bash.bash` to support ANSI Escape Codes
- echo-quote: add tests, add support for `--single` and `--double` arguments
- echo-regexp(.ts)?: better support for character classes, supporting `[[:XXX:]]` and `[:XXX:]` forms
- echo-revolving-door: rewrote to support all known edge cases
- added `echo-substr`: as command alias for `__substr` helper in `bash.bash`
- echo-wrap: fix help errors not showing, support --column=* alias for --width=*
- eval-helper: updated for TTY changes, aand fix all known edge cases
- expand-path.zsh: same functionality, but rewrote for clarity
- setup-util: linting, and only output the output if there is output
- setup-util-bash: compact `echo-style` calls for performance, include `setup-util --check` for performance
- until-success: rewrote for new TTY conventions
- echo-escape-special: fix everything being dumped together
- is-shapeshifter: rewrote and add tests, to fix all known edge cases, and now uses `bash.bash` helpers
- bash.bash:
    - remove deprecated usage of `__print_line ...` use `__print_lines ...` instead
    - support initial `--` argument in appropriate functions
    - rewrite to use [[ ... ]] instead of test/[ to better handle edge cases
- stdinargs.bash:
    - rewrite to use [[ ... ]] instead of test/[ to better handle edge cases, such as a trailing line containing only `>`
- zsh.zsh:
    - consistency with `bash.bash` changes
    - rewrote and fixed `__substr` helper for edge cases
    - added `is_shapeshifter` and `__escape_shapeshifting` helpers, used in `is-shapeshifter`
- ansi-escape-codes.md: removed excess docs

todos:

- decide if ask/choose/confirm linger should be outputted to stderr if there is commentary and a sucess code but no linger, check if consistent with choose
- setup-util: consider new wrapper for the font selection too

.trunk/configs/.shellcheckrc

@@ -1,4 +1,15 @@
 # https://github.com/trunk-io/configs
 enable=all
 source-path=SCRIPTDIR
-disable=SC2154,SC2164,SC2250,SC2310,SC2249,SC2312,SC1090,SC1091,SC2317,SC2016
+disable=SC2154,SC2164,SC2250,SC2310,SC2249,SC2312,SC1090,SC1091,SC2317,SC2016,SC2059
+# https://www.shellcheck.net/wiki/SC2154 var is referenced but not assigned.
+# https://www.shellcheck.net/wiki/SC2164 Use cd ... || exit in case cd fails.
+# https://www.shellcheck.net/wiki/SC2250 Prefer putting braces around variable references even when not strictly required.
+# https://www.shellcheck.net/wiki/SC2310 This function is invoked in an 'if' condition so set -e will be disabled. Invoke separately if failures should cause the script to exit.
+# https://www.shellcheck.net/wiki/SC2249 Consider adding a default *) case, even if it just exits with error.
+# https://www.shellcheck.net/wiki/SC2312 Consider invoking this command separately to avoid masking its return value (or use '|| true' to ignore).
+# https://www.shellcheck.net/wiki/SC1090 Can't follow non-constant source. Use a directive to specify location
+# https://www.shellcheck.net/wiki/SC1091 Not following: (error message here)
+# https://www.shellcheck.net/wiki/SC2317 Command appears to be unreachable. Check usage (or ignore if invoked indirectly).
+# https://www.shellcheck.net/wiki/SC2016 Expressions don't expand in single quotes, use double quotes for that.
+# https://www.shellcheck.net/wiki/SC2059 Don't use variables in the printf format string. Use printf "..%s.." "$foo".

commands.beta/echo-escape-special

@@ -35,7 +35,7 @@ function echo_escape_special() (
 	}
 
 	function on_input {
-		printf '%q' "$1"
+		printf '%q\n' "$1"
 	}
 
 	stdinargs "$@"

commands.beta/echo-revolving-screen

@@ -91,7 +91,6 @@ function echo_revolving_screen() (
 			fi
 		done
 		# we are now done, so clear wrapped
-		# echo-clear-lines --count="$lines" >"$terminal_device_file"
 		__print_string "${clear_screen}" >"$terminal_device_file"
 	fi
 )

commands.beta/is-shapeshifter

@@ -1,5 +1,145 @@
 #!/usr/bin/env bash
 
+function is_shapeshifter_test() (
+	source "$DOROTHY/sources/bash.bash"
+	echo-style --h1="TEST: $0"
+
+	local input inputs=(
+		# read-key
+		$'\e[A'    # up
+		$'\eM'     # up
+		$'\e[B'    # down
+		$'\e[C'    # right
+		$'\e[D'    # left
+		$'\e[H'    # home
+		$'\e[1~'   # home
+		$'\e[1;2D' # home
+		$'\r'      # carriage-return
+		$'\e[F'    # end
+		$'\e[4~'   # end
+		$'\e[1;2C' # end
+		$'\e[2~'   # insert
+		$'\e[3~'   # delete
+		$'\e[5~'   # page-up
+		$'\e[6~'   # page-down
+		$'\177'    # backspace
+		$'\b'      # backspace
+		# $'\n' # enter <-- don't do enter, as that is normal
+		# $'\t' # tab <-- don't do tab, as that is normal
+		$'\e[Z' # backtab
+
+		# styles.bash
+		$'\e[?1049h' # Default Screen Buffer
+		$'\e[?1049l' # Alternative Screen Buffer
+
+		# ansi escape codes
+		# https://terminals-wiki.org/wiki/index.php/CodeChart:ANSI/ESC/CSI
+		$'\e[A'    # Cursor Up
+		$'\e[0A'   # Cursor Up
+		$'\e[B'    # Cursor Down
+		$'\e[0B'   # Cursor Down
+		$'\e[C'    # Cursor Forward
+		$'\e[0C'   # Cursor Forward
+		$'\e[D'    # Cursor Back
+		$'\e[0D'   # Cursor Back
+		$'\e[E'    # Cursor Next Line
+		$'\e[0E'   # Cursor Next Line
+		$'\e[F'    # Cursor Previous Line
+		$'\e[0F'   # Cursor Previous Line
+		$'\e[G'    # Cursor Horizontal Absolute
+		$'\e[0G'   # Cursor Horizontal Absolute
+		$'\e[H'    # Cursor Position
+		$'\e[0H'   # Cursor Position
+		$'\e[0;H'  # Cursor Position
+		$'\e[0;0H' # Cursor Position
+		$'\e[I'    # Cursor Horizontal Tab
+		$'\e[0I'   # Cursor Horizontal Tab
+		$'\e[J'    # Erase Display
+		$'\e[0J'   # Erase Display
+		$'\e[K'    # Erase Line
+		$'\e[0K'   # Erase Line
+		$'\e[L'    # Insert Line
+		$'\e[0L'   # Insert Line
+		$'\e[M'    # Delete Line
+		$'\e[0M'   # Delete Line
+		$'\e[N'    # Erase Field
+		$'\e[0N'   # Erase Field
+		$'\e[O'    # Erase Area
+		$'\e[0O'   # Erase Area
+		$'\e[P'    # Delete Character
+		$'\e[0P'   # Delete Character
+		$'\e[Q'    # Select Editing Extent
+		$'\e[0Q'   # Select Editing Extent
+		$'\e[S'    # Scroll Up
+		$'\e[0S'   # Scroll Up
+		$'\e[T'    # Scroll Down
+		$'\e[0T'   # Scroll Down
+		$'\e[U'    # Next Page
+		$'\e[0U'   # Next Page
+		$'\e[V'    # Previous Page
+		$'\e[0V'   # Previous Page
+		$'\e[W'    # Cursor Tabulation Control
+		$'\e[0W'   # Cursor Tabulation Control
+		$'\e[X'    # Erase Character
+		$'\e[0X'   # Erase Character
+		$'\e[Y'    # Cursor Vertical Tab
+		$'\e[0Y'   # Cursor Vertical Tab
+		$'\e[Z'    # Cursor Backward Tab
+		$'\e[0Z'   # Cursor Backward Tab
+		$'\e[`'    # Horizontal Position Absolute
+		$'\e[0`'   # Horizontal Position Absolute
+		$'\e[a'    # Horizontal Position Right
+		$'\e[0a'   # Horizontal Position Right
+		$'\e[b'    # Repeat
+		$'\e[0b'   # Repeat
+		$'\e[c'    # Device Attributes
+		$'\e[0c'   # Device Attributes
+		$'\e[d'    # Vertical Position Absolute
+		$'\e[0d'   # Vertical Position Absolute
+		$'\e[e'    # Vertical Position Right
+		$'\e[0e'   # Vertical Position Right
+		$'\e[f'    # Horizontal Vertical Position
+		$'\e[0f'   # Horizontal Vertical Position
+		$'\e[g'    # Tabulation Clear
+		$'\e[0g'   # Tabulation Clear
+		$'\e[h'    # Set Mode
+		$'\e[0h'   # Set Mode
+		$'\e[i'    # Media Copy
+		$'\e[0i'   # Media Copy
+		$'\e[j'    # Horizontal Position Backward
+		$'\e[0j'   # Horizontal Position Backward
+		$'\e[k'    # Vertical Position Backward
+		$'\e[0k'   # Vertical Position Backward
+		$'\e[l'    # Reset Mode
+		$'\e[0l'   # Reset Mode
+		#$'\e[m' # Select Graphic Rendition <-- don't do this, as it is just colors
+		#$'\e[0m' # Select Graphic Rendition <-- don't do this, as it is just colors
+		$'\e[n'  # Device Status Report
+		$'\e[0n' # Device Status Report
+		$'\e[o'  # Define Area Qualifications
+		$'\e[0o' # Define Area Qualifications
+		# $'\e['    # Start Reversed String <-- don't do this, as it cannot be isolated
+		$'\e[0['  # Start Reversed String
+		$'\e\\'   # Parallel Texts
+		$'\e[0\\' # Parallel Texts
+		$'\e]'    # Start Directed String
+		$'\e[0]'  # Start Directed String
+		$'\e^'    # Select Implicit Movement Direction
+		$'\e[0^'  # Select Implicit Movement Direction
+
+		# https://www.gnu.org/software/screen/manual/html_node/Control-Sequences.html
+		$'\e7'  # Save Cursor
+		$'\e[s' # Save Cursor
+		$'\e8'  # Restore Cursor
+		$'\e[u' # Restore Cursor
+	)
+
+	eval-tester --status=1 -- is-shapeshifter -- "blah" "0123" $'\e[0m'
+	eval-tester --status=0 -- is-shapeshifter -- "${inputs[@]}"
+
+	echo-style --g1="TEST: $0"
+	return 0
+)
 function is_shapeshifter() (
 	source "$DOROTHY/sources/stdinargs.bash"
 
@@ -24,26 +164,64 @@ function is_shapeshifter() (
 		return 22 # EINVAL 22 Invalid argument
 	}
 
+	# process our own arguments, delegate everything else to stdinargs
+	local item option_quiet='yes' option_args=()
+	while test "$#" -ne 0; do
+		item="$1"
+		shift
+		case "$item" in
+		'--help' | '-h') help ;;
+		'--no-verbose'* | '--verbose'*)
+			option_quiet="$(get-flag-value --non-affirmative --fallback="$option_quiet" -- "$item")"
+			;;
+		'--no-quiet'* | '--quiet'*)
+			option_quiet="$(get-flag-value --affirmative --fallback="$option_quiet" -- "$item")"
+			;;
+		# forward to stdinargs, however support mixing and matching of our options, with stdinarg options
+		'--')
+			option_args+=("$item" "$@")
+			shift $#
+			break
+			;;
+		*) option_args+=("$item") ;;
+		esac
+	done
+
 	# =====================================
 	# Action
 
 	local found='no'
-	function on_input {
-		local line="$1"
-		# regexp should match [echo-clear-lines] [echo-revolving-door] [is-shapeshifter]
-		if [[ $line =~ $'\e\[[0-9]*[AKGFJ]' ]]; then
-			found='yes'
-			return 210 # ECUSTOM 210 Processing complete, exit early
-		fi
-	}
+	if test "$option_quiet" = 'yes'; then
+		function on_input {
+			local input="$1"
+			if __is_shapeshifter -- "$input"; then
+				found='yes'
+				return 210 # ECUSTOM 210 Processing complete, exit early
+			fi
+		}
+	else
+		function on_input {
+			local input="$1"
+			if __is_shapeshifter -- "$input"; then
+				found='yes'
+				printf '%s %q\n' 'yes:' "$input" >/dev/stderr
+			else
+				printf '%s %q\n' 'no:' "$input" >/dev/stderr
+			fi
+		}
+	fi
 	function on_finish {
 		test "$found" = 'yes'
 	}
 
-	stdinargs "$@"
+	stdinargs "${option_args[@]}"
 )
 
 # fire if invoked standalone
 if test "$0" = "${BASH_SOURCE[0]}"; then
-	is_shapeshifter "$@"
+	if test "$*" = '--test'; then
+		is_shapeshifter_test
+	else
+		is_shapeshifter "$@"
+	fi
 fi