improve get-installer --invoke usage, implement echo-(html|url)-coder

this now allows tool selection and prompting, as well as testing each tool, for:
- echo-html-coder
- echo-url-coder
- echo-math

/ref https://github.com/bevry/dorothy/actions/runs/10877091411/job/30177948850

commands/echo-html-coder

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+
+function ehco_html_coder_test() (
+	source "$DOROTHY/sources/bash.bash"
+	echo-style --h1="TEST: $0"
+
+	local inputs=(
+		'Jack & Jill'
+		'Jack & Jill'
+	)
+	# don't test   as it gets converted into a special character
+	local expected_encode=$'Jack & Jill\nJack & Jill'
+	local expected_decode=$'Jack & Jill\nJack & Jill'
+	local action actions=('encode' 'decode')
+	local tool all_tools=(deno php python3)
+	local expected
+
+	for action in "${actions[@]}"; do
+		if test "$action" = 'encode'; then
+			expected="$expected_encode"
+		else
+			expected="$expected_decode"
+		fi
+		for tool in "${all_tools[@]}"; do
+			if command-exists -- "$tool"; then
+				eval-tester --stdout="$expected" \
+					-- echo-html-coder --action="$action" --tool="$tool" -- "${inputs[@]}"
+
+				{
+					__print_lines "${inputs[@]}"
+				} | eval-tester --stdout="$expected" \
+					-- echo-html-coder --action="$action" --tool="$tool" --stdin
+			fi
+		done
+	done
+
+	echo-style --g1="TEST: $0"
+	return 0
+)
+function ehco_html_coder() (
+	source "$DOROTHY/sources/stdinargs.bash"
+
+	# textutil doesn't work
+	# xmlstarlet is too old, last update 9 August 2014; 10 years ago
+	local all_tools=(deno php python3)
+
+	# =====================================
+	# Arguments
+
+	function help {
+		cat <<-EOF >/dev/stderr
+			ABOUT:
+			For each input, encode or decode it's HTML entities.
+
+			USAGE:
+			echo-html-coder [...options] [--] ...<input>
+			echo-lines ...<input> | echo-html-coder [...options]
+
+			OPTIONS:
+			$(stdinargs_options_help --)
+
+			EXAMPLE:
+
+			echo-html-coder --encode -- 'Jack & Jill'
+
+			    Jack &amp; Jill
+			    # exit status: 0
+
+			echo-html-coder --decode -- 'Jack &amp; Jill
+
+			    Jack & Jill
+			    # exit status: 0
+
+		EOF
+		if test "$#" -ne 0; then
+			echo-error "$@"
+		fi
+		return 22 # EINVAL 22 Invalid argument
+	}
+
+	# process our own arguments, delegate everything else to stdinargs
+	local item option_action='' option_tool=''
+	while test "$#" -ne 0; do
+		item="$1"
+		shift
+		case "$item" in
+		'--help' | '-h') help ;;
+		'--encode' | '--decode') option_action="${item#--}" ;;
+		'--action='*) option_action="${item#*=}" ;;
+		'--tool='*) option_tool="${item#*=}" ;;
+		# forward to stdinargs, however support mixing and matching of our options, with stdinarg options
+		'--')
+			option_args+=("$item" "$@")
+			shift $#
+			break
+			;;
+		*) option_args+=("$item") ;;
+		esac
+	done
+
+	# ensure tool
+	if test "$option_tool" = '?'; then
+		option_tool="$(choose --required 'Which tool to use?' -- "${all_tools[@]}")"
+		if command-missing -- "$option_tool"; then
+			get-installer --first-success --invoke --quiet -- "$option_tool"
+		fi
+	elif test -z "$option_tool"; then
+		local item
+		for item in "${all_tools[@]}"; do
+			if command-exists -- "$item"; then
+				option_tool="$item"
+				break
+			fi
+		done
+	fi
+
+	# ensure action
+	if test "$option_action" = '?'; then
+		option_action="$(choose --required 'Which action to perform?' -- 'encode' 'decode')"
+	elif ! [[ $option_action =~ ^(encode|decode)$ ]]; then
+		help "You must provide a valid <action>"
+	fi
+
+	# =====================================
+	# Action
+
+	local script
+	# if test "$option_tool" = 'recode'; then
+	# 	script="$(type -P echo-html-coder.recode)"
+	# elif test "$option_tool" = 'textutil'; then
+	# 	script="$(type -P echo-html-coder.textutil)"
+	# elif test "$option_tool" = 'xmlstarlet'; then
+	# 	script="$(type -P echo-html-coder.xmlstarlet)"
+	if test "$option_tool" = 'deno'; then
+		script="$(type -P echo-html-coder.ts)"
+	elif test "$option_tool" = 'php'; then
+		script="$(type -P echo-html-coder.php)"
+	elif test "$option_tool" = 'python3'; then
+		script="$(type -P echo-html-coder.py)"
+	else
+		help "The tool [$option_tool] is not yet supported."
+	fi
+	function on_line {
+		"$script" "$option_action" "$1"
+	}
+
+	stdinargs "${option_args[@]}"
+)
+
+# fire if invoked standalone
+if test "$0" = "${BASH_SOURCE[0]}"; then
+	if test "$*" = '--test'; then
+		ehco_html_coder_test
+	else
+		ehco_html_coder "$@"
+	fi
+fi

commands/echo-html-coder.php

@@ -0,0 +1,7 @@
+#!/usr/bin/env php
+<?php
+if ( $argv[1] == "decode" ) {
+	printf("%s\n", html_entity_decode($argv[2]));
+} else {
+	printf("%s\n", htmlentities($argv[2]));
+}

commands/echo-html-coder.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+import html
+import sys
+
+if sys.argv[1] == "decode":
+    print(html.unescape(sys.argv[2]))
+else:
+    print(html.escape(sys.argv[2]))

commands/echo-html-coder.recode

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# recode decoding fails with: recode: Untranslatable input in step `ISO-10646-UCS-2..ANSI_X3.4-1968'
+if test "$1" = 'decode'; then
+	recode html..ascii <<<"$2"
+else
+	recode ascii..html <<<"$2"
+fi

commands/echo-html-coder.textutil

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# this doesn't work as expected
+if test "$1" = 'decode'; then
+	textutil -convert html -format txt -inputencoding UTF-8 -stdin -stdout <<<"$2"
+else
+	textutil -convert txt -format html -inputencoding UTF-8 -stdin -stdout <<<"$2"
+fi

commands/echo-html-coder.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env -S deno run --quiet --no-config --no-lock --no-npm
+import { Html5Entities } from 'https://deno.land/x/html_entities@v1.0/mod.js'
+const coder =
+	Deno.args[0] === 'decode' ? Html5Entities.decode : Html5Entities.encode
+const url = Deno.args[1]
+console.log(coder(url))

commands/echo-html-coder.xmlstarlet

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# xmlstarlet is too old to be available
+if test "$1" = 'decode'; then
+	xmlstarlet unesc "$2"
+else
+	xmlstarlet esc "$1"
+fi

commands/echo-html-decode

@@ -1,75 +1,41 @@
 #!/usr/bin/env bash
 
-function echo_html_decode() (
-	source "$DOROTHY/sources/stdinargs.bash"
-
-	# =====================================
-	# Arguments
-
-	function help {
-		cat <<-EOF >/dev/stderr
-			ABOUT:
-			For each input, decode it's HTML entities.
-
-			USAGE:
-			echo-html-decode [...options] [--] ...<input>
-			echo-lines ...<input> | echo-html-decode [...options]
-
-			OPTIONS:
-			$(stdinargs_options_help --)
-
-			EXAMPLE:
-
-			echo-html-decode -- 'Jack &amp; Jill'
-
-			    Jack & Jill
-			    # exit status: 0
-
-			echo-lines -- 'Jack &amp; Jill' | echo-html-decode --stdin
-
-			    Jack & Jill
-			    # exit status: 0
-
-		EOF
-		if test "$#" -ne 0; then
-			echo-error "$@"
-		fi
-		return 22 # EINVAL 22 Invalid argument
-	}
-
-	# =====================================
-	# Action
-
-	function on_input {
-		if command-exists -- recode; then
-			recode html..ascii <<<"$1"
-		elif command-exists -- textutil; then
-			textutil -convert txt -format html -inputencoding UTF-8 -stdin -stdout <<<"$1"
-		elif command-exists -- xmlstarlet; then
-			# https://xmlstar.sourceforge.net/docs.php
-			xmlstarlet unesc "$1"
-		elif command-exists -- deno; then
-			# https://github.com/matschik/deno_html_entities
-			deno eval --quiet \
-				"import { Html5Entities } from 'https://deno.land/x/html_entities@v1.0/mod.js'; console.log(Html5Entities.decode(Deno.args[0]))" \
-				"$1"
-		elif command-exists -- php; then
-			# https://www.php.net/manual/en/function.html-entity-decode
-			# trunk-ignore(shellcheck/SC2016)
-			php -R 'echo html_entity_decode($argv[0])' "$1"
-		elif command-exists -- python3; then
-			# https://docs.python.org/3/library/html.html
-			python3 -c "import html; print(html.unescape('''$1'''))"
-		else
-			get-installer --first-success --invoke --quiet -- recode textutil xmlstarlet deno php python3
-			on_input "$1"
+function echo_html_decode_test() (
+	source "$DOROTHY/sources/bash.bash"
+	echo-style --h1="TEST: $0"
+
+	local inputs=(
+		'Jack & Jill'
+		'Jack &amp; Jill'
+	)
+	# don't test &nbsp; as it gets converted into a special character
+	local expected_decode=$'Jack & Jill\nJack & Jill'
+	local tool all_tools=(deno php python3)
+
+	for tool in "${all_tools[@]}"; do
+		if command-exists -- "$tool"; then
+			eval-tester --stdout="$expected_decode" \
+				-- echo-html-decode --tool="$tool" -- "${inputs[@]}"
+
+			{
+				__print_lines "${inputs[@]}"
+			} | eval-tester --stdout="$expected_decode" \
+				-- echo-html-decode --tool="$tool" --stdin
 		fi
-	}
+	done
 
-	stdinargs "$@"
+	echo-style --g1="TEST: $0"
+	return 0
+)
+function echo_html_decode() (
+	echo-html-coder --decode "$@"
 )
 
 # fire if invoked standalone
 if test "$0" = "${BASH_SOURCE[0]}"; then
-	echo_html_decode "$@"
+	if test "$*" = '--test'; then
+		echo_html_decode_test
+	else
+		echo_html_decode "$@"
+	fi
 fi