http:^^www.cs.washington.edu^homes^ctkwok^simon-manual.html

This data set contains WWW-pages collected from computer science departments of various universities

There are two ways to invoke an operator:
<ol>
<li> Call it directly (as in Rodney),  for example:
<xmp>
(finger-firstname ?firstname ?domain)
</xmp>
<li> Use the call-op construct,  for example:
<xmp>
(call-op (finger-lastname ?lastname ?domain) ?goal)
</xmp>
</ol>

Whereas it always calls the operator in the first case, Simon will
perform checks on the goal if you use call-op (the second case). <p>

Specifically Simon will check the model manager to see if we have LCW
in the model manager, or whether the goal is already true in the model
manager.  If this is the case, Simon will not call the operator.  This
simulates XII's way of pruning redundant sensing.  In addition, Simon
will check the goal again after it executes the operator to see if the
goal is satisfied.  If the goal is not satisfied, this call-op action
will fail.<p>

<code>&lt;simon-goal&gt;</code> can be either a literal or a variable bound
to a goal.  For example:

<xmp>
(call-op (infer-office-phone-from-finger-rec ?officemate !phone !pt)
				      (office.phone ?officemate !phone))
</xmp>
If the goal is a literal, Simon will bind the variables in the literal
using bindings returned from execution, provided the execution
succeeds.  For example ?officemate and !phone in (office.phone
?officemate !phone) above will be bound.  Normally, the parameters
passed to operator execution (e.g. ?officemate, !phone and !pt) should
also be bound, but notice that if the goal is satisfied before calling
operator, the operator will not execute and thus the parameters will
not be bound.  However variables in the literal will still be bound.
For this example, this means that if the goal literal were true, !pt
wouldn't be bound.


<p>
<h4>FOREACH</h4>

This action has been extended to allow for iteration over all literal 
bindings in the model.
<xmp>
(foreach (<variable> <value>) <action>*) |
(foreach <literal> <action>*) |
(foreach (<xii-scope>) <action>*)  
</xmp>

Examples:
<xmp>
(setq ?x ("asd" "sdf"))
(foreach (?y ?x) (display ?y))
=>"asd"
  "sdf"

(foreach (userid.room ?u ?room) (find-out (lastname ?u "cs")))
</xmp>

In the latter case, Simon will look into the model manager to find all
the possible bindings for <code>?u</code> and <code>?room</code>, and
iterate over them.  The semantics of the literal is a CONTEMPLATE goal
to Simon.<br>
[For a more complete example see FIND below]

<p>
<h4>FIND</h4>

This new action allows for a conditional iteration over a list or
literal bindings.  This is similar to foreach except that iteration
will stop when the first binding has been found that allows a
successful execution of the associated actions, and the FIND action
fails when no such binding can be found.

<xmp>
(find (<variable> <value>) <action>*) | 
(find <literal> <action>*) |
(find (<xii-goal>) <action>*)
</xmp>

Examples:
<xmp>
(setq ?x ("asd" "sdf"))
(find (?y ?x) (display ?y))
=> "asd"
</xmp>
This displays only "asd" because (display "asd") is successful so 
(display "sdf") will not be executed.<p>
<xmp>
(find (userid.room ?u ?room) (achieve (find-out (lastname ?u "cs")))) 
</xmp>
Here, Simon will try to achieve <code>(lastname ?u "cs")</code> by
binding <code>?u</code> and <code>?room</code> to all the possible
bindings that already exists in the model manager.<p>

A more complex example:
<xmp>
  (find (machine.netfind.server ?machine)
	(netfind-person ?lastname ?keywords ?machine)
	(if (netfind.result ?keywords ?lastname !userid !domain)
	    (progn (assert (person.domain ?p !domain))
		   ;; do this to make sure the person is there
		   (finger-lastname ?lastname !domain))
	  (fail)))
</xmp>
Here, we try different netfind servers until we successfully find the
person's userid (because sometimes netfind servers are
overloaded).<br>

<p>
<h4>IF</h4>

<xmp>
(if <condition> <action> <action>)

<condition>        :- <literal> |
                      <xii-goal> |
                      <action>
</xmp>

This has been extended to allow more expressive conditions.  You can
specify actions, XII goals or literals or any mixture of these 3.  All
literals without annotations are assumed to be CONTEMPLATE goals if
the goal is a fact, or FIND-OUT goal otherwise.  For actions,
successful completion means the condition is true.

Examples:
<ol>
<li> Using a literal:
<xmp>
(if (publication.affiliation !pub !affil)
    (assert (affiliation ?p !affil)))
</xmp>
(Here, <code>(publication.affiliation !pub !affil)</code> is a FIND-OUT goal.)
<li> Using an XII goal:
<xmp>
(if (contemplate (is-bound ?domain) f)
    (setq ?domain "cs.washington.edu"))
</xmp>
<li> Using a mixture:
<xmp>
(if (and (userid ?officemate ?u "cs.washington.edu")
	 (neq ?officemate ?person)
	 (call-op 
	     (infer-office-phone-from-finger-rec ?officemate 
						  !phone !pt)
             (office.phone ?officemate !phone)))
    ;; then
    (assert (office.phone ?person !phone))
  ;; else
  (fail))
</xmp>
</ol>
The first example shows using a literal as a condition.  The second one
shows an XII goal with annotation CONTEMPLATE and false truth value.
The third example shows a combination of literals,  XII goal and 
action inside the condition.


<p>
<h4>COND</h4>

<xmp>
(cond <cond-clause>+)

<cond-clause>      :- ((<condition>) <simple-action>+)
</xmp>

This construct avoids cascades of if statements. This is similar to
the Lisp counterpart, you can also have <code>t</code> at the last
condition to specify a default.  Example:
<xmp>
(defaction finger-userid-action (?goal ?person ?domain)
  (cond ((userid ?person ?userid)
	 (call-op (finger-userid ?userid ?domain) ?goal))
	((lastname ?person ?last)
	 (call-op (finger-lastname ?last ?domain) ?goal))
	((firstname ?person ?first)
	 (call-op (finger-firstname ?first ?domain) ?goal))
	(t (display "Can't finger userid"))))
</xmp>
<p>
<h4>CASE</h4>

Again this is an attempt to make SAL more lisp like.  You can match 
constant objects against variables.

<xmp>
(case <variable> <case-choice>*)

<case-choice>      :- (<constant> <action>) | (otherwise <action>) |
                      ((<constant>+) <action>)
</xmp>

Example:
<xmp>
(defaction test-case (?x)
  (achieve (contemplate (annotation ?x ?ann)))
  (case ?ann
    ((satisfy find-out) (display "ASd"))
    (contemplate (display "BDS"))
    (otherwise (display "happy"))))
</xmp>

Here we have an annotation object bound to <code>?ann</code>, and we
match it against the annotation objects inside the case statements.
Like Lisp, we have have a list of constants (first line of the case
statment) in the case condition.  We can also provide a default case
with <code>otherwise</code> (the third line in the above example).

<!--  XXX This doesn't work yet
<p>
<h4>WHILE</h4>
The condition of iteration is extended as the "if" construct. 
<p>
-->

<h4>TRY</h4>

<xmp>
(try <action>* [t]) | (try <simon-goal> <action>* [t])
</xmp>

This action allows for specifying an explicit action choice point.
The sequence of actions is processed until one of them succeeds.  If a
<code>t</code> is present then the TRY action will always succeed,
otherwise it will fail if all listed actions fail.  If you provide an
optional goal as its second argument, try will try all the statements
until the goal is satisfied.  The goal can either be the parameter
passed by Simon into an action (for example, <code>?goal</code>), or a
literal.  If it is a literal, Simon will also try to bind the
variables in the literal.  See the call-op action above for
details.<br>

Here is a simple example of how try works:
<xmp>
(try ?goal
	A
	B
	t)
</xmp>
In this example,  Simon will try action A and see if goal ?goal is satisfied.
If so this try action will terminate successfully,  otherwise Simon will try
B,  if B also fail to satisfy ?goal, this try statment will still terminate
successfully because the last action is a "t".  If it is not a "t",  then
this try statment will fail.<br>

Here is a real example of a try statment:
<xmp>
(defaction office.room.action (?goal ?person !room)
  (if (is-bound ?person)
      (try ?goal
	   (call-op (person-office-room ?person !room) ?goal)
	   (if (lastname ?person ?lastname)
	       (call-op (staffdir ?lastname) ?goal)))
    (fail)))
</xmp>


<p>
<h4>FAIL </h4>

<xmp>
(fail)
</xmp>

Just fails an action.  Usually used in conditionals.

Example:
<xmp>
(if (condition-is-true)
    (do-something)
  (fail))   ;; otherwise we have no method to solve the goal and fail.
</xmp>

<!  I'm not going to include this in the manual
ASSERT-ATTRIBUTE :  This allows the programmer to assert attributes
                      of (partial) objects to the attribute cache.
>

<p>
<h4>PROGN</h4>
<xmp>
(progn <simple-action>+)
</xmp>
This groups actions just like Lisp's progn group procedure calls.
<xmp>
(if (firstname ?person ?firstname)
	(progn (setq ?fi (subseq ?firstname 0 1))
	       (assert (first.initial ?person ?fi))))))
</xmp>
<p>
<hr>

<h2>Miscellaneous</h2>

<h4> SAL new objects </h4>

Simon uses these new object type to distinguish between goal types (e.g.
SATISFY or FIND-OUT goals,  true or false goals etc).<p>

SAL introduces these 2 new object types:
<ol>
<li> <h4>Goal</h4>
These are goal objects being passed in variables.  For example,  the
?goal parameters in most SAL actions are bound to these objects.  Literals
are converted into goals if necessary.

<li> <h4>Annotation</h4>
These are annotation objects representing annotations in alits.  Simon
understands FIND-OUT, SATISFY, CONTEMPLATE and SCOPE.  
</ol>
<h4>SAL new facts and predicates</h4>

Usually they are used in if statments to analyse the nature of the goal 
and perform appropriate actions.  But you can also use them to obtain
values as well.
<ul>
<li>
<xmp>
(goal-tv <goal> <bool>)
<bool> can be one of t, f or u.
<goal> is a goal object.
</xmp>

If <code>bool</code> is bound:<br>
Satisfied if the truth value of the goal matches <code>bool</code>.<p>

If <code>bool</code> is unbound:<br>
Always satisfied.  A side effect is the truth value of the goal is
bound to <code>bool</code>.<p>

<li>
<xmp>
universal? <var>
</xmp>
Satisfied if <code>var</code> is universally quantified.<p>

<li>
<xmp>
annotation <goal> <annotation>
</xmp>
If <code>annotation</code> is bound:<br>
Satisfied if the annotation of <code>goal</code> matches
<code>annotation</code>.<p>

If <code>annotation</code> is unbound:<br>
Always satisfied.  A side effect is the annotation of
<code>goal</code> is bound to <code>annotation</code>.<p>

The supported annotations in SAL are FIND-OUT, SATISFY, CONTEMPLATE and
SCOPE.

A comprehensive example:
<xmp>
(defaction group.protection.file.action (?goal ?file ?protection)
  (if (annotation ?goal satisfy)
      (if (goal-tv ?goal f)
	  (call-op (group-unprotect-file ?file) ?goal)
	(call-op (group-protect-file ?file) ?goal))
    (protection-on-file ?file !g-read !g-write !g-exec)))

</xmp>
</ul>
<p>
<hr>
<a name="Repo">
<h2>Full SAL domains</h2>
</a>
Simon currently has rules for 4 domains: general, machine, files and
people.  The most interesting should be the people domain.<p>

The examples reside in 
<a href="file://localhost/projects/softbots/rodney/working/simon/domains">
/projects/softbots/rodney/working/simon/domains</a>.
The SAL actions are all included in files with -sal.lisp suffix.

<p>
<hr>
<a name = "Universal">
<h3>APPENDIX A Solving universally quantified goals</h3>
</a>

By default, Simon doesn't do anything special for universally
quantified goals.  However, in the case that there are operators with
matching universally quantified effects, we would like to solve such
goals by direct application of these operators.  lcw-match is useful
in allowing us to determine the scope of a goal and thus figuring out
which operators may be applicable.