Docs for TIP#201 and TIP#212; this allows these TIPs to become Final

3 files changed, 51 insertions, 10 deletions

diff --git a/ChangeLog b/ChangeLog
index a3030ba..3e80c4f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,15 +1,15 @@
 2004-10-08  Donal K. Fellows  <donal.k.fellows@man.ac.uk>
 
-	* tests/expr.test: Basic tests of 'in' and 'ni' behaviour.
+	TIP#201 AND TIP#212 IMPLEMENTATIONS
 
+	* doc/dict.n, doc/expr.n: Documentation for new functionality.
+	* tests/expr.test: Basic tests of 'in' and 'ni' behaviour.
 	* tests/dict.test (dict-21.*,dict-22.*): Tests for [dict update]
 	and [dict with].
-
 	* generic/tclExecute.c (TclExecuteByteCode): Implementation of the
 	INST_LIST_IN and INST_LIST_NOT_IN bytecodes.
 	* generic/tclParseExpr.c (GetLexeme): Parse the 'in' and 'ni'
 	operators for TIP#201.
-
 	* generic/tclDictObj.c (DictUpdateCmd,DictWithCmd): Core of
 	implementation of TIP#212; docs and tests still to do...
 
diff --git a/doc/dict.n b/doc/dict.n
index a84f24f..43466df 100644
--- a/doc/dict.n
+++ b/doc/dict.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: dict.n,v 1.8 2004/10/04 13:06:34 dkf Exp $
+'\" RCS: @(#) $Id: dict.n,v 1.9 2004/10/08 21:39:15 dkf Exp $
 '\"
 .so man.macros
 .TH dict n 8.5 Tcl "Tcl Built-In Commands"
@@ -174,6 +174,22 @@ through nested dictionaries to the mapping to remove. At least one key
 must be specified, but the last key on the key-path need not exist.
 All other components on the path must exist.
 .TP
+\fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR
+Execute the Tcl script in \fIbody\fR with the value for each \fIkey\fR
+(as found by reading the dictionary value in \fIdictionaryVariable\fR)
+mapped to the variable \fIvarName\fR. There may be multiple
+\fIkey\fR/\fIvarName\fR pairs. If a \fIkey\fR does not have a mapping,
+that corresponds to an unset \fIvarName\fR. When \fIbody\fR
+terminates, any changes made to the \fIvarName\fRs is reflected back
+to the dictionary within \fIdictionaryVariable\fR (unless
+\fIdictionaryVariable\fR itself becomes unreadable, when all updates
+are silently discarded), even if the result of \fIbody\fR is an error
+or some other kind of exceptional exit. The result of \fBdict
+update\fR is (unless some kind of error occurs) the result of the
+evaluation of \fIbody\fR. Note that the mapping of values to variables
+does not use traces; changes to the \fIdictionaryVariable\fR's
+contents only happen when \fIbody\fR terminates.
+.TP
 \fBdict values \fIdictionaryValue \fR?\fIglobPattern\fR?
 Return a list of all values in the given dictionary value. If a
 pattern is supplied, only those values that match it (according to the
@@ -182,6 +198,22 @@ will be in an arbitrary implementation-specific order, though where no
 pattern is supplied the i'th key returned by \fBdict keys\fR will be
 the key for the i'th value returned by \fBdict values\fR applied to
 the same dictionary value.
+.TP
+\fBdict with \fIdictionaryVariable \fR?\fIkey ...\fR? \fIbody\fR
+Execute the Tcl script in \fIbody\fR with the value for each key in
+\fIdictionaryVariable\fR mapped (in a manner similarly to \fBdict
+update\fR) to a variable with the same name. Where one or more
+\fIkey\fRs are available, these indicate a chain of nested
+dictionaries, with the innermost dictionary being the one opened out
+for the execution of \fIbody\fR. As with \fBdict update\fR, making
+\fIdictionaryVariable\fR unreadable will make the updates to the
+dictionary be discarded, and this also happens if the contents of
+\fIdictionaryVariable\fR are adjusted so that the chain of
+dictionaries no longer exists. The result of \fBdict update\fR is
+(unless some kind of error occurs) the result of the evaluation of
+\fIbody\fR. Note that the mapping of values to variables does not use
+traces; changes to the \fIdictionaryVariable\fR's contents only happen
+when \fIbody\fR terminates.
 .SH "DICTIONARY VALUES"
 Dictionaries are values that contain an efficient (but \fInot\fR
 order-preserving) mapping from arbitrary keys to arbitrary values.
@@ -214,11 +246,11 @@ set i 0
 puts "There are [\fBdict size\fR $employeeInfo] employees"
 \fBdict for\fR {id info} $employeeInfo {
    puts "Employee #[incr i]: $id"
-   puts "   Name: [\fBdict get\fR $info forenames]\\
-         [\fBdict get\fR $info surname]"
-   puts "   Address: [\fBdict get\fR $info street],\\
-         [\fBdict get\fR $info city]"
-   puts "   Telephone: [\fBdict get\fR $info phone]"
+   \fBdict with\fR info {
+      puts "   Name: $forenames $surname"
+      puts "   Address: $street, $city"
+      puts "   Telephone: $phone"
+   }
 }
 # Another way to iterate and pick out names...
 foreach id [\fBdict keys\fR $employeeInfo] {
diff --git a/doc/expr.n b/doc/expr.n
index e4dbfbc..3519327 100644
--- a/doc/expr.n
+++ b/doc/expr.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: expr.n,v 1.15 2004/09/18 17:37:13 dkf Exp $
+'\" RCS: @(#) $Id: expr.n,v 1.16 2004/10/08 21:39:16 dkf Exp $
 '\" 
 .so man.macros
 .TH expr n 8.5 Tcl "Tcl Built-In Commands"
@@ -147,6 +147,15 @@ Valid for all operand types.
 Boolean string equal and string not equal.  Each operator produces a
 zero/one result.  The operand types are interpreted only as strings.
 .TP 20
+\fBin\0\0ni\fR
+.VS 8.5
+List containment and negated list containment.  Each operator produces
+a zero/one result and treats its first argument as a string and its
+second argument as a Tcl list.  The \fBin\fR operator indicates
+whether the first argument is a member of the second argument list;
+the \fBni\fR operator inverts the sense of the result.
+.VE 8.5
+.TP 20
 \fB&\fR
 Bit-wise AND.  Valid for integer operands only.
 .TP 20