Trace formats
=============

Trace formats allow you to customize the appearance of Soar's traces.  The
basic idea is that you specify a set of tracing rules, each having certain
applicability conditions (5) (See Trace formats-Footnotes) and a *format
string*.  When Soar wants to print something, it looks for an applicable rule
(choosing the most specific one if more than one is applicable) and uses its
format string to control the printout.

There are two types of trace formats: *object trace formats* and {stack trace
formats}.  Object trace formats control how individual objects (e.g., G19 or
O37) are printed.  Stack trace formats control how context stack selections
are printed---they are used for the watch 0 trace and for the (pgs) command.

Each tracing rule can have either or both of two applicability restrictions:
     
   * It can have a *type restriction*---it only applies to items of a certain
     type: goal, problem space, state, or operator.  For example, in the
     watch 0 trace, goal selections are preceded by {==>} but other context
     selections aren't by having a stack-trace-format that applies only to
     goals.
     
   * It can have a *name restriction*---it only applies when a certain name
     symbol appears.
     
        * Object trace formats can be restricted to apply only to objects
          whose ^name attribute has a certain symbol as its value.
          
        * Stack trace formats can be restricted to apply only when the
          current problem space has a certain ^name.

Trace formats are manipulated using the object-trace-format and
stack-trace-format commands:


(object-trace-format :add {g|p|s|o|*} [object-name] "format-string")
(object-trace-format :remove {g|p|s|o|*} [object-name])
(object-trace-format) --> list current object trace formats

(stack-trace-format :add {g|p|s|o|*} [ps-name] "format-string")
(stack-trace-format :remove {g|p|s|o|*} [ps-name])
(stack-trace-format) --> list current stack trace formats

With an :add argument, these commands add a new tracing rule.  Its type
restriction is given by either g, p, s, o, or *.  (* indicates that there is
no type restriction---the rule applies to any type.)  An optional name
restriction follows the type restriction.  With a :remove argument, these
commands remove the tracing rule with the given type and name restrictions.

Note that there can only be one rule with given applicability conditions in
the system at a time.  If you try to :add a second rule with identical
conditions, the first one is removed and replaced by the second.

Also note that there can be two rules with different applicability conditions
that happen to apply to the same object.  For example, there could be one
rule with a name restriction that matches a certain object, and a second rule
that has no name restriction (and thus also matches the object).  In this
case, Soar uses whichever rule has the most specific conditions.  (For
purposes of this, name restrictions are considered more specific than type
restrictions.)

EXAMPLE 1.

 The following stack trace formats are the built-in
defaults in Soar 6, and yield the watch 0 trace.

(stack-trace-format :add g "%right[6,%dc]: %rsd[   ]==>G: %cg")
(stack-trace-format :add p "%right[6,%dc]: %rsd[   ]   P: %cp")
(stack-trace-format :add s "%right[6,%dc]: %rsd[   ]   S: %cs")
(stack-trace-format :add o "%right[6,%dc]: %rsd[   ]   O: %co")

The format strings have *escape sequences* embedded in them, starting with a
% sign.  Soar expands the escape sequences into the appropriate pieces of
text.  For example, in the first format string above, %right[6,%dc] means
print the current decision cycle number, right justified in a field 6
characters wide.  After that, the format string says to print a colon and a
space.  %rsd stands for "repeat subgoal depth"---the pattern in the brackets
is printed *current-subgoal-depth* times.  Finally, %cg means to print the
current goal, using whatever object-trace-format is appropriate.

The following escape sequences are supported:
     
   * %% --- print a percent sign.
     
   * %[ --- print a left bracket.
     
   * %] --- print a right bracket.
     
   * %cg, %cp, %cs, %co --- print the current goal,
     problem space, state, or operator using the appropriate object trace
     format.  (These escape sequences are only meaningful in stack traces,
     not object traces.)
     
   * %dc, %ec --- print the current decision cycle number or
     elaboration cycle number.  These are only meaningful in stack traces,
     not object traces; furthermore, they are not meaningful in stack traces
     produced by the (pgs) command.  In these cases, nothing is printed.
     
   * %sd --- print the current subgoal depth (0=top level).  This is
     meaningful only in stack traces, not object traces.
     
   * %rsd[pattern] --- repeat (subgoal depth) times: print the given
     pattern.  The pattern may contain other escape sequences.  This is
     meaningful only in stack traces, not object traces.
     
   * %left[num,pattern] --- print the given pattern, left justified
     in a field of num spaces.
     
   * %right[num,pattern] --- print the given pattern, right
     justified in a field of num spaces.
     
   * %id --- print the identifier of the current object.  
 

Printing attribute values:
     
   * %v[foo] --- print the value(s) of attribute ^foo on the
     current object.  If there is no ^foo on the current object, nothing is
     printed.
     
   * %v[foo.bar.baz] --- same as the above, only follow the given attribute
     path to get the value(s).
     
   * %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
     rather than just as O37, for example.
     
   * %av[args] --- same as %v, except the printed value is
     preceded 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,
     
     "%ifdef[foo has value: %v[foo]]"
     
     will print nothing if there is no ^foo on the current object.
 

EXAMPLE 2.  The following object trace formats are the built-in
defaults.

(object-trace-format :add * "%id %ifdef[(%v[name])]")
(object-trace-format :add g "%id %ifdef[(%v[attribute] %v[impasse])]")
(object-trace-format :add o evaluate-object
                     "%id (evaluate-object %o[object])")

The first rule says: any object is printed be printing its id, plus its name
in parentheses (if it has a name).  So we might print something like this:
O37 (my-operator-name).  The second rule says: to print a goal, print its id,
then the value of its ^attribute and ^impasse attributes (if it has such
attributes); for example, G5 (operator no-change).  The third rule handles
the evaluate-object operators in the selection space, saying: to print an
operator named evaluate-object, first print its id, then print in parentheses
"evaluate-object" followed by a printed representation of the thing being
evaluated.

Notice how the third rule gives a special format to be used only on operators
with a certain name.  You may find this technique useful in your own code, to
get certain parameters printed on certain operators but different parameters
printed on other operators.

EXAMPLE 3.  The following stack trace formats produce a trace where instead
of indenting for goals, the level of subgoal prefaces each context symbol.

(stack-trace-format :add g "%left[6,%dc] (%sd)   G: %cg")
(stack-trace-format :add p "%left[6,%dc] (%sd)   P: %cp")
(stack-trace-format :add s "%left[6,%dc] (%sd)   S: %cs")
(stack-trace-format :add o "%left[6,%dc] (%sd)   O: %co")

EXAMPLE 4.  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.)

(stack-trace-format :add o "%right[6,%dc]: %rsd[   ]   S: %cs
        %rsd[   ]   O: %co")

This format can be useful for watching the effects of a series of operator
applications.  Each time an operator is selected, the current state is also
printed, so you can see what modifications the previous operator made to the
state.