Program Flow

This section describes various commands to control the program flow. The IF command implements branching, and various loop commands implement looping. CATCH and THROW implement a mechanism to pass control across procedure boundaries.

.MAYBEOUTPUT

Exits a procedure and outputs a value if present; one input.

Syntax

.MAYBEOUTPUT value

Description

.MAYBEOUTPUT makes its input the output of the procedure. After .MAYBEOUTPUT is run, control returns to the calling procedure or to toplevel. If .MAYBEOUTPUT is used outside of a procedure, control returns to toplevel, and the result of the current toplevel command is .MAYBEOUTPUT’s input.

.MAYBEOUTPUT is the only Logo command that accepts a missing input. Usually, Logo reports an error if a procedure’s output is expected to be passed in to another procedure as an input value. .MAYBEOUTPUT, however, does not report an error. If there is no input, .MAYBEOUTPUT simply causes the procedure to output nothing. This makes it possible to return the result of Logo commands and procedures that may or may not output a value, like RUN.

Examples

TO RUNIT :what .MAYBEOUTPUT RUN :what END Result: RUNIT defined RUNIT [5 * 5] Result: 25 RUNIT [PRINT “HI] HI

APPLY

Applies a parameter list to a procedure; two inputs.

Syntax

APPLY procedure list

Description

APPLY runs the procedure or primitive given as its first input with the arguments supplied as the second input. The output of APPLY is the output of the operation.

Examples

APPLY “FPUT [“HELLO [BILL]] Result: [HELLO BILL]

CASE

Outputs a value based on an input value; two inputs.

Syntax

CASE expression [ [value [case-value]] ... [ELSE else-value]]

Description

CASE examines its first input and runs a list based on that value. Its second input is a list containing two-element lists. For each of these lists, the first element is either a value, or a list of values to compare against. If one of the values matches, CASE runs the list’s second element and outputs the result. If the first element of the case list is the word ELSE, CASE runs the list’s second element without further checks, making such a case list the default case.

Examples

TO SEL :VALUE OP CASE :VALUE [ [1 “ONE] [2 “TWO] [[3 4] “THREE.OR.FOUR] [ELSE [SE “SOMETHING “ELSE]] ] END Result: SEL defined SEL 1 Result: ONE SEL 3 Result: THREE.OR.FOUR SEL “NOTHING Result: [SOMETHING ELSE]

CATCH

Catches runtime errors and THROWn data; two inputs.

Syntax

CATCH word instructions
CATCH TRUE instructions
CATCH "ERROR instructions

Description

CATCH runs the instructions in its second input. If Logo executes a THROW command during the execution of the commands, Logo returns control to the command following the CATCH command if the input to THROW matches the word supplied as the first input. If the thrown word does not match, Logo searches for another CATCH command further up in the list of called procedures until a match is found, and returns control to the command following that CATCH command. The CATCH command is used to program procedure exits that span multiple nested procedure calls. If a thrown word is not caught, Logo treats it as a runtime error. The instruction list can contain another CATCH command. This way, multiple CATCH commands can be nested to catch different conditions.

There are a few special uses of CATCH. If the first input to CATCH is TRUE, any error that a procedure throws will be caught. Also, CATCH “ERROR catches an error that would otherwise print a Logo message and return to toplevel. CATCH “TOPLEVEL catches any attempt of the program to return to toplevel.

After catching an error or a thrown word, the built-in variable :ERROR contains the value that THROW threw (for a runtime error, that value is RUNTIME). The built-in variable :ERRORTEXT contains the error message that Logo would have printed. The ERROR command (not to be confused with the built-in variable :ERROR returns more detailed information about the last error.)

Examples

TO NAMEIT ; catch the NAMEIT1 value thrown inside NAMEIT1 CATCH “NOTNAME [NAMEIT1] END Result: NAMEIT defined TO NAMEIT1 PRINT [PLEASE ENTER A NAME] LOCAL “NAME MAKE “NAME READ ; throw the value NOTNAME in case of the input being a list IF NOT WORD? :NAME THEN THROW “NOTNAME PRINT SE :NAME [IS A GOOD NAME] END Result: NAMEIT defined NAMEIT Result: The name is thrown and caught

DO.UNTIL

Runs a list until a condition is true; two inputs.

Syntax

DO.UNTIL runlist testlist

Description

DO.UNTIL runs the Logo command(s) in its first input; it then evaluates its second input and re-runs its first input if the result is FALSE. DO.UNTIL will continue this process until the value of the testlist is TRUE. See also WHILE, DO.WHILE, and UNTIL.

Examples

MAKE “X 1 DO.UNTIL [PRINT :X MAKE “X :X + 1] [:X > 5] 1 2 3 4 5

DO.WHILE

Runs a list until a condition is false; two inputs.

Syntax

DO.WHILE runlist testlist

Description

DO.WHILE runs the Logo command(s) in its first input; it then evaluates its second input and re-runs its first input if the result is TRUE. DO.WHILE will continue this process until the value of the testlist is FALSE. See also WHILE, DO.UNTIL, and UNTIL.

Examples

MAKE “X 1 DO.WHILE [PRINT :X MAKE “X :X + 1] [:X <= 5] 1 2 3 4 5

ELSE

Starts the ELSE part of an IF command; no inputs.

Syntax

ELSE

Description

ELSE is not a procedure, but rather a keyword. If used as a procedure, it does not accept any inputs, and it does not output anything. Use it together with IF and THEN.

END

Ends a procedure definition; no inputs.

Syntax

END

Description

END ends the definition of a Logo procedure. It checks for any open brackets and reports an error if there are lists that are not closed correctly. END is used in Logo source files only.

Do not use END when defining a procedure with the DEFINE command. END is a special word like THEN or ELSE and not a procedure by itself.

ERROR

Outputs the last runtime error; no inputs.

Syntax

ERROR

Description

ERROR outputs a list describing the error just caught. If there was no error, ERROR outputs the empty list; otherwise, the output is a 4-element list. The first element is the value 0 (for backwards compabililty). The second element is the text of the message as :ERRORTEXT would have returned it. The third element is the name of the procedure where the error occurred, and the fourth element is the line number for that error.

The built-in variable :ERROR works together with the CATCH and THROW commands, and should not be confused with this command.

EVAL

Runs a list and collects all outputs; one input.

Syntax

EVAL list

Description

EVAL runs its input as if it were typed in directly. EVAL does not throw an error when the execution of the list yields a result; instead, all results are concatenated into a list and output by the procedure. See also RUN.

Examples

; PRINT “Hello does not add any value to the output of EVAL EVAL [1 2 PRINT “Hello “Three] Result: [1 2 THREE]

FOR

Runs a list for a defined number of times.

Syntax

FOR variable-name start-value end-value [runlist]
FOR [variable-name start-value end-value increment-value] [runlist]
(FOR variable-name start-value end-value [runlist] increment-value)
FOR [variable-name start-value end-value] [runlist]

Description

FOR allows you to execute a list of Logo commands a given number of times. Inputs to FOR are a control variable, a beginning value, an ending value, and a list of Logo commands to be executed. FOR assigns the beginning value to the variable, executes the instruction list, and then increments the variable by one. This process is repeated until the value of the variable is beyond the ending value. The variable increment step can be changed to a number other than one. Logo sets the loop variable to the next value at the end of each iteration after checking for the ending condition. You can, therefore, set the loop variable to a value that causes the FOR loop to exit early.

FOR comes in two flavors. The Terrapin Logo flavor expects the name of the variable, the beginning value, and the ending value as three separate inputs. If a different increment than 1 is desired, that value is an optional fifth input. Note that the variable needs to be a string constant for Logo to detect the Terrapin flavor.

The Berkeley version of FOR expects the variable name, the beginning value, and the ending value as a list, which is the first input. An optional increment value is appended to that list. You should use the Berkeley flavor of FOR so programs are more easily exchangeable with other Logo implementations.

In the Berkeley flavor of FOR, the variable is a temporary variable, which goes away after FOR terminates. It is only visible to the runlist, and hides other variables that have the same name. The Terrapin Logo flavor of FOR uses whatever variable of that name it finds, and creates the variable as a toplevel name if it does not exist.

Examples

; Berkeley version FOR [I 1 4 2] [PRINT :I] FOR (LIST “I 1 4) [PRINT :I] TO RETURN.LIST OUTPUT (LIST “I 1 4) END Result: RETURN.LIST defined FOR RETURN.LIST [PRINT :I] ; Terrapin version FOR “I 1 4 [PRINT :I] (FOR “I 1 4 [PRINT :I] 2)

FOREACH

Runs a list for each element of its first input; two inputs.

Syntax

FOREACH word-or-list runlist

Description

The FOREACH command runs a list of commands repeatedly. FOREACH sets an internal pointer to the first element of the list given as its first input. On each run, it substitutes all occurrences of a single question mark ? in the runlist with the list element that the internal pointer points to, runs the runlist, and advances the internal pointer to the next list element. If the runlist reports a value, FOREACH stops and reports that value. If the question mark is quoted as in “?, the list element is quoted as well; the same applies if the question mark has a leading colon as in :?. If the first input is a word, FOREACH runs the list for each character of the word.

If the first input is a word, FOREACH runs the list for each of the word’s characters.

FOREACH substitutes question marks inside sublists. Therefore, nested FOREACH loops are not possible. If you need nested FOREACH loops, you need to create a separate procdure for the inner FOREACH loop and call that procedure from the outer FOREACH loop.

Note that FOREACH is different from the FOREACH command of Berkeley Logo. The Berkeley Logo FOREACH command knows the ?REST symbol as well as the # symbol; Logo does not recognize these symbols. Also, Berkeley Logo does not transfer a quote or a colon from the question mark to the replaced symbol as Logo does.

Examples

; A quoted question mark: FOREACH [JOHN MARTHA] [PRINT “?] JOHN MARTHA

FOREVER

Runs a list forever; one input.

Syntax

FOREVER runlist

Description

FOREVER runs a list forever until a command like STOP or OUTPUT exits the loop, or until the program is stopped. FOREVER acts like the REPEAT command, with an incredibly high repeat count.

GO

Jumps to a label inside a procedure; one input.

Syntax

GO name

Description

GO transfers the flow within a procedure to the command immediately following its corresponding LABEL command. GO and its corresponding LABEL must reside within the same procedure, and they must reside within the same runlist. A GO from the body of a procedure to, for example, the runlist of an IF command is not possible.

Examples

; The procedure PINWHEEL runs forever; click the Stop button to stop the procedure. TO PINWHEEL FD 100 LABEL “LOOP REPEAT 4 [FD 50 RT 90] RT 20 GO “LOOP END Result: PINWHEEL defined PINWHEEL

HALT

Stops one or all background programs; expects between zero inputs and one input, but parentheses are needed if not called with one input.

Syntax

HALT id
HALT [list of ids]
(HALT)

Description

HALT causes one or more running background programs to stop execution. The input to HALT is the ID of a previously LAUNCHed program. The LAUNCH command launches a background program and reports the ID number of the Logo engine that runs the program which you can use as input to HALT. Alternatively, HALT also accepts a list of IDs to halt.

Engine #0 is always the main Logo engine.

If HALT is used without inputs, it stops all running background programs, including event handlers. Use STOP outside of a procedure in a background program, or :LOGOENGINE to stop the current background program.

See also LAUNCH, LAUNCHED and :LOGOENGINE.

IF

Runs instructions based on a condition.

Syntax

IF expression [then-instructions]
IF expression [then-instructions] [else-instructions]
IF expression then-instructions
IF condition THEN commands... [ELSE commands...]

Description

IF checks its first input for being TRUE or FALSE. If the value is TRUE, it runs or outputs its second input, and if the value if FALSE, it runs or outputs its third input. If the second or third inputs are lists, IF treats these inputs as instruction lists, and runs the input.

There are several ways to specify the inputs to IF. If other commands just follow the IF command, all commands are executed only if the condition is true. Optionally, the list of commands may be preceded by the THEN keyword. If the list of commands contains the keyword ELSE, the execution of commands stops at that keyword if the condition is true, and the remainder of the line is skipped. If the condition is false, all commands up to and including the ELSE keyword is skipped, and execution continues at the command behind ELSE. If the command following the condition is a list, the list is considered to be a runlist, and Logo executes that list if the condition is true, and continues execution at the command behind the list. If that command also is a list, however, that list is considered to be a runlist that is executed if the condition is false.

IF can also be used to evaluate expressions based on a condition and output the result. If outputs either its second input or its third input based on the condition.

Examples

MAKE “NIGHT TRUE IF :NIGHT THEN “NIGHT ELSE “DAY Result: NIGHT IF :NIGHT PR [IT IS NIGHT] “NIGHT IT IS NIGHT Result: NIGHT IF :NIGHT “NIGHT “DAY Result: NIGHT

IFFALSE

Also: IFF

Runs a list if TEST was false; one input.

Syntax

IFFALSE instruction-list

Description

IFFALSE runs its first input if the most recent TEST operation is FALSE. If its input is a list, IFFALSE treats it as an instruction list, and runs the input. If the TEST operation is TRUE, IFFALSE does nothing.

The TEST operation only affects the procedure where it is called, and procedures that the procedure calls. See also IFTRUE and IF.

Examples

TO GUESS.IT :NUM PR [CAN YOU GUESS MY NUMBER?] MAKE “GUESS READWORD TEST :NUM = :GUESS IFTRUE [PR [GOOD GUESS!] STOP] IFFALSE [PR [NO, TRY AGAIN.]] GUESS.IT :NUM END Result: GUESS.IT defined GUESS.IT 4

IFTRUE

Also: IFT

Runs a list if TEST was true; one input.

Syntax

IFTRUE instruction-list

Description

IFTRUE runs its first input if the most recent TEST operation is TRUE. If its input is a list, IFTRUE treats it as an instruction list, and runs the input. If the TEST operation is FALSE, IFTRUE does nothing.

The TEST operation only affects the procedure where it is called, and procedures that the procedure calls. See also IFFALSE and IF.

Examples

IGNORE

Ignores the output of a procedure; one input.

Syntax

IGNORE object

Description

IGNORE simply “swallows” any output created by its input, which can be any Logo object. IGNORE is very handy if the output of any procedure is not needed.

LABEL

Marks a target for the GO command; one input.

Syntax

LABEL object

Description

LABEL marks the target of a GO-LABEL loop. Its input must match the input of the corresponding GO command. LABEL is used in conjunction with GO.

Examples

LAUNCH

Launches a runlist or procedure for execution in the background; expects a minimum of one input, but parentheses are needed if not called with one input.

Syntax

LAUNCH runlist
LAUNCH "procedurename
(LAUNCH "procedurename input1 ...)

Description

LAUNCH launches a Logo runlist or a procedure to be run in the background. This runlist or procedure runs simultaneously with other Logo procedures. The output of LAUNCH is the ID number of the Logo engine that runs the runlist or procedure which can be used with the HALT command to halt a running background procedure. Event handlers are background procedures as well.

Background procedures may unexpectedly alter the value of any Logo variable! You should try to not change any global Logo name; names like :STANDARD.INPUT, :STANDARD.OUTPUT, or :CASE are especially very dangerous to change in a background procedure. Imagine a main program writing to a file after having changed :STANDARD.OUTPUT, and a background procedure changing :STANDARD.OUTPUT to an entirely different file! Also, the TELL command should not be used, because it changes the list of turtles and widgets that other Logo programs talk to.

.MACRO LOADMOUSE LMAKE “M MOUSE OP (SE “LMAKE ““X FIRST :M “LMAKE ““Y LAST :M) END Result: LOADMOUSE defined TO CHECK.MOUSE LOADMOUSE IF :X < -100 OR :X > 100 [PR [X IS OUT OF RANGE]] IF :Y < -100 OR :Y > 100 [PR [Y IS OUT OF RANGE]] END Result: CHECK.MOUSE defined MACROEXPAND “LOADMOUSE Result: [LMAKE “X 23 LMAKE “Y -156]

OUTPUT

Also: OP

Exits a procedure and outputs a value; one input.

Syntax

OUTPUT value

TEST determines whether its input is TRUE or FALSE and stores it for later use by IFTRUE or IFFALSE. The effect of TEST is local to the procedure in which it is used; any corresponding IFTRUE or IFFALSE must be in the same procedure or a subprocedure. If no procedure is active, the result of the TEST is stored globally, and any procedures that are called afterwards inherit this value. See also IF.

Examples

TEXT

Outputs a procedure definition; one input.

Syntax

TEXT procedurename

Description

TEXT takes a quoted procedure name as input and reports the definition of that procedure. The form of the output is a list. The first element of the list is any variable(s) defined in the title line of the procedure. If there are no variables, the first element is the empty list ([]). Each remaining element is a list that consists of one line of the procedure definition. The output of TEXT is in the same form as the required input for DEFINE. If the input to TEXT is a primitive, TEXT outputs the list [Primitive XXX], where XXX is the name of the primitive.

THEN

Starts the THEN part of an IF command; no inputs.

Syntax

THEN

Description

THEN is not a procedure, but rather a keyword. If used as a procedure, it does not accept any inputs, and it does not output anything. Use it together with IF and ELSE.

THROW

Throws a Logo word or a runtime error; expects between zero inputs and two inputs, but parentheses are needed if not called with one input.

Syntax

THROW word
(THROW word message)
(THROW)

Description

THROW returns control to the CATCH statement with a matching first input, or to the CATCH TRUE statement, whichever comes first in the chain of active procedures. If THROW is used without inputs, it re-throws an error that was caught with a CATCH statement in the same procedure. If there was no caught error, (THROW) does nothing. The command THROW “TOPLEVEL ends all programs and returns control to the Listener.

If THROW is executed with more than one input, the second input becomes the error message.

Examples

; Print an error if present, and rethrow that error. TO RETHROW :RUNLIST CATCH “ERROR :RUNLIST IF WORD? :ERROR [PR :ERRORTEXT] ; print error if present (THROW) ; rethrow the error END Result: RETHROW defined RETHROW [SQRT -1]

TOPLEVEL

Returns to toplevel; no inputs.

Syntax

TOPLEVEL

Description

TOPLEVEL stops execution of all Logo commands and returns Logo to toplevel, the command mode. TOPLEVEL in a procedure performs the same function as clicking the Stop button. You may also THROW “TOPLEVEL to return to toplevel. TOPLEVEL may also be caught with a CATCH command. Note that TOPLEVEL is different from STOP in that control is not returned to any calling procedure.

UNTIL

Runs a list until a condition is true; two inputs.

Syntax

UNTIL testlist runlist

Description

UNTIL evaluates its first input and runs the Logo command(s) in its second input if the value of the first input is FALSE. UNTIL will continue this process until the value of the first input is TRUE. See also WHILE, DO.WHILE, and DO.UNTIL.

Examples

MAKE “X 1 UNTIL [:X > 5] [PRINT :X MAKE “X :X + 1] Result: 1 2 3 4 5

WAIT

Waits for a number of milliseconds; one input.

Syntax

WAIT number

Description

WAIT inserts a pause before the next instruction is run. The length of the pause is the input to WAIT times 1/1000 of a second (milliseconds).

The accuracy of WAIT depends on the wait time and the number of executing background procedures. A WAIT time of under 15 is usually quite precise, while longer WAIT times may wait longer than expected. WAIT times under 15 do not release the CPU, while longer wait times do.

Examples

WAIT 1000

WHEN

Monitors a change to a Logo property or to a Logo event; expects between zero inputs and two inputs, but parentheses are needed if not called with two inputs.

Syntax

WHEN [name propertyname compare.to value] [runlist]
WHEN [name compare.to value] [runlist]
WHEN [name propertyname] [runlist]
WHEN [name] [runlist]
WHEN [name propertyname compare.to value] []
WHEN [name propertyname] []
WHEN [name] []
(WHEN [property-condition])
(WHEN)

Description

The WHEN command monitors changes to a Logo property, or a change to the Logo environment. Its first input tells WHEN what to watch, and the second input is a list of Logo commands that Logo should run when Logo detects the condition to watch,

If the second list is empty, Logo turns off monitoring the condition described in the first input.

The first input is a list of one to four elements.

If there is only one element, it is the name of the property list to watch; in that case, WHEN triggers the event if any of the property list’s properties change.

If there are two elements, Logo monitors changes to the supplied property, and runs the runlist if there are any changes to the property. To watch the light sensor of an InO-Bot, for example, the list would be [INOBOT LIGHT].

If there are three or four elements, the last two elements are a comparison operator (one of =, <>, <=, <, >=, > or any of its aliases), and the value to compare against. For example, if InO-Bot’s light sensor should trigger a runlist when the light level is above 0.5, the list would be [INOBOT LIGHT > 0.5].

Note that Logo runs the runlist only once when it compares a value with the <=, <, >=, or > operators. Logo will wait for the comparison to become FALSE before running the runlist again when the condition matches again. This means for the InO-Bot example that Logo would run the runlist once the light level is above 0.5, then wait the light level to drop below 0.5 before checking the level again. This prevents Logo from running the runlist anytime the light level is above 0.5.

Note that you do not use quotes inside a list. For example, if you want Logo to run a runlist when the key “A” is pressed, use [WHEN KEY = A], not [KEY = “A].

You can issue as many WHEN commands as you need to monitor a single property.

A more detailed explanation and many more examples can be found at the page WHEN Something Happens.

Note that WHEN stops running when the program terminates. To make Logo monitor changes continuously even after the program has ended, use the WHENEVER command.

Whenever Logo throws a runtime error that is reported to the Listener, Logo stops all monitoring.

The WHEN command with a single input is the same as the WHEN command with an empty runlist; it stop processing of the condition described in its input.

WHEN without any inputs stops all processing that was created with the WHEN command. It does not stop the processing of runlists defined with the WHENEVER command.

Examples

WHEN [MOUSE MOVED] [PENUP SETXY MOUSE] WHEN [MOUSE DRAGGED] [PENDOWN SETXY MOUSE] ; WAIT -1 causes the program to wait for the events above WAIT -1

WHENEVER

Monitors changes to a Logo property or to a Logo event; expects between zero inputs and two inputs, but parentheses are needed if not called with two inputs.

Syntax

WHENEVER [name propertyname compare.to value] [runlist]
WHENEVER [name compare.to value] [runlist]
WHENEVER [name propertyname] [runlist]
WHENEVER [name] [runlist]
WHENEVER [name propertyname compare.to value] []
WHENEVER [name propertyname] []
WHENEVER [name] []
(WHENEVER [property-condition])
(WHENEVER)

Description

The WHENEVER command causes Logo to monitor a property of a change to the Logo event. It is identical to the WHEN command, but Logo does not stop monitoring when the program that issued the WHENEVER command ends. Logo continues to monitor the condition until a WHENEVER command is entered with the very same condition, but an empty runlist.

Use WHENEVER to monitor changes that need to be monitored outside of a program, like a Bluetooth device being connected.

When Logo throws a runtime error that is reported to the Listener, it does not affect runlists defined with the WHENEVER command. Use (WHENEVER) to halt processing for these runlists. It does not stop processing of runlists that were defined with the WHEN command.

Examples

; Print the mouse position whenever it is moves with the button down WHENEVER [MOUSE DRAGGED] [PR MOUSE]

WHILE

Runs a list until a condition is false; two inputs.

Syntax

WHILE testlist runlist

Description

WHILE evaluates its first input and runs the Logo command(s) in its second input if the value of the first input is TRUE. WHILE will continue this process until the value of the first input is FALSE.

Examples

MAKE “X 1 WHILE [:X <= 5] [PRINT :X MAKE “X :X + 1] Result: 1 2 3 4 5