NAME

format-watch - Control the format of printed objects

SYNOPSIS

format-watch [type] [action]

DESCRIPTION

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 pgs 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.

FORMAT CONTROLS

The following control sequences can be used within trace format strings. The S indicates the sequence is ONLY usable in stack traces:

%cs
print the current state using the appropriate object trace format (S)
%co
print the current operator using the appropriate object trace format (S)
%dc
print the current decision cycle number (S). Not meaningful and therefore ignored in stack traces produced by the pgs command.
%ec
print the current elaboration cycle number (S). Not meaningful and therefore ignored in stack traces produced by the pgs command.
%sd
print the current subgoal depth (S). This uses 0 as the top level.
%rsd[pattern]
repeat (subgoal depth) times: print the given pattern (S).
%left[num,pattern]
print the pattern left justified in a field of num spaces.
%right[num,pattern]
print the pattern right justified in a field of num spaces.
%id
print the identifier of the current object.
%v[attr]
print the value(s) of attribute ^attr on the current object. If there is no ^attr on the current object, nothing is printed.
%v[path]
same as the above, only follow the given attribute path to get the value(s). A path is a sequence of attribute names separated by periods, such as foo.bar.baz.
%v[*]
print all values of all attributes on the current object.
%o[args]
same as %v, except that if the value is an identifier, it is printed using the appropriate object trace format.
%av[args]
same as %v, except the printed value is preceeded with "^attr " to indicate the attribute name.
%ao[args]
a combination of the above two.
%ifdef[pattern]
print the given pattern if and only if all escape sequences inside it are "meaningful" or "well-defined." For example, the format string %ifdef[foo has value: %v[foo]] will print nothing if there is no ^foo on the current object.
%%
print a percent sign
%[
print a left bracket
%]
print a right bracket

EXAMPLES

In the following examples, the phrase "the command prints X" is simply an abbreviation for the more accurate phrase "the command defines a trace format string which when used for printing will print X".

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.

SEE ALSO

watch, pgs