Script - Version 1.0 February 1998 
by Benedikt Stefansson benedikt@ucla.edu

RUNTIME SCRIPTING FOR SWARM OBJECTS 

DESCRIPTION 

The Script class is used to read and execute  messages to objects in a
Swarm  simulation at runtime.  This class  runs   as a sub-swarm in  a
top-level Swarm, usually the    ModelSwarm.  It uses probes and    the
activity library, in addition to it's own internal probe-like objects,
to schedule events according to a script, which allows us to alter the
models behavior in   a deterministic fashion without   recompiling the
application. 

The Script object executes method calls to objects, and in order to do
so it must be able to retrieve a pointer to  the object. It does so in
two ways: 

* If the target object is indicated to be the top-level Swarm the
Script probes the Swarm and sends a message to it according to the script. 

* If the target is another object you must provide a "getX" method
in the top-level Swarm where X is usually the name of the target 
object and the Script first accesses the top-level Swarm, calls the getX 
method, and then probes object X to relay the message. 

USING SCRIPT 

The format for a script is as follows: 

@begin
 target || getMethod  time  method  arg1  ...  argN 
 target || getMethod time method arg1 ... argN 
 ... 
 target || getMethod time method arg1 ... argN 
@end
 
Scripts must begin and end with the @begin,@end statements, which
must be at the beginning of a line. You can also put in comments,
both at the beginning of a script and inbetween lines of commands,
starting with a "#". Here is an example script: 

# A comment
@begin 
model 2 printX:Y: 1 2 
model 4 printX:Y: 2 4
model 6 printX:Y: 3 6
# Another comment
model 8 shockMarketTo: -1 
model 10 ping 
getMarket 20 setAlpha: 70
getMarket 30 setAlpha: 50 
getMarket 40 setAlpha: 70 
@end 

In this example the first  5 lines tell the Script  object to call the
ModelSwarm and exectute three different methods, at time steps 2,4,6,8
and 10. The first method  is printX:Y: which  takes two arguments, and
will  be  executed  at time   steps 2,4 and  6.  The  second method is
shockMarketTo:  which  takes one argument    and  will be executed  at
timestep 8. The third method is ping  which takes no argument and will
be executed at time step 10. 

The other three  messages all go to an  object that the ModelSwarm has
access  to. We  retrieve the pointer   to  that object  by calling the
getMarket  method. It gets three messages,  at timesteps 20,30 and 40.
The method name used is setAlpha: and it takes one argument. 
CREATING AND ACTIVATING A SCRIPT OBJECT

Script  executes  as  a subswarm  in a  top-level  Swarm,  such as the
ModelSwarm. You should think of it as  a schedule, and create it along
with the other schedules  in the Swarm.  Here is an  example of how we
enable a script called filename: 

  script=[Script create: [self getZone]]; 
  [script setFile: "filename"]; 
  [script buildActions: self]; 

Where you activate the Swarm's schedules, also put this line: 

  [script activateIn: self]; 

And the activity   library  will take  care of   merging the different
schedules into the right order. 

If you would like to log the events  that the script executes put this
line before  the   line [script  buildActions:  self]  above (the name
filename.log can of course be any arbitrary string): 

  [script logEvents: "filename.log"]; 

SOME CAVEATS

This class is fairly   extensively  debugged, and should output   some
helpful error messages if your script has problems. 

The only known problem at this point is that
when you  create and drop  Scripts as parts of a  subswarm, such as in
the  simpleExperBug  example  from   the  tutorial,   occasionally the
probeLibrary seems to generate a damaged  probe to the ModelSwarm. The
author is studying the problem.  

Benedikt Stefansson <benedikt@ucla.edu>
Last modified: Thu Feb 5 23:00:00 PST 1998
