This command defines a new Soar production. rule is a single argument parsed by the Soar kernel, so it should be enclosed in curly braces to avoid being parsed by Tcl. The overall syntax of a rule is as follows:
name ["documentation-string"] [FLAG*] LHS --> RHS
The first element of a rule is its name. Conventions for names are given in the Soar Users Manual. If given, the documentation-string must be enclosed in double quotes. Optional flags define the type of rule and the form of support its right-hand side assertions will receive. The specific flags are listed in a separate section below. The LHS defines the left-hand side of the production and specifies the conditions under which the rule can be fired. Its syntax is given in detail in a subsequent section. The --> symbol serves to separate the LHS and RHS portions. The RHS defines the right-hand side of the production and specifies the assertions to be made and the actions to be performed when the rule fires. The syntax of the allowable right-hand side actions are given in a later section. The Soar Users Manual gives an elaborate discussion of the design and coding of productions. Please see that reference for tutorial information about productions.
More complex productions can be formed by surrounding the rule with double quotes instead of curly braces. This enables variable and command result substitutions in productions. If another production with the same name already exists, it is excised.
The optional FLAGs are given below. Note that these switches are preceeded by a colon instead of a dash -- this is a Soar parser convention.
lhs ::= cond+ cond ::= positive_cond | - positive_cond positive_cond ::= conds_for_one_id | { cond+ } conds_for_one_id ::= ( [state |impasse] [id_test] attr_value_tests* ) id_test ::= test attr_value_tests ::= [-] ^ attr_test [.attr_test]* value_test* attr_test ::= test value_test ::= test [+] | conds_for_one_id [+] test ::= conjunctive_test | simple_test conjunctive_test ::= { simple_test+ } simple_test ::= disjunction_test | relational_test disjunction_test ::= << constant* >> relational_test ::= [relation] single_test relation ::= <> | < | > | <= | >= | = | <=> single_test ::= variable | constant constant ::= sym_constant | int_constant | float_constant
rhs ::= rhs_action* rhs_action ::= ( variable attr_value_make+ ) | function_call function_call ::= ( function_name rhs_value* ) function_name ::= sym_constant | + | - rhs_value ::= constant | function_call | variable constant ::= sym_constant | int_constant | float_constant attr_value_make ::= ^ rhs_value value_make+ value_make ::= rhs_value preferences preferences ::= [,] | preference-specifier+ preference-specifier ::= naturally-unary-preference [,] | forced-unary-preference | binary-preference rhs_value [,] naturally-unary-preference ::= + | - | ! | ~ | @ binary-preference ::= > | = | < | & forced-unary-preference ::= binary-preference {, | ) | ^}
sp {critter*create*space*critter "Formulate the initial problem space" (state <s> ^superstate nil) --> (<s> ^name move-around ^problem-space <p>) (<p> ^name critter)}
The production above has the name critter*create*space*critter. It has a documentation string that is surrounded by double quotes. The LHS is (state <s> ^superstate nil) and indicates that this rule will match whenever there is a state object that has the attribute-value pair ^superstate nil. The --> arrow separates the left and right-hand sides. The RHS consists of two lines. The first asserts that the state object is to be augmented with the name move-around and a problem space should be created. The second line of the RHS indicates that this problem space should be named critter.
Here is a variant of the above example using double quotes instead of curly braces. Double quotes are needed in order to imbed the value of the Tcl variable soar_agent_name in the production. The value of this variable is used to name the problem-space created.
sp "critter*create*space*critter (state <s> ^superstate nil) --> (<s> ^name move-around ^problem-space <p>) (<p> ^name $soar_agent_name)"
The primary change in the rule is the last clause of the RHS. In that clause, the Tcl variable soar_agent_name is expanded. If this rule is given in an interpreter which has the variable soar_agent_name set to fred, then the RHS would expand to the following before being sent to the Soar kernel to be parsed:
(<p> ^name fred)
Please be aware that when using double quotes, both the dollar sign (variable expansion) and square brackets (command result substitution) will be interpreted by Tcl. If these characters ($, [, and ]) are to be passed to the Soar production parser, they must be escaped (using a backslash) to avoid interpretation by Tcl.
The last production above does not contain a documentation string. If one were added, double quotes would need to be escaped to avoid premature termination of the rule:
sp "critter*create*space*critter \"Formulate the initial problem space\" (state ...