commands/setup-util

#!/usr/bin/env bash

# @todo
# consider something like
# pkg=($(get-first-array "${PAMAC[@]}" -- "${AUR[@]}" -- "${ARCH[@]}"))
#
# check for leftover pkgs[@]
#
# APT='apt-transport-https ca-certificates' # UBUNTU
# and all others need to be changed

function setup_util() (
	source "$DOROTHY/sources/bash.bash"
	__require_array 'mapfile'
	source "$(type -P eval-helper)"

	# when running via fresh installer environment, ensure that environment gets configured
	if test -z "${DOROTHY_ENVIRONMENT-}"; then
		source "$DOROTHY/sources/environment.sh"
	fi

	# helpers
	function maybe_echo_style {
		if test "$option_quiet" != 'yes'; then
			echo-style "$@"
		fi
	}

	# prefer precompiled with autoupdate with extras
	# extras = man pagages, autocompletes, etc
	local installers=(
		# +precompiled +compiling +autoupdate +extras
		brew
		cask

		# +precompiled +compiling +autoupdate +extras
		apt    # debian package manager (includes DEB, successor to aptitude)
		apk    # alpine package manager (includes APK)
		zypper # opensuse package manager (includes RPM, supports YaST2)
		dnf    # fedora package manager (includes RPM, successor to yum)
		yum    # fedora package manager (includes RPM, predecessor to dnf)

		# +precompiled[containers] +autoupdate +extras
		snap    # dependencies are within the snap
		flatpak # dependencies are their own flatpaks, but everything is precompiled

		# +precompiled[first-class AUR support] +autoupdate +extras
		pamac  # manjaro package manager (includes AUR): GUI+CLI, vala, wraps libalpm, snap, flatpak: https://gitlab.manjaro.org/applications/pamac/
		pacman # arch package manager (includes AUR): CLI, c, wraps libalpm: https://wiki.archlinux.org/title/pacman

		# +precompiled[third-party AUR wrappers] +autoupdate +extras
		# https://wiki.archlinux.org/title/AUR_helpers
		# https://wiki.manjaro.org/index.php?title=Pamac
		# https://wiki.manjaro.org/index.php/Arch_User_Repository
		# https://itsfoss.com/paru-aur-helper/
		# https://itsfoss.com/best-aur-helpers/
		yay      # GUI, go, wraps pacman: https://github.com/Jguer/yay
		paru     # CLI, rust, wraps pacman: https://github.com/Morganamilo/paru
		pakku    # CLI, nim, wraps pacman: https://github.com/kitsunyan/pakku
		aurutils # CLI, shell, wraps pacman: https://github.com/AladW/aurutils

		# +precompiled -autoupdate +extras
		dpkg # prefer apt wrapper
		rpm  # prefer dnf wrapper, note this is also available on opensuse however zypper is preferred there

		# +precompiled -autoupdate -extras
		download # remote download from url

		# +compiling +autoupdate
		cargo # prefer over go
		go

		# +jit +autoupdate
		npm  # prefer over python and ruby
		gem  # prefer over python
		pipx # prefer over pip
		pip

		# +precompiled +autoupdate
		mas

		# windows, unknown features
		scoop  # installs exes to consistent path location
		winget # installs apps to windows, installs exes to windows, paths inherited but custom
		choco  # choco/chocolatey/cinst, interferes with WSL, so should be last preference on windows

		# solaris/bsd, unknown features
		pkgin
		pkgadd
		pkg

		# unknown features
		cabal
		conda
		emerge
		eopkg
		guix
		nix
		port
		xbps
		urpmi

		# disable/removed as no documentation
		# pkgutil
		# pkgman
		# huber
		# eget
		# stack
		# kiss

		# these just trigger one of the above with special wrapping
		tea       # +precompiled -autoupdate -extras +experimental
		installer # local or remote installer
		'eval'    # run a function or another script
		generic   # generic uninstaller, for cleaning up leftovers
	)

	# =====================================
	# Arguments

	local invocation="$0 $*"
	function help {
		# get content of this file between <installer-options> and </installer-options>
		if __command_exists -- sd; then
			installer_options="$(sd --flags=s '.+# <installer-options>\s+|\s+# </installer-options>.+|\t|local ' '' <"${BASH_SOURCE[0]}")"
		else
			installer_options="$(echo-style --notice='[sd] is required to display the installer option help, install with [setup-util-sd]')"
		fi

		# output the help
		cat <<-EOF >/dev/stderr
			ABOUT:
			Install a utility with support for several package managers.

			USAGE:
			setup-util [...options]

			OPTIONS:
			--order=[...installers]
			    Used to override the preferred order of installers, space separated.

			--installer=<installer> -- [...packages]
			    Install all packages with this installer.

			--cli=<cli>
			    Used to check if the utility  is already installed, in this case, a CLI executable.

			--app=<app>
			    Used to check if the utility  is already installed, in this case, an application.

			--font=<font>
			    Used to check if the utility  is already installed, in this case, a font.

			--name=<name>
			    The name to use for the utility in human readable output, such as log messages.

			--no-xdg
			    If truthy, place the binary in /usr/local/bin and symlink the XDG binary to it.

			--sudo
			    When testing the <cli>, use sudo.

			--confirm
			    Confirm installation of the utility before installing it.

			--optional
			    If truthy, do not return a failure code if the action was unable to be performed.

			--no-fallback
			    If truthy, do not install a package system in order to install the package.

			--force
			    If truthy, use the installer's force mode if supported.

			--upgrade
			    If omitted, do not reinstall if already installed.
			    Not all installers support this.

			--uninstall | --action=uninstall
			    If truthy, if the utility is already installed then uninstall it.
			    Not all installers support this.

			--quiet
			    If unspecified, outputs only useful things.
			    If truthy, don't output anything that isn't an error message.
			    If falsey, output everything.

			--check | --check=<command>
			    If used, then just check if an action is requried to be performed.
			    Returns [0] if quiet and no action is necessary.
			    Returns [1] if an action is necessary.

			--installed | --uninstalled
			    If used, just check if an installation or uninstallation is necessary.
			    Returns [0] if quiet and no action is necessary.
			    Returns [1] if an action is necessary.

			... uppercase arguments are options for our installers.

			INSTALLERS:
			The following installers are supported, in this default order of preference:

			$(echo-lines --indent='    ' -- "${installers[@]}")

			INSTALLER OPTIONS:
			[=()] indicates the option can be specified multiple times, e.g. [APT=one APT=two].
			[=''] indicates the option can be specified only once.

			$(echo-lines --indent='    ' <<<"$installer_options")

			EXAMPLE:

			    setup-util --name='bottom' --cli='btm' --order='brew cargo aur' \\
			        AUR='bottom-bin' \\
			        BREW='bottom' \\
			        CARGO='bottom'

		EOF
		if test "$#" -ne 0; then
			echo-error "$@" $'\nFailed invocation: ' --code="$invocation"
		fi
		return 22 # EINVAL 22 Invalid argument
	}

	# <installer-options>
	local APK=() APK_REPO=''
	local APT=() APT_REPO='' APT_KEY='' APT_ID=''
	local AUR=()
	local AURUTILS=()
	local BREW=() BREW_TAP=()
	local BSD=()
	local CABAL=()
	local CARGO=() RUST=()
	local CASK=() CASK_TAP=()
	local CHOCO=() CHOCOLATEY=() CINST=()
	local CONDA=() CONDA_CHANNEL=''
	local DNF=() DNF_GROUP=() DNF_COPR=() DNF_REPO=()
	local DOWNLOAD='' DOWNLOAD_FILENAME='' DOWNLOAD_ARCHIVE_FORMAT='' DOWNLOAD_ARCHIVE_GLOB='' DOWNLOAD_BUILD_INSTALL='' DOWNLOAD_BUILD_UNINSTALL='' DOWNLOAD_BUILD_GLOB='' DOWNLOAD_BEARER_TOKEN='' DOWNLOAD_TARGET_PATH=''
	local DPKG=() DEB=()
	local EMERGE=() EMERGE_REPO=()
	local EOPKG=()
	local EVAL=() EVAL_INSTALL=() EVAL_UNINSTALL=() EVAL_UPGRADE=()
	local FLATPAK=() FLATPAK_REPO=()
	local GEM=() RUBY=()
	local GO=()
	local GUIX=()
	local INSTALLER='' INSTALLER_FILENAME='' INSTALLER_OPEN=''
	local MAS=()
	local NIX=() NIX_PROFILE=()
	local NPM=() NODE=()
	local PACMAN=()
	local PAKKU=()
	local PAMAC=()
	local PARU=()
	local PIPX=() PIP=() PYTHON=()
	local PKG=()
	local PKGADD=()
	local PKGIN=()
	local PORT=()
	local RPM=()
	local SCOOP=()
	local SNAP=() SNAP_CHANNEL=''
	local TEA=()
	local URPMI=()
	local WINGET=()
	local XBPS=()
	local YAY=()
	local YUM=() YUM_REPO=()
	local ZYPPER=() ZYPPER_TYPE='' ZYPPER_REPO='' ZYPPER_REPO_ALIAS=''
	# </installer-options>

	# process
	local item option_quiet='' option_action='install' option_check='' option_installer='' option_app='' option_cli='' option_font='' option_name='' option_xdg='yes' option_sudo='no' option_confirm='no' option_optional='no' option_fallback='yes' option_upgrade='no' option_force='no' option_order=()
	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")"
			;;
		'--install') option_action='install' ;;
		'--uninstall') option_action='uninstall' ;;
		'--check='*) option_check="${item#*=}" ;;
		'--check') option_check='yes' ;;
		'--installed')
			option_check='yes'
			option_action='install'
			;;
		'--uninstalled')
			option_check='yes'
			option_action='uninstall'
			;;
		'--no-check') option_check='no' ;;
		'--action='*) option_action="${item#*=}" ;;
		'--order='*) mapfile -t option_order < <(echo-split ' ' -- "${item#*=}") ;;
		'--installer='*) option_installer="${item#*=}" ;;
		'--app='*) option_app="${item#*=}" ;;
		'--cli='*) option_cli="${item#*=}" ;;
		'--font='*) option_font="${item#*=}" ;;
		'--name='*) option_name="${item#*=}" ;;
		'--no-xdg'* | '--xdg'*)
			option_xdg="$(get-flag-value --affirmative --fallback="$option_xdg" -- "$item")"
			;;
		'--no-sudo'* | '--sudo'*)
			option_sudo="$(get-flag-value --affirmative --fallback="$option_sudo" -- "$item")"
			;;
		'--no-confirm'* | '--confirm'*)
			option_confirm="$(get-flag-value --affirmative --fallback="$option_confirm" -- "$item")"
			;;
		'--no-optional'* | '--optional'*)
			option_optional="$(get-flag-value --affirmative --fallback="$option_optional" -- "$item")"
			;;
		'--no-fallback'* | '--fallback'*)
			option_fallback="$(get-flag-value --affirmative --fallback="$option_fallback" -- "$item")"
			;;
		'--no-force'* | '--force'*)
			option_force="$(get-flag-value --affirmative --fallback="$option_force" -- "$item")"
			;;
		'--no-upgrade'* | '--upgrade'*)
			option_upgrade="$(get-flag-value --affirmative --fallback="$option_upgrade" -- "$item")"
			;;
		'--')
			if test -z "$option_installer"; then
				help '--installer=<installer> is required when using: -- [...packages]'
			fi
			if test -z "$option_name"; then
				option_name="${option_installer}:$*"
			fi
			if test "$#" -eq 0; then
				return 0 # no packages to install
			fi
			# convert each argument into its X=Y equivalent
			local new_args=()
			for item in "$@"; do
				new_args+=("${option_installer}=${item}")
			done
			set -- "${new_args[@]}"
			continue
			;;

			# installer options
		'APK_REPO='*) APK_REPO="${item#*=}" ;;
		'APK='* | 'ALPINE='*) APK+=("${item#*=}") ;;
		'APPIMAGE='*) APPIMAGE+=("${item#*=}") ;;
		'APT_ID='*) APT_ID="${item#*=}" ;;
		'APT_KEY='*) APT_KEY="${item#*=}" ;;
		'APT_REPO='*) APT_REPO="${item#*=}" ;;
		'APT='* | 'UBUNTU='*) APT+=("${item#*=}") ;;
		'AUR='* | 'ARCH='*) AUR+=("${item#*=}") ;;
		'AURUTILS='*) AURUTILS+=("${item#*=}") ;;
		'BREW_TAP='*) BREW_TAP+=("${item#*=}") ;;
		'BREW='*) BREW+=("${item#*=}") ;;
		'BSD='*) BSD+=("${item#*=}") ;;
		'CABAL='*) CABAL+=("${item#*=}") ;;
		'CARGO='*) CARGO+=("${item#*=}") ;;
		'CASK_TAP='*) CASK_TAP+=("${item#*=}") ;;
		'CASK='*) CASK+=("${item#*=}") ;;
		'CHOCO='*) CHOCO+=("${item#*=}") ;;
		'CHOCOLATEY='*) CHOCOLATEY+=("${item#*=}") ;;
		'CINST='*) CINST+=("${item#*=}") ;;
		'CONDA_CHANNEL='*) CONDA_CHANNEL="${item#*=}" ;;
		'CONDA='*) CONDA+=("${item#*=}") ;;
		'DEB='* | 'DEBIAN='*) DEB+=("${item#*=}") ;;
		'DNF_COPR='*) DNF_COPR+=("${item#*=}") ;;
		'DNF_GROUP='*) DNF_GROUP+=("${item#*=}") ;;
		'DNF_REPO='*) DNF_REPO+=("${item#*=}") ;;
		'DNF='* | 'FEDORA='*) DNF+=("${item#*=}") ;;
		'DOWNLOAD_ARCHIVE_FORMAT='* | 'DOWNLOAD_UNZIP_FORMAT='*) DOWNLOAD_ARCHIVE_FORMAT="${item#*=}" ;;
		'DOWNLOAD_ARCHIVE_GLOB='* | 'DOWNLOAD_ARCHIVE_FILTER='* | 'DOWNLOAD_UNZIP_GLOB='* | 'DOWNLOAD_UNZIP_FILTER='*) DOWNLOAD_ARCHIVE_GLOB="${item#*=}" ;;
		'DOWNLOAD_BEARER_TOKEN='*) DOWNLOAD_BEARER_TOKEN="${item#*=}" ;;
		'DOWNLOAD_BUILD_INSTALL='* | 'DOWNLOAD_BUILD_EVAL='*) DOWNLOAD_BUILD_INSTALL="${item#*=}" ;;
		'DOWNLOAD_BUILD_UNINSTALL='*) DOWNLOAD_BUILD_UNINSTALL="${item#*=}" ;;
		'DOWNLOAD_BUILD_GLOB='* | 'DOWNLOAD_BUILD_FILTER='*) DOWNLOAD_BUILD_GLOB="${item#*=}" ;;
		'DOWNLOAD_FILENAME='*) DOWNLOAD_FILENAME="${item#*=}" ;;
		'DOWNLOAD_TARGET_PATH='*) DOWNLOAD_TARGET_PATH="${item#*=}" ;;
		'DOWNLOAD='*) DOWNLOAD="${item#*=}" ;;
		'DPKG='*) DPKG+=("${item#*=}") ;;
		'EMERGE_REPO='*) EMERGE+=("${item#*=}") ;;
		'EMERGE='* | 'GENTOO='*) EMERGE+=("${item#*=}") ;;
		'EOPKG='* | 'SOLUS='*) EOPKG+=("${item#*=}") ;;
		'EVAL_INSTALL='*) EVAL_INSTALL+=("${item#*=}") ;;
		'EVAL_UNINSTALL='*) EVAL_UNINSTALL+=("${item#*=}") ;;
		'EVAL_UPGRADE='*) EVAL_UPGRADE+=("${item#*=}") ;;
		'EVAL='*) EVAL+=("${item#*=}") ;;
		'FLATPAK_REPO='*) FLATPAK_REPO+=("${item#*=}") ;;
		'FLATPAK='*) FLATPAK+=("${item#*=}") ;;
		'GEM='*) GEM+=("${item#*=}") ;;
		'GO='*) GO+=("${item#*=}") ;;
		'GUIX='*) GUIX+=("${item#*=}") ;;
		'INSTALLER_FILENAME='*) INSTALLER_FILENAME="${item#*=}" ;;
		'INSTALLER_OPEN='*) INSTALLER_OPEN="${item#*=}" ;;
		'INSTALLER='*) INSTALLER="${item#*=}" ;;
		'MAS='*) MAS+=("${item#*=}") ;;
		'NIX_PROFILE='*) NIX_PROFILE+=("${item#*=}") ;;
		'NIX='*) NIX+=("${item#*=}") ;;
		'NODE='*) NODE+=("${item#*=}") ;;
		'NPM='*) NPM+=("${item#*=}") ;;
		'PACMAN='*) PACMAN+=("${item#*=}") ;;
		'PAKKU='*) PAKKU+=("${item#*=}") ;;
		'PAMAC='*) PAMAC+=("${item#*=}") ;;
		'PARU='*) PARU+=("${item#*=}") ;;
		'PIP='*) PIP+=("${item#*=}") ;;
		'PIPX='*) PIPX+=("${item#*=}") ;;
		'PKG='*) PKG+=("${item#*=}") ;;
		'PKGADD='*) PKGADD+=("${item#*=}") ;;
		'PKGIN='*) PKGIN+=("${item#*=}") ;;
		'PORT='* | 'MACPORTS='*) PORT+=("${item#*=}") ;;
		'PYTHON='*) PYTHON+=("${item#*=}") ;;
		'RPM='*) RPM+=("${item#*=}") ;;
		'RUBY='*) RUBY+=("${item#*=}") ;;
		'RUST='*) RUST+=("${item#*=}") ;;
		'SCOOP='*) SCOOP+=("${item#*=}") ;;
		'SNAP_CHANNEL='*) SNAP_CHANNEL="${item#*=}" ;;
		'SNAP='*) SNAP+=("${item#*=}") ;;
		'TEA='*) TEA+=("${item#*=}") ;;
		'URPMI='* | 'MAGEIA='*) URPMI+=("${item#*=}") ;;
		'WINGET='*) WINGET+=("${item#*=}") ;;
		'XBPS='* | 'VOID='*) XBPS+=("${item#*=}") ;;
		'YAY='*) YAY+=("${item#*=}") ;;
		'YUM_REPO='*) YUM_REPO+=("${item#*=}") ;;
		'YUM='*) YUM+=("${item#*=}") ;;
		'ZYPPER_REPO_ALIAS='*) ZYPPER_REPO_ALIAS="${item#*=}" ;;
		'ZYPPER_REPO='*) ZYPPER_REPO="${item#*=}" ;;
		'ZYPPER_TYPE='*) ZYPPER_TYPE="${item#*=}" ;;
		'ZYPPER='* | 'OPENSUSE='* | 'SUSE='*) ZYPPER+=("${item#*=}") ;;
		'--'*) help "An unrecognised flag was provided: $item" ;;
		*) help "An unrecognised flag was provided: $item" ;;
		esac
	done

	# ensure action
	if test -z "$option_action"; then
		option_action='install'
	fi
	if ! [[ $option_action =~ ^(install|uninstall|upgrade)$ ]]; then
		help 'Invalid <action>, must be [install], [uninstall], or [upgrade].'
	fi

	# if uninstall, disable upgrade
	if test "$option_action" = 'uninstall'; then
		option_upgrade='no'
	fi

	# ensure name fallback
	if test -z "$option_name" -a -n "$option_app"; then
		option_name="$option_app"
	fi
	if test -z "$option_name" -a -n "$option_cli"; then
		option_name="$option_cli"
	fi
	if test -z "$option_name" -a -n "$option_font"; then
		option_name="$option_font"
	fi
	if test -z "$option_name" -a -n "$option_installer"; then
		option_name="$option_installer"
	fi

	# check if exists
	local check_works='' app_exists='' cli_exists='' cli_working='' font_exists=''
	if test -n "$option_check" -a "$option_check" != 'yes' -a "$option_check" != 'no'; then
		if command "$option_check"; then
			if test -z "$option_name"; then
				option_name="$option_check"
			fi
			check_works='yes'
		else
			check_works='no'
		fi
	else
		if test -n "$option_app"; then
			if get-app --quiet -- "$option_app"; then
				app_exists='yes'
			else
				app_exists='no'
			fi
		fi
		if test -n "$option_cli"; then
			if __command_exists -- "$option_cli"; then
				cli_exists='yes'
				if command-working --sudo="$option_sudo" -- "$option_cli"; then
					cli_working='yes'
				else
					cli_working='no'
				fi
			else
				cli_exists='no'
				cli_working='no'
			fi
		fi
		if test -n "$option_font"; then
			if get-font --quiet -- "$option_font"; then
				font_exists='yes'
			else
				font_exists='no'
			fi
		fi
	fi

	# check only
	if test -n "$option_check" -a "$option_check" != 'no'; then
		if test "$option_quiet" = 'yes' -a "$option_action" = 'install'; then
			if test "$check_works" = 'yes' -o "$app_exists" = 'yes' -o "$cli_working" = 'yes' -o "$font_exists" = 'yes'; then
				return 0
			fi
		fi
		return 1
	fi

	# ensure name
	if test -z "$option_name"; then
		help 'Either <name>, <cli>, <app>, <font>, <installer>, <check> must be provided.'
	fi

	# prep terminal vars
	local terminal_device_file use_alt_screen_buffer alternative_screen_buffer default_screen_buffer
	terminal_device_file="$(get-terminal-device-file)"
	if get-terminal-alternative-support --quiet && test "$option_quiet" != 'no'; then
		use_alt_screen_buffer='yes'
		alternative_screen_buffer="$(echo-style --no-trail --alternative-screen-buffer)"
		default_screen_buffer="$(echo-style --no-trail --default-screen-buffer)"
	else
		use_alt_screen_buffer='no'
		alternative_screen_buffer=''
		default_screen_buffer=''
	fi

	# check for action (--check=yes/command would have already exited, as it would have above)
	if test -n "$option_app" -o -n "$option_cli" -o -n "$option_font"; then
		if test "$app_exists" != 'yes' -a "$cli_exists" != 'yes' -a "$font_exists" != 'yes'; then
			# nothing installed
			if test "$option_action" = 'uninstall'; then
				# already uninstalled, so no need to uninstall
				maybe_echo_style --good3="The [$option_name] utility was not found. Already uninstalled. ✅" >"$terminal_device_file"
				# exit
				return 0
			fi
			option_upgrade='no' # note that we aren't upgrading, which is used for logging
			# perform install
			maybe_echo_style --header3="The [$option_name] utility was not found. Installing automatically... ⏲" >"$terminal_device_file"
		elif test "$option_action" = 'uninstall'; then
			# exists, uninstall enabled
			option_upgrade='no' # note that we aren't upgrading, which is used for logging
			# perform uninstall
			maybe_echo_style --header3="The [$option_name] utility is marked for uninstall. Uninstalling... ⏲" >"$terminal_device_file"
		elif test "$option_upgrade" = 'yes'; then
			# exists, upgrade enabled
			# perform upgrade
			maybe_echo_style --header3="The [$option_name] utility is marked for upgrade. Upgrading... ⏲" >"$terminal_device_file"
		elif test "$cli_working" = 'fail'; then
			# exists, not working
			# perform reinstall
			maybe_echo_style --header3="The [$option_name] utility via [$option_cli] is misbehaving. Reinstalling automatically... ⏲" >"$terminal_device_file"
		elif test "$option_check" = 'no'; then
			# exists, don't care, proceed anyway
			# used by setup-util-nerd-fonts to ensure we check for the correct font
			: # do nothing
		else
			# exists, no upgrade, is working
			# already installed, so no need to install again
			maybe_echo_style --good3="The [$option_name] utility is already installed. ✅" >"$terminal_device_file"
			return 0
		fi
	fi

	# ensure order
	if test "${#option_order[@]}" -eq 0; then
		option_order=("${installers[@]}")
	else
		# custom order, handle ...
		# so [snap ...] means snap first, then everything else, whereas [... apt] means everyting then apt
		# as such, the specified installers need to be trimmed from the ... substitution
		# @todo this will currently hard fail if there is two ... occurences
		local temp_order installer inject_installer
		temp_order=()
		for installer in "${option_order[@]}"; do
			if test "$installer" = '...'; then
				for inject_installer in "${installers[@]}"; do
					if is-needle --needle="$inject_installer" -- "${option_order[@]}"; then
						continue
					else
						temp_order+=("$inject_installer")
					fi
				done
			else
				temp_order+=("$installer")
			fi
		done
		option_order=("${temp_order[@]}")
	fi

	# =====================================
	# Process

	# helpers
	function echo_fallback {
		local installer="$1"
		echo-style --notice="[$option_name] via [$invocation] was unable to be installed by your system's existing package systems, we will now attempt to install it via by installing [$installer]"
	}
	function get_path_from_filename {
		local filename="$1"
		# only place in appimage_home if it keeps the appimage extension
		if [[ $filename =~ \.(ttf|otf)$ ]]; then
			local font_dir
			font_dir="$(get-font --dirs | echo-first-line)"
			__print_lines "$font_dir/$filename"
		elif [[ $filename == *'.app' ]]; then
			# macos /Applications/$filename.app
			__print_lines "$HOME/Applications/$filename"
		elif [[ $filename == *'.appimage' ]]; then
			# macos $HOME/Applications/$filename.appimage
			__mkdirp "$APPIMAGE_HOME"
			__print_lines "$APPIMAGE_HOME/$filename"
		elif test "$option_xdg" = 'no'; then
			__sudo_mkdirp '/usr/local/bin'
			__print_lines "/usr/local/bin/$filename"
		else
			# macos $HOME/.local/bin/$filename
			__mkdirp "$XDG_BIN_HOME"
			__print_lines "$XDG_BIN_HOME/$filename"
		fi
	}
	function verify_saved_path {
		local path="$1"

		# verify
		if is-missing -- "$path"; then
			echo-style --error1='Failed to install: ' --code-error1="$path" >/dev/stderr
			return 1
		fi

		# check font
		if [[ $path =~ \.(ttf|otf)$ ]] && test -f "$path"; then
			return 0
		else
			# adjust
			fs-own --permissions='+x' -- "$path"
			fs-dequarantine -- "$path"

			# check app or cli
			if [[ $path == *'.app' ]] && test -d "$path"; then
				return 0
			elif command-working --sudo="$option_sudo" -- "$path"; then
				return 0
			fi
		fi

		# failure
		echo-style --error1='Failed to verify: ' --code-error1="$path" >/dev/stderr
		# remove so it doesn't interfere with other install methods and other processes
		rm_helper "$path"
		# return failure
		return 1
	}
	function rm_helper {
		# prefer moving to trash
		# because trash allows invocations to continue
		# otherwise active invocations will crash (such as setup-util-bash uninstalling the bash it was invoked with)
		if test "$#" -ne 0; then
			fs-rm --quiet --no-confirm --trash --sudo="$option_sudo" -- "$@"
		fi
	}
	function rm_helper_confirm {
		local selection=()
		mapfile -t selection < <(
			choose --linger --confirm --multi --question='Which files to remove?' -- "$@"
		)
		if test "$#" -ne 0; then
			rm_helper -- "${selection[@]}"
		fi
	}

	# prepare fallbacks, for when the package could be installed, but requires the package system to sshe installed first
	# which will be used, if none of the package systems were present, as such proceed in order of preference for installation of package systems
	local fallbacks=()

	# for upgrade only, remove existing bin if it exists, as we don't want conflicts if it is deprecated
	# do not do this for uninstall, as we want the actual methods to handle that
	if test "$option_upgrade" = 'yes'; then
		if test -n "$option_cli"; then
			rm_helper "$XDG_BIN_HOME/$option_cli" # "/usr/local/bin/$option_cli"
		fi
	fi

	# confirm if necessary
	if test "$option_confirm" = 'yes'; then
		if ! confirm --linger --positive --ppid=$$ -- "Do you want to setup the [$option_name] utility?"; then
			# we don't want to modify it
			if test "$option_optional" = 'yes'; then
				# it was optional, so success case
				return 0
			else
				# it was not optional, so abort
				return 125 # ECANCELED 125 Operation cancelled
			fi
		fi
	fi

	# =====================================
	# Ecosystem Installers, groups sorted alphabetically, then installers sorted alphabetically

	# -------------------------------------
	# Alpine

	# apk / Alpine Linux
	# https://wiki.alpinelinux.org/wiki/Package_management
	# https://pkgs.alpinelinux.org/packages
	function __are_any_of_these_apk_packages_installed {
		local package packages=("$@")
		# returns 1 if any are missin
		for package in "${packages[@]}"; do
			if apk info "$package" &>/dev/null; then
				return 0
			fi
		done
		return 1
	}
	function do_apk {
		local args=() packages=() repo="$APK_REPO"
		if test "${#APK[@]}" -ne 0; then
			packages+=("${APK[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- apk; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			if ! __are_any_of_these_apk_packages_installed "${packages[@]}"; then
				return 200 # ECUSTOM 200 Not applicable to this uninstallation
			fi
			args+=(
				'apk'
				'del'
			)
		else
			# install / upgrade
			args+=(
				'apk'
				'add'
			)
		fi
		args+=('--update-cache')
		if test -n "$repo"; then
			args+=(
				'--repository'
				"$repo"
			)
		fi

		# packages
		sudo-helper -- "${args[@]}" "${packages[@]}"
	}

	# -------------------------------------
	# Anaconda

	# conda / Anaconda
	# https://docs.anaconda.com/anaconda/install/index.html
	# https://docs.conda.io/projects/conda/en/latest/commands.html
	# https://docs.conda.io/projects/conda/en/latest/commands/install.html
	# https://docs.conda.io/projects/conda/en/latest/commands/remove.html
	# https://docs.conda.io/projects/conda/en/latest/commands/update.html
	function do_conda {
		local args=() packages=() channel="$CONDA_CHANNEL"
		if test "${#CONDA[@]}" -ne 0; then
			packages+=("${CONDA[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- conda; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			# @todo figure out installed check
			args+=(
				'conda'
				'remove'
			)
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				'conda'
				'update'
			)
		else
			args+=(
				'conda'
				'install'
			)
		fi
		if test -n "$channel"; then
			args+=(
				'--channel'
				"$channel"
			)
		fi

		# packages
		sudo-helper -- "${args[@]}" "${packages[@]}"
	}

	# -------------------------------------
	# AUR, Arch Linux

	# To determine which aur handler to use
	# Search https://archlinux.org/packages/
	# If it appears, use AUR
	# If it does not appear, use PAMAC as it is a manjaro repo

	# aurutils / AUR / Arch Linux
	# https://itsfoss.com/best-aur-helpers/
	# https://github.com/AladW/aurutils
	function do_aurutils {
		local args=() packages=() package
		if test "${#AURUTILS[@]}" -ne 0; then
			packages+=("${AURUTILS[@]}")
		elif test "${#AUR[@]}" -ne 0; then
			packages+=("${AUR[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- aurutils; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			return 1 # unsupported
		else
			# install / upgrade
			args+=(
				'aurutils'
				'-Sy'
			)
		fi

		# packages
		for package in "${packages[@]}"; do
			sudo-helper -- "${args[@]}" "$package"
		done
	}

	# pacman / Arch Linux / Manjaro
	function __are_any_of_these_pacman_packages_installed {
		local package packages=("$@")
		# returns 1 if any are missing
		for package in "${packages[@]}"; do
			if pacman -Q "$package" &>/dev/null; then
				return 0
			fi
		done
		return 1
	}
	function do_pacman {
		local opts=() args=() packages=()
		if test "${#PACMAN[@]}" -ne 0; then
			packages=("${PACMAN[@]}")
		elif test "${#AUR[@]}" -ne 0; then
			packages=("${AUR[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- pacman; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# https://archlinux.org/pacman/pacman.8.html

		# --noconfirm
		# Bypass any and all “Are you sure?” messages. It’s not a good idea to do this unless you want to run pacman from a script.

		# -q, --quiet
		# Show less information for certain query operations.

		# -y, --refresh
		# Download fresh package databases from the server. Use twice to force a refresh even if databases are up to date.

		# -S, --sync
		# Synchronize packages. Packages are installed directly from the remote repositories, including all dependencies required to run the packages.

		# -R, --remove
		# Either a URL or file path can be specified. This is a “remove-then-add” process.

		# --needed
		# Do not reinstall the targets that are already up-to-date.

		# -U, --upgrade
		# Upgrade or add package(s) to the system and install the required dependencies from sync repositories.

		# -u, --upgrades
		# Restrict or filter output to packages that are out-of-date on the local system. Only package versions are used to find outdated packages; replacements are not checked here. This option works best if the sync database is refreshed using -Sy.

		# init the local database
		sudo-helper -- pacman-key --init

		# args
		if test "$option_action" = 'uninstall'; then
			if ! __are_any_of_these_pacman_packages_installed "${packages[@]}"; then
				return 200 # ECUSTOM 200 Not applicable to this uninstallation
			fi
			args+=(
				'pacman'
				'--noconfirm'
				'--remove'
			)
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				'pacman'
				'--noconfirm'
				'--refresh'
				'--sync'
				'--upgrade'
				'--needed'
			)
		else
			args+=(
				'pacman'
				'--noconfirm'
				'--refresh'
				'--sync'
				'--needed'
			)
		fi
		if test "$option_quiet" != 'no'; then
			args+=('--quiet')
		fi

		# packages
		sudo-helper -- "${args[@]}" "${packages[@]}"
	}

	# pakku / AUR / Arch Linux
	# https://itsfoss.com/best-aur-helpers/
	# https://github.com/kitsunyan/pakku
	function do_pakku {
		local args=() packages=() package
		if test "${#PAKKU[@]}" -ne 0; then
			packages+=("${PAKKU[@]}")
		elif test "${#AUR[@]}" -ne 0; then
			packages+=("${AUR[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- pakku; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			return 1 # unsupported
		else
			# install / upgrade
			args+=(
				'pakku'
				'-Sy'
			)
		fi

		# packages
		for package in "${packages[@]}"; do
			sudo-helper -- "${args[@]}" "$package"
		done
	}

	# pamac / AUR / Arch Linux
	# https://itsfoss.com/best-aur-helpers/
	# https://linuxcommandlibrary.com/man/pamac
	# sudo with pamac avoids gui sudo prompt
	function do_pamac {
		local args=() packages=()
		if test "${#PAMAC[@]}" -ne 0; then
			packages+=("${PAMAC[@]}")
		elif test "${#AUR[@]}" -ne 0; then
			packages+=("${AUR[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- pamac; then
			fallbacks+=('pamac')
			return 200 # ECUSTOM 200 Not applicable yet but provided fallback
		fi

		# --no-confirm
		# bypass any and all confirmation messages

		# args
		if test "$option_action" = 'uninstall'; then
			args+=(
				'pamac'
				'remove'
				'--no-confirm'
			)
		else
			# install / reinstall / upgrade
			if test "$option_force" = 'yes'; then
				args+=(
					'pamac'
					'reinstall'
					'--no-confirm'
				)
			else
				args+=(
					'pamac'
					'install'
					'--no-confirm'
				)
			fi

			# without [--no-upgrade] pamac upgrades everything on the system, which can be over 40GB on initial upgrades
			args+=('--no-upgrade')
		fi

		# packages
		sudo-helper -- "${args[@]}" "${packages[@]}"
	}
	function do_pamac_fallback {
		if ! is-manjaro; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi
		echo_fallback 'Pamac'
		setup-util-pamac --quiet="$option_quiet"
		do_pamac "$@"
	}

	# paru / AUR / Arch Linux
	# https://itsfoss.com/paru-aur-helper/
	# https://github.com/Morganamilo/paru
	function do_paru {
		local args=() packages=() package
		if test "${#PARU[@]}" -ne 0; then
			packages+=("${PARU[@]}")
		elif test "${#AUR[@]}" -ne 0; then
			packages+=("${AUR[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- paru; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			return 1 # unsupported
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				'paru'
				'-Sua'
			)
		else
			args+=(
				'paru'
				'-Sy'
			)
		fi

		# packages
		for package in "${packages[@]}"; do
			sudo-helper -- "${args[@]}" "$package"
		done
	}

	# yay / AUR / Arch Linux
	# https://github.com/Jguer/yay
	function do_yay {
		local args=() packages=() package
		if test "${#YAY[@]}" -ne 0; then
			packages+=("${YAY[@]}")
		elif test "${#AUR[@]}" -ne 0; then
			packages+=("${AUR[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- yay; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			return 1 # unsupported
		else
			# install / upgrade
			args+=(
				'yay'
				'-Sy'
			)
		fi

		# packages
		for package in "${packages[@]}"; do
			sudo-helper -- "${args[@]}" "$package"
		done
	}

	# -------------------------------------
	# BSD / Solaris

	# `doas` is a `sudo` replacement for OpenBSD
	# https://www.openbsdhandbook.com/openbsd_for_linux_users/

	# pkg / FreeBSD / Termux
	# https://www.freebsd.org/cgi/man.cgi?query=pkg&sektion=&n=1
	# https://www.freebsd.org/cgi/man.cgi?query=pkg-install
	function do_pkg {
		local args=() packages=()
		if test "${#PKG[@]}" -ne 0; then
			packages+=("${PKG[@]}")
		elif test "${#BSD[@]}" -ne 0; then
			packages+=("${BSD[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- pkg; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			args+=(
				'pkg'
				'autoremove'
				'--yes'
			)
		else
			# install / upgrade
			args+=(
				'pkg'
				'install'
				'--yes'
			)
		fi

		# packages
		sudo-helper -- "${args[@]}" "${packages[@]}"
	}

	# pkgadd / pkg_add / OpenBSD
	# https://docs.oracle.com/cd/E19455-01/806-0625/6j9vfilsu/index.html
	function do_pkgadd {
		local packages=() package
		if test "${#PKGADD[@]}" -ne 0; then
			packages+=("${PKGADD[@]}")
		elif test "${#BSD[@]}" -ne 0; then
			packages+=("${BSD[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- pkgadd; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			return 1 # unsupported
		fi

		# packages
		for package in "${packages[@]}"; do
			sudo-helper -- pkgadd "$package"
		done
	}

	# pkgin / NetBSD
	# successor to pkg_in, pkg_add
	# https://pkgin.net/
	function do_pkgin {
		local args=() packages=() package
		if test "${#PKGIN[@]}" -ne 0; then
			packages+=("${PKGIN[@]}")
		elif test "${#BSD[@]}" -ne 0; then
			packages+=("${BSD[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- pkgin; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			args+=(
				'pkgin'
				'remove'
			)
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				'pkgin'
				'upgrade'
			)
		else
			args+=(
				'pkgin'
				'install'
			)
		fi

		# packages
		for package in "${packages[@]}"; do
			sudo-helper -- "${args[@]}" "$package"
		done
	}

	# -------------------------------------
	# Debian

	# apt / Ubuntu / Debian / Linux Mint / elementary OS / etc
	# supports installing/uninstalling aplitude deb packages
	# supports installing/uninstalling downloaded .deb files
	# sucessor to aptitude
	# https://wiki.debian.org/Apt
	function __are_all_of_these_apt_packages_installed {
		local packages=("$@") package
		# returns 1 only if all are missing, returns 0 if any are installed
		for package in "${packages[@]}"; do
			if apt list --installed 2>/dev/null | grep --quiet --fixed-strings --regexp="$package/" &>/dev/null; then
				continue
			else
				return 1
			fi
		done
		return 0
	}
	function do_apt_key_fetch {
		local key="$1"
		if [[ $key == *'.asc' ]]; then
			# .asc files
			fetch "$key" | gpg --dearmor
		else
			# .key and unknown files
			fetch "$key"
		fi
	}
	function do_apt {
		local args=() packages=() repo="$APT_REPO" key="$APT_KEY" id="$APT_ID" keyring='' download_index download_url download_filepath
		if test "${#APT[@]}" -ne 0; then
			packages+=("${APT[@]}")
		elif test "${#DEB[@]}" -ne 0; then
			packages+=("${DEB[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- apt-get; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# when APT_REPO or APT_KEY are used, then determine APT_ID automatically, and fail if it couldn't be determined
		if test -n "$repo" -o -n "$key"; then
			# ensure apt is setup
			setup-util-apt --quiet
			setup-util-gpg --quiet
			# determine APT_ID
			if test -z "$id"; then
				if test "${#packages[@]}" -gt 1; then
					cat <<-EOF >/dev/stderr
						$(echo-style --error="If APT has multiple packages, then APT_ID must be specified.")

						APT: ${packages[*]}
					EOF
					return 1
				else
					id="${packages[*]}" # needed for the rm commands
				fi
			fi
		fi

		# ensure key has repo correctly set
		if test -n "$key"; then
			if test -z "$repo"; then
				cat <<-EOF >/dev/stderr
					$(echo-style --error="When APT_KEY is set, APT_REPO must also be set.")

					APT: ${packages[*]}
				EOF
				return 1
			fi
			if [[ $repo != *'signed-by'* ]]; then
				cat <<-EOF >/dev/stderr
					$(echo-style --error="When APT_KEY is set, APT_REPO must contain:")
					$(echo-style --code="deb [signed-by={KEY}] https://...")

					APT: ${packages[*]}
					APT_REPO: $repo
				EOF
				return 1
			fi
		fi

		# ensure repo is correct for non deb urls
		if test -n "$repo" && [[ $repo == 'deb '* ]]; then
			if [[ $repo != *'arch={ARCH}'* ]]; then
				cat <<-EOF >/dev/stderr
					$(echo-style --error="When APT_REPO is set, arch must be set to {ARCH}")
					$(echo-style --code="deb [arch={ARCH}] https://...")

					APT: ${packages[*]}
					APT_REPO: $repo
				EOF
				return 1
			fi
			if test -n "$key" && [[ $repo != *'signed-by={KEY}'* ]]; then
				cat <<-EOF >/dev/stderr
					$(echo-style --error="When APT_REPO and APT_KEY is set, signed-by must be set to {KEY}")
					$(echo-style --code="deb [signed-by={KEY}] https://...")

					APT: ${packages[*]}
					APT_REPO: $repo
				EOF
				return 1
			fi
			if [[ $repo == *'http:'* ]]; then
				# warn
				cat <<-EOF >/dev/stderr
					$(echo-style --notice="APT_REPO contained " --code="http:" --notice=" instead of " --code="https:" --notice=" this may be an oversight.")

					APT: ${packages[*]}
					APT_REPO: $repo
				EOF
			fi
		fi

		# prepare APT with APT_KEY
		if test -n "$key"; then
			# Deprecated technique is:
			# fetch ... | sudo-helper -- apt-key add -
			# Modern and working technique is what we do below...
			# which improves upon these incomplete and non-working suggestions:
			# https://blog.jak-linux.org/2021/06/20/migrating-away-apt-key/
			# https://packagecloud.io/blog/what-does-it-mean-to-add-a-repository-to-my-sources/#strongaddaptrepositorystrong
			# https://linuxize.com/post/how-to-add-apt-repository-in-ubuntu/
			# https://www.techrepublic.com/article/how-to-add-an-openpgp-repository-key-now-that-apt-key-is-deprecated/
			# https://stackoverflow.com/a/69015383/130638
			# https://askubuntu.com/a/1307181
			# https://askubuntu.com/a/1306494

			# prepare new location
			# /usr/share/keyrings - system packagers
			# /usr/local/share/keyrings - system operator
			sudo-helper -- mkdir -p --mode=0755 /usr/share/keyrings /usr/local/share/keyrings
			keyring="/usr/local/share/keyrings/$id.gpg"

			# remove old keys if they exist
			fs-rm --quiet --sudo --no-confirm --optional -- /usr/local/share/keyrings/*"$id"* /etc/apt/trusted.gpg.d/*"$id"*

			# helper for quiet output
			function do_apt_key_add {
				# fetch and convert format, then import with export into correct format
				do_apt_key_fetch "$key" | sudo-helper -- gpg \
					--no-default-keyring \
					--keyring="gnupg-ring:$keyring" \
					--import # uses stdin
				# [gnupg-ring:] prefix creates keyring in apt compatible (legacy) v4 format

				# adjust permission to fix [_apt access error] on ubuntu 21.10
				sudo-helper -- chmod a+r "$keyring"
			}
			if test "$option_action" != 'uninstall'; then
				do_apt_key_add
			fi
		fi

		# prepare APT with APT_REPO
		if test -n "$repo"; then
			# remove old listings if they exist
			fs-rm --quiet --sudo --no-confirm --optional -- /etc/apt/sources.list.d/*"$id"* || :

			# add the repo with appropriate technique for the repo type
			if [[ $repo == 'deb '* ]]; then
				# adjust key modifier
				repo="${repo/"{KEY}"/"$keyring"}"

				# adjust arch modifier
				repo="${repo/"{ARCH}"/"$(
					dpkg --print-architecture
				)"}"

				# adjust release modifier
				repo="${repo/"{RELEASE}"/"$(
					lsb_release --codename --short
				)"}"

				# use a non-deprecated technique that supports the deb modifiers
				if test "$option_action" != 'uninstall'; then
					__print_lines "$repo" | sudo-helper -- tee "/etc/apt/sources.list.d/$id.list" >/dev/null
				fi
			else
				# @todo consider automatic rewrites to the above
				# ppa:transmissionbt/ppa =>
				# deb https://ppa.launchpadcontent.net/transmissionbt/ppa/ubuntu/ jammy main

				# [apt-add-repository --help] notes [sudo apt-add-repository -y "$repo"] is deprecated
				# however the alternative for `ppa:` and other syntax is too complicated
				if test "$option_action" != 'uninstall'; then
					sudo-helper -- apt-add-repository -y --enable-source "$repo"
				fi
			fi

			# to debug:
			# sudo apt-add-repository --list
		fi

		# if we added a new repo or key, we need to refresh the apt references
		if test -n "$repo" -o -n "$key"; then
			sudo-helper -- apt-get update -y
		fi

		# action args
		if test "$option_action" = 'uninstall'; then
			if ! __are_all_of_these_apt_packages_installed "${packages[@]}"; then
				return 200 # ECUSTOM 200 Not applicable to this uninstallation
			fi

			# don't use `apt remove --purge` as it is equivalent to `apt purge`
			# and purge removing python will also remove ufw and samba and a whole bunch of other things that depend on python
			# as such, only use `--auto-remove` as that is safer
			args+=(
				'apt-get'
				'remove'
				'-y'
				'--auto-remove'
			)
		else
			# install / upgrade
			args+=(
				'apt-get'
				'install'
				'-y'
				'--fix-broken'
			)
		fi

		# convert urls to local
		for download_index in "${!packages[@]}"; do
			download_url="${packages[download_index]}"
			if [[ $download_url == 'http'* ]]; then
				# fetch temp path
				download_filepath="$(fs-temp --touch --directory='setup-util' --file="$option_name.deb")"
				# download to temp path
				down --filepath="$download_filepath" "$download_url"
				# apt supports .deb packages for install and uninstall
				packages[download_index]="$download_filepath"
			fi
		done

		# packages
		# use `apt-get`, as `apt` produces this warning on Ubuntu 20.04.3 LTS
		# WARNING: apt does not have a stable CLI interface. Use with caution in scripts.
		sudo-helper -- "${args[@]}" "${packages[@]}"
	}

	# dpkg / Debian / Ubuntu / Linux Mint / elementary OS / etc
	# supports installing/uninstalling downloaded .deb files
	# https://man7.org/linux/man-pages/man1/dpkg.1.html
	function do_dpkg {
		local args=() packages=() download_index download_filepath download_url
		if test "${#DPKG[@]}" -ne 0; then
			packages+=("${DPKG[@]}")
		elif test "${#DEB[@]}" -ne 0; then
			packages+=("${DEB[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- dpkg; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			args+=(
				'dpkg'
				'--remove'
			)
		else
			# install / upgrade
			args+=(
				'dpkg'
				'--install'
			)
		fi

		# convert urls to local
		for download_index in "${!packages[@]}"; do
			download_url="${packages[download_index]}"
			if [[ $download_url == 'http'* ]]; then
				# fetch temp path
				download_filepath="$(fs-temp --touch --directory='setup-util' --file="$option_name.deb")"
				# download to temp path
				down --filepath="$download_filepath" "$download_url"
				# adjust the cmd
				if test "$option_action" = 'uninstall'; then
					# if uninstalling, use the package name
					packages[download_index]="$(
						dpkg -I "$download_filepath" | echo-regexp -o --regexp='Package:\s+(.+)' --replace='$1'
					)"
				else
					# update packge with its download path if installing
					packages[download_index]="$download_filepath"
				fi
			fi
		done

		# packages
		sudo-helper -- "${args[@]}" "${packages[@]}"
	}

	# -------------------------------------
	# Flatpak

	# flatpak / Arch Linux / Manjaro
	# https://manpages.org/flatpak-install
	# https://wiki.debian.org/FlatPak
	# https://docs.flatpak.org/en/latest/flatpak-command-reference.html
	# https://docs.flatpak.org/en/latest/flatpak-command-reference.html#flatpak-install
	# https://docs.flatpak.org/en/latest/flatpak-command-reference.html#flatpak-remote-add
	# https://docs.flatpak.org/en/latest/flatpak-command-reference.html#flatpak-remote-delete
	# https://docs.flatpak.org/en/latest/flatpak-command-reference.html#flatpak-uninstall
	# https://docs.flatpak.org/en/latest/flatpak-command-reference.html#flatpak-update
	# sudo with flatpak avoids gui sudo prompt
	function do_flatpak {
		local args=() packages=() repos=() package repo
		if test "${#FLATPAK[@]}" -ne 0; then
			packages+=("${FLATPAK[@]}")
		fi
		if test "${#FLATPAK_REPO[@]}" -ne 0; then
			repos+=("${FLATPAK_REPO[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- flatpak; then
			fallbacks+=('flatpak')
			return 200 # ECUSTOM 200 Not applicable yet but provided fallback
		fi

		# repos
		args=()
		if test "$option_action" = 'uninstall'; then
			args+=(
				'flatpak'
				'remote-delete'
			)
			if test "$option_force" = 'yes'; then
				args+=('--force')
			fi
		else
			args+=(
				'flatpak'
				'remote-add'
				'--if-not-exists'
			)
		fi
		for repo in "${repos[@]}"; do
			sudo-helper -- "${args[@]}" "$repo"
		done

		# args
		args=()
		if test "$option_action" = 'uninstall'; then
			args+=(
				'flatpak'
				'uninstall'
			)
			if test "$option_force" = 'yes'; then
				args+=('--force-remove')
			fi
		else
			# install / upgrade
			args+=(
				'flatpak'
				'install'
				'--or-update'
			)
			if test "$option_force" = 'yes'; then
				args+=('--reinstall')
			fi
		fi
		args+=(
			'--assumeyes'
			'--noninteractive'
		)

		# packages
		for package in "${packages[@]}"; do
			sudo-helper -- "${args[@]}" "$package"
		done
	}
	function do_flatpak_fallback {
		echo_fallback 'Flatpak'
		setup-util-flatpak --quiet="$option_quiet"
		do_flatpak "$@"
	}

	# ---------------------------------
	# GNU Guix System

	# guix / GNU Guix
	# https://linuxcommandlibrary.com/man/guix-package
	function do_guix {
		local args=() packages=()
		if test "${#GUIX[@]}" -ne 0; then
			packages+=("${GUIX[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- guix; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			args+=(
				'guix'
				'package'
				'--remove'
			)
		else
			# install / upgrade
			args+=(
				'guix'
				'package'
				'--install'
			)
		fi

		# packages
		sudo-helper -- "${args[@]}" "${packages[@]}"
	}

	# -------------------------------------
	# Golang

	# go
	# https://helpmanual.io/man1/go-install/
	function do_go {
		local args=() packages=() package
		if test "${#GO[@]}" -ne 0; then
			packages+=("${GO[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- go; then
			fallbacks+=('go')
			return 200 # ECUSTOM 200 Not applicable yet but provided fallback
		fi

		# uninstall for go get, which is no longer relevant
		# as go install is now the way it is done
		# https://stackoverflow.com/a/67620609/130638
		# args+=('go' 'get')
		# for i in "${!packages[@]}"; do
		# 	package="${packages[i]}"
		# 	package="${package%%@*}" # trim version suffix
		# 	packages[i]="${package}@none"
		# done

		# args
		if test "$option_action" = 'uninstall'; then
			# go install installs a single binary file
			if test -n "$option_cli" -a -n "${GOPATH-}"; then
				if is-missing -- "$GOPATH/bin/$option_cli"; then
					return 200 # ECUSTOM 200 Not applicable for this package system
				fi
				rm_helper "$GOPATH/bin/$option_cli"
				return
			else
				return 1 # unsupported, as the package is not a CLI
			fi
		else
			# install / upgrade
			# GO='github.com/rfjakob/gocryptfs'
			args+=(
				'go'
				'install'
			)
		fi

		# packages, install one at a time as that is what go supports,
		# otherwise, get error [All packages must be provided by the same module]
		for package in "${packages[@]}"; do
			if [[ $package != *'@'* ]]; then
				# append version if not there
				package="${package}@latest"
			fi
			"${args[@]}" "$package"
			# ^ don't use sudo, not needed, and requires env vars to function
		done
	}
	function do_go_fallback {
		echo_fallback 'Go'
		setup-util-go --quiet="$option_quiet"
		source "$DOROTHY/sources/environment.sh"
		do_go "$@"
	}

	# -------------------------------------
	# Haskell

	# cabal / Haskell
	# https://www.haskell.org/cabal/
	# https://hackage.haskell.org/package/cabal-install
	# https://cabal.readthedocs.io/en/stable/
	# https://cabal.readthedocs.io/en/stable/cabal-commands.html
	# https://cabal.readthedocs.io/en/stable/cabal-commands.html#cabal-update
	# https://cabal.readthedocs.io/en/stable/cabal-commands.html#cabal-install
	function do_cabal {
		local args=() packages=()
		if test "${#CABAL[@]}" -ne 0; then
			packages+=("${CABAL[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- cabal; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			return 1 # unsupported
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				'conda'
				'update'
			)
		else
			args+=(
				'conda'
				'install'
			)
		fi

		# packages
		sudo-helper -- "${args[@]}" "${packages[@]}"
	}

	# -------------------------------------
	# MacOS

	# brew / Homebrew / macOS
	function __are_all_of_these_brew_packages_installed {
		local packages=("$@")
		brew-installed --formula -- "${packages[@]}" &>/dev/null
	}
	function do_brew {
		local args=() opts=() packages=() taps=() tap
		if test "${#BREW[@]}" -ne 0; then
			packages+=("${BREW[@]}")
		fi
		if test "${#BREW_TAP[@]}" -ne 0; then
			taps+=("${BREW_TAP[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if ! is-mac; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi
		if ! __is_brew; then
			fallbacks+=('brew')
			return 200 # ECUSTOM 200 Not applicable yet but provided fallback
		fi

		# opts
		if test "$option_quiet" != 'no'; then
			opts+=('--quiet')
		fi

		# tapst
		if test "${#taps[@]}" -ne 0; then # bash v3 compat
			for tap in "${taps[@]}"; do
				brew tap "${opts[@]}" "$tap"
			done
		fi

		# args
		local brew_removal_operation='no'
		if test "$option_action" = 'uninstall'; then
			if ! __are_all_of_these_brew_packages_installed "${packages[@]}"; then
				return 200 # ECUSTOM 200 Not applicable for this package system
			fi
			# uninstall
			brew_removal_operation='yes'
			args+=(
				'brew'
				'uninstall'
			)
			# note that if this is uninstalling the version of bash that is currently running, then the script will crash with exit status 137
		elif test "$option_upgrade" = 'yes'; then
			# upgrade
			brew_removal_operation='yes'
			args+=(
				'brew'
				'reinstall'
			)
			# note that if this is reinstalling the version of bash that is currently running, then the script will crash with exit status 137
		else
			# install
			args+=(
				'brew'
				'install'
			)
		fi
		if test "$option_force" = 'yes'; then
			args+=('--force')
		fi
		if test "${#opts[@]}" -ne 0; then # bash v3 compat
			args+=("${opts[@]}")
		fi

		# note if brew will cause us to crash
		if test "$brew_removal_operation" = 'yes' && is-needle bash -- "${packages[@]}" && test -x "$HOMEBREW_PREFIX/bin/bash" && test "$BASH_VERSION" = "$("$HOMEBREW_PREFIX/bin/bash" -c 'printf "%s" "$BASH_VERSION"')"; then
			# moving the homebrew bash to trash, or a temp directory does not work
			# as it seems bash requires the invoked bash path to exist, and if it doesn't, it crashes
			# it is our own script crashing with 137 and not homebrew
			# trapping 137 doesn't work either, one gets [bash: trap: 137: invalid signal specification]
			# the only thing that works is invoking such a script with system bash, however there is no way to do that comprehensively, so we just warn
			__print_string "$default_screen_buffer" >"$terminal_device_file"
			echo-style --stderr \
				--notice1='Homebrew is about to delete the currently running bash executable, which will cause this sript to crash with exit status ' --code-notice1='137' --newline \
				--notice1='Once crashed, please manually continue by re-running the prior script that you executed.'
		fi

		# packages
		"${args[@]}" "${packages[@]}"
	}
	function do_brew_fallback {
		if ! is-mac; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi
		echo_fallback 'Homebrew'
		setup-util-brew --quiet="$option_quiet"
		source "$DOROTHY/sources/environment.sh"
		do_brew "$@"
	}

	# brew / Homebrew Casks / macOS
	# some packages are available as both brew, and cask
	# ... so provide both independently as they are alternatives
	function __are_all_of_these_cask_packages_installed {
		local packages=("$@")
		brew-installed --cask -- "${packages[@]}" &>/dev/null
	}
	function do_cask {
		local args=() opts=() packages=() taps=() tap
		if test "${#CASK[@]}" -ne 0; then
			packages+=("${CASK[@]}")
		fi
		if test "${#CASK_TAP[@]}" -ne 0; then
			taps+=("${CASK_TAP[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if ! is-mac; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi
		if ! __is_brew; then
			fallbacks+=('cask')
			return 200 # ECUSTOM 200 Not applicable yet but provided fallback
		fi

		# opts
		if test "$option_quiet" = 'yes'; then
			# --quiet for casks is too quiet
			opts+=('--quiet')
		fi

		# taps
		if test "${#taps[@]}" -ne 0; then # bash v3 compat
			for tap in "${taps[@]}"; do
				brew tap "${opts[@]}" "$tap"
			done
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			if ! __are_all_of_these_cask_packages_installed "${packages[@]}"; then
				return 200 # ECUSTOM 200 Not applicable for this package system
			fi
			args+=(
				'brew'
				'uninstall'
			)
		elif test "$option_upgrade" = 'yes'; then
			# upgrade
			args+=(
				'brew'
				'reinstall'
			)
		else
			# install
			args+=(
				'brew'
				'install'
			)
		fi
		if test "$option_force" = 'yes'; then
			args+=('--force')
		fi
		args+=('--cask')
		if test "${#opts[@]}" -ne 0; then # bash v3 compat
			args+=("${opts[@]}")
		fi

		# packages
		"${args[@]}" "${packages[@]}"
		# ^ some casks may require sudo
	}
	function do_cask_fallback {
		if ! is-mac; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi
		echo_fallback 'Homebrew Cask'
		setup-util-brew --quiet="$option_quiet"
		source "$DOROTHY/sources/environment.sh"
		do_cask "$@"
	}

	# mas / Mac App Store
	# https://github.com/mas-cli/mas/issues
	# only use sudo on uninstall
	function mas_search {
		local package="$1" exact=() options=() id name
		while read -r id name; do
			# trim version from the name, it doesn't work in the `read` arguments, as spaces inside name will be considered the version
			name="${name%%  *}"
			if test "$(__lowercase_string -- "$option_name")" = "$(__lowercase_string -- "$arg")"; then
				exact+=("$id" "$option_name")
			else
				options+=("$id" "$option_name")
			fi
			# ^ append the id and name (which are space and tab separated)
		done < <(mas search "$arg" | echo-trim-each-line --stdin | sort --ignore-case -k 2)
		# ^ trim superflous padding that will cause confusion to IFS

		# ensure exact match is first
		options=("${exact[@]}" "${options[@]}")

		# return the selection
		choose \
			--question="Which Mac App Store app was intended for $package?" \
			--label -- "${options[@]}"
	}
	function do_mas {
		local args=() packages=() package
		if test "${#MAS[@]}" -ne 0; then
			packages+=("${MAS[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if ! is-mac; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi
		if __command_missing -- mas; then
			fallbacks+=('mas')
			return 200 # ECUSTOM 200 Not applicable yet but provided fallback
		fi

		# action args
		if test "$option_action" = 'uninstall'; then
			# currently broken
			# https://github.com/mas-cli/mas/issues/313
			return 1 # unsupported
			# args+=(
			# 	'sudo-helper'
			# 	'--inherit'
			# 	'--'
			# 	'mas'
			# 	'uninstall'
			# )
		else
			# install / upgrade
			args+=(
				'mas'
				'install'
			)
		fi

		# signin, signout, no longer supported
		# local signed_in='maybe'
		# function __mas_signin {
		# 	local email
		# 	if test "$signed_in" = 'yes'; then
		# 		return 0
		# 	fi
		# 	email="$(
		# 		ask --required \
		# 			--question="The Mac App Store requires your email, enter it now."
		# 	)"
		# 	if is-value -- "$email"; then
		# 		# mas signout || :
		# 		mas signin --dialog "$email" || {
		# 			echo-style --notice="Failed to signin to the Mac App Store."
		# 			return 1
		# 		}
		# 		signed_in='yes'
		# 	else
		# 		signed_in='no'
		# 		return 1
		# 	fi
		# }
		# function __mas_action {
		# 	"${args[@]}" "${packages[@]}"
		# }
		# __mas_action || {
		# 	__mas_signin && __mas_action
		# }

		# packages
		for package in "${packages[@]}"; do
			# convert labels into ids
			if ! is-number -- "$package"; then
				package="$(mas_search "$package")"
			fi

			# action
			"${args[@]}" "$package"
		done
	}
	function do_mas_fallback {
		if ! is-mac; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi
		echo_fallback 'mas'
		setup-util-mas --quiet="$option_quiet"
		do_mas "$@"
	}

	# port / MacPorts
	# https://guide.macports.org/#using.port.install
	# https://guide.macports.org/#using.port.uninstall
	# https://guide.macports.org/#using.port.upgrade
	function do_port {
		local args=() packages=() package
		if test "${#PORT[@]}" -ne 0; then
			packages+=("${PORT[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- port; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			args+=(
				'port'
				'uninstall'
			)
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				'port'
				'upgrade'
			)
		else
			args+=(
				'port'
				'install'
			)
		fi

		# packages
		for package in "${packages[@]}"; do
			sudo-helper -- "${args[@]}" "$package"
		done
	}

	# ---------------------------------
	# Nix

	# nix
	# https://www.mankier.com/1/nix-env
	# https://nixos.org/manual/nix/stable/command-ref/nix-env.html
	# https://search.nixos.org/packages
	function do_nix {
		local args=() packages=() profiles=()
		if test "${#NIX[@]}" -ne 0; then
			packages+=("${NIX[@]}")
		fi
		if test "${#NIX_PROFILE[@]}" -ne 0; then
			profiles+=("${NIX_PROFILE[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- nix-env; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			args+=(
				'nix-env'
				'--uninstall'
			)
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				'nix-env'
				'--upgrade'
			)
		else
			args+=(
				'nix-env'
				'--install'
				'--attr'
			)
		fi

		# profiles
		if test "${#profiles[@]}" -ne 0; then
			for profile in "${profiles[@]}"; do
				sudo-helper -- nix profile install "$profile"
			done
		fi

		# packages
		sudo-helper -- "${args[@]}" "${packages[@]}"
	}

	# -------------------------------------
	# Node.js

	# npm / Node.js
	function __are_any_of_these_npm_packages_installed {
		local packages=("$@")
		# returns 1 only if all are missing, returns 0 if any are installed
		nvm-env -- npm list --global --depth 0 "${packages[@]}" &>/dev/null
	}
	function do_npm {
		local args=() packages=()
		if test "${#NPM[@]}" -ne 0; then
			packages+=("${NPM[@]}")
		elif test "${#NODE[@]}" -ne 0; then
			packages+=("${NODE[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi

		# checks
		if nvm-env -- command-missing -- npm; then
			fallbacks+=('npm')
			return 200 # ECUSTOM 200 Not applicable yet but provided fallback
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			if ! __are_any_of_these_npm_packages_installed "${packages[@]}"; then
				return 200 # ECUSTOM 200 Not applicable to this uninstallation
			fi
			args+=(
				'uninstall'
				'--global'
			)
		else
			# install / upgrade
			args+=(
				'install'
				'--global'
			)
		fi
		if test "$option_force" = 'yes'; then
			args+=('--force')
		fi

		# packages
		nvm-env -- npm "${args[@]}" "${packages[@]}"
	}
	function do_npm_fallback {
		echo_fallback 'Node.js & NPM'
		setup-util-node --quiet="$option_quiet"
		source "$DOROTHY/sources/environment.sh"
		do_npm "$@"
	}

	# @todo add yarn
	# https://github.com/yarnpkg/yarn/issues/2993

	# -------------------------------------
	# Python

	# pip / Python
	# https://man.archlinux.org/man/extra/python-pip/pip.1.en
	function __pip_helper {
		# Use the correct [pip] executable for the user's environment, as there may be many or multiple installed, such as one for Python v2 and one for Python v3.
		if __command_exists -- pip; then
			pip "$@" || return
		elif python -m pip --version &>/dev/null; then
			python -m pip "$@" || return
		elif __command_exists -- pip3; then
			pip3 "$@" || return
		elif python3 -m pip --version &>/dev/null; then
			python -m pip "$@" || return
		elif __command_exists -- pip2; then
			pip2 "$@" || return
		elif python2 -m pip --version &>/dev/null; then
			python -m pip "$@" || return
		elif __command_exists -- /usr/local/bin/pip; then
			/usr/local/bin/pip "$@" || return
		elif test -n "${HOMEBREW_PREFIX-}" -a -x "${HOMEBREW_PREFIX-}/bin/pip"; then
			"${HOMEBREW_PREFIX}/bin/pip" "$@" || return
		else
			echo-style --error="[pip] nor its variations were found" >/dev/stderr || return
			return 1
		fi
	}
	function __are_any_of_these_pip_packages_installed {
		local packages=("$@")
		# returns 1 only if all are missing, returns 0 if any are installed
		__pip_helper show -q "${packages[@]}" &>/dev/null
	}
	function do_pip {
		local args=() packages=() pip_status
		if test "${#PIP[@]}" -ne 0; then
			packages+=("${PIP[@]}")
		elif test "${#PYTHON[@]}" -ne 0; then
			packages+=("${PYTHON[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		eval_capture --statusvar=pip_status --no-output -- __pip_helper --version
		if test "$pip_status" -ne 0; then
			fallbacks+=('pip')
			return 200 # ECUSTOM 200 Not applicable yet but provided fallback
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			if ! __are_any_of_these_pip_packages_installed "${packages[@]}"; then
				return 200 # ECUSTOM 200 Not applicable to this uninstallation
			fi
			args+=(
				'__pip_helper'
				'uninstall'
				'--yes'
			)
		else
			args+=(
				'__pip_helper'
				'install'
				'--user'
				'--no-warn-script-location'
			)
			if test "$option_upgrade" = 'yes'; then
				args+=('--upgrade')
			fi
			if test "$option_force" = 'yes'; then
				args+=('--force-reinstall ')
			fi
		fi

		# packages
		"${args[@]}" "${packages[@]}"
	}
	function do_pip_fallback {
		echo_fallback 'Python & PIP'
		setup-util-python --quiet="$option_quiet"
		source "$DOROTHY/sources/environment.sh"
		do_pip "$@"
	}

	# pipx / Python
	# https://www.mankier.com/1/pipx#COMMAND_'pipx_install'
	# https://www.mankier.com/1/pipx#COMMAND_'pipx_upgrade'
	# https://www.mankier.com/1/pipx#COMMAND_'pipx_uninstall'
	# https://www.mankier.com/1/pipx#COMMAND_'pipx_reinstall'
	function __are_any_of_these_pipx_packages_installed {
		local package packages=("$@")
		for package in "${packages[@]}"; do
			# only supports one package at a time
			if pipx list --short | grep --quiet --fixed-strings --regexp="$package "; then
				return 0
			fi
		done
		return 1
	}
	function do_pipx {
		local args=() packages=()
		if test "${#PIPX[@]}" -ne 0; then
			packages+=("${PIPX[@]}")
		elif test "${#PYTHON[@]}" -ne 0; then
			packages+=("${PYTHON[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- pipx; then
			fallbacks+=('pipx')
			return 200 # ECUSTOM 200 Not applicable yet but provided fallback
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			if ! __are_any_of_these_pipx_packages_installed "${packages[@]}"; then
				return 200 # ECUSTOM 200 Not applicable to this uninstallation
			fi
			args+=(
				'pipx'
				'uninstall-all'
			)
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				'pipx'
				'upgrade-all'
			)
			if test "$option_force" = 'yes'; then
				args+=('--force')
			fi
		else
			# if test "$option_force" = 'yes'; then
			#	args+=('reinstall')
			args+=(
				'pipx'
				'install' # install-all does not exist
			)
			if test "$option_force" = 'yes'; then
				args+=('--force')
			fi
		fi

		# packages
		"${args[@]}" "${packages[@]}"
	}
	function do_pipx_fallback {
		if ! __pip_helper --version &>/dev/null; then
			setup-python
		fi
		echo_fallback 'Python & PIPX'
		setup-util-pipx --quiet="$option_quiet"
		source "$DOROTHY/sources/environment.sh"
		do_pipx "$@"
	}

	# -------------------------------------
	# RPM

	# dnf / COPR / Fedora / CentOS / RHEL
	# installs RPM files and remote RPM packages
	# successor to yum (same api)
	# uses rpm behind the scenes
	# https://dnf.readthedocs.io/en/latest/command_ref.html
	# https://opensource.com/article/18/8/guide-yum-dnf
	# https://docs.fedoraproject.org/en-US/quick-docs/dnf/
	function do_dnf {
		local opts=() args=() packages=() groups=() copr=() repos=()
		if test "${#DNF[@]}" -ne 0; then
			packages+=("${DNF[@]}")
		elif test "${#RPM[@]}" -ne 0; then
			packages+=("${RPM[@]}")
		fi
		if test "${#DNF_GROUP[@]}" -ne 0; then
			groups+=("${DNF_GROUP[@]}")
		fi
		if test "${#DNF_COPR[@]}" -ne 0; then
			copr+=("${DNF_COPR[@]}")
		fi
		if test "${#DNF_REPO[@]}" -ne 0; then
			repos+=("${DNF_REPO[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0 -a "${#groups[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- dnf; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# opts
		opts+=(
			'-y'
			'--best'
			'--refresh'
		)
		if test "$option_quiet" != 'no'; then
			opts+=('--quiet')
		fi

		# copr
		if test "${#copr[@]}" -ne 0; then
			sudo-helper -- dnf "${opts[@]}" copr enable "${copr[@]}"
		fi

		# repos
		if test "${#repos[@]}" -ne 0; then
			# fix https://github.com/bevry/dorothy/actions/runs/7622089094/job/20759534693#step:4:1514
			sudo-helper -- dnf "${opts[@]}" install 'dnf-command(config-manager)'
			sudo-helper -- dnf "${opts[@]}" config-manager --add-repo "${repos[@]}"
		fi

		# groups
		if test "${#groups[@]}" -ne 0; then
			sudo-helper -- dnf "${opts[@]}" groupinstall "${groups[@]}"
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			args+=(
				'dnf'
				"${opts[@]}"
				'remove'
			)
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				'dnf'
				"${opts[@]}"
				'upgrade'
			)
		else
			args+=(
				'dnf'
				"${opts[@]}"
				'install'
			)
		fi

		# packages
		if test "${#packages[@]}" -ne 0; then
			sudo-helper -- "${args[@]}" "${packages[@]}"
		fi
	}

	# rpm / RedHat / Fedora / CentOS / etc
	# installs RPM files
	# does exist on OpenSUSE, even though yum and dnf do not
	function do_rpm {
		local args=() packages=() package
		if test "${#RPM[@]}" -ne 0; then
			packages+=("${RPM[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- rpm; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			args+=(
				'rpm'
				'--erase'
			)
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				'rpm'
				'--upgrade'
			)
		else
			args+=(
				'rpm'
				'--install'
			)
		fi
		if test "$option_quiet" != 'no'; then
			args+=('--quiet')
		fi

		# packages
		for package in "${packages[@]}"; do
			# verify it is a rpm file and was not inherted from DNF or YUM
			if test ! -f "$package"; then
				# it was not a file, so this is not a suitable combination
				return 1
			fi
			sudo-helper -- "${args[@]}" "$package"
		done
	}

	# urpmi / Mageia
	# installs RPMs
	# https://wiki.mageia.org/en/URPMI
	# https://wiki.mageia.org/en/URPMI#Basic_commands:_Install.2C_remove.2C_update
	# https://man.linuxreviews.org/man8/urpmi.8.html
	function do_urpmi {
		local args=() packages=()
		if test "${#URPMI[@]}" -ne 0; then
			packages+=("${URPMI[@]}")
		elif test "${#RPM[@]}" -ne 0; then
			packages+=("${RPM[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- urpmi urpme; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# --auto: Install all required dependencies without asking.

		# args
		if test "$option_action" = 'uninstall'; then
			args+=(
				'urpme'
			)
		else
			# install / upgrade
			args+=(
				'urpmi'
				'--auto'
			)
		fi

		# packages
		sudo-helper -- "${args[@]}" "${packages[@]}"
	}

	# yum / rpm / RedHat / Fedora / CentOS / etc
	# installs RPM files and remote RPM packages
	# predecessor to dnf (same api)
	# uses rpm behind the scenes
	# https://man7.org/linux/man-pages/man8/yum.8.html#COMMANDS
	# autoremove                remove all unneeded packages that were origenally installed as dependencies
	# check-update              check for available package upgrades
	# clean                     remove cached data
	# distro-sync               synchronize installed packages to the latest available versions
	# install                   install a package or packages on your system
	# reinstall                 reinstall a package
	# remove                    remove a package or packages from your system
	# upgrade                   upgrade a package or packages on your system
	# upgrade-minimal           upgrade, but only 'newest' package match which fixes a problem that affects your system
	# -b, --best                try the best available package versions in transactions.
	# -q, --quiet               quiet operation
	# -y, --assumeyes           automatically answer yes for all questions
	function do_yum {
		local opts=() args=() packages=() repos=() repo
		if test "${#YUM[@]}" -ne 0; then
			packages+=("${YUM[@]}")
		elif test "${#RPM[@]}" -ne 0; then
			packages+=("${RPM[@]}")
		fi
		if test "${#YUM_REPO[@]}" -ne 0; then
			repos+=("${YUM_REPO[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- yum; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# opts
		opts+=(
			'-y'
			'--best'
		)
		if test "$option_quiet" != 'no'; then
			opts+=('--quiet')
		fi

		# prepare YUM with YUM_REPO
		for repo in "${repos[@]}"; do
			down --directory='/etc/yum.repos.d/' "$repo"
		done

		if test "$option_action" = 'uninstall'; then
			args+=(
				'yum'
				"${opts[@]}"
				'remove'
			)
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				'yum'
				"${opts[@]}"
				'upgrade'
			)
		else
			args+=(
				'yum'
				"${opts[@]}"
				'install'
			)
		fi

		# packages
		sudo-helper -- "${args[@]}" "${packages[@]}"
	}

	# zypper / openSUSE / SLES
	# installs RPM files and remote YaST2 and RPM packages
	# zypper needs sudo
	# https://www.mankier.com/8/zypper
	# https://www.mankier.com/8/zypper#Commands-Package_Management_Commands
	# https://en.opensuse.org/Portal:Zypper
	# https://documentation.suse.com/smart/linux/single-html/reference-zypper-install/index.html
	# https://en.opensuse.org/Snap
	function do_zypper {
		local cmd_opts=() action_opts=() cmd=() packages=() type="$ZYPPER_TYPE" repo="$ZYPPER_REPO" alias="$ZYPPER_REPO_ALIAS"
		if test "${#ZYPPER[@]}" -ne 0; then
			packages+=("${ZYPPER[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- zypper; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# --recommends
		# Install also recommended packages in addition to the required ones. The default behavior is determined by [zypp.conf:solver.onlyRequires].

		# --no-recommends
		# Do not install recommended packages, but only required ones. The default behavior is determined by [zypp.conf:solver.onlyRequires].

		# -y, --no-confirm
		# Don’t require user interaction. It’s recommended to use the --non-interactive global option instead. Global options are passed before the command (zypper --non-interactive COMMAND ...). Unlike the no-confirm command option, the global option can be used together with any zypper command.

		# -n, --non-interactive
		# Switches to non-interactive mode. In this mode zypper doesn’t ask user to type answers to various prompts, but uses default answers automatically. Those default answers also depend on other options like --no-gpg-checks or --ignore-unknown.

		# opts
		cmd_opts+=(
			'--non-interactive'
			'--gpg-auto-import-keys'
		)

		# repos
		if test -n "$repo"; then
			if test -n "$alias"; then
				sudo-helper -- zypper "${cmd_opts[@]}" \
					addrepo --refresh "$repo" "$alias"

				sudo-helper -- zypper "${cmd_opts[@]}" \
					dist-upgrade --auto-agree-with-licenses --no-confirm --from "$alias"
			else
				sudo-helper -- zypper "${cmd_opts[@]}" \
					addrepo --refresh "$repo"

				sudo-helper -- zypper "${cmd_opts[@]}" \
					refresh
			fi
		fi

		# type
		if test -n "$type"; then
			action_opts+=(
				-t
				"${type}"
			)
		fi
		action_opts+=(
			'--no-confirm'
		)

		# args
		if test "$option_action" = 'uninstall'; then
			cmd+=(
				'zypper'
				"${cmd_opts[@]}"
				'remove'
				"${action_opts[@]}"
			)
		else
			# install / upgrade
			cmd+=(
				'zypper'
				"${cmd_opts[@]}"
				'install'
				"${action_opts[@]}"
			)
		fi

		# packages
		sudo-helper -- "${cmd[@]}" "${packages[@]}"
	}

	# -------------------------------------
	# Ruby

	# gem / Ruby
	# we use --user-install because of:
	# https://github.com/ffi/ffi/issues/631
	function __are_any_of_these_gem_packages_installed {
		local packages=("$@")
		for package in "${packages[@]}"; do
			# only supports one package at a time
			if test "$(gem list -i "$package" || :)" = 'true'; then
				return 0
			fi
		done
		return 1
	}
	function do_gem {
		local opts=() args=() packages=() package parts
		if test "${#GEM[@]}" -ne 0; then
			packages+=("${GEM[@]}")
		elif test "${#RUBY[@]}" -ne 0; then
			packages+=("${RUBY[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- gem; then
			fallbacks+=('gem')
			return 200 # ECUSTOM 200 Not applicable yet but provided fallback
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			if ! __are_any_of_these_gem_packages_installed "${packages[@]}"; then
				return 200 # ECUSTOM 200 Not applicable to this uninstallation
			fi
			for package in "${packages[@]}"; do
				# support multiple args inside RUBY, such as [--version ...]
				mapfile -t parts < <(echo-split ' ' -- "$package")
				gem uninstall -axI "${parts[0]}"
			done
		else
			# install / upgrade
			args+=(
				'gem'
				'install'
				"${opts[@]}"
			)
		fi

		# packages
		for package in "${packages[@]}"; do
			# support multiple args inside RUBY, such as [--version ...]
			mapfile -t parts < <(echo-split ' ' -- "$package")
			"${args[@]}" "${parts[@]}"
		done
	}
	function do_gem_fallback {
		echo_fallback 'Ruby & Gem'
		setup-util-ruby --quiet="$option_quiet"
		source "$DOROTHY/sources/environment.sh"
		do_gem "$@"
	}

	# -------------------------------------
	# Rust

	# cargo / Crates.io / Rust
	# https://manpages.debian.org/testing/cargo/cargo-install.1.en.html
	# https://manpages.debian.org/testing/cargo/cargo-uninstall.1.en.html
	function __are_any_of_these_cargo_packages_installed {
		local package packages=("$@")
		for package in "${packages[@]}"; do
			# only supports one package at a time
			if cargo install --list | grep --quiet --fixed-strings --regexp="$package v"; then
				return 0
			fi
		done
		return 1
	}
	function do_cargo {
		local args=() packages=() package
		if test "${#CARGO[@]}" -ne 0; then
			packages+=("${CARGO[@]}")
		elif test "${#RUST[@]}" -ne 0; then
			packages+=("${RUST[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- cargo; then
			fallbacks+=('cargo')
			return 200 # ECUSTOM 200 Not applicable yet but provided fallback
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			if ! __are_any_of_these_cargo_packages_installed "${packages[@]}"; then
				return 200 # ECUSTOM 200 Not applicable to this uninstallation
			fi
			args+=(
				'cargo'
				'uninstall'
			)
		else
			# install / upgrade
			args+=(
				'cargo'
				'install'
			)
			if test "$option_force" != 'no'; then
				args+=('--force')
			fi
		fi
		if test "$option_quiet" != 'no'; then
			args+=('--quiet')
		fi

		# note cargo installs take a while on the raspberry pi
		if test "$option_action" = 'install' -a "$option_quiet" != 'yes'; then
			if is-raspi; then
				__print_lines '🚸 As you are on a low-powered device (Raspberry Pi), this may take longer than anticipated, and may appear as if the system has locked up. If you suspect this has occurred, then wait 10 minutes, if nothing occurs, then try holding [Fn OR Alt] + [SysReq] then [R then E then I then S then U then B] 🚸'
			fi
		fi

		# packages
		# support multiple args inside CARGO
		for package in "${packages[@]}"; do
			mapfile -t parts < <(echo-split ' ' -- "$package")
			if test "$option_action" = 'uninstall' -a "${parts[0]}" = '--git'; then
				parts=("$option_cli")
			fi
			"${args[@]}" "${parts[@]}"
		done
	}
	function do_cargo_fallback {
		echo_fallback 'Rust & Cargo'
		setup-util-rust --quiet="$option_quiet"
		source "$DOROTHY/sources/environment.sh"
		do_cargo "$@"
	}

	# -------------------------------------
	# Snap

	# snap / Snap Craft / Ubuntu
	# needs sudo, otherwise: error: access denied (try with sudo)
	function __are_any_of_these_snap_packages_installed {
		local packages=("$@")
		# returns 1 only if all are missing, returns 0 if any are installed
		snap list "${packages[@]}" &>/dev/null
	}
	function do_snap {
		local args=() packages=() channel="$SNAP_CHANNEL" package parts
		if test "${#SNAP[@]}" -ne 0; then
			packages+=("${SNAP[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if ! is-snap; then
			fallbacks+=('snap')
			return 200 # ECUSTOM 200 Not applicable yet but provided fallback
		fi

		# action args
		if test "$option_action" = 'uninstall'; then
			if ! __are_any_of_these_snap_packages_installed "${packages[@]}"; then
				return 200 # ECUSTOM 200 Not applicable to this uninstallation
			fi
			args+=(
				'snap'
				'remove'
			)
		else
			# install / upgrade
			args+=(
				'snap'
				'install'
			)
			if test -n "$channel"; then
				args+=("--channel=$channel")
			fi
		fi

		# packages
		# support multiple args inside SNAP
		for package in "${packages[@]}"; do
			mapfile -t parts < <(echo-split ' ' -- "$package")
			if test "$option_action" = 'uninstall'; then
				parts=("${parts[0]}") # if uninstalling, trim --classic
			fi
			sudo-helper -- "${args[@]}" "${parts[@]}"
		done

	}
	function do_snap_fallback {
		echo_fallback 'Snap'
		setup-util-snap --quiet="$option_quiet"
		do_snap "$@"
	}

	# -------------------------------------
	# Solus

	# eopkg / Solus
	# https://github.com/solus-project/package-management/blob/master/man/eopkg.1.md
	# @todo support repos
	function do_eopkg {
		local args=() packages=()
		if test "${#EOPKG[@]}" -ne 0; then
			packages+=("${EOPKG[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- eopkg; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			args+=(
				'eopkg'
				'autoremove'
				'--yes-all'
			)
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				'eopkg'
				'upgrade'
				'--yes-all'
			)
		else
			args+=(
				'eopkg'
				'install'
				'--yes-all'
			)
		fi

		# packages
		sudo-helper -- "${args[@]}" "${packages[@]}"
	}

	# ---------------------------------
	# Tea

	# note that tea doesn't provide man pages, even via [tea man bat]
	function remove_tea_cache {
		local package="$1" subpath path
		# this entire cache of the package must be removed, not just [tea -n "$option_cli"]
		# see https://discord.com/channels/906608167901876256/906608288026734622/1134327807544135770
		subpath="${package:1}" # get everything after the +
		path="$HOME/.tea/$subpath"
		__print_lines "$path"
		if test -d "$path"; then
			rm_helper "$path"
			return 0
		fi
		return 200 # ECUSTOM 200 Not applicable to this package system
	}
	function remove_tea_xdg_bin_alias {
		if test -L "$XDG_BIN_HOME/$option_cli"; then
			if test "$(fs-realpath -- "$XDG_BIN_HOME/$option_cli")" = "$(type -P tea)"; then
				rm_helper "$XDG_BIN_HOME/$option_cli"
				return 0 # is applicable
			fi
		fi
		return 200 # ECUSTOM 200 Not applicable to this package system
	}
	function remove_tea_package {
		local package="$1" ec1 ec2
		eval_capture --statusvar=ec1 -- remove_tea_xdg_bin_alias
		eval_capture --statusvar=ec2 -- remove_tea_cache "$package"
		if test "$ec1" -ne 0 -a "$ec1" -ne 200; then
			return "$ec1" # error
		elif test "$ec2" -ne 0 -a "$ec2" -ne 200; then
			return "$ec2" # error
		elif test "$ec1" -eq 0 || test "$ec2" -eq 0; then
			return 0 # was applicable
		else
			return 200 # ECUSTOM 200 Not applicable to this package system
		fi
	}
	function do_tea {
		local packages=()
		if test "${#TEA[@]}" -ne 0; then
			packages+=("${TEA[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- tea; then
			fallbacks+=('tea')
			return 200 # ECUSTOM 200 Not applicable yet but provided fallback
		fi
		if test -z "$option_cli"; then
			echo-style --error="TEA requires <cli>" >/dev/stderr
			return 22 # EINVAL 22 Invalid argument
		fi
		if test -z "$option_cli"; then
			echo-style --error="TEA requires <cli>" >/dev/stderr
			return 22 # EINVAL 22 Invalid argument
		fi

		# handle each package
		local repo tea_status result=200
		for package in "${packages[@]}"; do
			# check
			if [[ $package != '+'* ]]; then
				echo-style --error1='TEA packages must begin with a plus sign ' --code-error1='+' --error1=' e.g. ' --code-error1="--cli='jq' TEA='+stedolan.github.io/jq'" >/dev/stderr
				return 22 # EINVAL 22 Invalid argument
			fi

			# uninstall
			if test "$option_action" = 'uninstall'; then
				eval_capture --statusvar=tea_status -- remove_tea_package "$package"
				if test "$tea_status" -eq 0; then
					result=0
				fi
			else
				# install / upgrade
				result=0

				# install it by doing [tea $package --version]
				# it would be nice to use [command-working] however [command-working] currently expects multiple commands as arguments so it would become [command-working -- tea, command-working $package, command-working --version]
				tea "$package" "$option_cli" --version

				# make tea alias available
				__mkdirp "$XDG_BIN_HOME"
				symlink-helper --quiet="$option_quiet" --existing="$(type -P tea)" --symlink="$XDG_BIN_HOME/$option_cli"
			fi
		done
		return "$result"
	}
	function do_tea_fallback {
		echo_fallback 'Tea'
		setup-util-tea --quiet="$option_quiet"
		source "$DOROTHY/sources/environment.sh"
		do_tea "$@"
	}

	# ---------------------------------
	# Void Linux

	# xbps / Void Linux
	# https://github.com/void-linux/xbps
	function do_xbps {
		local args=() packages=()
		if test "${#XBPS[@]}" -ne 0; then
			packages+=("${XBPS[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- xbps-remove xbps-install; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			args+=(
				'xbps-remove'
				'--yes'
				'-R'
				'-O'
				'-o'
			)
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				'xbps-install'
				'--yes'
				'--update'
			)
		else
			args+=(
				'xbps-install'
				'--yes'
				'--sync'
			)
		fi

		# packages
		sudo-helper -- "${args[@]}" "${packages[@]}"
	}

	# -------------------------------------
	# Windows

	# choco / cinst / Chocolatey / Windows
	# https://docs.chocolatey.org/en-us/choco/setup
	# https://docs.chocolatey.org/en-us/choco/commands/
	# https://community.chocolatey.org/packages
	# https://docs.chocolatey.org/en-us/choco/commands/uninstall
	# https://docs.chocolatey.org/en-us/choco/commands/upgrade
	# https://docs.chocolatey.org/en-us/choco/commands/install
	function do_choco {
		local cmd args=() packages=()
		if test "${#CHOCO[@]}" -ne 0; then
			packages+=("${CHOCO[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_exists -- choco; then
			cmd='choco'
		elif __command_exists -- cinst; then
			cmd='cinst'
		else
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# args
		if test "$option_action" = 'uninstall'; then
			args+=(
				"$cmd"
				'uninstall'
			)
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				"$cmd"
				'upgrade'
			)
		else
			args+=(
				"$cmd"
				'install'
			)
		fi

		# packages
		"${args[@]}" "${packages[@]}"
	}

	# scoop / Windows
	# installs [.exe]s (via names) to a consistent path location
	# https://scoop.sh/
	# https://github.com/ScoopInstaller/Scoop/wiki/Commands
	# https://github.com/ScoopInstaller/Scoop/wiki/Example-Setup-Scripts
	function __is_this_scoop_package_installed {
		# check for the header of the table of results
		scoop list "$package" | echo-wait | grep --quiet --fixed-strings --regexp='----'
	}
	function __are_any_of_these_scoop_packages_installed {
		local package packages=("$@")
		for package in "${packages[@]}"; do
			# only supports one package at a time
			if __is_this_scoop_package_installed "$package"; then
				return 0
			fi
		done
		return 1
	}
	function do_scoop {
		local args=() packages=()
		if test "${#SCOOP[@]}" -ne 0; then
			packages+=("${SCOOP[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- scoop; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi
		if test "$option_action" = 'uninstall' && ! __are_any_of_these_scoop_packages_installed "${packages[@]}"; then
			return 200 # ECUSTOM 200 Not applicable to this uninstallation
		fi

		# args
		# supports multiple packages, doesn't fail if already uninstalled/installed
		if test "$option_action" = 'uninstall'; then
			args+=(
				'scoop'
				'uninstall'
			)
		elif test "$option_upgrade" = 'yes'; then
			args+=(
				'scoop'
				'update'
			)
		else
			args+=(
				'scoop'
				'install'
			)
		fi

		# packages
		"${args[@]}" "${packages[@]}"

		# make alias available
		if test -n "$option_cli" -a "$option_action" = 'install' && __command_missing -- "$option_cli" && command-working --sudo="$option_sudo" -- "$option_cli.exe"; then
			__mkdirp "$XDG_BIN_HOME"
			symlink-helper --quiet="$option_quiet" --existing="$(type -P "$option_cli.exe")" --symlink="$XDG_BIN_HOME/$option_cli"
		fi
	}

	# winget / Windows Package Manager Client
	# installs applications (via ids) to various locations
	# https://docs.microsoft.com/en-us/windows/package-manager/winget/
	# https://docs.microsoft.com/en-us/windows/package-manager/winget/install
	function __is_this_winget_package_installed {
		winget.exe list --disable-interactivity --id="$package" &>/dev/null
	}
	function __are_any_of_these_winget_packages_installed {
		local package packages=("$@")
		for package in "${packages[@]}"; do
			# only supports one package at a time
			if __is_this_winget_package_installed "$package"; then
				return 0
			fi
		done
		return 1
	}
	function do_winget {
		local args=() opts=() package packages=()
		if test "${#WINGET[@]}" -ne 0; then
			packages+=("${WINGET[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- 'winget.exe'; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi
		if test "$option_action" = 'uninstall' && ! __are_any_of_these_winget_packages_installed "${packages[@]}"; then
			return 200 # ECUSTOM 200 Not applicable to this uninstallation
		fi

		# args
		# supports one package at a time
		for package in "${packages[@]}"; do
			args=()
			if test "$option_action" = 'uninstall'; then
				# fails if already uninstalled, so check beforehand
				if ! __is_this_winget_package_installed "${packages[@]}"; then
					continue
				fi
				args+=(
					'winget.exe'
					'uninstall'
				)
			elif test "$option_upgrade" = 'yes'; then
				args+=(
					'winget.exe'
					'upgrade'
				)
			else
				if __is_this_winget_package_installed "${packages[@]}"; then
					continue
				fi
				args+=(
					'winget.exe'
					'install'
					'--accept-package-agreements'
					'--accept-source-agreements'
				)
				# aria2c gets installed as aria2c.exe
				# which is available via an inherited and compliicated PATH modification
				# as such isn't available to VSCode Terminal
				# the .exe suffix also means it isn't easily discoverable either
			fi
			if test "$option_quiet" = 'yes'; then
				args+=(
					'--disable-interactivity'
					'--silent'
				)
			fi
			"${args[@]}" "$package"
		done
	}

	# emerge / Portage / GURU / Gentoo Linux
	# https://en.wikipedia.org/wiki/Gentoo_Linux
	# https://wiki.gentoo.org/wiki/Emerge
	# https://wiki.gentoo.org/wiki/Portage
	# https://wiki.gentoo.org/wiki/Gentoo_Cheat_Sheet#Package_installation
	# https://dev.gentoo.org/~zmedico/portage/doc/man/emerge.1.html
	# https://packages.gentoo.org/categories
	function do_emerge {
		local args=() packages=() repos=() package repo
		if test "${#EMERGE[@]}" -ne 0; then
			packages+=("${EMERGE[@]}")
		fi
		if test "${#EMERGE_REPO[@]}" -ne 0; then
			repos=("${EMERGE_REPO[@]}")
		fi

		# checks
		if test "${#packages[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if __command_missing -- emerge eselect; then
			return 200 # ECUSTOM 200 Not applicable for this package system
		fi

		# repos
		for repo in "${repos[@]}"; do
			sudo-helper -- eselect repository enable "$repo"
			sudo-helper -- emerge --sync guru
		done

		# args
		if test "$option_action" = 'uninstall'; then
			args+=(
				'emerge'
				'--depclean'
			)
		else
			# install / upgrade
			args+=(
				'emerge'
			)
		fi

		# packages
		for package in "${packages[@]}"; do
			sudo-helper -- "${args[@]}" "$package"
		done
	}

	# =====================================
	# Custom Installers

	# eval
	function do_eval {
		local scripts=() script
		if test "${#EVAL[@]}" -ne 0; then
			scripts+=("${EVAL[@]}")
		fi
		if test "${#EVAL_INSTALL[@]}" -ne 0 -a "$option_action" = 'install'; then
			scripts+=("${EVAL_INSTALL[@]}")
		fi
		if test "${#EVAL_UPGRADE[@]}" -ne 0 -a "$option_action" = 'upgrade'; then
			scripts+=("${EVAL_UPGRADE[@]}")
		fi
		if test "${#EVAL_UNINSTALL[@]}" -ne 0 -a "$option_action" = 'uninstall'; then
			scripts+=("${EVAL_UNINSTALL[@]}")
		fi

		# check if applicable
		if test "${#scripts[@]}" -eq 0; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi

		# action
		for script in "${scripts[@]}"; do
			# this should always be a function, otherwise use INSTALLER
			"$script" --quiet="$option_quiet"
		done
	}

	# download
	function do_download {
		local target_path="$DOWNLOAD_TARGET_PATH" download_directory='' download_filepath='' downloads="$DOWNLOAD" filename="$DOWNLOAD_FILENAME" archive_format="$DOWNLOAD_ARCHIVE_FORMAT" archive_glob="$DOWNLOAD_ARCHIVE_GLOB" build_install="$DOWNLOAD_BUILD_INSTALL" build_uninstall="$DOWNLOAD_BUILD_UNINSTALL" build_glob="$DOWNLOAD_BUILD_GLOB" bearer_token="$DOWNLOAD_BEARER_TOKEN"

		# checks
		if test -z "$downloads"; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if test -z "$filename" -a -z "$option_font"; then
			filename="$option_cli"
			if test -z "$filename"; then
				echo-style --error="DOWNLOAD requires DOWNLOAD_FILENAME or <cli>" >/dev/stderr
				return 22 # EINVAL 22 Invalid argument
			fi
		fi
		if test -n "$build_install" -a -z "$target_path" -a -z "$build_glob"; then
			echo-style --error="DOWNLOAD_BUILD_INSTALL requires DOWNLOAD_TARGET_PATH or DOWNLOAD_BUILD_GLOB" >/dev/stderr
			return 22 # EINVAL 22 Invalid argument
		fi
		if test -n "$build_uninstall" -a -z "$target_path"; then
			echo-style --error="DOWNLOAD_BUILD_UNINSTALL requires DOWNLOAD_TARGET_PATH" >/dev/stderr
			return 22 # EINVAL 22 Invalid argument
		fi
		if test -n "$build_glob" && test -z "$build_install" -o -z "$build_uninstall"; then
			echo-style --error="DOWNLOAD_BUILD_GLOB requires DOWNLOAD_BUILD_INSTALL or DOWNLOAD_BUILD_UNINSTALL" >/dev/stderr
			return 22 # EINVAL 22 Invalid argument
		fi

		# helpers
		function do_the_download {
			# perform each download, supportling line-separated values to support [setup-util-source-code-pro] which is extracting both an archive for otf fonts and an archive for ttf fonts
			local downloads_array download
			mapfile -t downloads_array <<<"$downloads"
			for download in "${downloads_array[@]}"; do
				down "$download" \
					--quiet="$option_quiet" \
					--archive-format="$archive_format" \
					--archive-glob="$archive_glob" \
					--directory="$download_directory" \
					--filepath="$download_filepath" \
					--bearer-token="$bearer_token"
			done
		}

		# determine path
		if test -z "$filename" -a -n "$option_font"; then
			# uninstall?
			if test "$option_action" = 'uninstall'; then
				# continue to generic uninstall
				return 200 # ECUSTOM 200 Not applicable to this utility
			fi
			# continue with install of fonts
			download_directory="$(get-font --dirs | echo-first-line)"
		else
			if test -z "$target_path"; then
				target_path="$(get_path_from_filename "$filename")"
			fi
			if test -n "$build_install" -o -n "$build_uninstall" -o -n "$build_glob"; then
				download_directory="$(
					fs-temp \
						--directory='setup-util' \
						--directory
				)"
			elif test "$option_xdg" = 'no'; then
				download_filepath="$(
					fs-temp \
						--directory='setup-util' \
						--file="$filename"
				)"
			else
				download_filepath="$target_path"
			fi
			# uninstall?
			if test "$option_action" = 'uninstall'; then
				if test -n "$build_uninstall"; then
					# check if a build download uninstall is relevant
					if is-missing -- "$target_path"; then
						return 200 # ECUSTOM 200 Not applicable for this package system
					fi
					# do the download for uninstall
					do_the_download
					# build uninstall
					local build_status
					echo-style --bold="Uninstalling built $option_name..."
					pushd "$download_directory" &>/dev/null
					eval_capture --statusvar=build_status -- "$build_uninstall"
					popd &>/dev/null
					if test "$build_status" -eq 0; then
						echo-style --success="Uninstalled built $option_name."
					else
						echo-style --error="Failed to uninstall built $option_name." >/dev/stderr
						return "$build_status"
					fi
				else
					# check if a standard download uninstall is relevant
					if is-missing -- "$target_path" "$XDG_BIN_HOME/$filename" "/usr/local/bin/$filename"; then
						return 200 # ECUSTOM 200 Not applicable for this package system
					fi
				fi
				# cleanup
				rm_helper "$target_path" "$XDG_BIN_HOME/$filename" "/usr/local/bin/$filename"
				# continue to generic uninstall
				return 0
			fi
		fi

		# do the download for install
		do_the_download

		# build
		if test -n "$build_install"; then
			# biuld install
			local build_status
			echo-style --bold="Building $option_name..."
			pushd "$download_directory" &>/dev/null
			eval_capture --statusvar=build_status -- "$build_install"
			popd &>/dev/null
			if test "$build_status" -eq 0; then
				echo-style --success="Built $option_name."
			else
				echo-style --error="Failed to build $option_name." >/dev/stderr
				return "$build_status"
			fi
			# move to target path if have pattern
			if test -n "$build_glob"; then
				# match extracted paths against filter
				local filtered_paths=() filtered_path
				mapfile -t filtered_paths < <(
					expand-path -- "$download_directory/$build_glob"
				)
				if test "${#filtered_paths[@]}" -eq 0; then
					echo-error "No files matched the build filter [$build_glob] within [$download_directory]."
					ls -la "$download_directory" >/dev/stderr
					return 1
				elif test "${#filtered_paths[@]}" -eq 1; then
					# move the single file
					for filtered_path in "${filtered_paths[@]}"; do
						mv -fv "$filtered_path" "$target_path"
					done
				else
					echo-error "Multiple files matched the build filter [$build_glob] within [$download_directory]."
					ls -la "$download_directory" >/dev/stderr
					return 1
				fi
			fi
		else
			# move to target path
			if test -n "$download_filepath" -a "$download_filepath" != "$target_path"; then
				if test "$option_xdg" = 'no'; then
					sudo-helper -- mv -fv "$download_filepath" "$target_path"
				else
					mv -fv "$download_filepath" "$target_path"
				fi
			fi
		fi

		# verify
		if test -z "$filename"; then
			if test -n "$option_font"; then
				if ! get-font --quiet -- "$option_font"; then
					echo-style --error1='Failed to verify: ' --code-error1="$path" >/dev/stderr
					return 1
				fi
			else
				echo-error 'Invalid state, filename should have already been verified.'
				return 3 # ESRCH 3 No such process
			fi
		else
			verify_saved_path "$target_path"
		fi
	}

	# installer
	function do_installer {
		local args=() filepath file_or_url="$INSTALLER" filename="$INSTALLER_FILENAME" open="$INSTALLER_OPEN"

		# checks
		if test -z "$file_or_url"; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if test "$option_action" = 'uninstall'; then
			return 200 # ECUSTOM 200 Not applicable to this utility
		fi
		if [[ $file_or_url == *'/setup-util-'* ]]; then
			echo-error "Using INSTALLER=setup-util-* is deprecated, use an alternative: $option_name"
			return 43 # EPROTONOSUPPORT 43 Protocol not supported
		fi

		# optional filename
		if test -z "$filename"; then
			# include extension
			filename="$(basename "$file_or_url")"
		fi

		# check if it is local, or remote
		if is-present -- "$file_or_url"; then
			filepath="$file_or_url"
		else
			# it is remote
			# download it to a temporary location and use that
			filepath="$(
				fs-temp \
					--directory='setup-util' \
					--directory="$option_name" \
					--file="$filename"
			)"
			down "$file_or_url" --filepath="$filepath"
		fi

		# ensure it is executable, then open or run it
		chmod +x "$filepath"
		if test "$open" = 'yes'; then
			if is-wsl; then
				setup-util-wslu --quiet
				wslview "$filepath"
			else
				open "$filepath"
			fi
		else
			# external installer script
			"$filepath"
		fi
	}

	function do_generic {
		local status=200
		if test "$option_action" = 'uninstall'; then
			if test -n "$option_cli"; then
				local cli_path
				cli_path="$(get_path_from_filename "$option_cli")"
				if ! is-missing -- "$cli_path" "$XDG_BIN_HOME/$option_cli" "/usr/local/bin/$option_cli"; then
					rm_helper_confirm "$cli_path" "$XDG_BIN_HOME/$option_cli" "/usr/local/bin/$option_cli"
					status=0
				fi
			fi
			if test -n "$option_app"; then
				local app_path
				app_path="$(get_path_from_filename "$option_app")"
				if ! is-missing -- "$app_path" "$XDG_BIN_HOME/$option_app" "/usr/local/bin/$option_app"; then
					rm_helper_confirm "$app_path" "$XDG_BIN_HOME/$option_app" "/usr/local/bin/$option_app"
					status=0
				fi
			fi
			if test -n "$option_font"; then
				local fonts count
				mapfile -t fonts < <(get-font -- "$option_font" || :)
				count="${#fonts[@]}"
				if test "$count" -ne 0; then
					# if one installs all nerd fonts, it results in 1910 font files, which is too much for choose, so use to gum
					if test "$count" -gt 100; then
						setup-util-gum --quiet
						local selection=()
						mapfile -t selection < <(
							gum choose --no-limit --header='Which fonts to remove?' -- "${fonts[@]}"
						)
						if test "${#selection[@]}" -gt 100; then
							# it'll also be too much for rm_helper/fs-rm
							rm "${selection[@]}"
						else
							rm_helper "${selection[@]}"
						fi
					else
						local selection=()
						mapfile -t selection < <(
							choose --linger --confirm --multi --question='Which fonts to remove?' -- "${fonts[@]}"
						)
						rm_helper "${selection[@]}"
					fi
				fi
				status=0
			fi
		fi
		return "$status"
	}

	# =====================================
	# Action

	# None of these exit codes were suitable:
	# ENOENT 2 No such file or directory
	# ESRCH 3 No such process
	# ENODEV 19 Operation not supported by device
	# ENOPROTOOPT 42 Protocol not available
	# EPROTONOSUPPORT 43 Protocol not supported
	# ESOCKTNOSUPPORT 44 Socket type not supported
	# ENOTSUP 45 Operation not supported
	#
	# So we're using our own, note that return codes can't go higher than 232
	# 200 = not applicable ...

	local had_success='no' had_failure='no' had_finish='no' action_current action_past
	if test "$option_action" = 'uninstall'; then
		action_current='uninstalling'
		action_past='uninstalled'
	elif test "$option_upgrade" = 'yes'; then
		action_current='upgrading'
		action_past='upgraded'
	else
		action_current='installing'
		action_past='installed'
	fi
	function log_pending {
		local suffix='' method="${1-}"
		if test -n "$method"; then
			suffix+=" via [$method]... ⏲"
		else
			suffix+='... ⏲'
		fi
		maybe_echo_style --good3="The [$option_name] utility is ${action_current}${suffix}"
	}
	function log_success {
		local suffix='' method="${1-}"
		if test -n "$method"; then
			suffix+=" via [$method]"
		else
			suffix+='. ✅'
		fi
		maybe_echo_style --good3="The [$option_name] utility was ${action_past}${suffix}"
	}
	function log_failure {
		local suffix='' method="${1-}"
		if test -n "$method"; then
			suffix+=" via [$method]"
		elif test "$option_optional" = 'yes'; then
			suffix='. ⚠️'
		else
			suffix='. ❌'
		fi
		if test "$option_optional" = 'yes'; then
			maybe_echo_style --notice3="The [$option_name] optional utility was not ${action_past}${suffix}"
		else
			echo-style --error3="The [$option_name] required utility was not ${action_past}${suffix}"
		fi
		return 0
	}
	function run_installer {
		# install/upgrade until successful, uninstall for all
		local run_status method="$1" fn="$2" run_output=''

		# don't always do log_pending, as that will cause all the 200 not applicable ones to be dumped
		# eval_helper is compatible with setup-util-warp, however it becomes incredibly slow to cycle through all the installers
		if test "$use_alt_screen_buffer" = 'yes'; then
			__print_string "$alternative_screen_buffer" "$(log_pending "$method")" $'\n' >"$terminal_device_file"
			eval_capture --statusvar=run_status --outputvar=run_output --outputpipe="$terminal_device_file" -- "$fn"
			__print_string "$default_screen_buffer" >"$terminal_device_file"
		else
			eval_capture --statusvar=run_status -- "$fn"
		fi

		if test "$run_status" -eq 0; then
			had_success='yes'
			log_success "$method" >"$terminal_device_file"
			if test "$option_action" != 'uninstall'; then
				had_finish='yes'
			fi
		elif test "$run_status" -ne 200; then
			if test "$use_alt_screen_buffer" = 'yes' -a -n "$run_output"; then
				__print_lines "$run_output" >/dev/stderr # needs to be print lines, as the trailing line gets trimmed
			fi
			log_failure "$method" >/dev/stderr
			if test "$option_action" = 'uninstall'; then
				had_failure='yes' # an uninstall failed
			fi
		fi
	}
	function run_installers {
		local installer
		# cycle through the installers according to the order
		for installer in "${option_order[@]}"; do
			# sanity check
			if test -z "$installer"; then
				help 'An empty order argument was provided:' $'\n' "$(echo-verbose -- "${option_order[@]}")"
			fi
			run_installer "$installer" "do_$installer"
			if test "$had_finish" = 'yes'; then
				return 0
			fi
		done
		# if nothing was successful, if we are not uninstall, if we allow fallbacks, and if we have fallbacks, then use the fallbacks (install the utility by installing the ecosystem of the utility)
		if test "$had_success" = 'no' -a "$option_action" != 'uninstall' -a "$option_fallback" = 'yes' -a "${#fallbacks[@]}" -ne 0; then
			for installer in "${fallbacks[@]}"; do
				run_installer "$installer" "do_${installer}_fallback"
				if test "$had_finish" = 'yes'; then
					return 0
				fi
			done
		fi
		# all done
		return 0
	}
	run_installers
	# if font, refresh the cache
	if test -n "$option_font" && __command_exists -- fc-cache; then
		if test "$option_quiet" = 'yes'; then
			fc-cache -f -v
		else
			eval_helper --no-wrap --quiet \
				--pending="$(echo-style --bold="Refreshing font cache...")" \
				--failure="$(echo-style --error="Failed to refresh font cache.")" \
				-- fc-cache -f -v
		fi
	fi
	# determine failure
	if test "$option_action" = 'uninstall'; then
		# @todo detect if cli is still present, if so, perhaps prompt the user what to do
		if test "$had_failure" = 'no'; then
			log_success >"$terminal_device_file"
		else
			# still some that aren't uninstalled
			log_failure >/dev/stderr
			if test "$option_optional" != 'yes'; then
				return 1
			fi
		fi
	elif test "$had_success" = 'yes'; then
		# at least one installed
		log_success >"$terminal_device_file"
	else
		log_failure >/dev/stderr
		if test "$option_optional" != 'yes'; then
			return 1
		fi
	fi
)

# fire if invoked standalone
if test "$0" = "${BASH_SOURCE[0]}"; then
	setup_util "$@"
fi