watch
-----

Sets the trace level for Soar's run.  With no arguments given, watch prints
information about the current watch level.

SYNTAX

(watch arg*)
        arg  ::=  -1 | 0 | 0.5 | 1 | 1.5 | 2 | 3 | task
        arg  ::=  :context {on|off}
        arg  ::=  :phases {on|off}
        arg  ::=  :firings [default|user|chunk|nonchunk|all] {on|off}
        arg  ::=     :firings-wmes {0|1|2}
        arg  ::=     :firings-preferences {on|off}
        arg  ::=  :wmes {on|off}
        arg  ::=  :chunk-names {on|off}
        arg  ::=  :justification-names {on|off}
        arg  ::=  :chunks {on|off}
        arg  ::=  :justifications {on|off}
        arg  ::=  :backtracing {on|off}


The following keyword arguments may be given to the `watch' command:

:context controls whether context slot decisions are printed
          
 :phases controls whether phase names are printed
          
 :firings [default|user|chunk|nonchunk|all] controls which production
          
           firings and retractions are printed.  The optional argument (which
           defaults to `all') specifies which types of productions the `on/off'
           argument refers to.
 :firings-wmes controls the level of detail given about the wmes matched
          
           by productions whose firings and retractions are being traced.  Level
           0 means no information about the working memory elements is printed.  Level 1 means the
           working memory element timetags are printed.  Level 2 means the whole working memory elements are printed.
 :firings-preferences controls whether the preferences generated by
          
           the traced productions are printed when those productions fire or
           retract.  When a production fires, all the preferences it generates
           are printed.  When it retracts, only the ones being removed from
           preference memory are printed (i.e., the I-supported ones).
 :wmes controls whether changes to working memory are printed
          
 :chunk-names controls whether names of newly built chunks are printed
          
 :justification-names ditto, only for justifications (internal chunks)
          
 :chunks controls whether newly built chunks are printed
          
 :justifications ditto, only for justifications
          
 :backtracing controls whether backtracing information is printed

These keyword arguments are provided so you can have more complete control
over what gets traced.  The numeric arguments to `watch', as well as the
`print' and `trace' arguments to `learn', provide simple ways of getting some
useful watch settings.

The table below gives the corresponding keyword parameter settings for each
level.

            Watch Level:    -1    0  0.5    1  1.5    2    3
                          ---- ---- ---- ---- ---- ---- ----
  :context                 off   on   on   on   on   on   on
  :phases                  off  off   on   on   on   on   on
  :firings nonchunk        off  off   on   on   on   on   on
    :firings-wmes            0    0    0    1    2    2    2
    :firings-preferences   off  off  off  off  off  off   on
  :wmes                    off  off  off  off  off   on   on

Learn noprint/print/full-print and notrace/trace/full-trace also translate
into keyword parameter settings, as shown in the tables below:

         Learn:   noprint  print  full-print
                  -------  -----  ----------
  :chunk-names        off     on          on
  :chunks             off    off          on

         Learn:   notrace  trace  full-trace
                  -------  -----  ----------
  :firings chunk      off     on          on
  :backtracing        off    off          on


EXAMPLE

Soar> watch 1 :justifications off :chunks on

Soar> watch
Current watch settings:
  Context decisions:  on
  Phases:  on
  Firings/retractions
    default productions:  on
    user productions:  on
    chunks:  on
    justifications:  off
  WME detail level:  1
  Preferences generated by firings/retractions:  off
  Working memory changes:  off
  Chunk names:  on
  Justification names:  on
  Chunks:  on
  Justifications:  off
  Backtracing:  off