<type>documentation</type>
<domain>debug</domain>
<id>tracking-values</id>
<title>Watching Values</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

Wing can watch debug data values, using a variety of techniques for tracking the value
over time. Watching a value is initiated by right-clicking on a value in the ``Stack Data``,
``Modules``, or ``Watch`` tool and selecting one of the following ways to watch the
value in the `Watch <script:show_panel#panel_type="debug-watch">`__ tool:

  **Watch by Symbolic Path** uses the symbolic path from ``locals()`` or ``globals()`` for
  the currently selected stack frame, and tries to re-evaluate that path whenever the
  value may have changed. For example, if you define a dictionary variable called
  ``myvar`` and watch ``myvar['foo']``, the watched symbolic path is ``myvar.foo``.
  This can be applied to ``myvar`` whether it's a dictionary or an instance with
  attribute ``foo``. The ``Watch`` tool continues to show any value for that slot of
  ``myvar``, even if you delete ``myvar`` and recreate it, change its type, or move to
  another stack frame with a variable of the same name. In other words, the value is
  tracked only by reevaluation of the symbolic path ``myvar.foo`` and is independent of
  the life of any particular object instance.
  
  **Watch by Direct Object Reference** watches the selected value using its object
  reference. If you use this method to watch ``myvar``, it tracks the contents of that
  instance, even if the symbol ``myvar`` goes out of scope or is reassigned a new value.
  The ``Watch`` tool continues to show the contents of the instance as long as it exists,
  until there are no more references to it in the debug process. In other words, the
  symbolic path to the value that was originally watched is irrelevant and only instance
  identity is used to track the value. This is useful for watching a particular instance
  as you step in the debugger, even if references to that instance go out of scope.
  Because it is meaningless to track immutable types like ``None`` this way, this option
  is disabled or enabled according to the value you select to watch.
  
  **Watch by Parent Reference and Slot** combines the above methods by using the object
  reference to the parent of the selected data value and a symbolic representation of the
  slot within the parent in order to determine where to look for the watched value. For
  example, watching ``myinstance.attrib`` will store the object reference to the instance
  referenced by ``myinstance`` and the symbolic name ``attrib``. The ``Watch`` tool
  displays the attribute ``attrib`` in the referenced object instance, as long as there
  are still references to that instance in the debug process. This means that reassignment
  of ``myinstance`` to another value does not alter what is displayed in the
  ``Watch`` tool. Only reassignment of the selected instance slot changes what is displayed.
  
  **Watch by Module Slot** looks up a module by name in ``sys.modules`` and references the value
  within that module by symbolic path. Any change in the value, even across module
  reloads, is reflected in the ``Watch`` tool. This option is only available when clicking
  on values within a module, such as ``sys.path`` or ``os.environ``.

For any of these, if the value cannot be evaluated because it does not exist, the debugger
displays ``<undefined>``. This happens when the last object reference to an instance is
discarded, or if a selected symbolic path is undefined or cannot be evaluated.

The ``Watch`` tool will remember watch points across debug sessions, except those that
make use of an object reference because those do not survive the debug process.

As in the ``Stack Data`` tool, values in the ``Watch`` tool can be displayed as an array
or in textual form in the value details area.  This is done by right-clicking on a value
and selecting ``Show Value as Array`` or ``Show Value as Text``.

