watch - Run-time tracing of Soar


watch [level*] [-on | -off | -inc[lusive]]
watch [ aliases | backtracing | loading ] [-on | -off ]
watch [ learning ] [-noprint | -print | -fullprint ]


The watch command controls run-time tracing of Soar. With no arguments, this command prints out the current watch status. The various levels are used to modify the current watch settings. Each level can be indicated with either a number or a named flag as follows:

0  none
1  decisions
2  phases
3  productions
4  wmes
5  preferences

Setting either the -on or -off switch selectively turns on or off only that setting. Setting the -inclusive switch (which can be abbreviated as -inc) or setting no flag at all has the effect of setting all levels up to and including the level specified. For example, watch productions -on selectively turns on the tracing of production firings/retractions; watch productions -off selectively turns it off again. watch productions [-inc] turns on the tracing of productions and also turns on tracing of all levels below productions: decisions and phases, too. Individual watch parameters may be used to modify the inclusive settings as well, selectively turning on or off and levels outside or inside the inclusive range.


The following options are allowed (status is given as either -on, -off, or -inclusive, -inc is the default):

0 | none
turns off all printing about Soar's internals
1 | decisions status
controls whether state and operator decisions are printed as they are made
2 | phases status
controls whether decisions cycle phase names are printed as Soar executes.
3 | productions status
controls whether the names of productions are printed as they fire and retract. See the optional arguments below [-all|-chunks|-defaults|-justifications|-user] which specify which types of productions the status argument refers to.
4 | wmes
controls the printing of working memory elements that are added and deleted as productions are fired and retracted.
5 | preferences status
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).
-nowmes | -timetags | -fullwmes
controls the level of detail given about the wmes matched by productions whose firings and retractions are being traced. Level 0|-nowmes means no information about the wmes is printed. Level 1|-timetags means the wme timetags are printed. Level 2|-fullwmes means the whole wmes are printed.
-all|-default|-user|-chunks|-justifications -noprint|-print|-fullprint
allows user to selectively control printing by production *type* as they fire and retract. -noprint prints nothing, -print prints the production name, -fullprint prints the entire production. (fullprint not yet implemented as of 7.0.3) NOTE: these args can be abbreviated by the first char ONLY, otherwise the full arg must be specified.

The following options control printing of other Soar parameters and are not part of the above set of levels which can be controlled as a group.

aliases -on | -off
controls the echoing of aliases as they are defined.
backtracing -on | -off
controls the printing of backtracing information when a chunk or justification is created.
loading -on | -off
controls the printing of '*' for each production loaded and a '#' for each production excised
learning -noprint | -print | -fullprint
controls the printing of chunks/justifications as they are created. -noprint is don't print anything, -names prints just the names, -fullprint prints the entire chunk/justification.


The most common uses of watch are by using the numeric arguments which indicate watch levels:
watch 0

which turns off all printing of Soar internals (same as watch none), or

watch 3

which turns on printing of decisions, phases and productions (same as watch productions). Of course, individual options can be changed as well:

watch 1 wmes -on 

turns on printing of decisions and wmes, but not phases and productions. While

watch 4 phases -off

turns on printing of decisions, productions and wmes, and turns phases off.


The pwatch command can be used to watch named productions.


pwatch print And the soar interface. This is a complex command, and usage is the best definition, that is, how it works is how it works. This tutorial and the help functions not withstanding.