Instructions - richard42/turboturtle GitHub Wiki

This document applies to version 1.0 of TurboTurtle.

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.

• 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.

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.

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.

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.

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.

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.

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.

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

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

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

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.

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

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

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.

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.

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.