fs-* command consistency

todos:

- choose: needs truncating of choose body, if too long, possible with `fs-rm` and `fs-trim` with large directory content listing: `eza -lA | sed -e '5,$d' -e '4,$s/.*/Truncated./'` is suitable, however our own command would work
- eval-helper: check if pending/success/failure messages are still going to TTY
- is-not-symlink: update copy and pasted tests to match its functionality
- consider renames of `echo-exit-affirmative`, `echo-exit-status`, `is-root`

changes:

- choose:
    - optional will now cancel to nothing, only required cancels to defaults
    - can now press R to revert to defaults
- dorothy:
    - permissions action no longer trims junk files, as they are already git-ignored
- `fs-realpath`, `fs-structure`, `fs-trim`, `is-broken-symlink`, `is-directory`, `is-empty-directory`, `is-empty-file`, `is-file`, `is-missing`, `is-not-directory`, `is-not-symlink`, `is-present`, `is-readable`, `is-symlink`, `is-nonempty-file`:
    - support `--(sudo|user|group)` arguments
    - consistent internal structure
    - add tests where appropriate
- `fs-rm`, `fs-trim`, `fs-structure`:
    - rewrote `fs-rm` for new `fs-trim` command, with exact prompts on what to do, no longer overly complex and fragile
    - rewrote `fs-structure` to prefer `exa`, comment out verbose `dust`/`du` handling as `exa` is better and more understandable for this use case, made perms and time toggles
- fs-touch:
    - clarified touch functionality (will make directories, but not files, by default), make `--no-touch` not make directories
- add `fs-trim`:
    - consolidated functionality from: `fs-rm`, `rm-junk`, `rm-modules`
    - clear handling of symlinks
- add `is-broken-symlink`, `is-empty-directory`, `is-empty-file`, `is-not-symlink`, `is-file`, `is-not-symlink`, `is-symlink`:
- is-generic:
    - change return status behaviour on multiple arguments to be consistent with others
- promoted `is-even` from beta commands
- add `setup-util-qpdf` for `pdf-decrypt`, and updated `pdf-decrypt` for modern covnentions
- sudo-helper:
    - add `--[no-]sudo` flag, which if no and no user nor group, then no sudo is needed

fixes:

- choose: pressing escape/q to cancel now works again
- echo-values: fix help text being incorrect
- eval-helper: wrapping will now have wraps go to stdout
- get-terminal-theme: more accurate parsing of `COLORFGBG`
- is-admin: fix multiple users handling
- setup-dns: improve handling of bad interfaces fetch

renames and deprecations:

- `is-nonempty-string` to `is-not-whitespace`
- `is-empty-string` to `is-whitespace`
- `is-empty-ls` to `is-empty-directory`, turns out we had two commands doing the same thing
- `is-dir` to `is-directory`
- `is-either` to `is-needle`, `is-neither` to `! is-needle`
- `echo-if-empty` to `echo-with-whitespace-fallback`, added `echo-with-empty-fallback` for zero-length
- `echo-values` promoted from beta, used within `setup-dns`
- `fs-size` deprecated as it was the same as `fs-structure`; use `fs-structure` or `get-size` instead
- `rm-vmware` to `rm-vmware-fusion`
- `rm-junk` and `rm-modules` to `fs-trim --junk`
- deprecate `is-array-*` and `get-array-*` commands
- deprecate `is-exec`, `is-equal`, `rm-svn`, and `rm-sync` until there is a use case for them

linting:

- down: as `fs-temp` touch usage is now clarified, improve logic around mkdirp call
- fs-filename: use the new options help text format
- get-terminal-color-support: fix return status help text
- remove unnecessary `--status=0` in `eval-tester` calls
- improve wording of return statuses in help text
- improve wording around whether symlinks are considered or not in various commands
- added `Companion to ...` line to improve discovery of (related) commands and their functionality

commands/echo-affirmative → commands.beta/echo-affirmative

@@ -13,7 +13,6 @@ function echo_affirmative() (
 		cat <<-EOF >/dev/stderr
 			ABOUT:
 			For each <input>, output 'yes' if affirmative, 'no' if non-affirmative, otherwise note the invalidity to stderr.
-			Using [is-affirmative] for the validation.
 
 			USAGE:
 			echo-affirmative [...options] [--] ...<input>

commands.beta/echo-exit-affirmative

@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 
+# @should be renamed to eval-then-affirm-status
+
 function echo_exit_affirmative() (
 	source "$DOROTHY/sources/bash.bash"
 

commands.beta/echo-exit-status

@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 
+# @should be renamed to eval-then-echo-status
+
 function echo_exit_status() (
 	source "$DOROTHY/sources/bash.bash"
 

commands.beta/echo-if-directory

@@ -6,7 +6,7 @@ function echo_if_directory() (
 	function help {
 		cat <<-EOF >/dev/stderr
 			ABOUT:
-			Output inputs that are directories.
+			Output inputs that are directories (or symlinks to directories).
 
 			USAGE:
 			echo-if-directory [...options] [---] ...<input>

commands.beta/echo-with-empty-fallback

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+
+function echo_with_empty_fallback() (
+	source "$DOROTHY/sources/stdinargs.bash"
+
+	function help {
+		cat <<-EOF >/dev/stderr
+			ABOUT:
+			Output <fallback> if all <input> is zero-length.
+			Similar to [echo-with-whitespace-fallback], [eval-on-empty-stdin], [eval-on-not-empty-stdin].
+
+			USAGE:
+			echo-with-empty-fallback <fallback> [...options] [--] ...<input>
+			echo-lines ...<input> | echo-with-empty-fallback <fallback> [...options]
+
+			OPTIONS:
+			<fallback> | --fallback=<fallback>
+			    The fallback to use if <input> is empty.
+
+			$(stdinargs_options_help --)
+
+			EXAMPLE:
+
+			echo-with-empty-fallback 'my-fallback-value'
+
+			    my-fallback-value
+			    # exit status: 0
+
+			printf '' | echo-with-empty-fallback 'my-fallback-value'
+
+			    my-fallback-value
+			    # exit status: 0
+
+			printf ' ' | echo-with-empty-fallback 'my-fallback-value' --stdin
+
+			    # exit status: 0
+
+			printf 'value' | echo-with-empty-fallback 'my-fallback-value' --stdin
+
+			    value
+			    # exit status: 0
+		EOF
+		if [[ $# -ne 0 ]]; then
+			echo-error "$@"
+		fi
+		return 22 # EINVAL 22 Invalid argument
+	}
+
+	# process our own arguments, delegate everything else to stdinargs
+	local rand="$RANDOM"
+	local item option_fallback="$rand" option_args=()
+	while [[ $# -ne 0 ]]; do
+		item="$1"
+		shift
+		case "$item" in
+		'--help' | '-h') help ;;
+		'--fallback='*) option_fallback="${item#*=}" ;;
+		# forward to stdinargs, however support mixing and matching of our options, with stdinarg options
+		'--')
+			option_args+=("$item" "$@")
+			shift $#
+			break
+			;;
+		'--'*) option_args+=("$item") ;;
+		*)
+			if [[ $option_fallback == "$rand" ]]; then
+				option_fallback="$item"
+			else
+				option_args+=("$item")
+			fi
+			;;
+		esac
+	done
+
+	# check for expected
+	if [[ $option_fallback == "$rand" ]]; then
+		help 'Missing required argument: <fallback>'
+	fi
+
+	# action
+	local inputs=''
+	function on_inline {
+		inputs+="$1"
+	}
+	function on_line {
+		inputs+="$1"$'\n'
+		return 210 # ECUSTOM 210 Processing complete, exit early
+	}
+	function on_finish {
+		if [[ -z $inputs ]]; then
+			__print_string "$fallback"
+		else
+			__print_string "$inputs"
+		fi
+	}
+	stdinargs "${option_args[@]}"
+)
+
+# fire if invoked standalone
+if [[ $0 == "${BASH_SOURCE[0]}" ]]; then
+	echo_with_empty_fallback "$@"
+fi

commands.beta/echo-if-empty → commands.beta/echo-with-whitespace-fallback

@@ -1,16 +1,17 @@
 #!/usr/bin/env bash
 
-function echo_if_empty() (
+function echo_with_whitespace_fallback() (
 	source "$DOROTHY/sources/stdinargs.bash"
 
 	function help {
 		cat <<-EOF >/dev/stderr
 			ABOUT:
-			Output <fallback> if <input> is empty.
+			Output <fallback> if all <input> is only whitespace.
+			Similar to [echo-with-empty-fallback].
 
 			USAGE:
-			echo-if-empty <fallback> [...options] [--] ...<input>
-			echo-lines ...<input> | echo-if-empty <fallback> [...options]
+			echo-with-whitespace-fallback <fallback> [...options] [--] ...<input>
+			echo-lines ...<input> | echo-with-whitespace-fallback <fallback> [...options]
 
 			OPTIONS:
 			<fallback> | --fallback=<fallback>
@@ -20,23 +21,20 @@ function echo_if_empty() (
 
 			EXAMPLE:
 
-			echo-if-empty 'my-fallback-value'
+			echo-with-whitespace-fallback 'my-fallback-value'
 
 			    my-fallback-value
 			    # exit status: 0
 
-			echo | echo-if-empty 'my-fallback-value' --stdin
+			printf ' \n\t' | echo-with-whitespace-fallback 'my-fallback-value' --stdin
 
 			    my-fallback-value
 			    # exit status: 0
 
-			echo 'a-value' | echo-if-empty 'my-fallback-value' --stdin
+			printf 'value' | echo-with-whitespace-fallback 'my-fallback-value' --stdin
 
-			    'a-value'
+			    value
 			    # exit status: 0
-
-			ALTERNATIVES:
-			Use [ifne] from [moreutils], which is what we use in [eval-on-empty-stdin] and [eval-on-not-empty-stdin].
 		EOF
 		if [[ $# -ne 0 ]]; then
 			echo-error "$@"
@@ -70,9 +68,9 @@ function echo_if_empty() (
 		esac
 	done
 
-	# checck for expected
+	# check for expected
 	if [[ $option_fallback == "$rand" ]]; then
-		help "Missing required argument: <expected>"
+		help 'Missing required argument: <fallback>'
 	fi
 
 	# action
@@ -84,7 +82,7 @@ function echo_if_empty() (
 		inputs+="$1"$'\n'
 	}
 	function on_finish {
-		if is-empty-string -- "$inputs"; then
+		if is-whitespace -- "$inputs"; then
 			__print_string "$fallback"
 		else
 			__print_string "$inputs"
@@ -95,5 +93,5 @@ function echo_if_empty() (
 
 # fire if invoked standalone
 if [[ $0 == "${BASH_SOURCE[0]}" ]]; then
-	echo_if_empty "$@"
+	echo_with_whitespace_fallback "$@"
 fi