2010-06-17 Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
+ Document, test, and fix AT_ARG_OPTION, AT_ARG_OPTION_ARG.
+ * lib/autotest/general.m4 (_AT_ARG_OPTION): Fix translation of
+ hyphens to underscores when turning option names to variables.
+ Avoid macro name concatenation garbage with trailing `dnl'.
+ (AT_ARG_OPTION, AT_ARG_OPTION_ARG): Overhaul macro description.
+ The OPTIONS are space-separated, not comma-separated. The
+ negative form of AT_ARG_OPTION is prefixed with `--no-'.
+ * tests/autotest.at (AT@&t@_ARG_OPTION, AT@&t@_ARG_OPTION_ARG):
+ New tests.
+ * NEWS: Update.
+ * doc/autoconf.texi (Writing Testsuites): Document AT_ARG_OPTION
+ and AT_ARG_OPTION_ARG.
+ (testsuite Invocation): Call the thingies passed to the
+ testsuite options, not arguments. Note that the testsuite
+ author may add further package-specific options.
+
Autotest: enable colored test results.
* lib/autotest/general.m4 (HELP_TUNING_BEGIN): New diversion.
(HELP_TUNING, HELP_OTHER, HELP_END): Bump diversion numbers.
** Autotest testsuites may optionally provide colored test results.
+** The previously undocumented Autotest macros AT_ARG_OPTION and
+ AT_ARG_OPTION_ARG have seen bug fixes and are documented now.
+ AT_ARG_OPTION has been changed in that the negative of a long option
+ --OPTION is now --no-OPTION rather than --noOPTION.
+
* Major changes in Autoconf 2.65 (2009-11-21) [stable]
Released by Eric Blake, based on git versions 2.64.*.
@command{testsuite} and in @samp{testsuite --version}.
@end defmac
+@defmac AT_ARG_OPTION (@var{options}, @var{help-text}, @
+ @ovar{action-if-given}, @ovar{action-if-not-given})
+@atindex{ARG_OPTION}
+Accept options from the space-separated list @var{options}, a list that
+has leading dashes removed from the options. Long options will be
+prefixed with @samp{--}, single-character options with @samp{-}. The
+first word in this list is the primary @var{option}, any others are
+assumed to be short-hand aliases. The variable associated with it
+is @code{at_arg_@var{option}}, with any dashes in @var{option} replaced
+with underscores.
+
+If the user passes @option{--@var{option}} to the @command{testsuite},
+the variable will be set to @samp{:}. If the user does not pass the
+option, or passes @option{--no-@var{option}}, then the variable will be
+set to @samp{false}.
+
+@var{action-if-given} is run each time the option is encountered; here,
+the variable @code{at_optarg} will be set to @samp{:} or @samp{false} as
+appropriate. @code{at_optarg} is actually just a copy of
+@code{at_arg_@var{option}}.
+
+@var{action-if-not-given} will be run once after option parsing is
+complete and if no option from @var{options} was used.
+
+@var{help-text} is added to the end of the list of options shown in
+@command{testsuite --help} (@pxref{AS_HELP_STRING}).
+
+It it recommended that you use a package-specific prefix to @var{options}
+names in order to avoid clashes with future Autotest built-in options.
+@end defmac
+
+@defmac AT_ARG_OPTION_ARG (@var{options}, @var{help-text}, @
+ @ovar{action-if-given}, @ovar{action-if-not-given})
+@atindex{ARG_OPTION_ARG}
+Accept options with arguments from the space-separated list
+@var{options}, a list that has leading dashes removed from the options.
+Long options will be prefixed with @samp{--}, single-character options
+with @samp{-}. The first word in this list is the primary @var{option},
+any others are assumed to be short-hand aliases. The variable associated
+with it is @code{at_arg_@var{option}}, with any dashes in @var{option}
+replaced with underscores.
+
+If the user passes @option{--@var{option}=@var{arg}} or
+@option{--@var{option} @var{arg}} to the @command{testsuite}, the
+variable will be set to @samp{@var{arg}}.
+
+@var{action-if-given} is run each time the option is encountered; here,
+the variable @code{at_optarg} will be set to @samp{@var{arg}}.
+@code{at_optarg} is actually just a copy of @code{at_arg_@var{option}}.
+
+@var{action-if-not-given} will be run once after option parsing is
+complete and if no option from @var{options} was used.
+
+@var{help-text} is added to the end of the list of options shown in
+@command{testsuite --help} (@pxref{AS_HELP_STRING}).
+
+It it recommended that you use a package-specific prefix to @var{options}
+names in order to avoid clashes with future Autotest built-in options.
+@end defmac
+
@defmac AT_COLOR_TESTS
@atindex{COLOR_TESTS}
Enable colored test results by default when the output is connected to
@section Running @command{testsuite} Scripts
@cindex @command{testsuite}
-Autotest test suites support the following arguments:
+Autotest test suites support the following options:
@table @option
@item --help
Trigger shell tracing of the test groups.
@end table
+Besides these options accepted by every Autotest testsuite, the
+testsuite author might have added package-specific options
+via the @code{AT_ARG_OPTION} and @code{AT_ARG_OPTION_ARG} macros
+(@pxref{Writing Testsuites}); refer to @command{testsuite --help} and
+the package documentation for details.
+
@node Making testsuite Scripts
@section Making @command{testsuite} Scripts
m4_ifdef([AT_case_arg],[m4_undefine([AT_case_arg])])dnl
m4_foreach([AT_option], m4_split(m4_normalize([$1]),[[ \|]+]),
[m4_define_default([AT_first_option],AT_option)dnl
+m4_define_default([AT_first_option_tr],
+ [m4_bpatsubst(m4_defn([AT_first_option]), -, [_])])dnl
m4_append([AT_case],m4_if(m4_len(AT_option),1,[],[-])[-]AT_option, [ | ])dnl
-m4_append([AT_case_no],[--no]AT_option, [ | ])dnl
+m4_append([AT_case_no],[--no-]AT_option, [ | ])dnl
m4_append([AT_case_arg],
m4_if(m4_len(AT_option),1,[],[-])[-]AT_option[=*], [ | ])dnl
])dnl m4_foreach AT_option
])dnl
m4_divert_text([PARSE_ARGS_BEGIN],
[dnl Provide a default value for options without arguments.
-m4_ifvaln([$3],,[at_arg_[]m4_bpatsubst([AT_first_option], -, _)=false])dnl
-at_arg_given_[]m4_bpatsubst([AT_first_option], -, _)=false
+m4_ifvaln([$3],,[at_arg_[]AT_first_option_tr=false])dnl
+at_arg_given_[]AT_first_option_tr=false
])dnl m4_divert_text DEFAULTS
m4_divert_text([PARSE_ARGS],
[dnl Parse the options and args when necessary.
m4_ifvaln([$3],
[ AT_case )
- at_prev=--m4_bpatsubst([AT_first_option], -, _)
+ at_prev=--AT_first_option_tr
;;
AT_case_arg )
- at_arg_[]m4_bpatsubst([AT_first_option], -, _)=$at_optarg
- at_arg_given_[]m4_bpatsubst([AT_first_option], -, _)=:
+ at_arg_[]AT_first_option_tr=$at_optarg
+ at_arg_given_[]AT_first_option_tr=:
$4
;;],
[ AT_case )
at_optarg=:
- at_arg_[]m4_bpatsubst([AT_first_option], -, _)=:
- at_arg_given_[]m4_bpatsubst([AT_first_option], -, _)=:
- m4_ifval([$4],[$4])dnl
+ at_arg_[]AT_first_option_tr=:
+ at_arg_given_[]AT_first_option_tr=:
+ m4_ifval([$4],[$4])[]dnl
;;
AT_case_no )
at_optarg=false
- at_arg_[]m4_bpatsubst([AT_first_option], -, _)=false
- at_arg_given_[]m4_bpatsubst([AT_first_option], -, _)=:
- m4_ifval([$4],[$4])dnl
+ at_arg_[]AT_first_option_tr=false
+ at_arg_given_[]AT_first_option_tr=:
+ m4_ifval([$4],[$4])[]dnl
;;])dnl m4_ifvaln $3
])dnl m4_divert_text PARSE_ARGS
m4_ifvaln([$5],
##])dnl m4_divert_once PARSE_ARGS_END
m4_divert_text([PARSE_ARGS_END],
[
-AS_IF([$at_arg_given_[]m4_bpatsubst([AT_first_option], -, _)],,[$5])dnl
+AS_IF([$at_arg_given_[]AT_first_option_tr],,[$5])dnl
])dnl m4_divert_text PARSE_ARGS_END
])dnl m4_ifvaln $5
])dnl _AT_ARG_OPTION
# AT_ARG_OPTION(OPTIONS,HELP-TEXT,[ACTION-IF-GIVEN],[ACTION-IF-NOT-GIVEN])
# ------------------------------------------------------------------------
-# Accept a set of OPTIONS with arguments. Add HELP-TEXT to the HELP_OTHER
-# diversion.
+# Accept a list of space-separated OPTIONS, all aliases of the first one.
+# Add HELP-TEXT to the HELP_OTHER diversion.
#
-# Preceding dashes should not be passed into OPTIONS. Users will be required
+# Leading dashes should not be passed in OPTIONS. Users will be required
# to pass `--' before long options and `-' before single character options.
#
# $at_arg_OPTION will be set to `:' if this option is received, `false' if
-# if --noOPTION is received, and `false' by default.
+# if --no-OPTION is received, and `false' by default.
#
-# Run ACTION-IF-GIVEN each time an option in OPTIONS is encountered with
-# $at_optarg set to `:' or `false' as appropriate. $at_optarg is actually
-# just a copy of $at_arg_OPTION.
+# Run ACTION-IF-GIVEN each time an option in OPTIONS is encountered; here,
+# $at_optarg will be set to `:' or `false' as appropriate. $at_optarg is
+# actually just a copy of $at_arg_OPTION.
#
-# ACTION-IF-NOT-GIVEN will be run once after option parsing is complete
-# if no option from OPTIONS was found.
+# ACTION-IF-NOT-GIVEN will be run once after option parsing is complete and
+# if no option from OPTIONS was used.
m4_defun([AT_ARG_OPTION],[_AT_ARG_OPTION([$1],[$2],,[$3],[$4])])
# AT_ARG_OPTION_ARG(OPTIONS,HELP-TEXT,[ACTION-IF-GIVEN],[ACTION-IF-NOT-GIVEN])
# ----------------------------------------------------------------------------
-# Accept a set of OPTIONS with arguments, seperated by commas. Add HELP-TEXT
-# to the HELP_OTHER diversion.
+# Accept a set of space-separated OPTIONS with arguments, all aliases of the
+# first one. Add HELP-TEXT to the HELP_OTHER diversion.
#
-# Preceding dashes should not be passed into OPTIONS. Users will be required
+# Leading dashes should not be passed in OPTIONS. Users will be required
# to pass `--' before long options and `-' before single character options.
#
# By default, any argument to these options will be assigned to the shell
# variable $at_arg_OPTION, where OPTION is the first option in OPTIONS with
# any `-' characters replaced with `_'.
#
-# Run ACTION-IF-GIVEN each time an option in OPTIONS is encountered with
-# $at_optarg set. $at_optarg is actually just a copy of $at_arg_OPTION.
+# Run ACTION-IF-GIVEN each time an option in OPTIONS is encountered; here,
+# $at_optarg will be set to the option argument. $at_optarg is actually just
+# a copy of $at_arg_OPTION.
#
# ACTION-IF-NOT-GIVEN will be run once after option parsing is complete
-# if no option from OPTIONS was found.
+# and if no option from OPTIONS was used.
m4_defun([AT_ARG_OPTION_ARG],[_AT_ARG_OPTION([$1],[$2],1,[$3],[$4])])
AT_CLEANUP
+
+## ------------- ##
+## AT_ARG_OPTION ##
+## ------------- ##
+
+AT_CHECK_AT([AT@&t@_ARG_OPTION],
+[[
+AT_INIT([artificial test suite])
+AT_ARG_OPTION([frob fro fr f],
+ [AS_HELP_STRING([-f, --frob], [frobnicate the test run])],
+ [frob=$at_optarg], [frob=default])
+AT_ARG_OPTION([opt-with-hyphen],
+ [AS_HELP_STRING([--opt-with-hyphen], [option name with hypen])])
+AT_ARG_OPTION([ping],
+ [AS_HELP_STRING([--ping], [ping on every encounter])],
+ [echo ping])
+AT_SETUP([test argument handling])
+AT_CHECK([test "$frob" = "$FROB"])
+AT_CHECK([test "$at_arg_frob" = "$FROB_ARG"])
+AT_CLEANUP
+AT_SETUP([test hyphen normalization])
+AT_CHECK([test "$at_arg_opt_with_hyphen" = "$expected"])
+AT_CLEANUP
+]],
+[], [], [stdout], [], [],
+[# We already invoked --help.
+AT_CHECK([grep ' -f, --frob.*frobnicate' stdout], [], [ignore])
+for args in \
+ '1 FROB=default FROB_ARG=false' \
+ '1 -f FROB=: FROB_ARG=:' \
+ '1 --fr FROB=: FROB_ARG=:' \
+ '1 --fro FROB=: FROB_ARG=:' \
+ '1 --frob FROB=: FROB_ARG=:' \
+ '1 --no-f FROB=false FROB_ARG=false' \
+ '1 --no-fr FROB=false FROB_ARG=false' \
+ '1 --no-fro FROB=false FROB_ARG=false' \
+ '1 --no-frob FROB=false FROB_ARG=false' \
+ '2 expected=false' \
+ '2 --opt-with-hyphen expected=:' \
+ '2 --no-opt-with-hyphen expected=false'
+do
+ AT_CHECK([$CONFIG_SHELL ./micro-suite -x $args], [], [ignore])
+done
+AT_CHECK([$CONFIG_SHELL ./micro-suite 2 --ping --no-ping --ping expected=false],
+ [], [stdout])
+AT_CHECK([grep -c ping stdout], [], [[3
+]])
+], [--help])
+
+
+## ----------------- ##
+## AT_ARG_OPTION_ARG ##
+## ----------------- ##
+
+AT_CHECK_AT([AT@&t@_ARG_OPTION_ARG],
+[[
+AT_INIT([artificial test suite])
+AT_ARG_OPTION_ARG([frob fro fr f],
+ [AS_HELP_STRING([-f, --frob=FOO], [frobnicate FOO])],
+ [frob=$at_optarg], [frob=default])
+AT_ARG_OPTION_ARG([opt-with-hyphen],
+ [AS_HELP_STRING([--opt-with-hyphen=ARG],
+ [option name with hypen])])
+AT_ARG_OPTION_ARG([ping],
+ [AS_HELP_STRING([--ping], [ping on every encounter])],
+ [echo ping])
+AT_SETUP([test argument handling])
+AT_CHECK([test "$frob" = "$FROB"])
+AT_CHECK([test "$at_arg_frob" = "$FROB_ARG"])
+AT_CLEANUP
+AT_SETUP([test hyphen normalization])
+AT_CHECK([test "$at_arg_opt_with_hyphen" = "$expected"])
+AT_CLEANUP
+]],
+[], [], [stdout], [], [],
+[# We already invoked --help.
+AT_CHECK([grep ' -f, --frob.*frobnicate' stdout], [], [ignore])
+AT_CHECK([$CONFIG_SHELL ./micro-suite -x --frob], [1], [ignore], [stderr])
+AT_CHECK([grep 'requires an argument' stderr], [], [ignore])
+AT_CHECK([$CONFIG_SHELL ./micro-suite -x --no-frob], [1], [ignore], [stderr])
+AT_CHECK([grep 'invalid option' stderr], [], [ignore])
+for args in \
+ '1 FROB=default FROB_ARG=' \
+ '1 -f bar FROB=bar FROB_ARG=bar' \
+ '1 --fr bar FROB=bar FROB_ARG=bar' \
+ '1 --fro bar FROB=bar FROB_ARG=bar' \
+ '1 --frob bar FROB=bar FROB_ARG=bar' \
+ '1 -f=bar FROB=bar FROB_ARG=bar' \
+ '1 --fr=bar FROB=bar FROB_ARG=bar' \
+ '1 --fro=bar FROB=bar FROB_ARG=bar' \
+ '1 --frob=bar FROB=bar FROB_ARG=bar' \
+ '2 expected=' \
+ '2 --opt-with-hyphen=baz expected=baz'
+do
+ AT_CHECK([$CONFIG_SHELL ./micro-suite -x $args], [], [ignore])
+done
+AT_CHECK([$CONFIG_SHELL ./micro-suite 2 --ping=1 --ping=2 expected=],
+ [], [stdout])
+AT_CHECK([grep -c ping stdout], [], [[2
+]])
+], [--help])
+
+
m4_define([AT_SKIP_PARALLEL_TESTS],
[# Per BUGS, we have not yet figured out how to run parallel tests cleanly
# under dash and some ksh variants. For now, only run this test under
projects / thirdparty / autoconf.git / commitdiff
