Add a new 'empty' output mode

This output mode doesn't contain any Argbash-generated code.
It is suitable for economical storage of Argbash-powered script
if one believes to have reliable access to Argbash.

Author: matejak

bin/argbash

@@ -17,7 +17,7 @@
 # ARG_OPTIONAL_REPEATED([search],[I],[Directories to search for the wrapped scripts (directory of the template will be added to the end of the list)],["."])
 # ARG_OPTIONAL_SINGLE([debug],[],[(developer option) Tell autom4te to trace a macro])
 # ARG_TYPE_GROUP_SET([content],[content],[strip],[none,user-content,all])
-# ARG_TYPE_GROUP_SET([type],[type],[type],[bash-script,posix-script,manpage,manpage-defs,completion,docopt])
+# ARG_TYPE_GROUP_SET([type],[type],[type],[bash-script,posix-script,manpage,manpage-defs,completion,docopt,excised])
 # ARG_DEFAULTS_POS([])
 # ARG_HELP([Argbash is an argument parser generator for Bash.])
 # ARG_VERSION_AUTO([_ARGBASH_VERSION])
@@ -52,12 +52,12 @@ content()
 
 type()
 {
-	local _allowed=("bash-script" "posix-script" "manpage" "manpage-defs" "completion" "docopt") _seeking="$1"
+	local _allowed=("bash-script" "posix-script" "manpage" "manpage-defs" "completion" "docopt" "excised") _seeking="$1"
 	for element in "${_allowed[@]}"
 	do
 		test "$element" = "$_seeking" && echo "$element" && return 0
 	done
-	die "Value '$_seeking' (of argument '$2') doesn't match the list of allowed values: 'bash-script', 'posix-script', 'manpage', 'manpage-defs', 'completion' and 'docopt'" 4
+	die "Value '$_seeking' (of argument '$2') doesn't match the list of allowed values: 'bash-script', 'posix-script', 'manpage', 'manpage-defs', 'completion', 'docopt' and 'excised'" 4
 }
 
 
@@ -90,7 +90,7 @@ print_help()
 	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' "-i, --in-place, --no-in-place: Update a bash script in-place (off by default)"
-	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' "-t, --type: Output type to generate. Can be one of: 'bash-script', 'posix-script', 'manpage', 'manpage-defs', 'completion', 'docopt' and 'excised' (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. 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)"

doc/usage.rst

@@ -248,6 +248,7 @@ Bash completion                 completion                      all
 docopt help message             docopt                          all
 manpage template                manpage                         all
 manpage template definitions    manpage-defs                    all
+No generated code               excised                         all
 ============================    =======================         ==========================
 
 
@@ -328,6 +329,7 @@ Typically, you generate docopt output to the standard output from the generated
    You can't pass the script which sources the parsing code as Argbash input, as it doesn't contain any Argbash macros.
    If you pass the parsing code script/template as Argbash input, the output will have wrong basename, as Argbash will use the basename of the parsing code file, not of the real script.
 
+
 .. _manpage_output:
 
 Manpage output
@@ -351,6 +353,21 @@ So given a argbash-powered script or m4 file, your manpage workflow will typical
   $ man ./my-script.1
 
 
+.. _excise_output:
+
+Output without generated code
++++++++++++++++++++++++++++++
+
+Argbash can also generte output that doesn't contain parsing code --- only user code and the Argbash template.
+If the input contained parsing code, that one gets *excised*.
+There are following examples when the excised output makes sense when dealing with Argbash-powered scripts:
+
+- Space saving for e.g. copy-pasting:
+  Don't involve generated code earlier than you need to, as it does make the script larger, and that can be an annoyance.
+- Normalization of scripts for storage:
+  Store only definitions that are less likely to change, and generate implementation of parsing using the latest greatest version of Argbash just in time.
+
+
 .. _api_change:
 
 API changes support

resources/Makefile

@@ -19,6 +19,7 @@ M4_SRC += \
 	../src/output-bash-script.m4 \
 	../src/output-completion.m4 \
 	../src/output-docopt.m4 \
+	../src/output-excised.m4 \
 	../src/output-manpage.m4 \
 	../src/output-manpage-defs.m4 \
 	../src/output-posix-script.m4 \

src/argbash.m4

@@ -17,7 +17,7 @@
 # ARG_OPTIONAL_REPEATED([search], I, [Directories to search for the wrapped scripts (directory of the template will be added to the end of the list)], ["."])
 # ARG_OPTIONAL_SINGLE([debug],, [(developer option) Tell autom4te to trace a macro])
 # ARG_TYPE_GROUP_SET([content], [content], [strip], [none,user-content,all])
-# ARG_TYPE_GROUP_SET([type], [type], [type], [bash-script,posix-script,manpage,manpage-defs,completion,docopt])
+# ARG_TYPE_GROUP_SET([type], [type], [type], [bash-script,posix-script,manpage,manpage-defs,completion,docopt,excised])
 # ARG_DEFAULTS_POS()
 # ARG_HELP([Argbash is an argument parser generator for Bash.])
 # ARG_VERSION_AUTO([_ARGBASH_VERSION])

src/output-excised.m4

@@ -0,0 +1,7 @@
+dnl
+dnl $1: The macro call (the caller is supposed to pass [$0($@)])
+dnl What is also part of the API: The line
+dnl ### START OF CODE GENERATED BY Argbash vx.y.z one line above ###
+m4_define([ARGBASH_GO_BASE], [m4_do(
+	[[$1]],
+)])

tests/regressiontests/Makefile

@@ -15,6 +15,9 @@ ARGBASH_INIT_EXEC ?= $(ARGBASH_INIT)
 	$(word 2,$^) --type posix-script -o $@ $<
 	sed -i "s|#!/usr/bin/env bash|#!$(shell which dash)|" $@
 
+%-excised.m4: %.sh $(ARGBASH_BIN)
+	$(word 2,$^) --type excised -o $@ $<
+
 %.sh: %.m4 $(ARGBASH_BIN)
 	$(word 2,$^) $< -o $@
 
@@ -63,7 +66,6 @@ SCRIPTS = \
 	$(TESTDIR)/test-getopt-space.sh \
 	$(NUL)
 
-# bash tests
 TESTS += \
 	stability \
 	basic \
@@ -111,12 +113,17 @@ TESTS += \
 	test-getopt-equals \
 	$(NUL)
 
-# docopt tests
 TESTS += \
 	basic-docopt \
 	test-onlyopt-docopt \
 	$(NUL)
 
+
+TESTS += \
+	test-ls_like-excised \
+	$(NUL)
+
+
 TESTS_GEN += \
 	gen-test-pos \
 	gen-test-opt \
@@ -183,6 +190,7 @@ SCRIPTS += \
 	$(TESTDIR)/test-getopt-equals.sh \
 	$(TESTDIR)/basic.txt \
 	$(TESTDIR)/test-onlyopt.txt \
+	$(TESTDIR)/test-ls_like-excised.m4 \
 	$(NUL)
 
 ifneq "$(shell which dash 2> /dev/null)" ""
@@ -600,6 +608,9 @@ test-onlyopt-docopt: $(TESTDIR)/test-onlyopt.txt
 	grep -q "\[--opt-repeated OPT-REPEATED\]\.\.\." $<
 	grep -q "\[--incrx\]\.\.\." $<
 
+test-ls_like-excised: $(TESTDIR)/test-ls_like-excised.m4
+	diff -q $(TESTDIR)/test-ls_like.m4 $<
+
 test-delim-space: $(TESTDIR)/test-delim-space.sh
 	ERROR="unexpected argument '--opt=something'" $(REVERSE) $< --opt=something
 	$< --opt something | grep -q 'OPT_S=something,'

tests/regressiontests/make/Makefile.m4

@@ -11,6 +11,7 @@ m4_define([include_test], [m4_do(
 
 m4_include([tests/tests-base.m4])
 m4_include([tests/tests-docopt.m4])
+m4_include([tests/tests-excise.m4])
 m4_include([tests/tests-delimiters.m4])
 m4_include([tests/tests-init.m4])
 m4_include([tests/tests-env.m4])
@@ -36,6 +37,9 @@ ARGBASH_INIT_EXEC ?= $(ARGBASH_INIT)
 	$(word 2,$^) --type posix-script -o $@ $<
 	[sed -i "s|#!/usr/bin/env bash|#!]$(shell which dash)|" $@
 
+%-excised.m4: %.sh $(ARGBASH_BIN)
+	$(word 2,$^) --type excised -o $@ $<
+
 %.sh: %.m4 $(ARGBASH_BIN)
 	$(word 2,$^) $< -o $@
 
@@ -53,26 +57,31 @@ SCRIPTS = \
 	], m4_set_list([_TEST_SCRIPTS])) \
 	$(NUL)
 
-# bash tests
 TESTS += \
 	m4_join([ \
 	], m4_set_list([BASH_TESTS])) \
 	$(NUL)
 
-# docopt tests
 TESTS += \
 	m4_join([ \
 	], m4_set_list([DOCOPT_TESTS])) \
 	$(NUL)
 
+
+TESTS += \
+	m4_join([ \
+	], m4_set_list([EXCISE_OUTPUT_TESTS])) \
+	$(NUL)
+
+
 TESTS_GEN += \
 	m4_join([ \
 	], m4_set_list([_TEST_GEN_BASH])) \
 	$(NUL)
 
 SCRIPTS += \
 	m4_join([ \
-	], m4_set_list([_TEST_BASH_SCRIPTS]),m4_set_list([_TEST_DOCOPT_SCRIPTS])) \
+	], m4_set_list([_TEST_BASH_SCRIPTS]),m4_set_list([_TEST_DOCOPT_SCRIPTS]),m4_set_list([_TEST_EXCISE_OUTPUT_SCRIPTS])) \
 	$(NUL)
 
 ifneq "$(shell which dash 2> /dev/null)" ""

tests/regressiontests/make/make.m4

@@ -49,16 +49,41 @@ dnl
 dnl Remarks:
 dnl No leading/trailing newlines, around the test body as it already has those.
 m4_define([ADD_DOCOPT_TEST], [m4_do(
-	[m4_pushdef([_script], m4_default_quoted([$4], [$(TESTDIR)/$1.txt]))],
+	[m4_pushdef([_artifact], m4_default_quoted([$4], [$(TESTDIR)/$1.txt]))],
 	[m4_pushdef([_testname], [[$1-docopt]])],
 	[m4_set_add([DOCOPT_TESTS], _testname)],
-	[m4_set_add([_TEST_DOCOPT_SCRIPTS], m4_quote(_script))],
+	[m4_set_add([_TEST_DOCOPT_SCRIPTS], m4_quote(_artifact))],
 	[m4_divert_text([STDOUT3], [m4_do(
-		_testname[: _script[]m4_ifnblank([$3], [ $3])],
+		_testname[: _artifact[]m4_ifnblank([$3], [ $3])],
 		[$2],
 	)])],
 	[m4_popdef([_testname])],
-	[m4_popdef([_script])],
+	[m4_popdef([_artifact])],
+)])
+
+
+dnl
+dnl $1: The test name
+dnl $2: The test body (see also: TEST_BODY)
+dnl
+dnl Remarks:
+dnl No leading/trailing newlines, around the test body as it already has those.
+m4_define([ADD_EXCISE_OUTPUT_TEST], [m4_do(
+	[m4_pushdef([_original_source], [$(TESTDIR)/$1.m4])],
+	[m4_pushdef([_artifact], [$(TESTDIR)/$1-excised.m4])],
+	[m4_pushdef([_testname], [[$1-excised]])],
+	[m4_set_add([EXCISE_OUTPUT_TESTS], _testname)],
+	[m4_set_add([_TEST_EXCISE_OUTPUT_SCRIPTS], m4_quote(_artifact))],
+	[m4_divert_text([STDOUT3], [m4_do(
+		[_testname: _artifact],
+		[
+	diff -q _original_source $<],
+		[$2],
+		[
+],
+	)])],
+	[m4_popdef([_testname])],
+	[m4_popdef([_artifact])],
 )])
 
 

tests/regressiontests/make/tests/tests-excise.m4

@@ -0,0 +1,2 @@
+ADD_EXCISE_OUTPUT_TEST([test-ls_like], [])
+

tests/regressiontests/test-ls_like.m4

@@ -1,16 +1,16 @@
 #!/usr/bin/env -S bash -e
 
-# ARG_POSITIONAL_SINGLE([arg], [], [foo])
-# ARG_OPTIONAL_SINGLE([width], w, [])
-# ARG_OPTIONAL_BOOLEAN([time], t, [])
-# ARG_OPTIONAL_BOOLEAN([long], l, [)
-# ARG_OPTIONAL_INCREMENTAL([verbose], v, [])
+# ARG_POSITIONAL_SINGLE([arg],[],[foo])
+# ARG_OPTIONAL_SINGLE([width],[w],[])
+# ARG_OPTIONAL_BOOLEAN([time],[t],[])
+# ARG_OPTIONAL_BOOLEAN([long],[l],[])
+# ARG_OPTIONAL_INCREMENTAL([verbose],[v],[])
 # ARG_HELP([Testing program])
-# ARGBASH_GO
-#[
+# ARGBASH_GO()
+# [ <-- needed because of Argbash
 
 # Now we take the parsed data and assign them no nice-looking variable names,
 # sometimes after a basic validation
 echo "ARG=$_arg_arg,WIDTH=$_arg_width,TIME=$_arg_time,LONG=$_arg_long,VERBOSE=$_arg_verbose,"
 
-#]
+# ] <-- needed because of Argbash