modern conventions for all commands/

renames and deletions:
- `is-quiet-enabled` renamed to `echo-quiet-enabled`, and new `is-quiet-enabled` is provided
- `is-color-enabled` renamed to `echo-color-enabled`, and new `is-color-enabled` is provided
- `is-desktop-session` deleted in favor of `is-headful`
- `is-empty-size` moved to `commands.beta/` as it is faulty
- `echo-trim-stdin` renamed to `echo-trim-padding`: support arguments
- `echo-if-nonempty` renamed to `echo-trim-empty-lines`
- `is-needles` deleted as `is-needle` now supports multiple needles
- `is-values` deleted as `is-value` now supports multiple values
- `echo-escape-regex(-replacement)?` renamed to `echo-escape-regexp(-replacement)?`
- `expand-path-bash` deleted, inlined with `expand-path`, and noted case insensitivity inside `expand-path-zsh`
- asset filter renamed to asset regexp, archive/build filter renamed to archive/build glob

other actionable changes:
- all applicable commands now support `--`, you should use it
- get-flag-value now supports `--(non-)affirmative` flags, and optional name argument
- setup-util/setup-util-*: use simpler `setup-util --check` for improving performance
- stdinargs:
    - if `on_(arg|input)` are not provided, then support `on_(in)?line` for arguments
    - support `on_no_lines`
    - support `--max-args=<number>`
    - note that this means empty arguments `''` will not be processed by `on_inline` and `on_line` handlers, this is expected and coincides with stdin behaviour
- echo-(non-|exit-)?-affirmative/(echo|is)-(color|quiet)-enabled: return 91 on invalid values
- echo-clear-lines/echo-revolving-door: reworked to solve issues with multline inputs, long inputs, and problematic cursor positions
- fs-own: merged `--partial` and `--optional` into just `--optional`, optional now also ignores permission failures as expected, and improved performance

notable changes:
- all `commands/*` make use of dorothy argument conventions (including `--help` and `--` support)
- consistent rg/grep arguments, using grep when using `--fixed-strings`
- fix `=~` usage, it is a regular expression
- echo-*: support help errors
- is-*: add help, support dorothy argument conventions, support multiple arguments where applicable
- (is|echo)-(color|quiet)-enabled: support `--fallback=<fallback>` flag, and improved fallback/default handling
- echo-exit-affirmative: support `--fallback=<fallback>`
- dorothy: when testing, output the unsafe function calls, and support running only specific tests
- dorothy: when preparing, fixed creation of unnecessary nested symlinks

other changes:
- fix file permissions
- `dorothy permissions`: fix non-performant file and directory permission fix
- fix readme workflow badge
- more consistent option parsing
- contains-line: support arguments, support multiple needles
- echo-clear-lines: support help and arguments
- echo-count-lines: delegate to new stdinargs on_line handling, disable support for multiple arguments
- added `echo-escape-command`
- added `echo-escape-newlines`
- echo-file: support argument lines
- echo-filesnames: support argument lines
- echo-if-command-exists: support argument lines
- echo-if-file: support argument lines
- echo-lines-after: support multiple needles
- echo-lines-before: support multiple needles
- echo-magnet-hash: support argument lines
- echo-mkdir: support argument lines
- echo-non-affirmative: support argument lines
- echo-nothing-or-fail: support argument lines
- echo-or-fail: support argument lines
- echo-paths-and-basenames: support argument lines
- echo-split: delegate to new stdinargs on_line handling, support multiple needles
- echo-subpaths: support argument lines
- echo-trim-each-line: add tests, support argument lines, fix it not actually working
- echo-trim-special: support argument lines
- echo-trim-zero-length: support argument lines
- echo-url-decode: support argument lines
- echo-url-encode: support argument lines
- eval-helper/eval-tester: escape newlines in wrapping
- expand-path-bash: fix variable leak
- find-directories: support multiple paths
- fs-*: support `--path=<path>` flag
- fs-size: remove faulty size check
- get-app: support multiple apps
- get-array: support `--size=<size>` flag, verify size is integer
- get-devices: fixed trimming
- get-first-commit: add help, delegate to new git-helper methods, ensure GitHub CLI is installed
- git-helper: add `first-commit`, `first-commit-hash`, `first-commit-url`, `github-slug` actions
- is-admin: support help, support multiple users, support custom group, fix check on non-macos systems
- is-affirmative: redo help
- is-array-*: use `is-(non)?empty-string` checks
- is-empty-string/is-nonempty-string: fixed documentation
- is-generic: ignore case, add empty string, false, undefined, and null, as generics
- is-match: support `--ignore-case`
- added `is-non-affirmative`
- setup-util-node: install Node 20 instead of 18 on APT
- until-success: use `waiter` for better waiting message

.trunk/trunk.yaml

@@ -22,19 +22,19 @@ lint:
   enabled:
     - [email protected]
     - [email protected]
-    - [email protected].57
+    - [email protected].69
     - [email protected]
     - [email protected]
     - git-diff-check@SYSTEM
     - [email protected]
     - [email protected]
     - [email protected]
-    - prettier@3.1.1
-    - [email protected].12
+    - prettier@3.2.4
+    - [email protected].14
     - [email protected]
     - [email protected]
     - [email protected]
-    - [email protected].8
+    - [email protected].11
     - [email protected]
   disabled:
     - trivy

README.md

@@ -17,6 +17,7 @@
 
 <!-- /BADGES -->
 
+
 Dorothy is a dotfile ecosystem featuring:
 
 -   seamless support for [Bash](<https://en.wikipedia.org/wiki/Bash_(Unix_shell)>), [Zsh](https://en.wikipedia.org/wiki/Z_shell), [Fish](<https://en.wikipedia.org/wiki/Fish_(Unix_shell)>), [Nu](https://www.nushell.sh), [Xonsh](https://xon.sh), [Elvish](https://elv.sh), [Dash](https://wiki.archlinux.org/title/Dash), [KSH](https://en.wikipedia.org/wiki/KornShell)
@@ -277,12 +278,12 @@ Join the [Bevry Software community](https://discord.gg/nQuXddV7VP) to stay up-to
 
 #### Contributors
 
--   [Benjamin Lupton](https://github.com/balupton) — [view contributions](https://github.com/bevry/dorothy/commits?author=balupton 'View the GitHub contributions of Benjamin Lupton on repository bevry/dorothy')
--   [Bevry Team](https://github.com/BevryMe) — [view contributions](https://github.com/bevry/dorothy/commits?author=BevryMe 'View the GitHub contributions of Bevry Team on repository bevry/dorothy')
--   [BJReplay](https://github.com/BJReplay) — [view contributions](https://github.com/bevry/dorothy/commits?author=BJReplay 'View the GitHub contributions of BJReplay on repository bevry/dorothy')
--   [molleweide](https://github.com/molleweide) — [view contributions](https://github.com/bevry/dorothy/commits?author=molleweide 'View the GitHub contributions of molleweide on repository bevry/dorothy')
--   [Nutchanon Ninyawee](https://github.com/wasdee) — [view contributions](https://github.com/bevry/dorothy/commits?author=wasdee 'View the GitHub contributions of Nutchanon Ninyawee on repository bevry/dorothy')
--   [Sumit Rai](https://github.com/sumitrai) — [view contributions](https://github.com/bevry/dorothy/commits?author=sumitrai 'View the GitHub contributions of Sumit Rai on repository bevry/dorothy')
+-   [Benjamin Lupton](https://github.com/balupton) — [view contributions](https://github.com/bevry/dorothy/commits?author=balupton "View the GitHub contributions of Benjamin Lupton on repository bevry/dorothy")
+-   [Bevry Team](https://github.com/BevryMe) — [view contributions](https://github.com/bevry/dorothy/commits?author=BevryMe "View the GitHub contributions of Bevry Team on repository bevry/dorothy")
+-   [BJReplay](https://github.com/BJReplay) — [view contributions](https://github.com/bevry/dorothy/commits?author=BJReplay "View the GitHub contributions of BJReplay on repository bevry/dorothy")
+-   [molleweide](https://github.com/molleweide) — [view contributions](https://github.com/bevry/dorothy/commits?author=molleweide "View the GitHub contributions of molleweide on repository bevry/dorothy")
+-   [Nutchanon Ninyawee](https://github.com/wasdee) — [view contributions](https://github.com/bevry/dorothy/commits?author=wasdee "View the GitHub contributions of Nutchanon Ninyawee on repository bevry/dorothy")
+-   [Sumit Rai](https://github.com/sumitrai) — [view contributions](https://github.com/bevry/dorothy/commits?author=sumitrai "View the GitHub contributions of Sumit Rai on repository bevry/dorothy")
 
 ### Finances
 
@@ -297,7 +298,6 @@ Join the [Bevry Software community](https://discord.gg/nQuXddV7VP) to stay up-to
 #### Sponsors
 
 -   [Andrew Nesbitt](https://nesbitt.io) — Software engineer and researcher
--   [Balsa](https://balsa.com) — We're Balsa, and we're building tools for builders.
 -   [Codecov](https://codecov.io) — Empower developers with tools to improve code quality and testing.
 -   [Frontend Masters](https://FrontendMasters.com) — The training platform for web app engineering skills – from front-end to full-stack! 🚀
 -   [Mr. Henry](https://mrhenry.be)

commands.beta/echo-escape-special

@@ -28,6 +28,9 @@ function echo_escape_special() (
 			    # exit status: 0
 
 		EOF
+		if test "$#" -ne 0; then
+			echo-error "$@"
+		fi
 		return 22 # EINVAL 22 Invalid argument
 	}
 

commands.beta/echo-if-directory

@@ -28,6 +28,9 @@ function echo_if_directory() (
 			    # exit status: 0
 
 		EOF
+		if test "$#" -ne 0; then
+			echo-error "$@"
+		fi
 		return 22 # EINVAL 22 Invalid argument
 	}
 

commands.beta/echo-if-empty

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+
+function echo_if_empty() (
+	source "$DOROTHY/sources/stdinargs.bash"
+
+	function help {
+		cat <<-EOF >/dev/stderr
+			ABOUT:
+			Output <fallback> if <input> is empty.
+
+			USAGE:
+			echo-if-empty <fallback> [...options] [--] ...<input>
+			echo-lines ...<input> | echo-if-empty <fallback> [...options]
+
+			OPTIONS:
+			<fallback> | --fallback=<fallback>
+			    The fallback to use if <input> is empty.
+
+			$(stdinargs_options_help --)
+
+			EXAMPLE:
+
+			echo-if-empty 'my-fallback-value'
+
+			    my-fallback-value
+			    # exit status: 0
+
+			echo | echo-if-empty 'my-fallback-value'
+
+			    my-fallback-value
+			    # exit status: 0
+
+			echo 'a-value' | echo-if-empty 'my-fallback-value'
+
+			    'a-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 test "$#" -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 test "$#" -ne 0; do
+		item="$1"
+		shift
+		case "$item" in
+		'--help' | '-h') help ;;
+		'--fallback='*) option_fallback="${item#*--fallback=}" ;;
+		'--')
+			option_args+=("$item" "$@")
+			shift $#
+			break
+			;;
+		*)
+			if test "$option_fallback" = "$rand"; then
+				option_fallback="$item"
+			else
+				option_args+=("$item")
+			fi
+			;;
+		esac
+	done
+
+	# checck for expected
+	if test "$option_fallback" = "$rand"; then
+		help "Missing required argument: <expected>"
+	fi
+
+	# action
+	local inputs=''
+	function on_inline {
+		inputs+="$1"
+	}
+	function on_line {
+		inputs+="$1"$'\n'
+	}
+	function on_finish {
+		if is-empty-string -- "$inputs"; then
+			print_string "$fallback"
+		else
+			print_string "$inputs"
+		fi
+	}
+	stdinargs "${option_args[@]}"
+)
+
+# fire if invoked standalone
+if test "$0" = "${BASH_SOURCE[0]}"; then
+	echo_if_empty "$@"
+fi

commands.beta/echo-if-executable

@@ -18,7 +18,7 @@ function echo_if_executable() (
 			EXAMPLE:
 
 			touch executable
-			chmodx +x executable
+			chmod +x executable
 			touch file
 
 			echo-if-file -- executable file missing
@@ -32,6 +32,9 @@ function echo_if_executable() (
 			    # exit status: 0
 
 		EOF
+		if test "$#" -ne 0; then
+			echo-error "$@"
+		fi
 		return 22 # EINVAL 22 Invalid argument
 	}
 

commands.beta/echo-if-path

@@ -28,11 +28,14 @@ function echo_if_path() (
 			    # exit status: 0
 
 		EOF
+		if test "$#" -ne 0; then
+			echo-error "$@"
+		fi
 		return 22 # EINVAL 22 Invalid argument
 	}
 
 	function on_input {
-		if is-present "$1"; then
+		if is-present -- "$1"; then
 			print_line "$1"
 		fi
 	}

commands.beta/echo-nonflags

@@ -38,6 +38,9 @@ function echo_nonflags() (
 			    code -a --b c
 			    # exit status: 0
 		EOF
+		if test "$#" -ne 0; then
+			echo-error "$@"
+		fi
 		return 22 # EINVAL 22 Invalid argument
 	}
 

commands.beta/echo-numeric

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-# this command should have a --fallback (or be used with echo-on-empty-stdin), or a --quiet to suppress the error
+# this command should have a --fallback (or be used with echo-trim-empty-lines), or a --quiet to suppress the error
 function echo_numeric() (
 	source "$DOROTHY/sources/stdinargs.bash"
 
@@ -38,12 +38,15 @@ function echo_numeric() (
 			    # exit status: 0, it was ignored due to || :
 
 		EOF
+		if test "$#" -ne 0; then
+			echo-error "$@"
+		fi
 		return 22 # EINVAL 22 Invalid argument
 	}
 
 	local had_an_invalid_input=no
 	function on_input {
-		if is-number "$1"; then
+		if is-number -- "$1"; then
 			print_line "$1"
 		else
 			echo-style --error="[$1] is not a number" >/dev/stderr

commands.beta/echo-sort

@@ -43,6 +43,9 @@ function echo_sort() (
 				1.1
 				1.2
 		EOF
+		if test "$#" -ne 0; then
+			echo-error "$@"
+		fi
 		return 22 # EINVAL 22 Invalid argument
 	}
 

commands.beta/echo-values

@@ -39,11 +39,14 @@ function echo_values() (
 			    [3] = [z]
 
 		EOF
+		if test "$#" -ne 0; then
+			echo-error "$@"
+		fi
 		return 22 # EINVAL 22 Invalid argument
 	}
 
 	function on_input {
-		if is-value "$1"; then
+		if is-value -- "$1"; then
 			print_line "$1"
 		fi
 	}

commands.beta/edit-dns

@@ -40,7 +40,7 @@ function edit_dns() (
 	# this would work, but it is automatically generated from system preferences
 	# edit /etc/resolv.conf
 
-	if get-app --quiet 'ProtonVPN.app'; then
+	if get-app --quiet -- 'ProtonVPN'; then
 		print_line 'ProtonVPN enforces its own DNS'
 	elif command-exists dnscrypt-proxy; then
 		print_line 'Editing DNS configuration of dnscrypt-proxy'

commands.beta/ensure-trailing-newline

@@ -21,32 +21,32 @@ function ensure_trailing_newline() (
 	}
 
 	# process
-	local item paths=()
+	local item option_paths=()
 	while test "$#" -ne 0; do
 		item="$1"
 		shift
 		case "$item" in
 		'--help' | '-h') help ;;
 		'--')
-			paths+=("$@")
+			option_paths+=("$@")
 			shift "$#"
 			break
 			;;
 		'--'*) help "An unrecognised flag was provided: $item" ;;
-		*) paths+=("$item") ;;
+		*) option_paths+=("$item") ;;
 		esac
 	done
 
 	# check
-	if test "${#paths[@]}" -eq 0; then
-		help "No paths were provided"
+	if test "${#option_paths[@]}" -eq 0; then
+		help "No <path>s provided"
 	fi
 
 	# =====================================
 	# Action
 
 	local path result=0
-	for path in "${paths[@]}"; do
+	for path in "${option_paths[@]}"; do
 		if test -f "$path"; then
 			if test "$(tail -n1 <"$path" | wc -l)" -eq 0; then
 				if test -w "$path"; then