Sanitize nameref targets in args:opt/arg/varg/sub for hyphenated long flags

args:flag already strips non-alphanumeric chars when building the nameref
target (so `--dry-run` can write to a caller-declared `dry_run` variable);
the other four functions did not. Calling `args:opt gh-source ""` would
fail with "invalid variable name for name reference" because bash variable
names can't contain hyphens, even though the long-flag scan pattern (which
preserves the hyphen) was correct.

Apply the same `${1//[^_0-9a-zA-Z]/_}` substitution across args:opt,
args:arg, args:varg, args:sub. Existing alphanumeric-only call sites are
unaffected (substitution is a no-op).

Two regression tests added (smoke:opt:hyphenated-long-name,
smoke:flag:hyphenated-long-name).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mihai-stancu

bash-args.sh

@@ -79,7 +79,12 @@ function args:opt() {
 	local err=""; (($# >= 2)) && [[ "${*: -2:1}" == "--err" ]] && err="${*: -1}" && set -- "${@:1:$#-2}";
 	local required="false"; [[ "${1:-}" == "-r" || "${1:-}" == "--required" ]] && required="true" && shift;
 	local accumulate="false"; [[ "${1:-}" == "-a" || "${1:-}" == "--accumulate" ]] && accumulate="true" && shift;
-	local -n __value_="${1?ERROR: args:opt requires <long>}";
+	[[ -n "${1:-}" ]] || { echo "ERROR: args:opt requires <long>" >&2; return 1; };
+	# Strip non-alphanumeric chars (hyphens, dots) from the nameref target so
+	# hyphenated long flags like `--gh-source` can map to caller-declared
+	# variables like `local gh_source`. The unsanitized form is kept below for
+	# the `$long` flag-name scan pattern.
+	local -n __value_="${1//[^_0-9a-zA-Z]/_}";
 	local long="${1}"; shift;
 	local short="${1?ERROR: args:opt requires <short>}"; shift;
 	local pattern="${1:-(.*)}"; shift || true;
@@ -128,8 +133,9 @@ function args:arg() {
 	local err=""; (($# >= 2)) && [[ "${*: -2:1}" == "--err" ]] && err="${*: -1}" && set -- "${@:1:$#-2}";
 
 	local optional="false"; [[ "${1:-}" == "-o" || "${1:-}" == "--optional" ]] && optional="true" && shift;
+	[[ -n "${1:-}" ]] || { echo "ERROR: args:arg requires <name>" >&2; return 1; };
 	# shellcheck disable=SC2178  # nameref is a string, points to an array
-	local -n __value_="${1?ERROR: args:arg requires <name>}"; shift;
+	local -n __value_="${1//[^_0-9a-zA-Z]/_}"; shift;
 	local pattern="${1:-(.*)}"; shift || true;
 
 	[[ "${TOKENS[0]:-}" == "--" ]] && TOKENS=("${TOKENS[@]:1}");
@@ -173,8 +179,9 @@ function args:varg() {
 
 	local err=""; (($# >= 2)) && [[ "${*: -2:1}" == "--err" ]] && err="${*: -1}" && set -- "${@:1:$#-2}";
 	local optional="false"; [[ "${1:-}" == "-o" || "${1:-}" == "--optional" ]] && optional="true" && shift;
+	[[ -n "${1:-}" ]] || { echo "ERROR: args:varg requires <name>" >&2; return 1; };
 	# shellcheck disable=SC2178  # nameref is a string, points to an array
-	local -n __value_="${1?ERROR: args:varg requires <name>}"; shift;
+	local -n __value_="${1//[^_0-9a-zA-Z]/_}"; shift;
 
 	[[ "${TOKENS[0]:-}" == "--" ]] && TOKENS=("${TOKENS[@]:1}");
 
@@ -211,9 +218,11 @@ function args:sub() {
 
 	local err=""; (($# >= 2)) && [[ "${*: -2:1}" == "--err" ]] && err="${*: -1}" && set -- "${@:1:$#-2}";
 	local optional="false"; [[ "${1:-}" == "-o" || "${1:-}" == "--optional" ]] && optional="true" && shift;
+	[[ -n "${1:-}" ]] || { echo "ERROR: args:sub requires <name>" >&2; return 1; };
 	# shellcheck disable=SC2178  # nameref is a string, points to an array
-	local -n __value_="${1?ERROR: args:sub requires <name>}"; shift;
-	local -n __rest_="${1?ERROR: args:sub requires <rest>}"; shift;
+	local -n __value_="${1//[^_0-9a-zA-Z]/_}"; shift;
+	[[ -n "${1:-}" ]] || { echo "ERROR: args:sub requires <rest>" >&2; return 1; };
+	local -n __rest_="${1//[^_0-9a-zA-Z]/_}"; shift;
 	local pattern="${1?ERROR: args:sub requires <pattern>}"; shift;
 
 	local i captured;

bash-args.test

@@ -51,6 +51,25 @@ test:smoke:opt:absent() {
 	assert "$name" "" || return 1;
 }
 
+test:smoke:opt:hyphenated-long-name() {
+	# Hyphenated long flags (--gh-source) must map to caller-declared
+	# variables (gh_source) -- bash variable names can't contain hyphens, so
+	# the nameref target is sanitized while the flag name is preserved.
+	local ARGS=(--gh-source release);
+	local gh_source;
+	args:opt gh-source "" || return 1;
+	assert "$gh_source" "release" || return 1;
+	assert:array-eq ARGS "" || return 1;
+}
+
+test:smoke:flag:hyphenated-long-name() {
+	local ARGS=(--dry-run);
+	local dry_run;
+	args:flag dry-run "" || return 1;
+	assert "$dry_run" "true" || return 1;
+	assert:array-eq ARGS "" || return 1;
+}
+
 test:smoke:arg:positional() {
 	local ARGS=(foo);
 	local file;
@@ -1249,6 +1268,8 @@ flag:absent           | flag     | args:flag verbose v                    | *(no
 opt:long-space        | opt      | args:opt name n                        | --name foo                   | foo                                              |      0 | $(t smoke:opt:long-space)
 opt:short-space       | opt      | args:opt name n                        | -n foo                       | foo                                              |      0 | $(t smoke:opt:short-space)
 opt:absent            | opt      | args:opt name n                        | *(none)*                     | ""                                               |      0 | $(t smoke:opt:absent)
+opt:hyphenated        | opt      | args:opt gh-source ""                  | --gh-source release          | release                                          |      0 | $(t smoke:opt:hyphenated-long-name)
+flag:hyphenated       | flag     | args:flag dry-run ""                   | --dry-run                    | true                                             |      0 | $(t smoke:flag:hyphenated-long-name)
 arg:positional        | arg      | args:arg file                          | foo                          | foo                                              |      0 | $(t smoke:arg:positional)
 arg:missing           | arg      | args:arg file                          | *(none)*                     | -                                                |      1 | $(t smoke:arg:missing)
 arg:optional-missing  | arg      | args:arg -o file                       | *(none)*                     | ""                                               |      0 | $(t smoke:arg:optional-missing)

bash-args.test.md

@@ -10,6 +10,8 @@ flag:absent           | flag     | args:flag verbose v                    | *(no
 opt:long-space        | opt      | args:opt name n                        | --name foo                   | foo                                              |      0 | ✅
 opt:short-space       | opt      | args:opt name n                        | -n foo                       | foo                                              |      0 | ✅
 opt:absent            | opt      | args:opt name n                        | *(none)*                     | ""                                               |      0 | ✅
+opt:hyphenated        | opt      | args:opt gh-source ""                  | --gh-source release          | release                                          |      0 | ✅
+flag:hyphenated       | flag     | args:flag dry-run ""                   | --dry-run                    | true                                             |      0 | ✅
 arg:positional        | arg      | args:arg file                          | foo                          | foo                                              |      0 | ✅
 arg:missing           | arg      | args:arg file                          | *(none)*                     | -                                                |      1 | ✅
 arg:optional-missing  | arg      | args:arg -o file                       | *(none)*                     | ""                                               |      0 | ✅
@@ -224,5 +226,5 @@ multiple-args-across-separator | args:arg a1; args:arg a2; args:arg a3
 
 | ✅ Pass | ❌ Fail | ⚠️ Error |
 |---------|---------|----------|
-| 157 | 0 | 0 |
+| 159 | 0 | 0 |