merged tcl 8.1 branch back into the main trunk

1 files changed, 30 insertions, 12 deletions

diff --git a/doc/TraceVar.3 b/doc/TraceVar.3
index ac4891d..57a3350 100644
--- a/doc/TraceVar.3
+++ b/doc/TraceVar.3
@@ -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: TraceVar.3,v 1.2 1998/09/14 18:39:50 stanton Exp $
+'\" RCS: @(#) $Id: TraceVar.3,v 1.3 1999/04/16 00:46:33 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures"
@@ -44,7 +44,7 @@ must be in writable memory:  Tcl will make temporary modifications
 to it while looking up the name.
 .AP int flags in
 OR-ed combination of the values TCL_TRACE_READS, TCL_TRACE_WRITES, and
-TCL_TRACE_UNSETS, TCL_PARSE_PART1, and TCL_GLOBAL_ONLY.  
+TCL_TRACE_UNSETS, TCL_TRACE_ARRAY, and TCL_GLOBAL_ONLY.  
 Not all flags are used by all
 procedures.  See below for more information.
 .AP Tcl_VarTraceProc *proc in
@@ -96,6 +96,12 @@ A variable may be unset either explicitly by an \fBunset\fR command,
 or implicitly when a procedure returns (its local variables are
 automatically unset) or when the interpreter is deleted (all
 variables are automatically unset).
+.TP
+\fBTCL_TRACE_ARRAY\fR
+Invoke \fIproc\fR whenever the array command is invoked.
+This gives the trace procedure a chance to update the array before
+array names or array get is called.  Note that this is called
+before an array set, but that will trigger write traces.
 .PP
 Whenever one of the specified operations occurs on the variable,
 \fIproc\fR will be invoked.
@@ -120,7 +126,8 @@ in the normal two-part form (see the description of \fBTcl_TraceVar2\fR
 below for details).
 \fIFlags\fR is an OR-ed combination of bits providing several
 pieces of information.
-One of the bits TCL_TRACE_READS, TCL_TRACE_WRITES, or TCL_TRACE_UNSETS
+One of the bits TCL_TRACE_READS, TCL_TRACE_WRITES, TCL_TRACE_ARRAY,
+or TCL_TRACE_UNSETS
 will be set in \fIflags\fR to indicate which operation is being performed
 on the variable.
 The bit TCL_GLOBAL_ONLY will be set whenever the variable being
@@ -175,24 +182,26 @@ The procedures \fBTcl_TraceVar2\fR, \fBTcl_UntraceVar2\fR, and
 except that the name of the variable consists of two parts.
 \fIName1\fR gives the name of a scalar variable or array,
 and \fIname2\fR gives the name of an element within an array.
-If \fIname2\fR is NULL it means that either the variable is
-a scalar or the trace is to be set on the entire array rather
-than an individual element (see WHOLE-ARRAY TRACES below for
-more information).
-As a special case, if the flag TCL_PARSE_PART1 is specified,
+.VS 8.1
+When \fIname2\fR is NULL, 
 \fIname1\fR may contain both an array and an element name:
 if the name contains an open parenthesis and ends with a
 close parenthesis, then the value between the parentheses is
 treated as an element name (which can have any string value) and
 the characters before the first open
 parenthesis are treated as the name of an array variable.
-If the flag TCL_PARSE_PART1 is given,
-\fIname2\fR should be NULL since the array and element names
-are taken from \fIname1\fR.
+If \fIname2\fR is NULL and \fIname1\fR does not refer
+to an array element 
+.VE
+it means that either the variable is
+a scalar or the trace is to be set on the entire array rather
+than an individual element (see WHOLE-ARRAY TRACES below for
+more information). 
+
 
 .SH "ACCESSING VARIABLES DURING TRACES"
 .PP
-During read and write traces, the
+During read, write, and array traces, the
 trace procedure can read, write, or unset the traced
 variable using \fBTcl_GetVar2\fR, \fBTcl_SetVar2\fR, and
 other procedures.
@@ -245,6 +254,12 @@ access.
 If it deletes the variable then the traced access will return
 an empty string.
 .PP
+When array tracing has been specified, the trace procedure
+will be invoked at the beginning of the array command implementation,
+before any of the operations like get, set, or names have been invoked.
+The trace procedure can modify the array elements with \fBTcl_SetVar\fR
+and \fBTcl_SetVar2\fR.
+.PP
 When unset tracing has been specified, the trace procedure
 will be invoked whenever the variable is destroyed.
 The traces will be called after the variable has been
@@ -343,6 +358,9 @@ to clean up and free their own internal data structures.
 Tcl doesn't do any error checking to prevent trace procedures
 from misusing the interpreter during traces with TCL_INTERP_DESTROYED
 set.
+.PP
+Array traces are not yet integrated with the Tcl "info exists" command,
+nor is there Tcl-level access to array traces.
 
 .SH KEYWORDS
 clientData, trace, variable