* Implementation of TIP 85. Allows tcltest

        users to add new legal values of the -match option to [test],
        associating each with a Tcl command that does the matching of
        expected results with actual results of tests.  Thanks to
        Arjen Markus.  [Patch 521362]

1 files changed, 22 insertions, 7 deletions

diff --git a/doc/tcltest.n b/doc/tcltest.n
index db5d485..35eb110 100644
--- a/doc/tcltest.n
+++ b/doc/tcltest.n
@@ -7,7 +7,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: tcltest.n,v 1.16 2002/04/18 00:00:19 dgp Exp $
+'\" RCS: @(#) $Id: tcltest.n,v 1.17 2002/06/03 23:44:32 dgp Exp $
 '\" 
 .so man.macros
 .TH "tcltest" n 8.4 Tcl "Tcl Built-In Commands"
@@ -16,7 +16,7 @@
 .SH NAME
 tcltest \- Test harness support code and utilities
 .SH SYNOPSIS
-\fBpackage require tcltest ?2.0?\fR
+\fBpackage require tcltest ?2.1?\fR
 .sp
 \fBtcltest::test \fIname desc ?option value? ?option value? ...\fR
 .br
@@ -36,6 +36,8 @@ tcltest \- Test harness support code and utilities
 .sp
 \fBtcltest::preserveCore \fI?level?\fR
 .sp
+\fBtcltest::customMatch \fImode command\fR
+.sp
 \fBtcltest::testConstraint \fIconstraint ?value?\fR
 .sp
 \fBtcltest::limitConstraints \fI?constraintList?\fR
@@ -214,6 +216,18 @@ tcltest::cleanupTests is called from all.tcl.  Save any core files
 produced in tcltest::temporaryDirectory.
 .RE
 .TP
+\fBtcltest::customMatch \fImode script\fR
+Registers \fImode\fR as a new legal value of the \fB-match\fR option
+to \fItcltest::test\fR.  When the \fB-match \fImode\fR option is
+passed to \fItcltest::test\fR, the script \fIscript\fR will be evaluted
+to compare the actual result of the test script against the expected result.
+To perform the match, the \fIscript\fR is completed with two additional
+words, the expected result, and the actual result, and the completed script
+is evaluated in the global namespace.
+The completed script is expected to return a boolean value indicating
+whether or not the results match.  The built-in matching modes of
+\fItcltest::test\fR are \fBexact\fR, \fBglob\fR, and \fBregexp\fR.
+.TP
 \fBtcltest::testConstraint \fIconstraint ?value?\fR
 Sets or returns the value associated with the named \fIconstraint\fR.
 See the section \fI"Test constraints"\fR for more information.
@@ -405,7 +419,7 @@ test \fIname\fR \fIdescription\fR
     ?-output \fIexpectedOutput\fR?
     ?-errorOutput \fIexpectedError\fR?
     ?-returnCodes \fIcodeList\fR?
-    ?-match \fIexact|glob|regexp\fR?
+    ?-match \fImode\fR?
 .DE
 .PP
 The second form for the \fBtest\fR command (adds brace grouping):
@@ -419,7 +433,7 @@ test \fIname\fR \fIdescription\fR {
     ?-output\fIexpectedOutput\fR?
     ?-errorOutput \fIexpectedError\fR?
     ?-returnCodes \fIcodeList\fR?
-    ?-match \fIexact|glob|regexp\fR?
+    ?-match \fImode\fR?
 }
 .DE
 The \fIname\fR argument should follow the pattern:
@@ -468,11 +482,12 @@ The optional \fIcleanup\fR attribute indicates a script that will be
 run after the script indicated by the \fIscript\fR attribute.  If
 cleanup fails, the test will fail.  
 .TP
-\fB-match \fIregexp|glob|exact\fR
+\fB-match \fImode\fR
 The \fImatch\fR attribute determines how expected answers supplied in
 \fIresult\fR, \fIoutput\fR, and \fIerrorOutput\fR are compared.  Valid
-options for the value supplied are ``regexp'', ``glob'', and
-``exact''. If \fImatch\fR is not specified, the comparisons will be
+options for the value supplied are ``regexp'', ``glob'', ``exact'',
+and any value registered by a prior call to \fItcltest::customMatch\fR.
+If \fImatch\fR is not specified, the comparisons will be
 done in ``exact'' mode by default.
 .TP
 \fB-result \fIexpectedValue\fR