The format-watch command defines the format to use when printing Soar objects and the Soar goal stack. The optional type, if present, must be the switch -object or -stack and indicates which format to manipulate. Object trace formats control how Soar prints an object--e.g., a certain operator, problem-space, etc. Stack trace formats control how Soar prints its context stack selections in watch 0 and print -stack printouts. If no type is given, then -stack is assumed.
The second portion of the format-watch command is the action to apply to the selected trace format. An action consists of adding or removing formats to selected classes of objects. An action has the following form:
operation class [name] format
The operation must be either -add or -remove. An -add operation adds new trace formats replacing any existing ones with identical applicability conditions. A -remove operation removes trace formats with the given applicability conditions. The combination of class and name define the applicability conditions of the format (i.e., which classes of objects the format applies to). The class must be either s or o and indicates that the operation applies to states or operators, respectively. The wildcard symbol * may also be used to indicate that the format applies to all objects. If an -object trace is being manipulated, then an optional name may be given indicating the format applies only to objects with that name. If a -stack trace is being manipulated, then an optional name may be given indicating the format applies only within problem spaces of that name.
The format string can be any sequence of characters surrounded by curly braces. Note that double quotes are not sufficient because the square brackets in the format string will be interpreted as a command to be evaluated by Tcl. Certain formatting controls can be used within the string--see the section FORMAT CONTROLS below for more information.
If no arguments are given, then format-watch prints the current format settings.
The following control sequences can be used within trace format strings. The S indicates the sequence is ONLY usable in stack traces:
These commands are equivalent to the default settings for stack traces:
format-watch -stack -add s {%right[6,%dc]: %rsd[ ]==>S: %cs} format-watch -stack -add o {%right[6,%dc]: %rsd[ ] O: %co}
The above format strings print the decision cycle number right justified in a field 6 characters wide. After that, a colon and space are printed. Then, three spaces are printed as many times as the subgoal is deep. Finally, a few more characters are printed to indicate the item type and then the item itself is printed.
The following commands are equivalent to the default settings for object traces:
format-watch -object -add * {%id %ifdef[(%v[name])]} format-watch -object -add s {%id %ifdef[(%v[attribute] %v[impasse])]} format-watch -object -add o evaluate-object {%id (evaluate-object %o[object])}
The first command prints an identifier followed by its name in parentheses (if a name is defined) for all objects. This will hold unless overridden by more specific applicability conditions. This first format might print something like: O37 (my-operator-name). The last two commands define (overriding) formats for states and operators. The second command, for states, prints the state identifier followed, in parentheses, by its ^attribute and ^impasse attributes, if they are defined. For example, this might print G5 (operator no-change). Finally, the third command handles evaluate-object operators in the selection space. These operators will be printed as an id followed, in parentheses, by the string "evaluate-object " and the printed representation of the object being printed.
The following stack trace format causes both the current state and current operator to be printed whenever an operator is selected. (There is a linefeed in the middle of the format string.)
format-watch -stack -add o {%right[6,%dc]: %rsd[ ] S: %cs %rsd[ ] O: %co}
The above format is useful for watching the effects of operator applications.