NAME

sp - Define a Soar production

SYNOPSIS

sp rule

DESCRIPTION

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, and the new production is loaded.

RULE FLAGS

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.

:o-support
specifies that all the RHS actions are to be given o-support when the production fires
:no-support
specifies that all the RHS actions are only to be given i-support when the production fires
:default
specifies that this production is a default production (this matters for excise -task and watch task)
:chunk
specifies that this production is a chunk (this matters for learn trace)

LHS GRAMMAR

Grammar for left hand sides of productions:
   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 GRAMMAR

Grammar for right hand sides of productions:
   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 [.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 {,  | )  | ^}

EXAMPLES

There are many examples in the Soar Users Manual and the demos subdirectory. Here is a simple production to create a problem space. It comes from the critter-world demo (see the file critter.tcl):

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.

New for Soar 8, is right-hand-side dot notation. So this production could also be written:


sp {critter*create*space*critter
   "Formulate the initial problem space"
  (state <s> ^superstate nil)
  -->
  (<s> ^name move-around ^problem-space.name 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.

WARNINGS

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

SEE ALSO

excise, learn, watch