Merge pull request #88 from matejak/set_completion

Improved help message.

Author: matejak

ChangeLog

@@ -1,5 +1,9 @@
 2.8.1 (TBA)
------------
+------------------
+
+New features:
+
+* The help message now contains reference for one-of argument types (#76).
 
 Bugfixes:
 

bin/argbash

@@ -88,9 +88,9 @@ print_help()
 	printf 'Usage: %s [-o|--output <arg>] [-t|--type <type>] [--(no-)library] [--strip <content>] [--(no-)check-typos] [-c|--(no-)commented] [-I|--search <arg>] [--debug <arg>] [-h|--help] [-v|--version] <input>\n' "$0"
 	printf '\t%s\n' "<input>: The input template file (pass '-' for stdin)"
 	printf '\t%s\n' "-o, --output: Name of the output file (pass '-' for stdout) (default: '-')"
-	printf '\t%s\n' "-t, --type: Output type to generate (default: 'bash-script')"
+	printf '\t%s\n' "-t, --type: Output type to generate. Can be one of: 'bash-script', 'posix-script', 'manpage', 'manpage-defs', 'completion' and 'docopt' (default: 'bash-script')"
 	printf '\t%s\n' "--library, --no-library: Whether the input file if the pure parsing library (off by default)"
-	printf '\t%s\n' "--strip: Determines what to have in the output (default: 'none')"
+	printf '\t%s\n' "--strip: Determines what to have in the output. Can be one of: 'none', 'user-content' and 'all' (default: 'none')"
 	printf '\t%s\n' "--check-typos, --no-check-typos: Whether to check for possible argbash macro typos (on by default)"
 	printf '\t%s\n' "-c, --commented, --no-commented: Commented mode - include explanatory comments with the parsing code (off by default)"
 	printf '\t%s' "-I, --search: Directories to search for the wrapped scripts (directory of the template will be added to the end of the list) (default array elements:"

bin/argbash-init

@@ -77,7 +77,7 @@ print_help()
 	printf '\t%s\n' "--opt: Add an single-valued optional argument (empty by default)"
 	printf '\t%s\n' "--opt-bool: Add an optional boolean argument (empty by default)"
 	printf '\t%s\n' "--wrap: What script(s) to wrap (empty by default)"
-	printf '\t%s\n' "-m, --mode: The slider between feature-rich and simple script. (default: 'default')"
+	printf '\t%s\n' "-m, --mode: The slider between feature-rich and simple script.. Can be one of: 'default', 'full' and 'minimal' (default: 'default')"
 	printf '\t%s\n' "-v, --version: Prints version"
 	printf '\t%s\n' "-h, --help: Prints help"
 }

doc/usage.rst

@@ -285,7 +285,7 @@ The basename is inferred either from the source filename, or from the destinatio
 .. note::
 
    The general recommendation is not to save your scripts to files without suffixes.
-   Keep the ``.sh`` suffixe only for files that are Bash modules.
+   Keep the ``.sh`` suffix only for files that are Bash modules.
 
 After you generate the completion file, put it in the appropriate place (which may vary depending on your environment).
 In order to use it right away, simply source it.
@@ -298,6 +298,11 @@ Typically, you generate bash completion ``my-script.sh`` from the generated scri
 
 and you move the created completion file ``my-script.sh`` to ``/etc/bash_completion.d/`` directory.
 
+.. note::
+
+   Completion is not implemented for positional arguments.
+   The corresponding Bash completion algorithm has to be much more complex in order to distinguish between 1st, 2nd etc. positional arguments.
+
 
 .. _docopt_output:
 

src/argument_value_types.m4

@@ -73,6 +73,16 @@ argbash_api([ARG_TYPE_GROUP_SET], [m4_do(
 )])
 
 
+dnl
+dnl $1: Argname
+dnl $2: If it is of the set type
+dnl $3: If it is NOT of the set type
+m4_define([_IF_ARG_IS_OF_SET_TYPE], [m4_set_contains([GROUP_SET_ARGS], [$1], [$2], [$3])])
+
+
+m4_define([LIST_OF_VALUES_OF_ARGNAME], [[_LIST_]m4_quote(m4_indir([$1_VAL_TYPE]))])
+
+
 dnl
 dnl The common stuff to perform when adding a typed group
 dnl Registers the argument-type pair to be retreived by _GET_VALUE_TYPE or _GET_VALUE_STR

src/docopt.m4

@@ -1,10 +1,26 @@
+m4_include([argument_value_types.m4])
+m4_include([value_validators.m4])
+
+dnl
+dnl $1: Argname
+m4_define([_REPRESENT_VALUE_VERBOSE], [_IF_ARG_IS_OF_SET_TYPE([$1],
+	[m4_list_join(LIST_OF_VALUES_OF_ARGNAME([$1]), [|])],
+	[_CAPITALIZE([$1])])])
+
+
+dnl
+dnl $1: Argname
+m4_define([_REPRESENT_VALUE_SYNOPSIS], [m4_set_contains([TYPED_ARGS], [$1],
+	[m4_indir([$1_VAL_GROUP])],
+	[_CAPITALIZE([$1])])])
+
 
 m4_define([_SYNOPSIS_OF_OPTIONAL_ARGS], [m4_lists_foreach_optional([_ARGS_LONG,_ARGS_SHORT,_ARGS_CATH], [_argname,_arg_short,_arg_type], [m4_do(
 	[ @<:@],
 	[m4_case(_arg_type,
 		[bool], [_FORMAT_OPTIONAL_ARGUMENT_FOR_HELP_SYNOPSIS(_argname, )],
-		[arg], [_FORMAT_OPTIONAL_ARGUMENT_FOR_HELP_SYNOPSIS(_argname, , _CAPITALIZE(_argname))],
-		[repeated], [_FORMAT_OPTIONAL_ARGUMENT_FOR_HELP_SYNOPSIS(_argname, , _CAPITALIZE(_argname))],
+		[arg], [_FORMAT_OPTIONAL_ARGUMENT_FOR_HELP_SYNOPSIS(_argname, , _REPRESENT_VALUE_SYNOPSIS(_argname))],
+		[repeated], [_FORMAT_OPTIONAL_ARGUMENT_FOR_HELP_SYNOPSIS(_argname, , _REPRESENT_VALUE_SYNOPSIS(_argname))],
 		[_FORMAT_OPTIONAL_ARGUMENT_FOR_HELP_SYNOPSIS(_argname, )])],
 	[@:>@],
 	[m4_case(_arg_type,
@@ -38,7 +54,7 @@ m4_define([APPEND_TO_LISTS_WITH_HELP_ELEMENTS], [m4_do(
 	[m4_list_append([_LIST_DOCOPT_OPTIONALS_SPECS], m4_case(_arg_type,
 		[bool], [_FORMAT_OPTIONAL_ARGUMENT_FOR_HELP_SYNOPSIS([$1], [$2], , [, ])],
 		[action], [_FORMAT_OPTIONAL_ARGUMENT_FOR_HELP_SYNOPSIS([$1], [$2], , [, ])],
-		[_FORMAT_OPTIONAL_ARGUMENT_FOR_HELP_SYNOPSIS([$1], [$2], _CAPITALIZE([$1]), [, ])]))],
+		[_FORMAT_OPTIONAL_ARGUMENT_FOR_HELP_SYNOPSIS([$1], [$2], _REPRESENT_VALUE_VERBOSE([$1]), [, ])]))],
 	[m4_list_append([_LIST_LOCAL_DEFAULTS], m4_case(_arg_type,
 		[bool], [[$4]],
 		[action], [],

src/output-completion.m4

@@ -106,14 +106,15 @@ m4_define([_OUTER_CASE_ELEMENTS], [m4_do(
 			)),
 		)],
 	)])],
-	[_JOIN_INDENTED(2,
-		[m4_list_join([OPTIONS_FOLLOWED_BY_SOME_VALUE], [|])[@:}@]],
-		_INDENT_MORE(m4_dquote_elt(
-			[COMPREPLY=( $(compgen -o bashdefault -o default -- "${cur}") )],
-			[return 0],
-			[;;],
-		)),
-	)],
+	[m4_list_ifempty([OPTIONS_FOLLOWED_BY_SOME_VALUE], ,
+		[_JOIN_INDENTED(2,
+			[m4_list_join([OPTIONS_FOLLOWED_BY_SOME_VALUE], [|])[@:}@]],
+			_INDENT_MORE(m4_dquote_elt(
+				[COMPREPLY=( $(compgen -o bashdefault -o default -- "${cur}") )],
+				[return 0],
+				[;;],
+			)),
+		)])],
 	[_JOIN_INDENTED(1,
 		[_INDENT_()[*@:}@]],
 	)],

src/stuff.m4

@@ -222,19 +222,26 @@ m4_define([_MAKE_HELP_SYNOPSIS], [m4_do(
 )])
 
 
+dnl
+dnl $1: Argname
+dnl $2: Prelude
+m4_define([GET_SET_ARG_HELP_MESSAGE],
+	[[$2]m4_list_join(LIST_OF_VALUES_OF_ARGNAME([$1]), [, ], ', ', [ and ])])
+
+
 m4_define([_MAKE_HELP_FUNCTION_POSITIONAL_PART], [m4_lists_foreach_positional(
 	[_ARGS_LONG,_ARGS_CATH,_POSITIONALS_MINS,_POSITIONALS_DEFAULTS,_ARGS_HELP],
 	[argname0,_arg_type,_min_argn,_defaults,_msg], [m4_ifnblank(_msg, [m4_do(
 	[dnl We would like something else for argname if the arg type is 'inf' and _INF_VARNAME is not empty
 ],
 	[m4_pushdef([argname1], <m4_dquote(argname0)[[]m4_ifnblank(m4_quote($][1), m4_quote(-$][1))]>)],
 	[m4_pushdef([argname], m4_if(_arg_type, [inf], [m4_default(_INF_REPR, argname1)], [[argname1($][@)]]))],
+	[_IF_ARG_IS_OF_SET_TYPE(argname0, [m4_define([_msg], m4_dquote(_msg[]GET_SET_ARG_HELP_MESSAGE(argname0, [. Can be one of: ])))])],
 	[_INDENT_()[printf '\t%s\n' "]argname[: ]_SUBSTITUTE_LF_FOR_NEWLINE_WITH_DISPLAY_INDENT_AND_ESCAPE_DOUBLEQUOTES(_msg)],
 	[_POS_ARG_HELP_DEFAULTS([argname], _arg_type, _min_argn, _defaults)],
+	["_ENDL_()],
 	[m4_popdef([argname])],
 	[m4_popdef([argname1])],
-	["
-],
 )])])])
 
 
@@ -253,6 +260,7 @@ m4_define([_MAKE_PRINTF_OPTARG_HELP_STATEMENTS], [m4_do(
 			[_GET_VALUE_DESC([$1])])])])],
 	[m4_pushdef([_options], [$6([$1], [$2], [$3])])],
 	[m4_pushdef([_help_msg], [_SUBSTITUTE_LF_FOR_NEWLINE_WITH_DISPLAY_INDENT_AND_ESCAPE_DOUBLEQUOTES([$5])])],
+	[_IF_ARG_IS_OF_SET_TYPE([$1], [m4_pushdef([_help_msg], m4_quote(_help_msg[]GET_SET_ARG_HELP_MESSAGE([$1], [. Can be one of: ])))])],
 	[m4_case([$3],
 		[action],
 		[_INDENT_()[printf '\t%s\n'] "_options: _help_msg"],
@@ -266,6 +274,7 @@ m4_define([_MAKE_PRINTF_OPTARG_HELP_STATEMENTS], [m4_do(
 _INDENT_()[printf " '%s'" $4]
 _INDENT_()[printf '@:}@\n']])],
 		[_INDENT_()[printf '\t%s\n'] "_options: _help_msg[]m4_ifblank(_default, [[ (no default)]], [ ([default: ]'_default')])"])],
+	[_IF_ARG_IS_OF_SET_TYPE([$1], [m4_popdef([_help_msg])])],
 	[m4_popdef([_help_msg])],
 	[m4_popdef([_options])],
 	[m4_popdef([_type_spec])],

tests/regressiontests/Makefile

@@ -698,7 +698,8 @@ test-group: $(TESTDIR)/test-group.sh
 	ERROR="allowed" $(REVERSE) $< bar
 	@# Assure that there is not the string '_idx' in the script since we don't want indices support in this test
 	! grep -q _idx $<
-	# $< -h | grep action | grep ACTION | grep -q 'foo,baz'
+	$< -h | grep act-ion | grep -q "'foo,baz'"
+	$< -h | grep act-ion | grep -q "'bar bar'"
 	test -z "$(SHELLCHECK)" || $(SHELLCHECK) "$(TESTDIR)/test-group.sh"
 test-group-idx: $(TESTDIR)/test-group-idx.sh
 	$< foo | grep -q "ACT=foo,IDX=0,"

tests/regressiontests/make/tests/tests-types.m4

@@ -26,7 +26,8 @@ ADD_TEST_BASH([test-group], [[
 	ERROR="allowed" $(REVERSE) $< bar
 	@# Assure that there is not the string '_idx' in the script since we don't want indices support in this test
 	! grep -q _idx $<
-	# $< -h | grep action | grep ACTION | grep -q 'foo,baz'
+	$< -h | grep act-ion | grep -q "'foo,baz'"
+	$< -h | grep act-ion | grep -q "'bar bar'"
 ]])
 
 ADD_TEST_BASH([test-group-idx], [[

tests/regressiontests/test-group.m4

@@ -1,8 +1,9 @@
 #!/bin/bash
 
-# ARG_POSITIONAL_SINGLE([act-ion], [], [foo])
+# ARG_POSITIONAL_SINGLE([act-ion], [help], [foo])
 # ARG_TYPE_GROUP_SET([act_null], [ACTION], [act-ion], [foo,baz,bar bar,[foo,baz],])
-# ARG_OPTIONAL_REPEATED([repeated])
+# dnl The construction below is there for precise targeting of a sed substitution.
+# ARG_OPTIONAL_REPEATED([repeated][], , [help])
 # ARG_TYPE_GROUP_SET([act_nonull], [ACTION2], [repeated], [foo,baz])
 # ARG_HELP([Testing program])
 # ARGBASH_GO