Allow checking whether optionals provided explicitly

Since boolean optionals default to "off" we have no way to
check if a boolean optional was actually specified on the command line.

The ability to check if a boolean optional has been given is useful in
cases where we source values from a configuration file where we want any
explicitly given arguments to override the configuration.

An example that mostly works is (for plain optionals with an empty default):

        test -f ~/.standard-values-for-this-script && source "$_"
        MYOPT="${MYOPT:-$_arg_myopt}"
        ... # Code using MYOPT

This works since optionals can default to an empty string. We still are
not entirely sure if the optional was actually passed here, but it tends
to be "good enough" in most cases.

In the case where `myopt` is boolean, the above case would always use
"off" if the argument was not specified, thus overriding the sourced
configuration file.

This patch introduces `_supplied_<argname>`, a value that gets set if
and only if an argument is supplied for that option. This must be
enabled on a per-argument basis by declaring

        ARG_SUPPLIED([long arg name])

Where `long arg name` matches the argument name for any
`ARG_OPTIONAL_*`.

This allows us to do the following:

        test -f ~/.standard-values-for-this-script && source "$_"
        if [[ "${_supplied_arg_myopt-x}" = 1 ]]; then
                MYOPT="$_arg_myopt" # We override
        fi
        # Alternatively
        if [[ -v _supplied_arg_myopt ]]; then
                # ...
        fi
        ... # Code using MYOPT

Author: kstrafe

bin/argbash

@@ -495,7 +495,7 @@ then
 	# match against suspicious, then inverse match against correct stuff:
 	# #<optional whitespace>\(allowed\|another allowed\|...\)<optional whitespace><opening bracket <or> end of line>
 	# Then, extract all matches (assumed to be alnum chars + '_') from grep and put them in the error msg.
-	grep_output="$(printf "%s" "$output" | grep '^#\s*\(ARG_\|ARGBASH\)' | grep -v '^#\s*\(ARGBASH_SET_INDENT\|ARG_OPTIONAL_SINGLE\|ARG_VERSION\|ARG_VERSION_AUTO\|ARG_HELP\|ARG_OPTIONAL_INCREMENTAL\|ARG_OPTIONAL_REPEATED\|ARG_VERBOSE\|ARG_OPTIONAL_BOOLEAN\|ARG_OPTIONAL_ACTION\|ARG_POSITIONAL_SINGLE\|ARG_POSITIONAL_INF\|ARG_POSITIONAL_MULTI\|ARG_POSITIONAL_DOUBLEDASH\|ARG_OPTION_STACKING\|ARG_RESTRICT_VALUES\|ARG_DEFAULTS_POS\|ARG_LEFTOVERS\|ARGBASH_WRAP\|INCLUDE_PARSING_CODE\|DEFINE_LOAD_LIBRARY\|DEFINE_SCRIPT_DIR\|DEFINE_SCRIPT_DIR_GNU\|ARGBASH_SET_DELIM\|ARGBASH_GO\|ARGBASH_PREPARE\|ARG_TYPE_GROUP\|ARG_TYPE_GROUP_SET\|ARG_USE_ENV\|ARG_USE_PROGRAM\)\s*\((\|$\)' | sed -e 's/#\s*\([[:alnum:]_]*\).*/\1 /' | tr -d '\n\r')"
+	grep_output="$(printf "%s" "$output" | grep '^#\s*\(ARG_\|ARGBASH\)' | grep -v '^#\s*\(ARGBASH_SET_INDENT\|ARG_OPTIONAL_SINGLE\|ARG_VERSION\|ARG_VERSION_AUTO\|ARG_HELP\|ARG_OPTIONAL_INCREMENTAL\|ARG_OPTIONAL_REPEATED\|ARG_VERBOSE\|ARG_OPTIONAL_BOOLEAN\|ARG_OPTIONAL_ACTION\|ARG_POSITIONAL_SINGLE\|ARG_POSITIONAL_INF\|ARG_POSITIONAL_MULTI\|ARG_POSITIONAL_DOUBLEDASH\|ARG_SUPPLIED\|ARG_OPTION_STACKING\|ARG_RESTRICT_VALUES\|ARG_DEFAULTS_POS\|ARG_LEFTOVERS\|ARGBASH_WRAP\|INCLUDE_PARSING_CODE\|DEFINE_LOAD_LIBRARY\|DEFINE_SCRIPT_DIR\|DEFINE_SCRIPT_DIR_GNU\|ARGBASH_SET_DELIM\|ARGBASH_GO\|ARGBASH_PREPARE\|ARG_TYPE_GROUP\|ARG_TYPE_GROUP_SET\|ARG_USE_ENV\|ARG_USE_PROGRAM\)\s*\((\|$\)' | sed -e 's/#\s*\([[:alnum:]_]*\).*/\1 /' | tr -d '\n\r')"
 	test -n "$grep_output" && die "Your script contains possible misspelled Argbash macros: $grep_output" 1
 fi
 if test "$outfname" != '-'

doc/guide.rst

@@ -305,6 +305,15 @@ Special arguments
   A use case for this is wrapping of scripts that are completely ``Argbash``-agnostic.
   Therefore, your script can take its own arguments and the rest that is not recognized can go to the wrapped script.
 
+* Detect supplied arguments:
+  ::
+
+    ARG_SUPPLIED([long arg name])
+
+  This macro will cause a variable to be set if the argument was explicitly provided. This only works for optional arguments.
+
+  For example, if you have `ARG_OPTIONAL_BOOLEAN([quiet], , , [off])`, followed by `ARG_SUPPLIED([quiet])`, then if `--quiet` was provided on the command line the variable `_supplied_arg_quiet=1` would be set. This allows you to see if an argument was explicitly provided using `[[ -v _supplied_arg_quiet ]]` or `[ "${_supplied_arg_quiet-x}" = 1 ]`.
+
 Typing macros
 +++++++++++++
 

src/collectors.m4

@@ -409,6 +409,7 @@ m4_define([_DISCARD_VALUES_FOR_ALL_ARGUMENTS], [m4_do(
 	[m4_define([_POSITIONALS_INF], 0)],
 	[m4_define([HAVE_POSITIONAL_VARNUM], 0)],
 	[m4_define([HAVE_DOUBLEDASH], 0)],
+	[m4_define([HAVE_SUPPLIED], [])],
 )])
 
 
@@ -525,6 +526,15 @@ m4_define([_ARG_POSITIONAL_DOUBLEDASH], [m4_do(
 )])
 
 
+argbash_api([ARG_SUPPLIED], [m4_do(
+	[_ARG_SUPPLIED($@)],
+)])
+
+
+m4_define([_ARG_SUPPLIED], [m4_do(
+	[m4_list_append([HAVE_SUPPLIED], $@)],
+)])
+
 dnl
 dnl $1: The mode of argument grouping: One of 'none', 'getopts'
 argbash_api([ARG_OPTION_STACKING], _CHECK_PASSED_ARGS_COUNT(1)[m4_do(

src/stuff.m4

@@ -444,6 +444,7 @@ dnl $5: Where to get the last value (optional)
 m4_define([_VAL_OPT_ADD_SPACE_WITHOUT_GETOPT_OR_SHORT_OPT], [_JOIN_INDENTED(_INDENT_LEVEL_IN_ARGV_CASE_BODY,
 	[test $[]# -lt 2 && die "Missing value for the optional argument '$_key'." 1],
 	[$3([$1], ["@S|@2"], [$4])],
+	[m4_list_contains([HAVE_SUPPLIED], [$1], [_supplied$4=1], [])],
 	[_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_SPACE([$4], [m4_default_quoted([$5], [@S|@2])])],
 	[shift],
 )])
@@ -458,6 +459,7 @@ dnl $5: Where to get the last value (optional)
 m4_define([_VAL_OPT_ADD_GETOPTS], [_JOIN_INDENTED(_INDENT_LEVEL_IN_ARGV_CASE_BODY,
 	[test "$OPTARG" = "" && die "Missing value for the optional argument '-$_key'." 1],
 	[$3([$1], ["$OPTARG"], [$4])],
+	[m4_list_contains([HAVE_SUPPLIED], [$1], [_supplied$3=1], [])],
 	[_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_SPACE([$4], [m4_default_quoted([$5], [$OPTARG])])],
 )])
 
@@ -470,6 +472,7 @@ dnl $4: The name of the argument-holding variable
 dnl $5: Where to get the last value (optional)
 m4_define([_VAL_OPT_ADD_EQUALS_WITH_LONG_OPT], [_JOIN_INDENTED(_INDENT_LEVEL_IN_ARGV_CASE_BODY,
 	[$3([$1], ["${_key##--$1=}"], [$4])],
+	[m4_list_contains([HAVE_SUPPLIED], [$1], [_supplied$4=1], [])],
 	[_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_EQUALS([$4])],
 )])
 
@@ -482,6 +485,7 @@ dnl $4: The name of the argument-holding variable
 dnl $5: Where to get the last value (optional)
 m4_define([_VAL_OPT_ADD_ONLY_WITH_SHORT_OPT_GETOPT], [_JOIN_INDENTED(_INDENT_LEVEL_IN_ARGV_CASE_BODY,
 	[$3([$1], ["${_key##-$2}"], [$4])],
+	[m4_list_contains([HAVE_SUPPLIED], [$1], [_supplied$4=1], [])],
 	[_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_GETOPT([$4])],
 )])
 
@@ -731,12 +735,14 @@ m4_define([_MAKE_OPTARG_SIMPLE_CASE_SECTION], [m4_do(
 		[bool],
 		[_JOIN_INDENTED(_INDENT_LEVEL_IN_ARGV_CASE_BODY,
 			[[$5="on"]],
+			[m4_list_contains([HAVE_SUPPLIED], [$1], [_supplied$5=1], [])],
 			[_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_SPACE([$5])],
 			[[test "${1:0:5}" = "--no-" && $5="off"]],
 		)],
 		[incr],
 		[_JOIN_INDENTED(_INDENT_LEVEL_IN_ARGV_CASE_BODY,
 			[[$5=$(($5 + 1))]],
+			[m4_list_contains([HAVE_SUPPLIED], [$1], [_supplied$5=1], [])],
 			[_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_SPACE([$5])],
 		)],
 		[action],
@@ -763,11 +769,13 @@ m4_define([_MAKE_OPTARG_GETOPTS_CASE_SECTION], [m4_do(
 		[bool],
 		[_JOIN_INDENTED(_INDENT_LEVEL_IN_ARGV_CASE_BODY,
 			[[$5="on"]],
+			[m4_list_contains([HAVE_SUPPLIED], [$1], [_supplied$5=1], [])],
 			[_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_SPACE([$5])],
 		)],
 		[incr],
 		[_JOIN_INDENTED(_INDENT_LEVEL_IN_ARGV_CASE_BODY,
 			[[$5=$(($5 + 1))]],
+			[m4_list_contains([HAVE_SUPPLIED], [$1], [_supplied$5=1], [])],
 			[_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_SPACE([$5])],
 		)],
 		[action],
@@ -823,12 +831,14 @@ m4_define([_MAKE_OPTARG_GETOPT_CASE_SECTION], [m4_do(
 		[bool],
 		[_JOIN_INDENTED(_INDENT_LEVEL_IN_ARGV_CASE_BODY,
 			[[$5="on"]],
+			[m4_list_contains([HAVE_SUPPLIED], [$1], [_supplied$5=1], [])],
 			_PASS_WHEN_GETOPT([$2]),
 			[_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_SPACE([$5])],
 		)],
 		[incr],
 		[_JOIN_INDENTED(_INDENT_LEVEL_IN_ARGV_CASE_BODY,
 			[[$5=$(($5 + 1))]],
+			[m4_list_contains([HAVE_SUPPLIED], [$1], [_supplied$5=1], [])],
 			_PASS_WHEN_GETOPT([$2]),
 			[_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_SPACE([$5])],
 		)],

tests/regressiontests/Makefile

@@ -372,6 +372,9 @@ test-simple: $(TESTDIR)/test-simple.sh
 	ERROR="[Nn]ot enough" 	$(REVERSE) $<
 	ERROR="require exactly 1" 	$(REVERSE) $<
 	$< pos -o 'uf ta' | grep -q 'OPT_S=uf ta,POS_S=pos,'
+	$< pos -o 'uf ta' --print-optionals | grep -q '_supplied_arg_prefix=1,_supplied_arg_print_optionals=1,_supplied_arg_la=x,_supplied_arg_not_supplied=x'
+	$< pos -o 'uf ta' --print-optionals --la x | grep -q '_supplied_arg_prefix=1,_supplied_arg_print_optionals=1,_supplied_arg_la=1,_supplied_arg_not_supplied=x'
+	$< pos -o 'uf ta' --print-optionals --la x --not-supplied | grep -q '_supplied_arg_prefix=1,_supplied_arg_print_optionals=1,_supplied_arg_la=1,_supplied_arg_not_supplied=x'
 	test -z "$(SHELLCHECK)" || $(SHELLCHECK) "$(TESTDIR)/test-simple.sh"
 test-simple-dash: $(TESTDIR)/test-simple-dash.sh
 	$< pos | grep -q 'OPT_S=x,POS_S=pos,'

tests/regressiontests/make/tests/tests-base.m4

@@ -144,6 +144,9 @@ m4_define([test_simple_body], [[
 
 ADD_TEST_BASH([test-simple], [test_simple_body
 	$< pos -o 'uf ta' | grep -q 'OPT_S=uf ta,POS_S=pos,'
+	$< pos -o 'uf ta' --print-optionals | grep -q '_supplied_arg_prefix=1,_supplied_arg_print_optionals=1,_supplied_arg_la=x,_supplied_arg_not_supplied=x'
+	$< pos -o 'uf ta' --print-optionals --la x | grep -q '_supplied_arg_prefix=1,_supplied_arg_print_optionals=1,_supplied_arg_la=1,_supplied_arg_not_supplied=x'
+	$< pos -o 'uf ta' --print-optionals --la x --not-supplied | grep -q '_supplied_arg_prefix=1,_supplied_arg_print_optionals=1,_supplied_arg_la=1,_supplied_arg_not_supplied=x'
 ])
 
 ADD_TEST_DASH([test-simple], [test_simple_body

tests/regressiontests/test-simple.m4

@@ -2,7 +2,12 @@
 
 # ARG_POSITIONAL_SINGLE([pos-arg], [help line PEND-\n-PBEGIN])
 # ARG_OPTIONAL_SINGLE([prefix],[o],[help line END-\n-BEGIN "line 2" END-\\n-2BEGIN],[x])
+# ARG_OPTIONAL_BOOLEAN([print-optionals],[p],[Print the set of optional arguments],[off])
 # ARG_OPTIONAL_SINGLE([la], [l], [help line END-\n-BEGIN "line 2"])
+# ARG_OPTIONAL_BOOLEAN([not-supplied])
+# ARG_SUPPLIED([prefix])
+# ARG_SUPPLIED([print-optionals])
+# ARG_SUPPLIED([la])
 # ARG_VERSION([echo "$0 FOO"])
 # ARG_HELP([Testing program m4_fatal(BOOM!)], [m4_fatal([CRASH!])])
 # ARG_DEFAULTS_POS()
@@ -12,7 +17,11 @@
 
 # Now we take the parsed data and assign them no nice-looking variable names,
 # sometimes after a basic validation
-echo "OPT_S=$_arg_prefix,POS_S=$_arg_pos_arg,LA=$_arg_la,"
+if [ "$_arg_print_optionals" = on ]; then
+    echo "_supplied_arg_prefix=${_supplied_arg_prefix-x},_supplied_arg_print_optionals=${_supplied_arg_print_optionals-x},_supplied_arg_la=${_supplied_arg_la-x},_supplied_arg_not_supplied=${_supplied_arg_not_supplied-x}"
+else
+    echo "OPT_S=$_arg_prefix,POS_S=$_arg_pos_arg,LA=$_arg_la,"
+fi
 
 # ] <-- needed because of Argbash
 m4_ifdef([m4_esyscmd], [m4_fatal([The m4_esyscmd macro is enabled!])])