# Turtle Languages Help

The Turtle System supports programming in several specially designed languages. These languages all mimic an existing language, but incorporate native Turtle Graphics support, and are pared down to facilitate teaching and learning in a simpler and less daunting environment (and to enable the compilers to produce much more precise and detailed error messages). The guides on this page, together with the Commands & Constants Reference, cover the essentials for programming in the Turtle System. For a more complete description of the languages, see the Turtle Language Specifications.

### Programs and Procedures: the Basics

The simplest BASIC programs take this form:

REM [program commands]
END

The first couple of Turtle example programs (from the Examples menu) are like this. But the ‘Olympic rings’ program introduces a global variable: it is called ringsize% and specifies the size of the rings. Such variables are ‘declared’ by assigning a value, like this:

ringsize% = 130
REM [other program commands]
END

Complicated programs are usually divided into subroutines, to separate the various tasks and make them easier to understand. BASIC has two types of subroutine, procedures (which are like mini-programs) and functions (which are designed to calculate some value).

The ‘Simple procedure’ example program has a procedure to draw a ‘prong’ – a line ending in a blot – and then return to the starting point. Procedures fit into a BASIC program after the end of the main program, indicated by END. They look like this:

DEF PROCmyprocedure(par1%)
LOCAL local1%, local2$REM [procedure commands] ENDPROC All procedure names must begin with ‘PROC’, e.g. PROCmyprocedure. A procedure can have its own local variables, declared using LOCAL. A PRIVATE variable is declared the same way, but unlike a LOCAL variable, it retains its value between procedure calls. A procedure can also have parameters (or ‘arguments’) that are values sent into the subroutine when it is called from the program, and given a name within the subroutine (e.g. par1% above). A function is similar to a procedure, with the addition that it returns a value. Also a function name must begin with ‘FN’, for example: DEF FNmyfunction$(par1%)
REM [procedure commands]
= "output"

### Boolean Operators

The four main boolean operators are represented in the standard way:

 NOT negation AND conjunction OR disjunction (inclusive) EOR exclusive disjunction

These are used between integers, where zero stands for false and any other number stands for true. FALSE stands for 0 and TRUE for -1. The Boolean operators can also be used in a bitwise fashion (i.e. each binary bit in the result is calculated as the result of the relevant boolean operation on the corresponding bits of the inputs, e.g. 21 AND 6 = 4 (binary 10101 AND 00110 = 100); 21 OR 6 = 23 (10111); 21 EOR 6 = 19 (10011).

### Comparison Operators

The six comparison operators are applicable to all types (with strings compared alphabetically):

 = equality <> inequality < less than <= less than or equal > greater than >= greater than or equal

### Bracketing

Complex expressions require brackets, e.g.

IF (n% < 0) OR (n% > 9) THEN
n% = ((a% + 1) * (b% + 3) + c%) MOD 10

### Arithmetical Operators

Documentation for Turtle C is still being prepared. Please check back here soon.

### Arithmetical Operators

Documentation for Turtle Java is still being prepared. Please check back here soon.

### Arithmetical Operators

The four main arithemetical operators are represented as:

 + addition (also used for string concatenation) - subtraction * multiplication / division

/ is integer division, with the remainder discarded (e.g. 14 / 3 = 4). Remainders are given by:

 mod remainder

(e.g. 14 mod 3 = 2; 67 mod 10 = 7).

### Doing Fractional (e.g. Decimal) Arithmetic

The Turtle Machine is designed to handle memory simply and transparently for the learning of computer science, and so has no special type for representing fractional numbers; which is why / is integer division. But the Turtle System can handle fractional numbers by treating them explicitly as fractions, with both a numerator (above the line) and a denominator (below the line). A denominator of 1000000, for instance, allows decimal arithmetic to 6 decimal places.

Thus to get the sine of 34.56 degrees to six decimal places, you could use n := sin(3456, 100, 1000000) â€“ this makes n equal to the sine of the angle 3456/100, multiplied by 1000000 (and rounded). writeln(qstr(n, 1000000, 6)) will then print n/1000000 to six decimal places, i.e. "0.567269". For more illustrations of this sort of decimal arithmetic, see the example program ‘Mathematical functions’.

### Boolean Operators

The four main boolean operators are represented in the standard way:

 not negation and conjunction or disjunction (inclusive) xor exclusive disjunction

These can also be used between integers, in a bitwise fashion (i.e. each binary bit in the result is calculated as the result of the relevant boolean operation on the corresponding bits of the inputs), e.g. 21 and 6 = 4 (binary 10101 and 00110 = 100); 21 or 6 = 23 (10111); 21 xor 6 = 19 (10011).

### Comparison Operators

The six comparison operators are applicable to all types (with strings compared alphabetically):

 = equality <> inequality < less than <= less than or equal > greater than >= greater than or equal

### Bracketing

Complex expressions require brackets, e.g.

if (n < 0) or (n > 9) then
n := ((a + 1) * (b + 3) + c) mod 10

### Arithmetical Operators

The four main arithemetical operators are represented as:

 + addition (also used for string concatenation) - subtraction * multiplication // division

// is integer division, with the remainder discarded (e.g. 14 // 3 = 4). Remainders are given by:

 mod remainder

(e.g. 14 mod 3 == 2; 67 mod 10 == 7).

### Doing Fractional (e.g. Decimal) Arithmetic

The Turtle Machine is designed to handle memory simply and transparently for the learning of computer science, and so has no special type for representing fractional numbers; which is why // is integer division. But the Turtle System can handle fractional numbers by treating them explicitly as fractions, with both a numerator (above the line) and a denominator (below the line). A denominator of 1000000, for instance, allows decimal arithmetic to 6 decimal places.

Thus to get the sine of 34.56 degrees to six decimal places, you could use n = sin(3456, 100, 1000000) – this makes n equal to the sine of the angle 3456/100, multiplied by 1000000 (and rounded). writeln(qstr(n, 1000000, 6)) will then print n/1000000 to six decimal places, i.e. '0.567269'. For more illustrations of this sort of decimal arithmetic, see the example program ‘Mathematical functions’.

### Boolean Operators

The four main boolean operators are represented in the standard way:

 not negation and conjunction or disjunction (inclusive) xor exclusive disjunction

These can also be used between integers, in a bitwise fashion (i.e. each binary bit in the result is calculated as the result of the relevant boolean operation on the corresponding bits of the inputs), e.g. 21 and 6 = 4 (binary 10101 and 00110 = 100); 21 or 6 = 23 (10111); 21 xor 6 = 19 (10011).

### Comparison Operators

The six comparison operators are applicable to all types (with strings compared alphabetically):

 == equality != inequality < less than <= less than or equal > greater than >= greater than or equal

### Bracketing

Complex expressions require brackets, e.g.

if (n < 0) or (n > 9):
n = ((a + 1) * (b + 3) + c) mod 10

### Arithmetical Operators

Documentation for Turtle TypeScript is still being prepared. Please check back here soon.

### User Input

The facilities for user input – via keyboard or mouse – are designed to be as straightforward and comprehensible as possible, while operating strictly through simple processes that are consistent with the workings of the Turtle Machine.

#### Mouse Position Detection

The x- and y-coordinates of the mouse’s current position can be found at any time by using the special global variables ?MOUSEX and ?MOUSEY – these do not require the mouse to be clicked.

#### Mouse Click Detection

When a mouse click is performed, the x- and y-coordinates of the click position are remembered by the variables ?CLICKX and ?CLICKY. However to identify the type of click, use the variable ?CLICK, which is initially set to a value of -1, but after any click has taken place is set to a numerical value of 128 plus additions as follows:

 1 if the click was with the left mouse button 2 if the click was with the right mouse button 4 if the click was with the middle mouse button 8 if the shift key was held down while clicking 16 if the alt key was held down while clicking 32 if the ctrl key was held down while clicking 64 if it was a double-click

So if n% = ?CLICK makes n% equal to 137 (128+8+1), this indicates that a left-click is currently under way, with the shift key held down. When the click event is finished, the ?CLICK value will become negative. Thus if ?CLICK returns a value of -137, this indicates that the last click event – now finished – was shift+left; the coordinate position of that click can still be identified – until the next click takes place – as (?CLICKX, ?CLICKY). On a left-click, the variable ?LMOUSE records the relevant value (as calculated above); likewise ?RMOUSE and ?MMOUSE record any right-click or middle-click. Again, these are all made negative when the click is released, so an empty loop like:

REPEAT
UNTIL ?LMOUSE > 0

waits for a left-click with the mouse. Afterwards, ?CLICKX and ?CLICKY indicate where that click event occurred, and ?CLICK can be queried using the bitwise AND operator to discover which special keys were pressed (e.g. IF (ABS(?CLICK) AND 8) > 0 will test whether shift was being held down).

#### Key Press Detection

Detecting key presses (rather than typing in of characters) uses the variables ?KEY and ?KSHIFT, and the function KEYSTATUS. ?KEY gives the code of the last key to be pressed – these codes can be tested using the special keycode constants \ALT, \BACKSPACE, \CAPSLOCK, \CTRL, \DELETE, \DOWN, \END, \ESCAPE, \HOME, \INSERT, \LEFT, \LWIN, \PGDN, \PGUP, \RETURN, \RIGHT, \RWIN, \SHIFT, \SPACE, \TAB, and \UP, as well as \A to \Z, \0 to \9, \HASH, \EQUALS etc. Keys on the numeric keypad have codes \#0, \#1 etc., and function keys \F1, \F2 etc. All these stand for numeric values (e.g. \RETURN is 13, \ESCAPE is 27), but IF ?KEY = \RETURN is easier to understand than IF ?KEY = 13.

Like the mouse-click variables, ?KEY becomes negative after the key is released, so REPEAT : UNTIL ?KEY = -\A will wait until the ‘A’ key has been released. If you want to identify the last key whether it is still pressed or not, use ABS (e.g. IF ABS(?KEY) = \A THEN).

Whenever a key is pressed, the variable ?KSHIFT gives its ‘shift-status’, calculated in the same way as ?CLICK (i.e. 128 plus 8 if shift was down, 16 for alt, 32 for ctrl, and turning negative after the key is released). So to test if ctrl was down on the last keypress, use IF (ABS(?KSHIFT) AND 32) > 0, with AND here acting as a bitwise boolean operator.

To recover the shift-status for the last press of the X key (say), use KEYSTATUS(\X), which can tell you (a) whether shift / alt / ctrl were down; (b) whether the X is still pressed (since KEYSTATUS goes negative on release); (c) whether X has been pressed at all (since all of these input codes are set to -1 initially, and can be reset to -1 using RESET(\X) etc.).

#### Keyboard Input

The system provides a keyboard buffer to store typed characters. Initially this is set to store up to 32 characters, but can be extended using e.g. KEYBUFFER(50). To read from the buffer into a string, use e.g. s$= GET$(10), which reads up to 10 characters (depending on how many are in the buffer). KEYSTATUS(\KEYBUFFER) returns the number of characters it contains, and RESET(\KEYBUFFER) flushes it.

s$= GETLINE$ reads a line of text, waiting until the return key is pressed and then making s\$ equal to what has been typed into the buffer (discarding the return character).

The function DETECT waits a given time for some input to be received (e.g. a specific key pressed), and returns TRUE when that input is received, or FALSE if it is not received in time. Thus IF DETECT(\ESCAPE, 5000) THEN - ELSE - gives 5 seconds to press the escape key (meanwhile continuing to collect any typed characters in the keyboard buffer). By default, text that goes into the keyboard buffer is also ‘echoed’ to the console (below the Canvas), along with text that is output (using WRITE or WRITELN). This behaviour can be turned on and off with KEYECHO(TRUE) and KEYECHO(FALSE).

### User Input

Documentation for Turtle C is still being prepared. Please check back here soon.

### User Input

Documentation for Turtle Java is still being prepared. Please check back here soon.

### User Input

The facilities for user input – via keyboard or mouse – are designed to be as straightforward and comprehensible as possible, while operating strictly through simple processes that are consistent with the workings of the Turtle Machine.

#### Mouse Position Detection

The x- and y-coordinates of the mouse’s current position can be found at any time by using the special global variables ?mousex and ?mousey – these do not require the mouse to be clicked.

#### Mouse Click Detection

When a mouse click is performed, the x- and y-coordinates of the click position are remembered by the variables ?clickx and ?clicky. However to identify the type of click, use the variable ?click, which is initially set to a value of -1, but after any click has taken place is set to a numerical value of 128 plus additions as follows:

 1 if the click was with the left mouse button 2 if the click was with the right mouse button 4 if the click was with the middle mouse button 8 if the shift key was held down while clicking 16 if the alt key was held down while clicking 32 if the ctrl key was held down while clicking 64 if it was a double-click

So if n := ?click makes n equal to 137 (128 + 8 + 1), this indicates that a left-click is currently under way, with the shift key held down. When the click event is finished, the ?click value will become negative. Thus if ?click returns a value of -137, this indicates that the last click event – now finished – was shift+left; the coordinate position of that click can still be identified – until the next click takes place – as (?clickx, ?clicky). On a left-click, the variable ?lmouse records the relevant value (as calculated above); likewise ?rmouse and ?mmouse record any right-click or middle-click. Again, these are all made negative when the click is released, so an empty loop like:

repeat
until ?lmouse > 0;

waits for a left-click with the mouse. Afterwards, ?clickx and ?clicky indicate where that click event occurred, and ?click can be queried using the bitwise and operator to discover which special keys were pressed (e.g. if (abs(?click) and 8) > 0 will test whether shift was being held down).

#### Key Press Detection

Detecting key presses (rather than typing in of characters) uses the variables ?key and ?kshift, and the function keystatus. ?key gives the code of the last key to be pressed – these codes can be tested using the special keycode constants \alt, \backspace, \capslock, \ctrl, \delete, \down, \end, \escape, \home, \insert, \left, \lwin, \pgdn, \pgup, \return, \right, \rwin, \shift, \space, \tab, and \up, as well as \a to \z, \0 to \9, \hash, \equals etc. Keys on the numeric keypad have codes \#0, \#1 etc., and function keys \f1, \f2 etc. All these stand for numeric values (e.g. \return is 13, \escape is 27), but if ?key = eturn is easier to understand than if ?key = 13.

Like the mouse-click functions, ?key becomes negative after the key is released, so repeat until ?key = -\a will wait until the A key has been released. If you want to identify the last key whether it is still pressed or not, use abs (e.g. if abs(?key) = \a then {commands}).

Whenever a key is pressed, the variable ?kshift gives its ‘shift-status’, calculated in the same way as ?click (i.e. 128 plus 8 if shift was down, 16 for alt, 32 for ctrl, and turning negative after the key is released). So to test if ctrl was down on the last keypress, use if (abs(?kshift) and 32) > 0, with and here acting as a bitwise boolean operator.

To recover the shift-status for the last press of the X key (say), use keystatus(\x), which can tell you (a) whether shift / alt / ctrl were down; (b) whether the X is still pressed (since keystatus goes negative on release); (c) whether X has been pressed at all (since all of these input codes are set to -1 initially, and can be reset to -1 using reset(\x) etc.).

#### Keyboard Input

The system provides a keyboard buffer to store typed characters. Initially this is set to store up to 32 characters, but can be extended using e.g. keybuffer(50). To read from the buffer into a string, use e.g. s := read(10), which reads up to 10 characters (depending on how many are in the buffer). keystatus(\keybuffer) returns the number of characters it contains, and reset(\keybuffer) flushes it.

s := readln reads a line of text, waiting until the return key is pressed and then making s equal to what has been typed into the buffer (discarding the return character).

The function detect waits a given time for some input to be received (e.g. a specific key pressed), and returns true when that input is received, or false if it is not received in time. Thus if detect(\escape, 5000) then {command1} else {command2} gives 5 seconds to press the escape key (meanwhile continuing to collect any typed characters in the keyboard buffer). By default, text that goes into the keyboard buffer is also ‘echoed’ to the console (below the Canvas), along with text that is output (using write or writeln). This behaviour can be turned on and off with keyecho(true) and keyecho(false).

### User Input

The facilities for user input – via keyboard or mouse – are designed to be as straightforward and comprehensible as possible, while operating strictly through simple processes that are consistent with the workings of the Turtle Machine.

#### Mouse Position Detection

The x- and y-coordinates of the mouse’s current position can be found at any time by using the special global variables ?mousex and ?mousey – these do not require the mouse to be clicked.

#### Mouse Click Detection

When a mouse click is performed, the x- and y-coordinates of the click position are remembered by the variables ?clickx and ?clicky. However to identify the type of click, use the variable ?click, which is initially set to a value of -1, but after any click has taken place is set to a numerical value of 128 plus additions as follows:

 1 if the click was with the left mouse button 2 if the click was with the right mouse button 4 if the click was with the middle mouse button 8 if the shift key was held down while clicking 16 if the alt key was held down while clicking 32 if the ctrl key was held down while clicking 64 if it was a double-click

So if n = ?click makes n equal to 137 (128 + 8 + 1), this indicates that a left-click is currently under way, with the shift key held down. When the click event is finished, the ?click variable will become negative. Thus if ?click returns a value of -137, this indicates that the last click event – now finished – was shift+left; the coordinate position of that click can still be identified – until the next click takes place – as (?clickx, ?clicky). On a left-click, the variable ?lmouse records the relevant value (as calculated above); likewise ?rmouse and ?mmouse record any right-click or middle-click. Again, these are all made negative when the click is released, so an empty loop like:

while not(?lmouse > 0):
pass  # this statement does nothing!

waits for a left-click with the mouse. Afterwards, ?clickx and ?clicky indicate where that click event occurred, and ?click can be queried using the bitwise and operator to discover which special keys were pressed (e.g. if (abs(?click) and 8) > 0 will test whether shift was being held down).

#### Key Press Detection

Detecting key presses (rather than typing in of characters) uses the variables ?key and ?kshift, and the function keystatus. ?key gives the code of the last key to be pressed – these codes can be tested using the special keycode constants \alt, \backspace, \capslock, \ctrl, \delete, \down, \end, \escape, \home, \insert, \left, \lwin, \pgdn, \pgup, \return, \right, \rwin, \shift, \space, \tab, and \up, as well as \a to \z, \0 to \9, \hash, \equals etc. Keys on the numeric keypad have codes \#0, \#1 etc., and function keys \f1, \f2 etc. All these stand for numeric values (e.g. \return is 13, \escape is 27), but if ?key = eturn is easier to understand than if ?key = 13.

Like the mouse-click variables, ?key becomes negative after the key is released, so while not(?key = -\a): pass will wait until the A key has been released. If you want to identify the last key, whether it is still pressed or not, use abs (e.g. if abs(?key) = \a: # command).

Whenever a key is pressed, the variable ?kshift gives its ‘shift-status’, calculated in the same way as ?click (i.e. 128 plus 8 if shift was down, 16 for alt, 32 for ctrl, and turning negative after the key is released). So to test if ctrl was down on the last keypress, use if (abs(?kshift) and 32) > 0, with and here acting as a bitwise boolean operator.

To recover the shift-status for the last press of the X key (say), use keystatus(\x), which can tell you (a) whether shift / alt / ctrl were down; (b) whether the X is still pressed (since keystatus goes negative on release); (c) whether X has been pressed at all (since all of these input codes are set to -1 initially, and can be reset to -1 using reset(\x) etc.).

#### Keyboard Input

The system provides a keyboard buffer to store typed characters. Initially this is set to store up to 32 characters, but can be extended using e.g. keybuffer(50). To read from the buffer into a string, use e.g. s = read(10), which reads up to 10 characters (depending on how many are in the buffer). keystatus(\keybuffer) returns the number of characters it contains, and reset(\keybuffer) flushes it.

s = readln reads a line of text, waiting until the return key is pressed and then making s equal to what has been typed into the buffer (discarding the return character).

The function detect waits a given time for some input to be received (e.g. a specific key pressed), and returns True when that input is received, or False if it is not received in time. Thus if detect(\escape, 5000): #command1 else: #command2 gives 5 seconds to press the escape key (meanwhile continuing to collect any typed characters in the keyboard buffer). By default, text that goes into the keyboard buffer is also ‘echoed’ to the console (below the Canvas), along with text that is output (using write or writeln). This behaviour can be turned on and off with keyecho(True) and keyecho(False).

### User Input

Documentation for Turtle TypeScript is still being prepared. Please check back here soon.