(special form)

TO procname :input1 :input2 ...

Command that prepares Logo to accept a procedure definition. The procedure is named procname and there must not already be a procedure by that name. The inputs are named input1, input2, etc. Any number of inputs is allowed, including none. Names of procedures and inputs are case-insensitive.

Unlike nearly every other Logo procedure, TO takes as its inputs the actual words typed in the instruction line, as if they were all quoted, rather than the results of evaluating expressions to provide the inputs. (That's what "special form" means.)

FMSLogo allows procedures to have a variable numbers of inputs. Every procedure has a minimum, default, and maximum number of inputs. The maximum may be infinite.

The minimum number of inputs is the number of required inputs, which must come first. A required input is indicated by the

:inputname

notation.

After all the required inputs can be zero or more optional inputs, represented by the following notation:

[:inputname default.value.expression]

When the procedure is invoked, if actual inputs are not supplied for these optional inputs, the default.value.expressions are evaluated to set values for the corresponding input names. The inputs are processed from left to right, so a default value expression can be based on earlier inputs. For example:

TO PROC :inlist [:startvalue first :inlist]

When the procedure is invoked as

PROC [a b c]

the :inlist input has the value [a b c] and the :startvalue input has the value "a. When the procedure is invoked as

(PROC [a b c] "x)

the :inlist has the value [a b c] and :startvalue has the value "x.

After all the required and optional input can come a single "rest" input, represented by the following notation:

[:inputname]

This is a rest input rather than an optional input because there is no default value expression. There can be at most one rest input. When the procedure is invoked, the value of the rest input is a list containing all inputs that are not used for required or optional inputs. Example:

TO PROC :in1 [:in2 "foo] [:in3]

When this procedure is invoked as:

PROC "x

:in1 has the value "x, :in2 has the value "foo, and :in3 has the value [] (the empty list). When it is invoked as:

(PROC "a "b "c "d)

:in1 has the value "a, :in2 has the value "b, and :in3 has the value [c d].

The maximum number of inputs for a procedure is infinite if a "rest" input is given; otherwise, it is the number of required inputs plus the number of optional inputs.

The default number of inputs for a procedure, which is the number of inputs that it accepts when its invocation is not enclosed in parentheses, is ordinarily equal to the minimum number. If you want a different default number you can indicate that by putting the desired default number as the last thing on the TO line.

For example:

TO PROC :in1 [:in2 "foo] [:in3] 3

This procedure has a minimum of one input, a default of three inputs, and an infinite maximum.

FMSLogo displays a dialog box if you enter a TO instruction in the commander's edit box. Whatever instructions you type into the popup become part of the definition. You can finish the definition by pressing the "end" button or abandon the definition by pressing the "Cancel" button.

TO ECHO :times :thing
  REPEAT :times [PRINT :thing]
END

ECHO 2 "Hello
Hello
Hello
ECHO 3 "Bye
Bye
Bye
Bye