Add "testcase group" API

1 files changed, 48 insertions, 2 deletions

diff --git a/doc/dejagnu.texi b/doc/dejagnu.texi
index cafb531..47a3ed7 100644
--- a/doc/dejagnu.texi
+++ b/doc/dejagnu.texi
@@ -3181,7 +3181,7 @@ lappend libdirs $srcdir/../../gcc/testsuite/lib
 load_lib foo.exp
 @end example
 
-@node testsuite procedure,  , load_lib procedure, Core Internal Procedures
+@node testsuite procedure, testcase procedure, load_lib procedure, Core Internal Procedures
 @subsubheading testsuite Procedure
 @findex testsuite
 
@@ -3249,6 +3249,52 @@ Any number of words are joined together into a single name, beginning
 with a multiplex entry point and forming the full name of an API call
 as documented in this manual.
 
+@node testcase procedure,  , testsuite procedure, Core Internal Procedures
+@subsubheading testcase Procedure
+
+The @code{testcase} procedure is a multiplex call for retrieving or
+providing information about the state of the testing process.
+
+@subsubheading testcase group
+
+The @code{testcase group} command provides support for grouping tests
+into hierarchical groups within a test script.
+
+Group names are internally tracked as Tcl lists, but are reported as
+strings delimited using forward slash (@samp{/}) characters.
+Individual name elements may not contain whitespace, but may contain
+forward slash.  A group entered by traversing intermediate levels must
+be left by traversing those same levels.  Groups must properly nest.
+
+There are three uses:
+
+@quotation
+@t{  @b{testcase group}}
+@end quotation
+
+Return the current group as a string delimited with forward slash
+(@samp{/}) characters.
+
+@quotation
+@t{  @b{testcase group begin} @i{name}}
+@end quotation
+@quotation
+@t{  @b{testcase group end} @i{name}}
+@end quotation
+
+These forms allow a group to be explicitly entered and left.  The
+@i{name} parameter must be identical across a pair of these calls, and
+both the @code{begin} and @code{end} calls must be in the same file.
+
+@quotation
+@t{  @b{testcase group eval} @i{name} {@i{code}}}
+@end quotation
+
+This form is available to wrap the @code{begin} and @code{end} calls
+around the execution of the provided @i{code}.  This form is preferred
+for convenience in top-level scripts, but the @code{begin} and
+@code{end} calls are preferred in helper procedures for performance.
+
 @node Procedures For Remote Communication, connprocs, Core Internal Procedures, Built-in Procedures
 @section Procedures For Remote Communication
 
@@ -5855,4 +5901,4 @@ This makes @code{runtest} exit.  Abbreviation: @kbd{q}.
 @c  LocalWords:  subdirectory prepend prepended testsuite filename Expect's svn
 @c  LocalWords:  DejaGnu CVS RCS SCCS prepending subcommands Tcl Awk Readline
 @c  LocalWords:  POSIX KFAIL KPASS XFAIL XPASS hostname multitable gfortran api
-@c  LocalWords:  boolean subcommand
+@c  LocalWords:  boolean subcommand testcase eval