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 to 1
if an argument is supplied for that option, otherwise it's set to 0.
This must be enabled on a per-argument basis by declaring:

        ARGBASH_INDICATE_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" = 1 ]; then
                MYOPT="$_arg_myopt" # We override
        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\|ARGBASH_INDICATE_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:
+  ::
+
+    ARGBASH_INDICATE_SUPPLIED([long opt arg name], [another long opt arg name (optional)], ...)
+
+  This macro takes a list of long optional argument names and will generate a variable for each optional that will be set if that argument was explicitly provided on the command line. This only works for optional arguments.
+
+  For example, if you have `ARG_OPTIONAL_BOOLEAN([quiet], , , [off])`, followed by `ARGBASH_INDICATE_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 `[ "$_supplied_arg_quiet" = 1 ]`. If the argument was not passed to the program then this variable will be set to `0`.
+
 Typing macros
 +++++++++++++
 

src/collectors.m4

@@ -525,6 +525,12 @@ m4_define([_ARG_POSITIONAL_DOUBLEDASH], [m4_do(
 )])
 
 
+argbash_api([ARGBASH_INDICATE_SUPPLIED], [m4_do(
+	[[$0($@)]],
+	[m4_set_add_all([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])],
+	[_INDICATION_OF_SUPPLY([$1], [$4])],
 	[_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])],
+	[_INDICATION_OF_SUPPLY([$1], [$3])],
 	[_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])],
+	[_INDICATION_OF_SUPPLY([$1], [$4])],
 	[_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])],
+	[_INDICATION_OF_SUPPLY([$1], [$4])],
 	[_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_GETOPT([$4])],
 )])
 
@@ -522,6 +526,13 @@ m4_define([_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_EQUALS], [m4_do(
 )])
 
 
+dnl
+dnl $1: The name of the option arg
+dnl $2: The name of the argument-holding variable
+m4_define([_INDICATION_OF_SUPPLY], [m4_do(
+	[m4_set_contains([HAVE_SUPPLIED], [$1], [_supplied$2=1], [])],
+)])
+
 m4_define([_MAKE_SEE_ALSO_OPTION_PHRASE], [m4_do(
 	[[See the comment of option '$1' to see what's going on here - principle is the same.]],
 )])
@@ -731,6 +742,7 @@ m4_define([_MAKE_OPTARG_SIMPLE_CASE_SECTION], [m4_do(
 		[bool],
 		[_JOIN_INDENTED(_INDENT_LEVEL_IN_ARGV_CASE_BODY,
 			[[$5="on"]],
+			[_INDICATION_OF_SUPPLY([$1], [$5])],
 			[_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_SPACE([$5])],
 			[[test "${1:0:5}" = "--no-" && $5="off"]],
 		)],
@@ -763,6 +775,7 @@ m4_define([_MAKE_OPTARG_GETOPTS_CASE_SECTION], [m4_do(
 		[bool],
 		[_JOIN_INDENTED(_INDENT_LEVEL_IN_ARGV_CASE_BODY,
 			[[$5="on"]],
+			[_INDICATION_OF_SUPPLY([$1], [$5])],
 			[_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_SPACE([$5])],
 		)],
 		[incr],
@@ -823,6 +836,7 @@ m4_define([_MAKE_OPTARG_GETOPT_CASE_SECTION], [m4_do(
 		[bool],
 		[_JOIN_INDENTED(_INDENT_LEVEL_IN_ARGV_CASE_BODY,
 			[[$5="on"]],
+			[_INDICATION_OF_SUPPLY([$1], [$5])],
 			_PASS_WHEN_GETOPT([$2]),
 			[_APPEND_WRAPPED_ARGUMENT_TO_ARRAY_SPACE([$5])],
 		)],
@@ -1234,6 +1248,7 @@ m4_define([_MAKE_DEFAULTS_OPTIONAL], [m4_do(
 			[incr], [_arg_varname=m4_expand(_default)_ENDL_],
 			[repeated], [_arg_varname=(_default)_ENDL_],
 			[_arg_varname=_sh_quote(_default)_ENDL_])],
+		[m4_set_contains([HAVE_SUPPLIED], _argname, [[_supplied]_arg_varname=0]_ENDL_, [])],
 	)])],
 )])
 

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=0,_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=0,_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,11 @@
 
 # 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],[s])
+# ARGBASH_INDICATE_SUPPLIED([prefix])
+# ARGBASH_INDICATE_SUPPLIED([print-optionals],[la])
 # ARG_VERSION([echo "$0 FOO"])
 # ARG_HELP([Testing program m4_fatal(BOOM!)], [m4_fatal([CRASH!])])
 # ARG_DEFAULTS_POS()
@@ -12,7 +16,12 @@
 
 # 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
+    set -u
+    echo "_supplied_arg_prefix=${_supplied_arg_prefix},_supplied_arg_print_optionals=${_supplied_arg_print_optionals},_supplied_arg_la=${_supplied_arg_la},_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!])])