Improve module unit testing

* grecs: Update.
* dico/cmdline.opt: fix the style of option descriptions
* dicod/cmdline.opt (--test option): Rename to --runtest (-r).
Stop further processing after this option.
* dicod/loader.c (dicod_module_test): Fix comment.
* dicod/main.c: Ignore configuration file if in unit testing
mode.

* doc/dico.texi: Document unit testing mode.
* doc/dicod.8in: Likewise.

* modules/metaphone2/tests/build.at: Fix dicod arguments.
* modules/metaphone2/tests/comp01.at: Likewise.
* modules/metaphone2/tests/comp02.at: Likewise.
* modules/metaphone2/tests/encode.at: Likewise.

2 files changed, 217 insertions, 79 deletions

diff --git a/doc/dico.texi b/doc/dico.texi
index a7eb6ca..fdf6920 100644
--- a/doc/dico.texi
+++ b/doc/dico.texi
@@ -2142,7 +2142,7 @@ modules listed in the argument.  For example:
 load-module (stratall,substr,word);
 @end example
 
-
+@anchor{load path}
 @cindex module load path
 @cindex load path
   A @dfn{module load path} is an internal list of directories which
@@ -2152,8 +2152,12 @@ follows:
 
 @enumerate 1
 @item
+@kwindex prepend-load-path
+@kwindex --load-dir
+@kwindex -L
 Optional @dfn{prefix} search directories specified by the
-@code{prepend-load-path} directive (see below).
+@code{prepend-load-path} directive (see below) and the
+@option{--load-dir} (@option{-L}) command line option.
 
 @item
 GNU Dico module directory: @file{$prefix/lib/dico}.
@@ -2660,15 +2664,99 @@ An error in the configuration file was detected.
 @cindex command line options
 @cindex options, @command{dicod}.
    This section summarizes @command{dicod} command line options.
-   
+Options are subdivided in five categories.
+
+@menu
+* Operation Mode::
+* Help Options::
+* Modifier Options::
+* Preprocessor Control::
+* Debugging Options::
+@end menu
+
+@node Operation Mode
+@subsection Dicod Operation Mode   
+The following options select the operation mode.  Only one of them can
+be present in the command line:
+
 @table @option
-@opsummary{define}
-@item --define=@var{symbol}[=@var{value}]
-@itemx -D @var{symbol}[=@var{value}]
-Define the preprocessor symbol @var{symbol}.  Optional @var{value}
-supplies the new symbol value.  This option is passed to the
-preprocessor verbatim.
+@item -E
+Preprocess configuration file and exit.  @xref{Preprocessor}.
+
+@opsummary{inetd}
+@item -i
+@itemx --inetd
+Run in inetd mode.  @xref{Inetd Mode}.
+
+@opsummary{runtest}
+@item -r
+@itemx --runtest
+@itemx --test
+Run unit tests for the module.  Arguments following that option are
+parsed as follows:
+
+@example
+@var{modname} [@var{testargs}] [-- @var{initargs}]
+@end example
+
+@noindent
+where @var{modname} stands for the name of the module to test,
+@var{testargs} are arguments to the @code{dico_run_test} function of
+the module, and @var{initargs} are module initialization arguments
+(passed to the @code{dico_init} method).  Square brackets denote
+optional parts.  Before passing to the corresponding method, both
+argument lists are augmented by prepending module name as the first
+element (with index 0).
+
+This option implies @option{--stderr}.
+
+@kwindex --load-dir
+@kwindex -L
+Use the @option{--load-dir} (@option{-L}) option (@pxref{--load-dir}),
+if the module is not located in one of the default load directories
+(@pxref{load path}).
+
+@xref{Unit Testing}, for a detailed discussion of module unit testing.
+
+@opsummary{lint}
+@item -t
+@itemx --lint
+Check configuration file syntax and exit with code @samp{0} if it is
+OK, or with @samp{78} if there are errors.  @xref{Configuration}.
+@end table
+
+@node Help Options
+@subsection Informational Options
+
+The informational options cause the program to print a selected piece
+of information and exit.  Only one informational option can be used at
+a time.
+
+@table @option
+@opsummary{config-help}
+@item --config-help
+Show a summary of the configuration file syntax and allowed
+statements.  @xref{Configuration}.
 
+@opsummary{help}
+@item -h
+@itemx --help
+Display a short command line option summary and exit.
+
+@opsummary{usage}
+@item --usage
+List all available command line options and exit.
+
+@opsummary{version}
+@item --version
+Print program version and exit.
+@end table
+
+@node Modifier Options
+@subsection Modifier Options
+These options modify the program behavior:
+
+@table @option
 @opsummary{config}
 @item --config=@var{file}
 Read this configuration file instead of the default
@@ -2679,6 +2767,21 @@ Read this configuration file instead of the default
 @itemx --foreground
 Operate in foreground.  @xref{Daemon Mode}.
 
+@opsummary{load-dir}
+@item -L @var{dir}
+@itemx --load-dir=@var{dir}
+Adds @var{dir} to the beginning of module load path.  @xref{load
+path}, for  detailed discussion.
+
+@opsummary{single-process}
+@item -s
+@itemx --single-process
+In daemon mode, process connections in the main process, without
+starting subprocesses for each connection (@pxref{Daemon Mode}).  This
+means that the daemon is able to serve only one client at a time.  The
+@option{--single-process} option is provided for debugging purposes
+only.  Never use it in production environment.
+
 @opsummary{stderr}
 @item --stderr
 Output the diagnostics to stderr.  @xref{Daemon Mode, --stderr}.
@@ -2687,21 +2790,21 @@ Output the diagnostics to stderr.  @xref{Daemon Mode, --stderr}.
 @item --syslog
 After successful startup, output any diagnostic to syslog.  This is
 the default.
+@end table
 
-@item -E
-Preprocess configuration file and exit.  @xref{Preprocessor}.
-
-@opsummary{preprocessor}
-@item --preprocessor=@var{prog}
-Use @var{prog} as a preprocessor for configuration file.  The default
-preprocessor command line is @command{m4 -s}, unless overridden while
-configuring the package (@pxref{Default Preprocessor}).
+@node Preprocessor Control
+@subsection Preprocessor Control
 
-@xref{Preprocessor}.
+The following options control the use of preprocessor.
+@xref{Preprocessor}, for a detailed discussion.
 
-@opsummary{no-preprocessor}
-@item --no-preprocessor
-Do not use external preprocessor.  @xref{Preprocessor}.
+@table @option
+@opsummary{define}
+@item --define=@var{symbol}[=@var{value}]
+@itemx -D @var{symbol}[=@var{value}]
+Define the preprocessor symbol @var{symbol}.  Optional @var{value}
+supplies the new symbol value.  This option is passed to the
+preprocessor verbatim.
 
 @opsummary{include-dir}
 @item -I @var{dir}
@@ -2709,14 +2812,32 @@ Do not use external preprocessor.  @xref{Preprocessor}.
 Add the directory @var{dir} to the list of directories to be searched for
 preprocessor include files.  @xref{Preprocessor}.
 
-@opsummary{single-process}
-@item -s
-@itemx --single-process
-In daemon mode, process connections in the main process, without
-starting subprocesses for each connection (@pxref{Daemon Mode}).  This
-means that the daemon is able to serve only one client at a time.  The
-@option{--single-process} option is provided for debugging purposes
-only.  Never use it in production environment.
+@opsummary{no-preprocessor}
+@item --no-preprocessor
+Do not use external preprocessor.  @xref{Preprocessor}.
+
+@opsummary{preprocessor}
+@item --preprocessor=@var{prog}
+Use @var{prog} as a preprocessor for configuration file.  The default
+preprocessor command line is @command{m4 -s}, unless overridden while
+configuring the package (@pxref{Default Preprocessor}).
+@end table
+
+@node Debugging Options
+@subsection Debugging Options
+@table @option
+@opsummary{debug}
+@item -x
+@itemx --debug=@var{level}
+Set debug verbosity level.  The @var{level} argument is an integer 
+ranging from @samp{0} (no debugging) to @samp{100} (maximum debugging
+information).
+
+@opsummary{no-transcript}
+@item --no-transcript
+Disable transcript mode.  This is the default.  Use this option if you
+wish to temporarily disable transcript mode, enabled in the
+configuration file (@pxref{Logging and Debugging, transcript}).
 
 @opsummary{transcript}
 @item -T
@@ -2730,61 +2851,17 @@ session.  Transcript is logged via the default logging channel
 See also @ref{Session Transcript}, for a description of the similar
 mode in @command{dico}, the client program.
 
-@opsummary{no-transcript}
-@item --no-transcript
-Disable transcript mode.  This is the default.  Use this option if you
-wish to temporarily disable transcript mode, enabled in the
-configuration file (@pxref{Logging and Debugging, transcript}).
-
-@opsummary{inetd}
-@item -i
-@itemx --inetd
-Run in inetd mode.  @xref{Inetd Mode}.
-
-@opsummary{debug}
-@item -x
-@itemx --debug=@var{level}
-Set debug verbosity level.  The @var{level} argument is an integer 
-ranging from @samp{0} (no debugging) to @samp{100} (maximum debugging
-information).
-
 @opsummary{source-info}
 @item --source-info
 Include source line information in the debugging output.
 
 @opsummary{trace-grammar}
 @item --trace-grammar
-Trace parsing of the config file.  The option is provided for debugging
-purposes. 
+Trace parsing of the config file.
 
 @opsummary{trace-lex}
 @item --trace-lex
-Trace the configuration file lexer.  The option is provided for debugging
-purposes. 
-
-@opsummary{config-help}
-@item --config-help
-Show a summary of the configuration file syntax and allowed
-statements.  @xref{Configuration}.
-
-@opsummary{lint}
-@item -t
-@itemx --lint
-Check configuration file syntax and exit with code @samp{0} if it is
-OK, or with @samp{78} if there are errors.  @xref{Configuration}.
-
-@opsummary{help}
-@item -h
-@itemx --help
-Display a short command line option summary and exit.
-
-@opsummary{usage}
-@item --usage
-List all available command line options and exit.
-
-@opsummary{version}
-@item --version
-Print program version and exit.
+Trace the configuration file lexer.
 @end table
 
 @node Modules
@@ -4704,6 +4781,7 @@ This chapter describes the API for Dico loadable modules.
 * dico_database_module::
 * Strategies::
 * Output::
+* Unit Testing::
 @end menu
 
 @node dico_database_module
@@ -4926,6 +5004,12 @@ called before outputting the result set @var{rp} if @code{OPTION MIME}
 is in effect (@pxref{OPTION, OPTION MIME}).
 @end deftypefn
 
+@deftypefn {Dico Callback} int dico_run_test (int @var{argc}, char **@var{argv})
+Runs unit tests for the module.  Argument vector contains all command
+line arguments that follow the @option{--runtest} option, up to the
+@samp{--} marker or end of line, whichever is encountered first.
+@end deftypefn
+
 @node Strategies
 @section Strategies
 
@@ -5220,6 +5304,42 @@ Same as @code{dico_stream_write}, but ends the output with a
 @kbd{newline} character (ASCII 10).              
 @end deftypefn
 
+@node Unit Testing
+@section Module Unit Testing
+@cindex testing, modules
+@cindex unit testing
+The @code{dico_run_test} member of @code{struct dico_database_module}
+(@pxref{dico_database_module, dico_run_test}) points to the function
+that serves as entry point for unit tests of that module.  If it is
+NULL, the module does not support unit testing.  Otherwise, unit tests
+can be run using the following command line syntax:
+
+@example
+$ dicod --runtest @var{module} [@var{test_args}] [-- @var{init_args}]
+@end example
+
+As usual, square brackets denote optional parts.  The arguments that
+follow the @option{--runtest} (@option{-r}) option are collected into
+two arrays: arguments up to the @samp{--} marker form the vector that
+is passed to the module's @code{dico_run_test} function.  The 
+@samp{--} marker is optional.  If present, arguments that follow it
+are collected into a separate argument vector starting from slot 1,
+the slot 0 is set to point to the module name and the resulting vector
+is passed to the @code{dico_init} method of the module.
+
+When running unit tests, @command{dicod} prints its diagnostic
+messages to the standard error output.
+
+@kwindex --load-dir
+@kwindex -L
+Use the @option{--load-dir} (@option{-L}) command line option, if the
+module being tested cannot be found in the default load path
+(@pxref{load path}), e.g.:
+
+@example
+$ dicod -L ../lib --runtest metaphone2 build A B C
+@end example
+
 @node dico client
 @chapter Dico --- a client program.
 @cindex dico, a program
diff --git a/doc/dicod.8in b/doc/dicod.8in
index 243c2c2..599b141 100644
--- a/doc/dicod.8in
+++ b/doc/dicod.8in
@@ -21,9 +21,10 @@ dicod \- GNU dictionary server
 .nh
 .na
 \fBdicod\fR\
- [\fB\-ETVXfist\fR]\
+ [\fB\-ETVfist\fR]\
  [\fB\-D\fR \fISYMBOL\fR[\fB=\fIVALUE\fR]]\
  [\fB\-I\fR \fIDIR\fR]\
+ [\fB\-L\fR \fIDIR\fR]\
  [\fB\-x\fR \fILEVEL\-SPEC\fR]\
  [\fB\-\-config=\fIFILE\fR]\
  [\fB\-\-config\-help\fR]\
@@ -32,6 +33,7 @@ dicod \- GNU dictionary server
  [\fB\-\-foreground\fR]\
  [\fB\-\-include\-dir=\fIDIR\fR]\
  [\fB\-\-inetd\fR]\
+ [\fB\-\-lib-dir=\fIDIR\fR]\
  [\fB\-\-lint\fR]\
  [\fB\-\-no\-preprocessor\fR]\
  [\fB\-\-no\-transcript\fR]\
@@ -40,11 +42,17 @@ dicod \- GNU dictionary server
  [\fB\-\-source\-info\fR]\
  [\fB\-\-stderr\fR]\
  [\fB\-\-syslog\fR]\
- [\fB\-\-test\fR]\
  [\fB\-\-trace\-grammar\fR]\
  [\fB\-\-trace\-lex\fR]\
  [\fB\-\-transcript\fR]
 .PP
+\fBdicod\
+ [\fIOPTIONS\fR]\
+ \fB-r\fR|\fB\-\-runtest\
+ \fIMODULE\fR\
+ [\fIARG\fR...]\
+ [\fB\-\-\fR \fIARG\fR...]
+.PP
 .B dicod \-h
 .PP
 .B dicod \-\-help
@@ -131,8 +139,18 @@ Run in \fIinetd mode\fR.
 .BR \-t ", " \-\-lint
 Check configuration file syntax and exit.
 .TP
-.BR \-X ", " \-\-test
-Run unit tests for module.
+.BR \-r ", " \-\-runtest
+Run unit tests for module.  The arguments that follow this option
+are collected into two arrays: arguments up to the \fB\-\-\fR marker
+(or end of line, if it is not present) form the vector that is passed
+to the module's \fBdico_run_test\fR function.  If the \fB\-\-\fR
+marker is present, arguments that follow it are collected into a
+separate argument vector starting from slot 1, its 0th element is set
+to point to the module name and the resulting vector is passed to the
+\fBdico_init\fR function of the module. 
+
+When running unit tests, configuration file is ignored.  The diagnostic
+messages are printed to the standard error output.
 .SS Modifiers
 .TP
 .BI \-\-config= FILE