diff options
Diffstat (limited to 'tcl/doc/TraceVar.3')
| -rw-r--r-- | tcl/doc/TraceVar.3 | 43 |
1 files changed, 31 insertions, 12 deletions
diff --git a/tcl/doc/TraceVar.3 b/tcl/doc/TraceVar.3 index b45e754f3c8..3048d18713c 100644 --- a/tcl/doc/TraceVar.3 +++ b/tcl/doc/TraceVar.3 @@ -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 @@ -72,7 +72,7 @@ whenever the variable is read or written or unset. If the trace is created successfully then \fBTcl_TraceVar\fR returns TCL_OK. If an error occurred (e.g. \fIvarName\fR specifies an element of an array, but the actual variable isn't an array) then TCL_ERROR -is returned and an error message is left in \fIinterp->result\fR. +is returned and an error message is left in the interpreter's result. .PP The \fIflags\fR argument to \fBTcl_TraceVar\fR indicates when the trace procedure is to be invoked and provides information @@ -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,10 @@ 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 + |