galapagos-website/www/manual.html

1405 lines
47 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>Galapagos - Programmer's Manual</TITLE>
<META NAME="Author" CONTENT="">
<META NAME="GENERATOR" CONTENT="Mozilla/3.01Gold (Win95; I) [Netscape]">
</HEAD>
<BODY background=stone.jpg>
<CENTER>
<A href="implementation.html"><IMG border=0 src=prev.gif ALT=" [PREV] "></A>
<A href="bib.html"><IMG border=0 src=next.gif ALT=" [PREV] "></A>
<A href="index.html#toc"><IMG border=0 src=toc.gif ALT=" [PREV] "></A>
</CENTER>
<HR width=80% align=right color=blue>
<P>
<H1 ALIGN=CENTER><A NAME="top"></A>PROGRAMMER'S MANUAL:<BR>
NONSTANDARD PRIMITIVES</H1>
<UL>
<LI><A HREF="manual.html#ENVIRONMENTS">Environments</A></LI>
<LI><A HREF="manual.html#MESSAGE">Message Queues</A></LI>
<LI><A HREF="manual.html#WINDOW">Window Commands</A></LI>
<LI><A HREF="manual.html#TURTLE">Turtle Commands</A></LI>
<LI><A HREF="manual.html#VISION">Vision</A></LI>
<LI><A HREF="manual.html#INTERRUPTS">Interrupts (Notifications)</A></LI>
<LI><A HREF="manual.html#THREADS">Threads</A></FONT></B><BR></LI>
</UL>
<P>
<HR WIDTH="100%"></P>
<P><FONT FACE="Tms Rmn">Welcome to Galapagos Scheme. This chapter is intended
as a quick reference to Galapagos's extensions over traditional Scheme.
Knowledge of Scheme is assumed. Galapagos Scheme is compliant with both
</FONT>R4RS and IEEE standard P1178. If you've read the chapter titled
&quot;Scheme extensions&quot;, you can and should skip the short introduction
in each section. This complete chapter appears as on-line help in Galapagos,
just a F1 click away.<BR>
</P>
<H2>
<HR WIDTH="100%"></H2>
<H2><A NAME="ENVIRONMENTS"></A>ENVIRONMENTS<BR>
</H2>
<P><FONT FACE="Tms Rmn">An <I>environment</I> is a list of <I>frames</I>,
with the <I>global environment</I> in its tail. A <I>frame</I> is a list
of <I>bindings</I>, which map variables to their values. <I><FONT COLOR="#808080">(define...)
</FONT></I>adds a binding to the frame at the top of the current environment.
<I><FONT COLOR="#808080">(set!...) </FONT></I>family of commands modify
an existing binding, in the frame where it was defined. When a variable
is referenced, the current environment is searched from head to tail, and
the first binding found dictates the value of the variable.</FONT> </P>
<P><FONT FACE="Tms Rmn">The first interpreter, which pops up as Galapagos
is started, runs at the global environment (the way traditional Scheme
works). Additional interpreters (threads) run at distinct environments,
which contain a single initially empty frame, and a pointer to the global
environment. </FONT><BR>
<BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(clone-environment
env [depth]) </FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Clone-environment will make an exact copy of the
environment <B><FONT COLOR="#008080">env</FONT></B>, by copying its frames
one by one. If depth is specified then the new environment will be the
collection of frames which is up to <B><FONT COLOR="#008080">depth</FONT></B>
frames from the current frame. And the last frame will point to the <B><FONT COLOR="#008080">depth
+ 1 </FONT></B>frames from the current one in <B><FONT COLOR="#008080">env</FONT></B>.<B><FONT COLOR="#008080">
</FONT></B></FONT><BR>
</P>
<P><FONT FACE="Tms Rmn">This means that if we are now in environment <B><FONT COLOR="#008080">e1</FONT></B>
and done <I><FONT COLOR="#808080">(define x 7).</FONT></I> Then if we'll
write </FONT></P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define e2 (clone-environment
(current-environment))),</FONT></FONT></I> </P>
<P><FONT FACE="Tms Rmn">the result of</FONT> </P>
<P><FONT FACE="Tms Rmn"><I><FONT COLOR="#808080">(eval@ e2 x</FONT></I>)</FONT>
</P>
<P><FONT FACE="Tms Rmn">will return 7.</FONT><BR>
</P>
<P><FONT FACE="Tms Rmn">But if we are not in a lower frame than the one
x was defined in and write </FONT></P>
<P><FONT FACE="Tms Rmn"><I><FONT COLOR="#808080">(define e2 (clone-environment
(current-environment) 1))</FONT></I> </FONT></P>
<P><FONT FACE="Tms Rmn">and write the value of x is undefined.</FONT> </P>
<P><FONT FACE="Tms Rmn">(Unless it was defined in the global environment)
</FONT><BR>
</P>
<P><FONT FACE="Tms Rmn">Note: Only the bindings are copied. The bound values
are not. Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define x (cons 1 2))</FONT></FONT></I>
</P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define e (clone-environment
(current-environment))) </FONT></FONT></I></P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(eval@ e (set-cdr! X 6))</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">will change the 2 into 6 at both environments.
However,</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(set! x 7)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">will only affect one copy.</FONT><BR>
</P>
<CENTER><P><FONT FACE="Tms Rmn"><B><FONT COLOR="#008080">(pop-environment
env)</FONT></B> </FONT><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Returns the current environment without the first
frame. This means the first frame on the list of frames is &quot;popped&quot;
out.</FONT> </P>
<P><FONT FACE="Tms Rmn">If <B><FONT COLOR="#008080">env</FONT></B> was
made from f3-&gt;f2-&gt;f1-&gt;Global, the result will be f2-&gt;f1-&gt;Global.</FONT>
</P>
<P><FONT FACE="Tms Rmn">(fx means frame number x)</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define e2 (pop-environment
(current-environment)))</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(extend-environment
env)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Extends <B><FONT COLOR="#008080">env </FONT></B>with
a new empty frame (where nothing is defined yet).</FONT> </P>
<P><FONT FACE="Tms Rmn">This means the if <B><FONT COLOR="#008080">env
</FONT></B>was f2-&gt;f1-&gt;Global the result will be f3-&gt;f2-&gt;f1-&gt;Global.</FONT>
</P>
<P><FONT FACE="Tms Rmn">(fx means frame number x)</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define e2 (extend-environment
(current-environment)))</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(current-environment)
</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Returns the current environment.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(environment?
env) </FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">A predicate that is true if <B><FONT COLOR="#008080">env
</FONT></B>is an environment.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><FONT FACE="Tms Rmn"><I><FONT COLOR="#808080">(environment? (current-environment))</FONT></I>
</FONT></P>
<P><FONT FACE="Tms Rmn">Will return true.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(parent-environment)
</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Returns the parent environment. This is the environment
where <B><FONT COLOR="#008080">(new-thread)</FONT></B> was called to create
this thread. The First thread returns the global environment.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(eval@ (parent-environment)
y)</FONT></FONT></I> </P>
<P><FONT FACE="Tms Rmn">Will return the value of y in the parent environment.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(base-environment)
</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">The environment where the interpreter runs. </FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(set-base-environment
env)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Sets the base environment (where the interpreter
runs) to be <B><FONT COLOR="#008080">env</FONT></B></FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(set-base-environment
(parent-environment))</FONT></FONT></I> </P>
<P><FONT FACE="Tms Rmn">Will make this thread run in the same environment
as its father)</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(eval@ env forms...)
</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Evaluates forms in given environment.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define x 7)</FONT></FONT></I>
</P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define e2 (clone-environment
(current-environment)))</FONT></FONT></I> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(eval@ e2 x)</FONT></FONT></I><BR>
</P>
<P><FONT FACE="Tms Rmn">The result will be 7</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(eval@p forms...)
</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Evaluates forms in parent environment.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><FONT FACE="Tms Rmn">Say we want to make our turtle walk 30 degrees
more than the father's turtle. Then we can write:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(set-heading! T (+ 30
(eval@p (turtle-heading t))))</FONT></FONT></I><BR>
</P>
<H2><A NAME="MESSAGE"></A>MESSAGE QUEUES<BR>
</H2>
<P><FONT FACE="Tms Rmn">Message queues are MT-safe mechanisms used to pass
messages, possibly between threads. Messages accepted must be cons, its
car being the message type and the cdr is the message body. Both can be
any kind of Scheme object.</FONT><BR>
<BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(make-queue)</FONT></FONT></B>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Creates a new message queue.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define q (make-queue))
</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(message-queue?
q)</FONT></FONT></B> </P></CENTER>
<P><FONT FACE="Tms Rmn">A predicate that is true if <B><FONT COLOR="#008080">q</FONT></B>
is a queue.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(message-queue? q) </FONT></FONT></I></P>
<P><FONT FACE="Tms Rmn">Will return true for q from the previous example.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(peek-message
q [type])</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Return true if there is a message (of given type,
or of any type if unspecified) in the queue <B><FONT COLOR="#008080">q</FONT></B>.</FONT>
</P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(peek-message q)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will return falsif the queue q is empty.</FONT>
</P>
<P><FONT FACE="Tms Rmn">Note: types are compared using <I><FONT COLOR="#808080">(equals?)</FONT></I>
.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(post-message
q typ_msg)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Posts the message <B><FONT COLOR="#008080">typ_msg</FONT></B>
to the queue <B><FONT COLOR="#008080">q. </FONT></B></FONT></P>
<P><FONT FACE="Tms Rmn"><B><FONT COLOR="#008080">typ_msg</FONT></B> must
be a cons (type . message).</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(post-message q (cons
'type-welcome 'hello))</FONT></FONT><FONT FACE="Miriam"> </FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(get-message [time-out]
q [type])</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Get message from queue <B><FONT COLOR="#008080">q
, </FONT></B>if <B><FONT COLOR="#008080">time-out </FONT></B>is defined
waits only <B><FONT COLOR="#008080">time-out</FONT></B> seconds, and </FONT></P>
<P><FONT FACE="Tms Rmn">optionally gets only messages from type <B><FONT COLOR="#008080">type.</FONT></B></FONT>
</P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define msg (get-message
7 q 'type-welcome))</FONT></FONT></I> </P>
<P><FONT FACE="Tms Rmn">The result will be (if the previous posting was
done) ('type-welcome . 'hello)</FONT> </P>
<P><FONT FACE="Tms Rmn">Note: types are compared using <I><FONT COLOR="#808080">(equals?)</FONT></I>
.</FONT><BR>
</P>
<H2><A NAME="WINDOW"></A>WINDOW COMMANDS<BR>
<BR>
</H2>
<P><FONT FACE="Tms Rmn">A window is the graphical board on which the turtles
and the user draw. It is a bitmap of size 800x600. </FONT><BR>
<BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(new-window [name])
</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Makes a new window, <B><FONT COLOR="#008080">name</FONT></B>
is a symbol or a string which will also be the window's title. The window's
color will be white and it's size 800x600.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define w (new-window
'my-window))</FONT></FONT></I> </P>
<P><FONT FACE="Tms Rmn">Will create a new window with the title my-window.
</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(rename-window!
win [name])</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Renames the window win. <B><FONT COLOR="#008080">name</FONT></B>
is a symbol or a string which will also be the window's title.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(rename-window! w 'foo)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will make the title of w to be foo.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(set-background-color!
R G B)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Set the background color of the window. All the
turtles in the window are notified on the new color (used in pen-erase)</FONT>
</P>
<P><FONT FACE="Tms Rmn">The colors are defined in terms of <B><FONT COLOR="#008080">R</FONT></B>ed
<B><FONT COLOR="#008080">G</FONT></B>reen <B><FONT COLOR="#008080">B</FONT></B>lue
(where 0,0,0 is black and 255,255,255 is white).</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(set-background-color!
w 255 255 0)</FONT></FONT></I> </P>
<P><FONT FACE="Tms Rmn">Will turn the background color of <B><FONT COLOR="#008080">w
</FONT></B>to yellow</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(clear-window
w) </FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Clears the screen from all the previous drawings,
leaving only the turtles images on it.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(clear-window w)</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(load-bitmap w
&quot;filename&quot; [x y])</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Loads the bitmap <B><FONT COLOR="#008080">&quot;filename&quot;</FONT></B>
and makes it the background of w. <B><FONT COLOR="#008080">x y </FONT></B>are
the coordinates of the upper left corner of the picture. If <B><FONT COLOR="#008080">x
y </FONT></B>are not given then the picture is centered.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(load-bitmap w &quot;c:\\windows\\forest.bmp&quot;)
</FONT></FONT></I><BR>
</P>
<P><FONT FACE="Tms Rmn">This operation can also be done using the Board
menu.</FONT><BR>
<BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(save-bitmap w
&quot;filename&quot;)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Saves the window into a bitmap file called <B><FONT COLOR="#008080">&quot;filename&quot;</FONT></B>.</FONT>
</P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(save-bitmap w &quot;my_draw.bmp&quot;)
</FONT></FONT></I><BR>
</P>
<P><FONT FACE="Tms Rmn">This operation can also be done using the Board
menu.</FONT><BR>
</P>
<CENTER><P><FONT FACE="Tms Rmn"><B><FONT COLOR="#008080">(window-alive?
win)</FONT></B> </FONT><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">True if <B><FONT COLOR="#008080">win</FONT></B>
is alive, meaning it can get commands.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(window-name w)</FONT></FONT></B>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Returns the name of <B><FONT COLOR="#008080">w</FONT></B>.</FONT>
</P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(window-name w)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will return &quot;foo&quot; on our window. </FONT><BR>
</P>
<H2><A NAME="TURTLE"></A>TURTLE COMMANDS</H2>
<P><FONT FACE="Tms Rmn">A turtle is an object which is connected to a certain
window. It has inner state variables:</FONT><BR>
</P>
<P><FONT FACE="Tms Rmn"><FONT COLOR="#008080">- width</FONT>: the width
of the pen.</FONT> </P>
<P><FONT FACE="Tms Rmn"><FONT COLOR="#008080">- heading:</FONT> the direction
the turtle will go on command <B><FONT COLOR="#008080">forward!</FONT></B>.
The heading is in degrees where 0 is upwards and adding to the heading
means clock wise rotation.</FONT> </P>
<P><FONT FACE="Tms Rmn"><FONT COLOR="#008080">- visibility:</FONT> if the
body of the turtle is visible on the board or not.</FONT> </P>
<P><FONT FACE="Tms Rmn"><FONT COLOR="#008080">- solid:</FONT> if the turtle
is a &quot;solid&quot; turtle (its interior is also drawn) or &quot;hollow&quot;
one (only its circumference is drawn).</FONT> </P>
<P><FONT FACE="Tms Rmn"><FONT COLOR="#008080">- position:</FONT> the location
of the turtle on the board, where 0,0 is the upper left corner.</FONT>
</P>
<P><FONT FACE="Tms Rmn"><FONT COLOR="#008080">- color:</FONT> the color
of the turtle and it's pen, given in RGB format.</FONT> </P>
<P><FONT FACE="Tms Rmn"><FONT COLOR="#008080">- pen condition: </FONT>the
turtle's pen can be in three states:</FONT> </P>
<UL>
<LI><FONT FACE="Tms Rmn"><FONT COLOR="#000080">pen-down</FONT> : the turtle
will draw as it moves.</FONT> </LI>
<LI><FONT FACE="Tms Rmn"><FONT COLOR="#000080">pen-up</FONT> : the turtle
will not draw as it moves.</FONT> </LI>
<LI><FONT FACE="Tms Rmn"><FONT COLOR="#000080">pen-erase</FONT> : the turtle
will draw in the color of the background as it moves.</FONT> </LI>
</UL>
<P><FONT FACE="Tms Rmn"><FONT COLOR="#008080">- pen width: </FONT>the width
of the pen, the bigger the width the thicker the pen will be.</FONT><BR>
</P>
<P><FONT FACE="Tms Rmn">Turtles can also &quot;see&quot; the board or other
turtles (only from the same board) and can handle user interrupts. A turtle
is always connected to a certain view, which is the view it is drawing
on. Turtles can move between views. </FONT><BR>
<BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(make-turtle win
[name])</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Creates and return a new turtle, in window win,
optional name (where <B><FONT COLOR="#008080">name</FONT></B> can be anything).</FONT>
</P>
<P><FONT FACE="Tms Rmn">The inner state of the new turtle will be:</FONT>
</P>
<UL>
<LI><FONT FACE="Tms Rmn">position - 400,300</FONT> </LI>
<LI><FONT FACE="Tms Rmn">heading - 0</FONT> </LI>
<LI><FONT FACE="Tms Rmn">color - 0,0,0 (black)</FONT> </LI>
<LI><FONT FACE="Tms Rmn">width - 2</FONT> </LI>
<LI><FONT FACE="Tms Rmn">visible - true</FONT> </LI>
<LI><FONT FACE="Tms Rmn">solid - true</FONT> </LI>
</UL>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define t (make-turtle
'turty)) </FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(turtle-alive?
t) </FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">A predicate that is true if <B><FONT COLOR="#008080">t</FONT></B>
is alive, meaning <B><FONT COLOR="#008080">t </FONT></B>can get commands.</FONT>
</P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(turtle-alive? t) </FONT></FONT></I></P>
<P><FONT FACE="Tms Rmn">Will return true on our t.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(clone-turtle
t [name])</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Creates an identical turtle to <B><FONT COLOR="#008080">t</FONT></B>
(same inner state).</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define t2 (clone-turtle
t))</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(rename-turtle
t [name])</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Renames the turtle, name is a string or a symbol</FONT>
</P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(rename-turtle t 'pongy)
</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(turtle-name t)
</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Returns the name of <B><FONT COLOR="#008080">t</FONT></B>.</FONT>
</P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(turtle-name t)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will return &quot;pongy&quot; on our t.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(forward! t d)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Makes <B><FONT COLOR="#008080">t</FONT></B> go
forward (in the heading of <B><FONT COLOR="#008080">t</FONT></B>)
<B><FONT COLOR="#008080">d</FONT></B> steps.
<B><FONT COLOR="#008080">t </FONT></B>will draw while going according to
the state of it's pen.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(forward! t 100)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will cause <B><FONT COLOR="#008080">t</FONT></B>
to go forward 100 steps. (In our case since <B><FONT COLOR="#008080">t</FONT></B>'s
heading hasn't changed it will go upwards)</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(turtle-width!
t n)</FONT></FONT></B> </P></CENTER>
<P><FONT FACE="Tms Rmn">Set the width of <B><FONT COLOR="#008080">t</FONT></B>'s
pen to be <B><FONT COLOR="#008080">n</FONT></B>. The bigger <B><FONT COLOR="#008080">n</FONT></B>
is the wider the pen will be.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(backwards! t
d) </FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Same as forward, just in the opposite direction.</FONT>
</P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(backwards! t 100)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">is the same as </FONT></P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(forward! t -100)</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(right! t d)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Will set a new heading to <B><FONT COLOR="#008080">t</FONT></B>.
The new heading is the old heading plus <B><FONT COLOR="#008080">d, </FONT></B>meaning
<B><FONT COLOR="#008080">t</FONT></B> will rotate clock-wise.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(right! t 90)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will make <B><FONT COLOR="#008080">t</FONT></B>
turn 90 degrees to the </FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(left! t d)</FONT></FONT></B>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Same as right, other direction</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(set-heading!
t val)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Sets the heading of <B><FONT COLOR="#008080">t</FONT></B>
to be <B><FONT COLOR="#008080">val. </FONT></B>0 is upwards and 90 is to
the right.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(set-heading t 180)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will cause <B><FONT COLOR="#008080">t</FONT></B>
to point to the bottom of the screen.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(move-to! t x
y) </FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Makes <B><FONT COLOR="#008080">t</FONT></B> move
to point <B><FONT COLOR="#008080">x,y</FONT></B> without painting. 0,0
is the top-left corner of the window.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(move-to! T 100 100)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will cause <B><FONT COLOR="#008080">t</FONT></B>
to move to point 100,100.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(draw-to! t x
y) </FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Moves <B><FONT COLOR="#008080">t</FONT></B> to
<B><FONT COLOR="#008080">x,y </FONT></B>possibly drawing or erasing according
to the state of <B><FONT COLOR="#008080">t</FONT></B>'s pen.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(draw-to! t 0 0)</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(move-turtle-to-window
t win)</FONT></FONT></B> </P></CENTER>
<P><FONT FACE="Tms Rmn">Move <B><FONT COLOR="#008080">t</FONT></B> to the
window <B><FONT COLOR="#008080">win</FONT></B></FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(move-turtle-to-window
t w)</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(pen-up! t)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">The pen of <B><FONT COLOR="#008080">t</FONT></B>
is up, so he won't paint when moving.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(pen-up! t)</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(pen-down! t)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Causes <B><FONT COLOR="#008080">t</FONT></B>'s
pen to be down, meaning he will draw as he is moving.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(pen-erase! t)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Causes <B><FONT COLOR="#008080">t</FONT></B>'s
pen to be in the same color as the background color of the window it is
attached to.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(show-turtle!
t) </FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Makes <B><FONT COLOR="#008080">t</FONT></B> visible.
Meaning he will be seen on the board.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(show-turtle! t)</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(hide-turtle!
t) </FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Makes <B><FONT COLOR="#008080">t</FONT></B> invisible.
Meaning he will not be seen on the board. (but all the drawing he does
will be seen)</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(hide-turtle! t)</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(make-turtle-solid!
t)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Makes <B><FONT COLOR="#008080">t</FONT></B> a solid
turtle.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(make-turtle-hollow!
t)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Make <B><FONT COLOR="#008080">t</FONT></B> a &quot;hollow&quot;
turtle.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(kill-turtle!
t) </FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Kills <B><FONT COLOR="#008080">t</FONT></B>. Meaning
it will be erased from the board and will not accept further commands.</FONT>
</P>
<P><FONT FACE="Tms Rmn">Note: This is the only way to get rid of a turtle.</FONT>
</P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(kill-turtle! t)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will cause when writing <I><FONT COLOR="#808080">t</FONT></I>
in the command line to the response</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">#&lt;dead turtle&gt;</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(set-color! t
R G B) or (set-color! t (list R G B)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Sets <B><FONT COLOR="#008080">t</FONT></B>'s color
(and it's pen), in RGB format.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(set-color! t 255 0 255)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will cause <B><FONT COLOR="#008080">t</FONT></B>
to be pinkish.</FONT> </P>
<P><FONT FACE="Tms Rmn">Same as:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define pinkish '(255
0 255))</FONT></FONT></I> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(set-color! t pinkish)</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(turtle-inner-state
t)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Returns a list of 6 parameters: color, heading,
hidden-flag, pen width, solid flag, location (cons x y))</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define new-t (make-turtle
w))</FONT></FONT></I> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(turtle-inner-state new-t)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will return the list</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">((0 0 0) 0.0 #f 2 #t (400.0
. 300.0))</FONT></FONT></I><BR>
</P>
<P><FONT FACE="Tms Rmn">Below are functions that returns only one of the
parameters returned by <B><FONT COLOR="#008080">turtle-inner-state</FONT></B>:
</FONT><BR>
</P>
<P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(turtle-color t)</FONT></FONT></B>
</P>
<P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(turtle-heading t)</FONT></FONT></B>
</P>
<P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(turtle-visible t)</FONT></FONT></B>
</P>
<P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(turtle-width t)</FONT></FONT></B>
</P>
<P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(turtle-solid? t)</FONT></FONT></B>
</P>
<P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(turtle-position t)</FONT></FONT></B><BR>
</P>
<H2><A NAME="VISION"></A>TURTLE VISION<BR>
</H2>
<P><FONT FACE="Tms Rmn">A turtle can interact with the board. It can &quot;see&quot;
colors or other turtles.</FONT><BR>
<BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(look t distance
angle '(R G B))</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Will return true if there is a point in color <B><FONT COLOR="#008080">(R
G B) </FONT></B>in distance <B><FONT COLOR="#008080">distance </FONT></B>from
<B><FONT COLOR="#008080">t</FONT></B> and in the area bordered by the angle
2*<B><FONT COLOR="#008080">angle.</FONT></B></FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(look t 50 20 '(0 0 0))</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will cause <B><FONT COLOR="#008080">t</FONT></B>
to search for the color black (RGB 0,0,0) in the area shown here in blue:</FONT><BR>
</P>
<CENTER><P><IMG border=0 SRC="img00003.gif" HEIGHT=75 WIDTH=48><BR>
</P></CENTER>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(look t distance
angle [t1])</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Same as if looking for color, just this time it
will be true is t1 is in the visible area.</FONT> </P>
<P><FONT FACE="Tms Rmn">If no target turtle is defined then the function
will return true if any turtle from this window is in the visible area.</FONT>
</P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define new-t (clone-turtle
t))</FONT></FONT></I> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(forward! new-t 30)</FONT></FONT></I>
</P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(look t 50 20 new-t)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">And</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(look t 50 20)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will both return true.</FONT><BR>
<BR>
</P>
<H2><A NAME="INTERRUPTS"></A>INTERRUPTS (NOTIFICATIONS<TT><FONT FACE="Courier New"><FONT SIZE=+1>)
</FONT></FONT></TT><BR>
</H2>
<P><FONT FACE="Tms Rmn">A turtle can hold a list of interrupts (or notifications).
When an interrupt is invoked it send a given message to the thread that
sent the command. Every interrupt is defined by a &quot;look&quot; arguments.
An interruptcan be of three kinds: </FONT><BR>
</P>
<P><FONT FACE="Tms Rmn">A &quot;yes&quot; interrupt - The interrupt will
happen (message sent) on every &quot;first&quot; time the look returns
yes.</FONT> </P>
<P><FONT FACE="Tms Rmn">Meaning if a turtle is told to invoke an interrupt
every time it sees blue on a certain region. Then the first time it sees
blue it will invoke the interrupt. From now on if the blue is in view it
will not invoke the interrupt. Then if it loses sight of the blue object,
the next time it sees blue again it will invoke the interrupt, and so on.</FONT><BR>
</P>
<P><FONT FACE="Tms Rmn">A &quot;no&quot; interrupt - Same as the &quot;yes&quot;
interrupt, just this time the interrupt is invoked when the sought object
is not seen.</FONT><BR>
</P>
<P><FONT FACE="Tms Rmn">A &quot;both&quot; interrupt - First time the sought
object is viewed the &quot;yes&quot; message is sent, then the first time
the turtle loses sight of the object the &quot;no&quot; message is sent
and so on.</FONT> </P>
<P><FONT FACE="Tms Rmn">A message can be any SCHEME object.</FONT><BR>
</P>
<P><FONT FACE="Tms Rmn">When the interpreter is installing interrupt to
a turtle it need to install a <B>handler</B>, which is a function that
takes only one argument and this argument is the messages that comes from
the interrupt.</FONT> </P>
<P><FONT FACE="Tms Rmn">If no handler is installed, the messages will be
sent but will have no affect on the thread of execution.</FONT> </P>
<P><FONT FACE="Tms Rmn">There can be only one handler per thread and a
handler can not be a primitive procedure.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(turtle-notify
t msg1 msg2 distance angle TARGET)</FONT></FONT></B> </P></CENTER>
<P><FONT FACE="Tms Rmn">Instructs a turtle to send msg1 and msg2 upon seeing
and not seeing, respectively, the target. The messages can be any Scheme
objects, which are sent to the thread as if by (tell-thread). The other
parameters - see (look)</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(turtle-notify t 'yes
'no 50 10 new-t)</FONT></FONT></I> </P>
<P><FONT FACE="Tms Rmn">This is a &quot;both&quot; kind interrupt. </FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(turtle-no-notify
t distance angle TARGET)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Tells the turtle to stop notifying in the given
case. Very like deleting the interrupt from the turtle. </FONT><BR>
</P>
<CENTER><P><FONT FACE="Tms Rmn"><B><FONT COLOR="#008080">(notify-when[-not]
t1 msg dist ang TARGET)</FONT></B> </FONT><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Instructs a turtle to send msg upon [stopping]
seeing the target. This is a &quot;yes&quot; or &quot;no&quot; interrupt.</FONT>
</P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(notify-when t 'gotcha
50 10 new-t)</FONT></FONT></I> </P>
<P><FONT FACE="Tms Rmn">Will cause <B><FONT COLOR="#008080">t</FONT></B>
to send the message &quot;gotcha&quot; every &quot;first&quot; time it
sees <B><FONT COLOR="#008080">new-t</FONT></B>. </FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(stop-notifying
t)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn"><B><FONT COLOR="#008080">t</FONT></B> will temporarily
stop notifying on interrupts. Like &quot;clear interrupts&quot;.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(continue-notifying
t)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn"><B><FONT COLOR="#008080">t</FONT></B> will resume
notifying on interrupts.</FONT><BR>
</P>
<CENTER><P><FONT FACE="Tms Rmn"><B><FONT COLOR="#008080">(no-notifications
t)</FONT></B> </FONT></P></CENTER>
<P><FONT FACE="Tms Rmn">Deletes all <B><FONT COLOR="#008080">t</FONT></B>'s
interrupts.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(notify-on-click
turtle msg)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Instructs turtle to send msg when right-clicked
with the mouse (distance of 5 pixels from the turtle location). There can
be only one interrupt of this kind per turtle.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(notify-on-click t 'ouch)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will case <B><FONT COLOR="#008080">t</FONT></B>
to send the message &quot;ouch&quot; when the user right-clicks next to
it.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(notify-on-click
window msg)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Instructs <B><FONT COLOR="#008080">window </FONT></B>to
send <B><FONT COLOR="#008080">msg</FONT></B> when right-clicked with the
mouse not close to any turtle.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(clear-notify-click
t)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Clears the user right click interrupt</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(install-handler
func)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Installs a message handler. When a message arrives,
<B><FONT COLOR="#008080">func</FONT></B> is called with it as a sole argument.</FONT>
</P>
<P><FONT FACE="Tms Rmn">There can be only one handler per thread. <B><FONT COLOR="#008080">func</FONT></B>
can not be a primitive procedure.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define (print x) (write
x))</FONT></FONT></I> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(notify-on-click t 'click-on-t)</FONT></FONT></I>
</P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(install-handler print)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will cause that the message &quot;click-on-t&quot;
will be printed each time the user right clicked on <B><FONT COLOR="#008080">t</FONT></B>.
</FONT><BR>
</P>
<H2><A NAME="THREADS"></A>THREADS<BR>
</H2>
<P><FONT FACE="Tms Rmn">Galapagos supports multiple threads. Every thread
is a complete Scheme interpreter, with its own base environment. Every
thread has a <I>Thread Object</I>, which uniquely identifies it.</FONT><BR>
</P>
<P><FONT FACE="Tms Rmn">A <I>console</I> is a text window where the user
can type commands (when the interpreter is idle) and see output. A thread
may or may not be bound to a console. Information printed by a non-bound
thread is lost; a non-bound thread waiting for input is stuck (unless provisions
were made to allow a new console to be created by means of inter-thread
communications.) If a non-bound thread has nothing to do, instead of waiting
for input like a bound thread, it will terminate. </FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(this-thread)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Returns the thread-object of the current thread.</FONT>
</P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(this-thread)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will return something like </FONT></P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">#&lt;thread 0x6d1e2c&gt;
</FONT></FONT></I><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(is-first-thread?)
</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">True if the current thread is the first SCM thread.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(thread? t)</FONT></FONT></B>
</P></CENTER>
<P><FONT FACE="Tms Rmn">True if t is a thread</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(thread? (this-thread))
</FONT></FONT></I></P>
<P><FONT FACE="Tms Rmn">Will return true</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(active-threads)
</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Returns the number of active threads</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(new-thread form+)</FONT></FONT></B>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Creates a new thread that will calculate the form[s]</FONT>
</P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(new-thread (define t
(make-turtle w)) (forward! t 200))</FONT></FONT></I> </P>
<P><FONT FACE="Tms Rmn">Will make a new thread that will create a new turtle
and will move it forward 200 steps and then terminates.</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(new-thread (bind-to-console))</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will make a new thread that's ready to accept commands
form a newly-created window. The same can be achieved by selecting &quot;Fork&quot;
from &quot;Scheme&quot; menu.</FONT><BR>
<BR>
<BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(break&amp; form+)
</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Causes the current thread to stop and calculate
the form[s]. The current computation is lost.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(bind-to-console)
</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">The thread will get its commands from a console.
</FONT></P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(new-thread (bind-to-console))</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will create a new thread that gets it.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(unbind-console)</FONT></FONT></B>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Close bound console. </FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(rename-console
name)</FONT></FONT></B> </P></CENTER>
<P><FONT FACE="Tms Rmn">New name for the current console</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(install-handler
func)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Installs a message handler. When a message arrives,
<B><FONT COLOR="#008080">func</FONT></B> is called with it as a sole argument.</FONT>
</P>
<P><FONT FACE="Tms Rmn">There can be only one handler per thread. <B><FONT COLOR="#008080">func</FONT></B>
can not be a primitive procedure.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define (print x) (write
x))</FONT></FONT></I> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(notify-on-click t 'click-on-t)</FONT></FONT></I>
</P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(install-handler print)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will cause that the message &quot;click-on-t&quot;
will be printed each time the user right clicked on <B><FONT COLOR="#008080">t</FONT></B>.</FONT>
</P>
<P><FONT FACE="Tms Rmn">Note: <I><FONT COLOR="#808080">(new -thread (install-handler
f))</FONT></I> is a bad idea, because the fresh thread will terminate immediately.
</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(tell-thread th
x)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Sends message <B><FONT COLOR="#008080">X</FONT></B>
to thread <B><FONT COLOR="#008080">th</FONT></B>. Returns true on success.</FONT>
</P>
<P><FONT FACE="Tms Rmn">If <B><FONT COLOR="#008080">th</FONT></B> has no
handler installed it will cause nothing.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(quit-thread)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Kills the current thread, does not work on the
main thread.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(quit-program)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Quits the program.</FONT><BR>
<BR>
<BR>
</P>
<P><B><FONT FACE="Tms Rmn">These are primitives taken from SCM, which were
modifies to be multithread-safe:
</FONT></B>
</P>
<P>
<FONT FACE="Tms Rmn">An <B><I>arbiter</I></B>
is a data object the canbe used as a
guard for critical sections. It can be either "locked" or "unlocked". It
is ideal when a busy/wait mechanism is required, since it is MT-safe.
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(sleep n)</FONT></FONT></B>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Causes the current thread to block for (approximately)
n seconds.<I><FONT COLOR="#808080"> (sleep 0)</FONT></I> is a way to instruct
a thread to give up its remaining processor time.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(make-arbiter
name) </FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Makes an arbiter called <B><FONT COLOR="#008080">name</FONT></B>.</FONT>
</P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(define x-arb (make-arbiter
'x-guard))</FONT></FONT></I><BR>
<BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(try-arbiter arb)
</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Checks if the arbiter <B><FONT COLOR="#008080">arb
</FONT></B>is up. If the arbiter is up returns false, otherwise it sets
the arbiter to be &quot;up&quot; and returns true.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(try-arbiter x-arb)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will return true and set <I><FONT COLOR="#808080">x-arb</FONT></I>
to be &quot;up&quot;. But trying it for the second time return false since
<I><FONT COLOR="#808080">x-arb</FONT></I> is &quot;up&quot;.</FONT><BR>
</P>
<CENTER><P><B><FONT FACE="Tms Rmn"><FONT COLOR="#008080">(release-arbiter
arb)</FONT></FONT></B><BR>
</P></CENTER>
<P><FONT FACE="Tms Rmn">Set the <B><FONT COLOR="#008080">arb</FONT></B>
to be &quot;down&quot;. If the arbiter was &quot;up&quot; returns true
otherwise returns false.</FONT> </P>
<P><FONT FACE="Tms Rmn">Example:</FONT> </P>
<P><I><FONT FACE="Tms Rmn"><FONT COLOR="#808080">(release-arbiter x-arb)</FONT></FONT></I>
</P>
<P><FONT FACE="Tms Rmn">Will return true , but using this function again
will return false since <I><FONT COLOR="#808080">x-arb</FONT></I> is already
down.</FONT> </P>
<P>
<HR width=80% align=left color=blue>
<CENTER>
<A href="#top"><IMG border=0 src=back.gif ALT=" [TOP] "></A>
<A href="implementation.html"><IMG border=0 src=prev.gif ALT=" [PREV] "></A>
<A href="bib.html"><IMG border=0 src=next.gif ALT=" [PREV] "></A>
<A href="index.html#toc"><IMG border=0 src=toc.gif ALT=" [PREV] "></A>
</CENTER>
</BODY>
</HTML>