NAME

matches - List production match information

SYNOPSIS

matches production-name [-count | -timetags | -wmes | 0 | 1 | 2]
matches [-assertions | -retractions] [-names | -timetags | -wmes | 0 | 1 | 2]

DESCRIPTION

This command prints partial match information for a selected production. If issued at the end of the Decision Phase, it also prints the current set of productions that are about to fire or retract in the next preference phase. This information is useful for determining what changes to working memory are necessary in order to achieve a match of the left-hand sides of productions.

If no production name is given, then it is assumed that the user desires information about the match set, including both assertions and retractions.

OPTIONS

Normally both assertions and retractions are printed by the matches command. This can be restricted using one of the following options:
-assertions
List only those productions about to fire
-retractions
List only those productions about to retract

The optional detail specifies the kind of information desired and must be one of the following (the 0 option is the default):

-count or -names or 0
Print just the partial match counts. If the match set is being printed, then print just the production names.
-timetags or 1
Print the same information as the -count option plus the timetags of wmes at the the first failing condition
-wmes or 2
Print the same information as the -timetags option except print the full wmes rather than just their timetags

EXAMPLES

This example prints the productions which are about to fire and the wmes that match the productions on their left-hand sides:
matches -assertions -wmes

This example prints the wme timetags for a single production. This example takes advantage of the unique prefix abbreviation feature of switches.

matches -t my*first*production

WARNINGS

In Soar 8, the Decision Phase occurs in the middle of the Decision Cycle, followed by the Apply Phase. Therefore, at the end of the Decision Cycle, productions will have already fired and the "matches" command will not be very helpful. To examine the match information in immediately after the Decision Phase in Soar 8, users can implement either of the following callbacks:

monitor -add {matches -wmes} after-decision-phase-cycle
monitor -add {stop-soar -self} after-decision-phase-cycle

The first example can use any options to the matches command, whatever the user finds most helpful. The second option, which stops Soar at the end of the Decision Phase, offers the most flexibility for debugging. It is recommended that users issue this callback for all agents, so they don't get out of synch when running. Once the productions have been debugged, the monitors can be deleted.

SEE ALSO

monitor