Instructions

Richard Goedeken edited this page Aug 16, 2015 · 1 revision

Version

This document applies to version 1.0 of TurboTurtle.

Instructions

TurboTurtle supports about 100 built-in Logo instructions. This page is intended to be a reference for the usage of these instructions.

Instructions which have parentheses around their names are parenthesized instructions. These are special instructions which use a different number of input parameters from their non-parenthesized versions, or contain a variable number of input parameters. For a parenthesized instruction, like: (SUM 1 2 3 4 5), all of the available parameters within the parentheses are gathered and used as inputs to the instruction.

Operand Types

  • number
    • A floating-point numeric value. Can be either an immediate number (like 42 or 10.3), or a numeric value returned from another instruction, or a numeric value in a variable, or a combination of any of these in a numeric expression (such as 42 * :angle + Heading)
  • immediate number
    • A numeric value which is given directly in the Logo program, such as 1 or 3.14159
  • boolean
    • A boolean value. Can be either an immediate boolean (True or False), or a boolean value returned from another instruction, or a boolean value in a variable, or a comparison expression. A comparison expression can either compare two numeric values (42 * :angle < 180.0) or two booleans (:LastCond <> Xor :a :b). Boolean comparisons can only compare for equality or non-equality, while numeric comparisons can also compare for greater-than or less-than.
  • word
    • A text value. Can be either an immediate word, or a text value returned from an instruction, or a text value in a variable.
  • immediate word
    • A word whose value is given directly in the Logo program, such as "This_is_a_word
  • list
    • An ordered list of numbers. Can be either an immediate list, or a list returned from an instruction, or the value of a list variable
  • immediate list
    • A group of immediate numbers separated by spaces and surrounded by brackets, such as: [1 2 3 4.5 67 0.899 -20]
  • instructionlist
    • A sequence of instructions surrounded by brackets, such as [ Home FD 20 RT 90 ]
  • array
    • A set of numbers in a 1, 2, or 3 dimensional matrix. The only functions which can return arrays are ARRAY and MDARRAY, and these 2 functions can only be used as inputs to the MAKE instruction. All other instructions must use arrays stored in variables.

Variable Definition

There are two instructions for defining variables: one for global variables and one for local variables. These instructions do not return any value.

  • MAKE name value
    • Operand types: name (immediate word), value (number or list or word or array or boolean)
    • Usage: This instruction creates a global variable named name and assigns it a value of value.
  • LOCALMAKE name value
    • Operand types: name (immediate word), value (number or list or word or array or boolean)
    • Usage: This instruction creates a local variable named name and assigns it a value of value. The LOCALMAKE instruction can only be used inside of a procedure.

Control Structures

The control instructions handle normal programming constructs like looping, conditional execution, exiting and returning a value from a procedure, and jumping to a different part of the program.

Return Type Instruction Abbreviated Name Operand 1 Operand 2 Usage
REPEAT number count instructionlist instructionlist Executes the instructions in instructionlist in a loop count times. If count is less than 1, instructionlist will not be executed.
FOREVER instructionlist instructionlist Executes the instructions in instructionlist continuously.
number REPCOUNT # Returns the value of the loop counter for the innermost REPEAT or FOREVER instruction. The counter begins at 1 and increments by 1 at the end of each loop iteration.
FOR special forcontrol instructionlist instructionlist This instruction will create a new local variable and execute the instructions in instructionlist, updating the value of the local variable after each iteration, until a condition is met. The format of forcontrol can be either [varname start stop] or [varname start stop step]. varname is the name of the local variable which will be created. varname is like an immediate word, but without the preceding quotation mark. start, stop, (and limit if present) are numbers. For the 3-parameter variant, first varname is initialized to the number start, the loop begins and the instructionlist is executed, then varname changes in the direction of stop by 1.0 units. If the value of varname has not crossed over stop and is not equal to stop, another loop iteration begins and instructionlist is executed again. The 3-parameter variant guarantees that instructionlist will be executed at least once and will not be executed more than floor(abs(stop - start))+1 times. For the 4-parameter variant, first varname is initialized to the number start, then the loop begins. The loop starts by comparing the sign of varname-stop to the sign of step. If varname is equal to stop or the sign of varname-stop is different from the sign of step, then the instructionlist is executed, step is added to varname, and the loop begins again. Otherwise the loop ends. It is possible to construct a 4-parameter FOR loop which will not execute the instructionlist at all, such as FOR [ i 0 2 -1 ]
DO.WHILE instructionlist instructionlist boolean tf This instruction repeatedly executes instructionlist and then tests value of the expression tf, until the value of tf is False. For example, if tf is the immediate boolean False, the instructionlist will only execute once. However, if tf is the immediate boolean True, it will execute repeatedly forever.
WHILE boolean tf instructionlist instructionlist This instruction repeatedly tests the value of the expression tf, breaks out of the loop if the value of tf is False, otherwise executes instructionlist and begins the loop again. If tf is the immediate boolean False, the instructionlist will not execute at all. However, if tf is the immediate boolean True, it will execute repeatedly forever.
DO.UNTIL instructionlist instructionlist boolean tf This instruction repeatedly executes instructionlist and then tests value of the expression tf, until the value of tf is True. For example, if tf is the immediate boolean False, the instructionlist will execute repeatedly forever. However, if tf is the immediate boolean True, it will only execute once.
UNTIL boolean tf instructionlist instructionlist This instruction repeatedly tests the value of the expression tf, breaks out of the loop if the value of tf is True, otherwise executes instructionlist and begins the loop again. If tf is the immediate boolean False, the instructionlist will execute repeatedly forever. However, if tf is the immediate boolean True, it will not execute at all.
Instruction Abbreviated Name Operand 1 Operand 2 Operand 3 Usage
IF boolean tf instructionlist instructionlist If the boolean expression tf evaluates to True, then the instructions in instructionlist will be executed.
IFELSE boolean tf instructionlist instructionlist1 instructionlist instructionlist2 If the boolean expression tf evaluates to True, then the instructions in instructionlist1 will be executed. Otherwise, the instructions in instructionlist2 will be executed.
TEST boolean tf This instruction evaluates the boolean expression tf and sets an internal flag with the result. This internal flag can be subsequently used to conditionally execute instructions with the IFTRUE and IFFALSE instructions.
IFTRUE IFT instructionlist instructionlist If and only if the value of the internal flag which is set by the TEST instruction is True, then the instructions in instructionlist will be executed. The default value of the internal flag is False.
IFFALSE IFF instructionlist instructionlist If and only if the value of the internal flag which is set by the TEST instruction is False, then the instructions in instructionlist will be executed. The default value of the internal flag is False.
Instruction Abbreviated Name Operand 1 Usage
STOP The STOP instruction returns from a procedure and resumes execution at the next instruction after the procedure call. The STOP instruction does not return any value. The STOP instruction can only be used from within a user-defined procedure. A procedure cannot contain both STOP and OUTPUT instructions.
OUTPUT OP number or list or word or boolean value The OUTPUT instruction exits from a user-defined procedure and returns value in the place where the procedure was called. The OUTPUT instruction can only be used from within a user-defined procedure. A procedure cannot contain both STOP and OUTPUT instructions, and all OUTPUT instructions in a user-defined procedure must return the same type.
WAIT number time This instruction pauses for a specified amount of time. The amount of time for which the program execution is paused is equal to time/60 seconds. For example, "WAIT 60.0" will pause for exactly 1 second.
GOTO immediate word label The GOTO instruction causes the execution path of the program to jump to the instruction TAG with the same label as label.
TAG immediate word label The TAG instruction denotes the place in the program to where a GOTO instruction with the same label will jump.

Graphics

These are instructions for drawing lines, plotting points, and writing text on the drawing surface. These instructions do not return any value.

Instruction Abbreviated Name Operand 1 Operand 2 Usage
FORWARD FD number dist Moves the turtle from the current position to a new position forward by dist steps in the current direction. If the Pen is down, a line will be drawn. The color of the line will be the Pen color if the Pen is in Paint mode, or the Background color if in Erase mode.
BACK BK number dist Moves the turtle from the current position to a new position backward by dist steps. If the Pen is down, a line will be drawn. The color of the line will be the Pen color if the Pen is in Paint mode, or the Background color if in Erase mode.
LEFT LT number angle Causes the turtle to turn to the left (counter-clockwise) by angle degrees.
RIGHT RT number angle Causes the turtle to turn to the right (clockwise) by angle degrees.
DOT number xpos number ypos Plots a dot at the position (xpos, ypos) in the current pen color and size, if the pen is down.
(LABEL) number or word thing1 number or word ... Prints the values of each of its inputs, separated by spaces. The output is drawn to the screen using the current pen color, the current font and font height, and is positioned at the current turtle position with the current horizontal and vertical justification. This instruction must be surrounded by parentheses and can accept one or more operands.
SETFONT number fontnum Sets the current font. There are three available fonts, numbered 0 through 2. All three fonts are fixed-width. The dimensions of font 0 are 8x12, font 1 is 12x16, and font 2 is 10x18.
SETFONTHEIGHT number height Sets the current font height to height turtle steps. The width of each character will be set to maintain the correct aspect ratio for the selected font.
SETJUSTIFYVERT number index Sets the current vertical justification type used by the LABEL instruction. An index value of 0 or less will cause the text to be drawn below the turtle position. An index value of exactly 1 will cause the text to be drawn vertically centered over the turtle position. And index value of 2 or more will cause the text to be drawn above the turtle position.
SETJUSTIFYHORZ number index Sets the current horizontal justification type used by the LABEL instruction. An index value of 0 or less will cause the text to be drawn to the right of the turtle position. An index value of exactly 1 will cause the text to be drawn horizontally centered over the turtle position. And index value of 2 or more will cause the text to be drawn to the left of the turtle position.
SETPOS list pos Sets the current turtle position to the X,Y location given by the first 2 elements of the list pos. This draws a line if the pen is down.
SETXY number xcor number ycor Sets the current turtle position to the X,Y location given by the two input numbers xcor,ycor. This draws a line if the pen is down
SETX number xcor Sets the X coordinate of the turtle position to xcor. This draws a line if the pen is down.
SETY number ycor Sets the Y coordinate of the turtle position to ycor. This draws a line if the pen is down.
SETHEADING SETH number degrees Sets the current heading of the turtle (the direction that it's facing) to degrees. The heading is measured in degrees clockwise from the +Y axis (straight up).
SETSCRUNCH number xratio number yratio Sets the scrunch ratios in the X and Y directions. This is primarily useful to correct for displays with non-square pixel aspect ratios. Currently the scrunch ratios are only used for the FORWARD and BACK instructions. They are not taken into account for other instructions like SETPOS and SETXY.

Turtle Motion Queries

These instructions return information about the current status of the turtle.

Return Type Instruction Operand 1 Usage
list POS Returns a 2-item list containing the current X and Y coordinates of the turtle.
number XCOR Returns the current X coordinate of the turtle.
number YCOR Returns the current Y coordinate of the turtle.
number HEADING Returns the current heading of the turtle, measured in degrees clockwise from the +Y axis.
number TOWARD list pos Returns a number which is the heading (in degrees) necessary to make the turtle point from its current position to the position given by pos.

Turtle and Window Control

These are control instructions for the turtle and display window. These instructions do not take any operands or return any value.

Instruction Abbreviated Name Usage
CLEAN Displays everything drawn since the last CLEAN, CLEARSCREEN, or ERASESCREEN instruction and erases the drawing surface. This instruction does not move the turtle.
CLEARSCREEN CS Performs exactly the same actions as calling both HOME and CLEAN.
ERASESCREEN Erases everything on the drawing surface without displaying any previously drawn lines or dots on the screen.
HOME Moves the turtle to position (0,0) and sets the heading to 0 degrees.
WRAP Sets the current screen wrapping mode to WRAP. In this mode, when the turtle moves past any of the 4 display boundaries (top, bottom, left, or right), it is transported to the opposite boundary and continues moving. Using either the WRAP or WINDOW instructions in a TurboTurtle program will cause a performance penalty.
WINDOW Sets the current screen wrapping mode to WINDOW. In this mode, when the turtle moves past any of the 4 display boundaries, the lines drawn are no longer visible on the screen until the turtle comes back within the display boundaries. This is the default mode for TurboTurtle programs. Using either the WRAP or WINDOW instructions in a TurboTurtle program will cause a performance penalty.

Pen and Background Control

These are control instructions for the turtle's pen. These instructions do not return any value.

Instruction Abbreviated Name Operand 1 Usage
PENDOWN PD Puts the turtle into the PenDown mode, so that subsequent move commands will cause lines to be drawn.
PENUP PU Puts the turtle into the PenUp mode, so that subsequent move commands will only change the position of the turtle, without drawing lines or points.
PENPAINT PPT Sets the turtle into Paint mode, so that subsequent points or lines will be drawn with the PenColor.
PENERASE PE Sets the turtle into Erase mode, so that subsequent points or lines will be drawn with the Background Color.
SETPENCOLOR SETPC number or list color Sets the current Pen Color (foreground). If the input is a number, it must be between 0 and 15, and the color will be set according to the color table below. If the input is a list, it must have at least 3 elements, and the color will be set to the RGB value given by the first 3 elements of the list. Each element should be between 0 and 255.
SETPENSIZE number size Sets the Pen Size, which affects the width of lines drawn and points plotted. The default Pen Size is 1.0.
SETBACKGROUND SETBG number or list color Sets the current Background Color. If the input is a number, it must be between 0 and 15, and the color will be set according to the color table below. If the input is a list, it must have at least 3 elements, and the color will be set to the RGB value given by the first 3 elements of the list. Each element should be between 0 and 255.

Color Table

0 black 1 blue 2 green 3 cyan
4 red 5 magenta 6 yellow 7 white
8 brown 9 tan 10 forest 11 aqua
12 salmon 13 purple 14 orange 15 grey

Constructors

Return Type Instruction Operand 1 Operand 2 Usage
list LIST number num1 number num2 Returns a list with 2 elements: num1 and num2.
list (LIST) number num1 number ... Returns a list with 1 or more elements, one for each of the numeric values within the parentheses.
list FPUT number num1 list list1 FirstPut - Returns a list which begins with the value of num1, and then contains all of the elements of list1
list LPUT number num1 list list1 LastPut - Returns a list which begins with all of the elements of list1, followed by the value of num1
list REVERSE list list1 Returns a list with the elements in the opposite order of those in list1
array ARRAY number size Returns a 1 dimensional array of length size. The first index number of the array is 1. This instruction can only be used as an input to MAKE or LOCALMAKE
array (ARRAY) number size number start Returns a 1 dimensional array of length size. The first index number of the array is start. This instruction can only be used as an input to MAKE or LOCALMAKE
array MDARRAY list sizelist Returns a multi-dimensional array with the same number of dimensions as there are elements in sizelist. The length of each dimension in the array is given by the corresponding element in sizelist. The first index number of each dimension in the array is 0 (this is different from most Logo interpreters). This instruction can only be used as an input to MAKE or LOCALMAKE

Selectors

These are instructions which return numbers or lists generated from lists or arrays.

Return Type Instruction Operand 1 Operand 2 Usage
number FIRST list list1 Returns the first element in list1
number LAST list list1 Returns the last element in list1
list BUTFIRST list list1 Returns a list containing all elements but the first in list1
list BUTLAST list list1 Returns a list containing all elements but the last in list1
number ITEM number index list or array thing Returns the numeric element corresponding to index in thing.
number MDITEM list indexlist array array1 Returns the numeric element corresponding to the vector indexlist in multi-dimensional array1. The first index number of each dimension in the array is 0.
number PICK list list1 Returns one of the elements in list1, randomly selected

Queries, Predicates, and Mutators

Return Type Instruction Operand 1 Operand 2 Operand 3 Usage
number COUNT list list1 Returns the number of elements in list1
boolean EMPTYP list list1 Returns True if there are no elements in list1, otherwise False
None SETITEM number index array array1 number value Sets the numeric element corresponding to index in array1 to value.
None MDSETITEM list indexlist array array1 number value Sets the numeric element corresponding to the vector indexlist in multi-dimensional array1 to value.

Numeric opterations

These instructions perform numeric calculations. They all return a number.

Instruction Operand 1 Operand 2 Usage
ABS number num1 Returns the absolute value of num1
MINUS number num1 Returns -1 times the value of num1
SUM number num1 number num2 Returns the sum of num1 and num2
(SUM) number num1 number ... Returns the sum of all inputs. There must be at least two.
DIFFERENCE number num1 number num2 Returns num1 - num2
PRODUCT number num1 number num2 Returns num1 times num2
(PRODUCT) number num1 number ... Returns the product of all inputs multiplied together. There must be at least two.
QUOTIENT number num1 number num2 Returns num1 divided by num2
(QUOTIENT) number num1 Returns 1.0 divided by num1
REMAINDER number num1 number num2 Returns the remainder of the integer (whole part of) num1 divided by the integer of num2
INT number num1 Returns the integer of num1
ROUND number num1 Returns the value of num1 rounded to the nearest integer. If the fractional part of num1 is one half, it's rounded away from zero
SQRT number num1 Returns the square root of num1
POWER number num1 number num2 Returns the value of num1 raised to the power of num2
EXP number num1 Returns the value of e (the base of the natural logarithm) to the power of num1
LOG10 number num1 Returns the value of the base-10 logarithm of num1
LN number num1 Returns the value of the natural logarithm of num1
SIN number degrees Returns the sine of degrees
RADSIN number radians Returns the sine of radians
COS number degrees Returns the cosine of degrees
RADCOS number radians Returns the cosine of radians
ARCTAN number ratio Returns the arctangent of ratio, in degrees
(ARCTAN) number x number y Returns the arctangent of y/x, in degrees
RADARCTAN number ratio Returns the arctangent of ratio, in radians
(RADARCTAN) number x number y Returns the arctangent of y/x, in radians

Random numbers

Return Type Instruction Operand 1 Operand 2 Usage
number GAUSSIAN Returns a random number of gaussian distribution with mean 0.0 and standard deviation 1.0
number RANDOM number range Returns a random integer evenly distributed between 0 and range-1
number (RANDOM) number start number end Returns a random integer evenly distributed between start and end
RERANDOM Initializes the random number generator to a predictable state. The sequence of random numbers will always be the same (given the same ranges) after a RERANDOM instruction
(RERANDOM) number seed Initializes the random number generator to a predictable state. Each integer value of seed will give a unique, predictable sequence of random numbers after the RERANDOM instruction

Logical operations

These instructions perform logical calculations. They all return a boolean.

Instruction Operand 1 Operand 2 Usage
AND boolean tf1 boolean tf2 Returns True if both tf1 and tf2 are True, otherwise returns False.
(AND) boolean tf boolean ... Returns True if all of the inputs are True, otherwise returns False. There must one or more inputs.
OR boolean tf1 boolean tf2 Returns True if either tf1 or tf2 are True, otherwise returns False.
(OR) boolean tf boolean ... Returns True if any of the inputs are True, otherwise returns False. There must one or more inputs.
NOT boolean tf1 Returns the logical inverse of tf1.

Special Instructions

Instruction Operand 1 Operand 2 Usage
.SETSPECIAL immediate word name number value This instruction sets the special TurboTurtle program constant named name to a value of value. The supported variable names are given in the table below.
(PRINT) word or number or boolean thing1 word or number or boolean ... This is a debugging instruction. It prints the values of each of its inputs, separated by spaces, to the standard output (terminal). There must one or more inputs.

Special variables

Name Meaning
FramesPerSec Setting the FramesPerSec special variable to a non-zero value will cause the wrapper code to insert a variable delay after each CLEAN or CLEARSCREEN instruction in order to maintain an average speed of the given number of Frames per Second
HighPrecision Setting the HighPrecision special variable to a non-zero value will cause the Logo program and wrapper to use double-precision floating-point variables instead of single-precision. This can remove artifacts in some very sensitive programs such as Fern.logo
WindowSize Setting the WindowSize special variable to any value will cause the display window's height and width to be at least the given number of turtle steps
LineSmooth Setting the LineSmooth special variable to 0 will disable line anti-aliasing. Setting LineSmooth to 1 will enable the fastest line anti-aliasing. Setting LineSmooth to 2 (the default) will enable the highest-quality line anti-aliasing.
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.