home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / lib / tclX-6.4 / help / variables / trace < prev    next >
Encoding:
Text File  |  1992-12-17  |  8.0 KB  |  143 lines
  1.           trace option ?arg arg ...?
  2.                Cause Tcl commands  to  be  executed  whenever  certain
  3.                operations  are  invoked.   At  present,  only variable
  4.                tracing is implemented. The legal option's  (which  may
  5.                be abbreviated) are:
  6.  
  7.                trace variable name ops command
  8.                     Arrange   for  command  to  be  executed  whenever
  9.                     variable name is accessed in one of the ways given
  10.                     by  ops.   Name may refer to a normal variable, an
  11.                     element of an array, or to an  array  as  a  whole
  12.                     (i.e.  name may be just the name of an array, with
  13.                     no parenthesized index).   If  name  refers  to  a
  14.                     whole  array, then command is invoked whenever any
  15.                     element of the array is manipulated.
  16.  
  17.                     Ops indicates which operations  are  of  interest,
  18.                     and  consists  of  one  or  more  of the following
  19.                     letters:
  20.  
  21.                          r
  22.                               Invoke  command whenever the variable is
  23.                               read.
  24.  
  25.                          w
  26.                               Invoke  command whenever the variable is
  27.                               written.
  28.  
  29.                          u
  30.                               Invoke  command whenever the variable is
  31.                               unset.    Variables   can    be    unset
  32.                               explicitly  with  the  unset command, or
  33.                               implicitly when procedures  return  (all
  34.                               of  their  local  variables  are unset).
  35.                               Variables   are    also    unset    when
  36.                               interpreters  are  deleted,  but  traces
  37.                               will not be invoked because there is  no
  38.                               interpreter in which to execute them.
  39.  
  40.                     When  the  trace  triggers,  three  arguments  are
  41.                     appended  to command so that the actual command is
  42.                     as follows:
  43.  
  44.                          command name1 name2 op
  45.  
  46.                     Name1 and name2 give the name(s) for the  variable
  47.                     being  accessed:  if the variable is a scalar then
  48.                     name1 gives the variable's name and  name2  is  an
  49.                     empty  string; if the variable is an array element
  50.                     then name1 gives the name of the array  and  name2
  51.                     gives the index into the array; if an entire array
  52.                     is being deleted and the trace was  registered  on
  53.                     the  overall  array, rather than a single element,
  54.                     then name1 gives the array name and  name2  is  an
  55.                     empty  string.   Op  indicates  what  operation is
  56.                     being performed on the variable, and is one of  r,
  57.                     w, or u as defined above.
  58.  
  59.                     Command executes in the same context as  the  code
  60.                     that   invoked   the  traced  operation:   if  the
  61.                     variable was accessed as part of a Tcl  procedure,
  62.                     then  command  will  have access to the same local
  63.                     variables as code in the procedure.  This  context
  64.                     may  be  different  than  the context in which the
  65.                     trace  was  created.   Note  that  name1  may  not
  66.                     necessarily  be  the  same as the name used to set
  67.                     the trace on the variable;  differences can  occur
  68.                     if  the  access is made through a variable defined
  69.                     with the upvar command.
  70.  
  71.                     For read and write traces, command can modify  the
  72.                     variable  to  affect  the  result  of  the  traced
  73.                     operation.  If command modifies  the  value  of  a
  74.                     variable  during  a  read  trace,  then  the value
  75.                     returned by the traced read operation will be  the
  76.                     value  of  the  variable  after command completes.
  77.                     For write traces, command  is  invoked  after  the
  78.                     variable's  value has been changed; it can write a
  79.                     new  value  into  the  variable  to  override  the
  80.                     original  value  specified in the write operation.
  81.                     The value returned by the traced  write  operation
  82.                     will  be  the  value  of the variable when command
  83.                     completes.  If command returns an error  during  a
  84.                     read  or write trace, then the traced operation is
  85.                     aborted with an error.  This mechanism can be used
  86.                     to  implement  read-only  variables,  for example.
  87.                     Command's result is always ignored.
  88.  
  89.                     While command is executing during a read or  write
  90.                     trace,  traces  on  the  variable  are temporarily
  91.                     disabled.   This  means  that  reads  and   writes
  92.                     invoked  by  command  will occur directly, without
  93.                     invoking command (or any other traces) again.   It
  94.                     is  illegal  to  unset a variable while a trace is
  95.                     active for it.  It is also  illegal  to  unset  an
  96.                     array  if  there  are traces active for any of the
  97.                     array's elements.
  98.  
  99.                     When an unset trace is invoked, the  variable  has
  100.                     already  been  deleted:   it  will  appear  to  be
  101.                     undefined with no  traces.   If  an  unset  occurs
  102.                     because of a procedure return, then the trace will
  103.                     be  invoked  in  the  variable  context   of   the
  104.                     procedure  being  returned to:  the stack frame of
  105.                     the returning  procedure  will  no  longer  exist.
  106.                     Traces are not disabled during unset traces, so if
  107.                     an unset trace command creates  a  new  trace  and
  108.                     accesses the variable, the trace will be invoked.
  109.  
  110.                     If there are multiple traces on  a  variable  they
  111.                     are  invoked  in  order  of  creation, most-recent
  112.                     first.  If one trace returns  an  error,  then  no
  113.                     further  traces  are invoked for the variable.  If
  114.                     an array element has a trace  set,  and  there  is
  115.                     also  a  trace  set  on  the array as a whole, the
  116.                     trace on the overall array is invoked  before  the
  117.                     one on the element.
  118.  
  119.                     Once created, the trace remains in  effect  either
  120.                     until  the trace is removed with the trace vdelete
  121.                     command described below,  until  the  variable  is
  122.                     unset,   or  until  the  interpreter  is  deleted.
  123.                     Unsetting an element  of  array  will  remove  any
  124.                     traces on that element, but will not remove traces
  125.                     on the overall array.
  126.  
  127.                     This command returns an empty string.
  128.  
  129.                trace vdelete name ops command
  130.                     If  there is a trace set on variable name with the
  131.                     operations and command given by ops  and  command,
  132.                     then  the  trace  is removed, so that command will
  133.                     never again be invoked.  Returns an empty string.
  134.  
  135.                trace vinfo name
  136.                     Returns  a  list  containing  one element for each
  137.                     trace  currently  set  on  variable  name.    Each
  138.                     element  of  the  list is itself a list containing
  139.                     two  elements,  which  are  the  ops  and  command
  140.                     associated  with the trace.  If name doesn't exist
  141.                     or doesn't have any traces set, then the result of
  142.                     the command will be an empty string.
  143.