BMUG Revelations/BMUG Revelations.toast/Programming/Programming Languages/UCB Logo 3.0/usermanual

Text File | 1993-08-14 | 101.2 KB | 2,935 lines | [TEXT/JV01]

Berkeley Logo User Manual

 *    Copyright (C) 1993 by the Regents of the University of California
 *
 *      This program is free software; you can redistribute it and/or modify
 *      it under the terms of the GNU General Public License as published by
 *      the Free Software Foundation; either version 2 of the License, or
 *      (at your option) any later version.
 *
 *      This program is distributed in the hope that it will be useful,
 *      but WITHOUT ANY WARRANTY; without even the implied warranty of
 *      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *      GNU General Public License for more details.
 *
 *      You should have received a copy of the GNU General Public License
 *      along with this program; if not, write to the Free Software
 *      Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

This is a program that is still being written.  Many things are missing,
including adequate documentation.  This manual assumes that you already know
how to program in Logo, and merely presents the details of this new
implementation.  Read _Computer_Science_Logo_Style,_Volume_1:_
_Intermediate_Programming_ by Brian Harvey (MIT Press, 1985) for a tutorial
on Logo programming with emphasis on symbolic computation.

Here are the special features of this dialect of Logo:

    Source file compatible among Unix, DOS, and Mac platforms.

    Random-access arrays.

    Variable number of inputs to user-defined procedures.

    Mutators for list structure (dangerous).

    Pause on error, and other improvements to error handling.

    Comments and continuation lines; formatting is preserved when
    procedure definitions are saved or edited.

    Terrapin-style tokenization (e.g., [2+3] is a list with one member)
    but LCSI-style syntax (no special forms except TO).  The best of
    both worlds.

    First-class instruction and expression templates (see APPLY).

    Macros.


ENTERING AND LEAVING LOGO
=========================

To start Logo, just type the word "logo" to the shell.  To leave Logo, enter
the command "bye".  If you include one or more filenames on the command line
when starting Logo, those files will be loaded before the interpreter starts
reading commands from your terminal.  If you load a file that executes some
program that includes a "bye" command, Logo will run that program and exit.
You can therefore write standalone programs in Logo and run them with
shell/batch scripts.  To support this technique, Logo does not print its
usual welcoming and parting messages if you give file arguments to the logo
command.

If you type your interrupt character (see table below) Logo will stop what
it's doing and return to toplevel, as if you did THROW "TOPLEVEL.  If you
type your quit character Logo will pause as if you did PAUSE.

            Unix          DOS        Mac

    toplevel    usually ctrl-C    ctrl-Q      command-. (period)

    pause        usually ctrl-\    ctrl-W      command-, (comma)

If you have an environment variable called LOGOLIB whose value is the name of
a directory, then Logo will use that directory instead of the default
library.  If you invoke a procedure that has not been defined, Logo first
looks for a file in the current directory named proc.lg where "proc" is the
procedure name in lower case letters.  If such a file exists, Logo loads
that file.  If the missing procedure is still undefined, or if there is no
such file, Logo then looks in the library directory for a file named proc
(no ".lg") and, if it exists, loads it.  If neither file contains a
definition for the procedure, then Logo signals an error.  Several
procedures that are primitive in most versions of Logo are included in the
default library, so if you use a different library you may want to include
some or all of the default library in it.


TOKENIZATION
============

Names of procedures, variables, and property lists are case-insensitive.  So
are the special words END, TRUE, and FALSE.  Case of letters is preserved
in everything you type, however.

Within square brackets, words are delimited only by spaces and square
brackets.  [2+3] is a list containing one word.

After a quotation mark outside square brackets, a word is delimited by
a space, a square bracket, or a parenthesis.

A word not after a quotation mark or inside square brackets is delimited
by a space, a bracket, a parenthesis, or an infix operator +-*/=<>.  Note
that words following colons are in this category.  Note that quote and
colon are not delimiters.

A word consisting of a question mark followed by a number (e.g., ?3),
when runparsed (i.e., where a procedure name is expected), is treated
as if it were the sequence

    ( ? 3 )

making the number an input to the ? procedure.  (See the discussion of
templates, below.)  This special treatment does not apply to words read
as data, to words with a non-number following the question mark, or if
the question mark is backslashed.

A line (an instruction line or one read by READLIST or READWORD) can be
continued onto the following line if its last character is a tilde (~).
READWORD preserves the tilde and the newline; READLIST does not.

A semicolon begins a comment in an instruction line.  Logo ignores
characters from the semicolon to the end of the line.  A tilde as the
last character still indicates a continuation line, but not a continuation
of the comment.  For example, typing the instruction

    print "abc;comment ~
    def

will print the word abcdef.  Semicolon has no special meaning in data
lines read by READWORD or READLIST, but such a line can later be reparsed
using RUNPARSE and then comments will be recognized.  If a tilde is typed
at the terminal for line continuation, Logo will issue a tilde as a prompt
character for the continuation line.

To include an otherwise delimiting character (including semicolon or tilde)
in a word, precede it with backslash (\).  If the last character of a line
is a backslash, then the newline character following the backslash will be
part of the last word on the line, and the line continues onto the following
line.  To include a backslash in a word, use \\.  If the combination
backslash-newline is entered at the terminal, Logo will issue a backslash as
a prompt character for the continuation line.  All of this applies to data
lines read with READWORD or READLIST as well as to instruction lines.  A
character entered with backslash is EQUALP to the same character without the
backslash, but can be distinguished by the BACKSLASHEDP predicate.  (In
Europe, backslashing is effective only on characters for which it is
necessary: whitespace, parentheses, brackets, infix operators, backslash,
vertical bar, tilde, quote, question mark, colon, and semicolon.)

An alternative notation to include otherwise delimiting characters in words
is to enclose a group of characters in vertical bars.  All characters between
vertical bars are treated as if they were letters.  In data read with READWORD
the vertical bars are preserved in the resulting word.  In data read with
READLIST (or resulting from a PARSE or RUNPARSE of a word) the vertical bars
do not appear explicitly; all potentially delimiting characters (including
spaces, brackets, parentheses, and infix operators) appear as though entered
with a backslash.  Within vertical bars, backslash may still be used; the only
characters that must be backslashed in this context are backslash and vertical
bar themselves.

Characters entered between vertical bars are forever special, even if the
word or list containing them is later reparsed with PARSE or RUNPARSE.
The same is true of a character typed after a backslash, except that when
a quoted word containing a backslashed character is runparsed, the backslashed
character loses its special quality and acts thereafter as if typed normally.
This distinction is important only if you are building a Logo expression out
of parts, to be RUN later, and want to use parentheses.  For example,

    PRINT RUN (SE "\( 2 "+ 3 "\))

will print 5, but

    RUN (SE "MAKE ""|(| 2)

will create a variable whose name is open-parenthesis.  (Each example would
fail if vertical bars and backslashes were interchanged.)


DATA STRUCTURE PRIMITIVES
=========================

CONSTRUCTORS
------------

WORD word1 word2
(WORD word1 word2 word3 ...)

    outputs a word formed by concatenating its inputs.

LIST thing1 thing2
(LIST thing1 thing2 thing3 ...)

    outputs a list whose members are its inputs, which can be any
    Logo object (word, list, or array).

SENTENCE thing1 thing2
SE thing1 thing2
(SENTENCE thing1 thing2 thing3 ...)
(SE thing1 thing2 thing3 ...)

    outputs a list whose members are its inputs, if those inputs are
    not lists, or the members of its inputs, if those inputs are lists.

FPUT thing list

    outputs a list equal to its second input with one extra member,
    the first input, at the beginning.

LPUT thing list

    outputs a list equal to its second input with one extra member,
    the first input, at the end.

ARRAY size
(ARRAY size origin)

    outputs an array of "size" elements (must be a positive integer),
    each of which initially is an empty list.  Array elements can be
    selected with ITEM and changed with SETITEM.  The first element of
    the array is element number 1 unless an "origin" input (must be an
    integer) is given, in which case the first element of the array has
    that number as its index.  (Typically 0 is used as the origin if
    anything.)  Arrays are printed by PRINT and friends, and can be
    typed in, inside curly braces; indicate an origin with {a b c}@0.

MDARRAY sizelist                    (library procedure)
(MDARRAY sizelist origin)

    outputs a multi-dimensional array.  The first input must be a list
    of one or more positive integers.  The second input, if present,
    must be a single integer that applies to every dimension of the array.
    Ex: (MDARRAY [3 5] 0) outputs a two-dimensional array whose elements
    range from [0 0] to [2 4].

LISTTOARRAY list                    (library procedure)
(LISTTOARRAY list origin)

    outputs an array of the same size as the input list, whose elements
    are the members of the input list.

ARRAYTOLIST array                    (library procedure)

    outputs a list whose members are the elements of the input array.
    The first member of the output is the first element of the array,
    regardless of the array's origin.

COMBINE thing1 thing2                    (library procedure)

    if thing2 is a word, outputs WORD thing1 thing2.  If thing2 is a list,
    outputs FPUT thing1 thing2.

REVERSE list                        (library procedure)

    outputs a list whose members are the members of the input list, in
    reverse order.

GENSYM                            (library procedure)

    outputs a unique word each time it's invoked.  The words are of the
    form G1, G2, etc.


SELECTORS
---------

FIRST thing

    if the input is a word, outputs the first character of the word.
    If the input is a list, outputs the first member of the list.
    If the input is an array, outputs the origin of the array (that
    is, the INDEX OF the first element of the array).

FIRSTS list

    outputs a list containing the FIRST of each member of the input
    list.  It is an error if any member of the input list is empty.
    (The input itself may be empty, in which case the output is also
    empty.)  This could be written as

        to firsts :list
        output map "first :list
        end

    but is provided as a primitive in order to speed up the iteration
    tools MAP, MAP.SE, and FOREACH.

        to transpose :matrix
        if emptyp first :matrix [op []]
        op fput firsts :matrix transpose bfs :matrix
        end

LAST wordorlist

    if the input is a word, outputs the last character of the word.
    If the input is a list, outputs the last member of the list.

BUTFIRST wordorlist
BF wordorlist

    if the input is a word, outputs a word containing all but the first
    character of the input.  If the input is a list, outputs a list
    containing all but the first member of the input.

BUTFIRSTS list
BFS list

    outputs a list containing the BUTFIRST of each member of the input
    list.  It is an error if any member of the input list is empty or an
    array.  (The input itself may be empty, in which case the output is
    also empty.)  This could be written as

        to butfirsts :list
        output map "butfirst :list
        end

    but is provided as a primitive in order to speed up the iteration
    tools MAP, MAP.SE, and FOREACH.

BUTLAST wordorlist
BL wordorlist

    if the input is a word, outputs a word containing all but the last
    character of the input.  If the input is a list, outputs a list
    containing all but the last member of the input.

ITEM index thing

    if the "thing" is a word, outputs the "index"th character of the
    word.  If the "thing" is a list, outputs the "index"th member of
    the list.  If the "thing" is an array, outputs the "index"th
    element of the array.  "Index" starts at 1 for words and lists;
    the starting index of an array is specified when the array is
    created.

MDITEM indexlist array                    (library procedure)

    outputs the element of the multidimensional "array" selected by
    the list of numbers "indexlist".

PICK list                        (library procedure)

    outputs a randomly chosen member of the input list.

REMOVE thing list                    (library procedure)

    outputs a copy of "list" with every member equal to "thing" removed.

REMDUP list                        (library procedure)

    outputs a copy of "list" with duplicate members removed.  If two or
    more members of the input are equal, the rightmost of those members
    is the one that remains in the output.

QUOTED thing                        (library procedure)

    outputs its input, if a list; outputs its input with a quotation
    mark prepended, if a word.


MUTATORS
--------

SETITEM index array value

    command.  Replaces the "index"th element of "array" with the new
    "value".  Ensures that the resulting array is not circular, i.e.,
    "value" may not be a list or array that contains "array".

MDSETITEM indexlist array value                (library procedure)

    command.  Replaces the element of "array" chosen by "indexlist"
    with the new "value".

.SETFIRST list value

    command.  Changes the first member of "list" to be "value".
    WARNING: Primitives whose names start with a period are DANGEROUS.
    Their use by non-experts is not recommended.  The use of .SETFIRST
    can lead to circular list structures, which will get some Logo
    primitives into infinite loops; unexpected changes to other data
    structures that share storage with the list being modified; and
    the permanent loss of memory if a circular structure is released.

.SETBF list value

    command.  Changes the butfirst of "list" to be "value".
    WARNING: Primitives whose names start with a period are DANGEROUS.
    Their use by non-experts is not recommended.  The use of .SETBF
    can lead to circular list structures, which will get some Logo
    primitives into infinite loops; unexpected changes to other data
    structures that share storage with the list being modified; Logo
    crashes and coredumps if the butfirst of a list is not itself a list;
    and the permanent loss of memory if a circular structure is released.

.SETITEM index array value

    command.  Changes the "index"th element of "array" to be "value",
    like SETITEM, but without checking for circularity.
    WARNING: Primitives whose names start with a period are DANGEROUS.
    Their use by non-experts is not recommended.  The use of .SETITEM
    can lead to circular arrays, which will get some Logo primitives into
    infinite loops; and the permanent loss of memory if a circular
    structure is released.

PUSH stackname thing                    (library procedure)

    command.  Adds the "thing" to the stack that is the value of the
    variable whose name is "stackname".  This variable must have a list
    as its value; the initial value should be the empty list.  New
    members are added at the front of the list.

POP stackname                        (library procedure)

    outputs the most recently PUSHed member of the stack that is the
    value of the variable whose name is "stackname" and removes that
    member from the stack.

QUEUE queuename thing                    (library procedure)

    command.  Adds the "thing" to the queue that is the value of the
    variable whose name is "queuename".  This variable must have a list
    as its value; the initial value should be the empty list.  New
    members are added at the back of the list.

DEQUEUE queuename                    (library procedure)

    outputs the least recently QUEUEd member of the queue that is the
    value of the variable whose name is "queuename" and removes that
    member from the queue.


PREDICATES
----------

WORDP thing

    outputs TRUE if the input is a word, FALSE otherwise.

LISTP thing

    outputs TRUE if the input is a list, FALSE otherwise.

ARRAYP thing

    outputs TRUE if the input is an array, FALSE otherwise.

EMPTYP thing

    outputs TRUE if the input is the empty word or the empty list,
    FALSE otherwise.

EQUALP thing1 thing2

    outputs TRUE if the inputs are equal, FALSE otherwise.  Two numbers
    are equal if they have the same numeric value.  Two non-numeric words
    are equal if they contain the same characters in the same order.  If
    there is a variable named CASEIGNOREDP whose value is TRUE, then an
    upper case letter is considered the same as the corresponding lower
    case letter.  (This is the case by default.)  Two lists are equal if
    their members are equal.  An array is only equal to itself; two
    separately created arrays are never equal even if their elements are
    equal.  (It is important to be able to know if two expressions have
    the same array as their value because arrays are mutable; if, for
    example, two variables have the same array as their values then
    performing SETITEM on one of them will also change the other.)

BEFOREP word1 word2

    outputs TRUE if word1 comes before word2 in ASCII collating sequence
    (for words of letters, in alphabetical order).  Case-sensitivity is
    determined by the value of CASEIGNOREDP.  Note that if the inputs are
    numbers, the result may not be the same as with LESSP; for example,
    BEFOREP 3 12 is false because 3 collates before 1.

.EQ thing1 thing2

    outputs TRUE if its two inputs are the same object, so that applying a
    mutator to one will change the other as well.  Outputs FALSE otherwise,
    even if the inputs are equal in value.
    WARNING: Primitives whose names start with a period are DANGEROUS.
    Their use by non-experts is not recommended.  The use of mutators
    can lead to circular data structures, infinite loops, or Logo crashes.

MEMBERP thing1 thing2

    if "thing2" is a list or an array, outputs TRUE if "thing1" is EQUALP
    to a member or element of "thing2", FALSE otherwise.  If "thing2" is
    a word, outputs TRUE if "thing1" is EQUALP to a substring of "thing2",
    FALSE otherwise.  Note that this behavior for words is different from
    other dialects, in which "thing1" must be a single character in order
    to make MEMBERP true with "thing2" a word.

NUMBERP thing

    outputs TRUE if the input is a number, FALSE otherwise.

BACKSLASHEDP char

    outputs TRUE if the input character was originally entered into Logo
    with a backslash (\) before it to prevent special syntactic meaning,
    FALSE otherwise.  (In Europe, outputs TRUE only if the character is
    a backslashed space, tab, newline, or one of ()[]+-*/=<>":;\~? )


QUERIES
-------

COUNT thing

    outputs the number of characters in the input, if the input is a word;
    outputs the number of members or elements in the input, if it is a list
    or an array.  (For an array, this may or may not be the index of the
    last element, depending on the array's origin.)

ASCII char

    outputs the integer (in the United States, between 0 and 127) that
    represents the input character in the ASCII code.

CHAR int

    outputs the character represented in the ASCII code by the input,
    which must be an integer between 0 and 127.

MEMBER thing1 thing2

    if "thing2" is a word or list and if MEMBERP with these inputs would
    output TRUE, outputs the portion of "thing2" from the first instance
    of "thing1" to the end.  If MEMBERP would output FALSE, outputs the
    empty word or list according to the type of "thing2".  It is an error
    for "thing2" to be an array.

LOWERCASE word

    outputs a copy of the input word, but with all uppercase letters
    changed to the corresponding lowercase letter.  (In the United
    States, letters that were initially read by Logo preceded by a
    backslash are immune to this conversion.)

UPPERCASE word

    outputs a copy of the input word, but with all lowercase letters
    changed to the corresponding uppercase letter.  (In the United
    States, letters that were initially read by Logo preceded by a
    backslash are immune to this conversion.)

STANDOUT thing

    outputs a word that, when printed, will appear like the input but
    displayed in standout mode (boldface, reverse video, or whatever your
    terminal does for standout).  The word contains terminal-specific
    magic characters at the beginning and end; in between is the printed
    form (as if displayed using TYPE) of the input.  The output is always
    a word, even if the input is of some other type, but it may include
    spaces and other formatting characters.  Note: a word output by
    STANDOUT while Logo is running on one terminal will probably not have
    the desired effect if printed on another type of terminal.

PARSE word

    outputs the list that would result if the input word were entered
    in response to a READLIST operation.  That is, PARSE READWORD has
    the same value as READLIST for the same characters read.

RUNPARSE wordorlist

    outputs the list that would result if the input word or list were
    entered as an instruction line; characters such as infix operators
    and parentheses are separate members of the output.  Note that
    sublists of a runparsed list are not themselves runparsed.


COMMUNICATION
=============

TRANSMITTERS
------------

Note:  If there is a variable named PRINTDEPTHLIMIT with a nonnegative
integer value, then complex list and array structures will be printed
only to the allowed depth.  That is, members of members of... of members
will be allowed only so far.  The elements or members omitted because
they are just past the depth limit are indicated by an ellipsis for each
one, so a too-deep list of two elements will print as [... ...].

If there is a variable named PRINTWIDTHLIMIT with a nonnegative integer
value, then only the first so many elements or members of any array or
list will be printed.  A single ellipsis replaces all missing objects
within the structure.  The width limit also applies to the number of
characters printed in a word, except that a PRINTWIDTHLIMIT between 0 and 9
will be treated as if it were 10 when applied to words.  This limit
applies not only to the top-level printed object but to any substructures
within it.

PRINT thing
PR thing
(PRINT thing1 thing2 ...)
(PR thing1 thing2 ...)

    command.  Prints the input or inputs to the current write stream
    (initially the terminal).  All the inputs are printed on a single
    line, separated by spaces, ending with a newline.  If an input is a
    list, square brackets are not printed around it, but brackets are
    printed around sublists.  Braces are always printed around arrays.

TYPE thing
(TYPE thing1 thing2 ...)

    command.  Prints the input or inputs like PRINT, except that no
    newline character is printed at the end and multiple inputs are not
    separated by spaces.  Note: printing to the terminal is ordinarily
    "line buffered"; that is, the characters you print using TYPE will
    not actually appear on the screen until either a newline character
    is printed (for example, by PRINT or SHOW) or Logo tries to read
    from the keyboard (either at the request of your program or after an
    instruction prompt).  This buffering makes the program much faster
    than it would be if each character appeared immediately, and in most
    cases the effect is not disconcerting.  To accommodate programs that
    do a lot of positioned text display using TYPE, Logo will force
    printing whenever SETCURSOR is invoked.  This solves most buffering
    problems.  Still, on occasion you may find it necessary to force the
    buffered characters to be printed explicitly; this can be done using
    the WAIT command.  WAIT 0 will force printing without actually
    waiting.

SHOW thing
(SHOW thing1 thing2 ...)

    command.  Prints the input or inputs like PRINT, except that
    if an input is a list it is printed inside square brackets.


RECEIVERS
---------

READLIST
RL

    reads a line from the read stream (initially the terminal) and
    outputs that line as a list.  The line is separated into elements as
    though it were typed in square brackets in an instruction.  If the
    read stream is a file, and the end of file is reached, READLIST
    outputs the empty word (not the empty list).  READLIST processes
    backslash, vertical bar, and tilde characters in the read stream;
    the output list will not contain these characters but they will have
    had their usual effect.  READLIST does not, however, treat semicolon
    as a comment character.

READWORD
RW

    reads a line from the read stream and outputs that line as a word.
    The output is a single word even if the line contains spaces,
    brackets, etc.  If the read stream is a file, and the end of file is
    reached, READWORD outputs the empty list (not the empty word).
    READWORD processes backslash, vertical bar, and tilde characters in
    the read stream.  In the case of a tilde used for line continuation,
    the output word DOES include the tilde and the newline characters, so
    that the user program can tell exactly what the user entered.
    Vertical bars in the line are also preserved in the output.
    Backslash characters are not preserved in the output, but the
    character following the backslash has 128 added to its
    representation.  Programs can use BACKSLASHEDP to check for this
    code.  (In Europe, backslashedness is preserved only for certain
    characters.  See BACKSLASHEDP.)

READCHAR
RC

    reads a single character from the read stream and outputs that
    character as a word.  If the read stream is a file, and the end of
    file is reached, READCHAR outputs the empty list (not the empty
    word).  If the read stream is a terminal, echoing is turned off
    when READCHAR is invoked, and remains off until READLIST or READWORD
    is invoked or a Logo prompt is printed.  Backslash, vertical bar,
    and tilde characters have no special meaning in this context.

READCHARS num
RCS num

    reads "num" characters from the read stream and outputs those
    characters as a word.  If the read stream is a file, and the end of
    file is reached, READCHARS outputs the empty list (not the empty
    word).  If the read stream is a terminal, echoing is turned off
    when READCHARS is invoked, and remains off until READLIST or READWORD
    is invoked or a Logo prompt is printed.  Backslash, vertical bar,
    and tilde characters have no special meaning in this context.

SHELL command
(SHELL command wordflag)

    Under Unix, outputs the result of running "command" as a shell
    command.  (The command is sent to /bin/sh, not csh or other
    alternatives.)  If the command is a literal list in the instruction
    line, and if you want a backslash character sent to the shell, you
    must use \\ to get the backslash through Logo's reader intact.  The
    output is a list containing one member for each line generated by
    the shell command.  Ordinarily each such line is represented by a
    list in the output, as though the line were read using READLIST.  If
    a second input is given, regardless of the value of the input, each
    line is represented by a word in the output as though it were read
    with READWORD.  Example:

            to dayofweek
            output first first shell [date]
            end

    This is "first first" to extract the first word of the first (and
    only) line of the shell output.

    Under DOS, SHELL is a command, not an operation; it sends its
    input to a DOS command processor but does not collect the result
    of the command.

    The Macintosh, of course, is not programmable.


FILE ACCESS
-----------

OPENREAD filename

    command.  Opens the named file for reading.  The read position is
    initially at the beginning of the file.

OPENWRITE filename

    command.  Opens the named file for writing.  If the file already
    existed, the old version is deleted and a new, empty file created.

OPENAPPEND filename

    command.  Opens the named file for writing.  If the file already
    exists, the write position is initially set to the end of the old
    file, so that newly written data will be appended to it.

OPENUPDATE filename

    command.  Opens the named file for reading and writing.  The read and
    write position is initially set to the end of the old file, if any.
    Note: each open file has only one position, for both reading and
    writing.  If a file opened for update is both READER and WRITER at
    the same time, then SETREADPOS will also affect WRITEPOS and vice
    versa.  Also, if you alternate reading and writing the same file,
    you must SETREADPOS between a write and a read, and SETWRITEPOS
    between a read and a write.

CLOSE filename

    command.  Closes the named file.

ALLOPEN

    outputs a list whose members are the names of all files currently open.
    This list does not include the dribble file, if any.

CLOSEALL                        (library procedure)

    command.  Closes all open files.  Abbreviates
    FOREACH ALLOPEN [CLOSE ?]

ERASEFILE filename
ERF filename

    command.  Erases (deletes, removes) the named file, which should not
    currently be open.

DRIBBLE filename

    command.  Creates a new file whose name is the input, like OPENWRITE,
    and begins recording in that file everything that is read from the
    keyboard or written to the terminal.  That is, this writing is in
    addition to the writing to WRITER.  The intent is to create a
    transcript of a Logo session, including things like prompt
    characters and interactions.

NODRIBBLE

    command.  Stops copying information into the dribble file, and
    closes the file.

SETREAD filename

    command.  Makes the named file the read stream, used for READLIST,
    etc.  The file must already be open with OPENREAD or OPENUPDATE.  If
    the input is the empty list, then the read stream becomes the
    terminal, as usual.  Changing the read stream does not close the
    file that was previously the read stream, so it is possible to
    alternate between files.

SETWRITE filename

    command.  Makes the named file the write stream, used for PRINT,
    etc.  The file must already be open with OPENWRITE, OPENAPPEND, or
    OPENUPDATE.  If the input is the empty list, then the write stream
    becomes the terminal, as usual.  Changing the write stream does not
    close the file that was previously the write stream, so it is
    possible to alternate between files.

READER

    outputs the name of the current read stream file, or the empty list
    if the read stream is the terminal.

WRITER

    outputs the name of the current write stream file, or the empty list
    if the write stream is the terminal.

SETREADPOS charpos

    command.  Sets the file pointer of the read stream file so that the
    next READLIST, etc., will begin reading at the "charpos"th character
    in the file, counting from 0.  (That is, SETREADPOS 0 will start
    reading from the beginning of the file.)  Meaningless if the read
    stream is the terminal.

SETWRITEPOS charpos

    command.  Sets the file pointer of the write stream file so that the
    next PRINT, etc., will begin writing at the "charpos"th character
    in the file, counting from 0.  (That is, SETWRITEPOS 0 will start
    writing from the beginning of the file.)  Meaningless if the write
    stream is the terminal.

READPOS

    outputs the file position of the current read stream file.

WRITEPOS

    outputs the file position of the current write stream file.

EOFP

    predicate, outputs TRUE if there are no more characters to be
    read in the read stream file, FALSE otherwise.


TERMINAL ACCESS
---------------

KEYP

    predicate, outputs TRUE if there are characters waiting to be
    read from the read stream.  If the read stream is a file, this
    is equivalent to NOT EOFP.  If the read stream is the terminal,
    then echoing is turned off and the terminal is set to CBREAK
    (character at a time instead of line at a time) mode.  It
    remains in this mode until some line-mode reading is requested
    (e.g., READLIST).  The Unix operating system forgets about any
    pending characters when it switches modes, so the first KEYP
    invocation will always output FALSE.

CLEARTEXT
CT

    command.  Clears the text screen of the terminal.

SETCURSOR vector

    command.  The input is a list of two numbers, the x and y
    coordinates of a screen position (origin in the upper left
    corner, positive direction is southeast).  The screen cursor
    is moved to the requested position.  This command also forces
    the immediate printing of any buffered characters.

CURSOR

    outputs a list containing the current x and y coordinates of
    the screen cursor.  Logo may get confused about the current
    cursor position if, e.g., you type in a long line that wraps
    around or your program prints escape codes that affect the
    terminal strangely.

SETMARGINS vector

    command.  The input must be a list of two numbers, as for
    SETCURSOR.  The effect is to clear the screen and then arrange for
    all further printing to be shifted down and to the right according
    to the indicated margins.  Specifically, every time a newline
    character is printed (explicitly or implicitly) Logo will type
    x_margin spaces, and on every invocation of SETCURSOR the margins
    will be added to the input x and y coordinates.  (CURSOR will report
    the cursor position relative to the margins, so that this shift will
    be invisible to Logo programs.)  The purpose of this command is to
    accommodate the display of terminal screens in lecture halls with
    inadequate TV monitors that miss the top and left edges of the
    screen.


ARITHMETIC
==========

NUMERIC OPERATIONS
------------------

SUM num1 num2
(SUM num1 num2 num3 ...)
num1 + num2

    outputs the sum of its inputs.

DIFFERENCE num1 num2
num1 - num2

    outputs the difference of its inputs.  Minus sign means infix
    difference in ambiguous contexts (when preceded by a complete
    expression), unless it is preceded by a space and followed
    by a nonspace.

MINUS num
- num

    outputs the negative of its input.  Minus sign means unary minus if
    it is immediately preceded by something requiring an input, or
    preceded by a space and followed by a nonspace.  There is a difference
    in binding strength between the two forms:

        MINUS 3 + 4    means    -(3+4)
        - 3 + 4        means    (-3)+4

PRODUCT num1 num2
(PRODUCT num1 num2 num3 ...)
num1 * num2

    outputs the product of its inputs.

QUOTIENT num1 num2
(QUOTIENT num)
num1 / num2

    outputs the quotient of its inputs.  The quotient of two integers
    is an integer if and only if the dividend is a multiple of the divisor.
    (In other words, QUOTIENT 5 2 is 2.5, not 2, but QUOTIENT 4 2 is
    2, not 2.0 -- it does the right thing.)  With a single input,
    QUOTIENT outputs the reciprocal of the input.

REMAINDER num1 num2

    outputs the remainder on dividing "num1" by "num2"; both must be
    integers and the result is an integer with the same sign as num2.

INT num

    outputs its input with fractional part removed, i.e., an integer
    with the same sign as the input, whose absolute value is the
    largest integer less than or equal to the absolute value of
    the input.

    Note:  Inside the computer numbers are represented in two different
    forms, one for integers and one for numbers with fractional parts.
    However, on most computers the largest number that can be represented
    in integer format is smaller than the largest integer that can be
    represented (even with exact precision) in floating-point (fraction)
    format.  The INT operation will always output a number whose value
    is mathematically an integer, but if its input is very large the output
    may not be in integer format.  In that case, operations like REMAINDER
    that require an integer input will not accept this number.

ROUND num

    outputs the nearest integer to the input.

SQRT num

    outputs the square root of the input, which must be nonnegative.

POWER num1 num2

    outputs "num1" to the "num2" power.  If num1 is negative, then
    num2 must be an integer.

EXP num

    outputs e (2.718281828+) to the input power.

LOG10 num

    outputs the common logarithm of the input.

LN num

    outputs the natural logarithm of the input.

SIN degrees

    outputs the sine of its input, which is taken in degrees.

RADSIN radians

    outputs the sine of its input, which is taken in radians.

COS degrees

    outputs the cosine of its input, which is taken in degrees.

RADCOS radians

    outputs the cosine of its input, which is taken in radians.

ARCTAN num
(ARCTAN x y)

    outputs the arctangent, in degrees, of its input.  With two
    inputs, outputs the arctangent of y/x, if x is nonzero, or
    90 or -90 depending on the sign of y, if x is zero.

RADARCTAN num
(RADARCTAN x y)

    outputs the arctangent, in radians, of its input.  With two
    inputs, outputs the arctangent of y/x, if x is nonzero, or
    pi/2 or -pi/2 depending on the sign of y, if x is zero.

    The expression 2*(RADARCTAN 0 1) can be used to get the
    value of pi.


PREDICATES
----------

LESSP num1 num2
num1 < num2

    outputs TRUE if its first input is strictly less than its second.

GREATERP num1 num2
num1 > num2

    outputs TRUE if its first input is strictly greater than its second.


RANDOM NUMBERS
--------------

RANDOM num

    outputs a random nonnegative integer less than its input, which
    must be an integer.

RERANDOM
(RERANDOM seed)

    command.  Makes the results of RANDOM reproducible.  Ordinarily
    the sequence of random numbers is different each time Logo is
    used.  If you need the same sequence of pseudo-random numbers
    repeatedly, e.g. to debug a program, say RERANDOM before the
    first invocation of RANDOM.  If you need more than one repeatable
    sequence, you can give RERANDOM an integer input; each possible
    input selects a unique sequence of numbers.


PRINT FORMATTING
----------------

FORM num width precision

    outputs a word containing a printable representation of "num",
    possibly preceded by spaces (and therefore not a number for
    purposes of performing arithmetic operations), with at least
    "width" characters, including exactly "precision" digits after
    the decimal point.  (If "precision" is 0 then there will be no
    decimal point in the output.)

    As a debugging feature, (FORM num -1 format) will print the
    floating point "num" according to the C printf "format", to allow

        to hex :num
        op form :num -1 "|%08X %08X|
        end

    to allow finding out the exact result of floating point operations.
    The precise format needed may be machine-dependent.


BITWISE OPERATIONS
------------------

BITAND num1 num2
(BITAND num1 num2 num3 ...)

    outputs the bitwise AND of its inputs, which must be integers.

BITOR num1 num2
(BITOR num1 num2 num3 ...)

    outputs the bitwise OR of its inputs, which must be integers.

BITXOR num1 num2
(BITXOR num1 num2 num3 ...)

    outputs the bitwise EXCLUSIVE OR of its inputs, which must be
    integers.

BITNOT num

    outputs the bitwise NOT of its input, which must be an integer.

ASHIFT num1 num2

    outputs "num1" arithmetic-shifted to the left by "num2" bits.
    If num2 is negative, the shift is to the right with sign
    extension.  The inputs must be integers.

LSHIFT num1 num2

    outputs "num1" logical-shifted to the left by "num2" bits.
    If num2 is negative, the shift is to the right with zero fill.
    The inputs must be integers.


LOGICAL OPERATIONS
==================

AND tf1 tf2
(AND tf1 tf2 tf3 ...)

    outputs TRUE if all inputs are TRUE, otherwise FALSE.  All inputs
    must be TRUE or FALSE.  (Comparison is case-insensitive regardless
    of the value of CASEIGNOREDP.  That is, "true" or "True" or "TRUE"
    are all the same.)

OR tf1 tf2
(OR tf1 tf2 tf3 ...)

    outputs TRUE if any input is TRUE, otherwise FALSE.  All inputs
    must be TRUE or FALSE.  (Comparison is case-insensitive regardless
    of the value of CASEIGNOREDP.  That is, "true" or "True" or "TRUE"
    are all the same.)

NOT tf

    outputs TRUE if the input is FALSE, and vice versa.


GRAPHICS
========

Berkeley Logo provides traditional Logo turtle graphics with one turtle.
Multiple turtles, dynamic turtles, and collision detection are not supported.
This is the most hardware-dependent part of Logo; some features may exist
on some machines but not others.  Nevertheless, the goal has been to make
Logo programs as portable as possible, rather than to take fullest advantage
of the capabilities of each machine.  In particular, Logo attempts to scale
the screen so that turtle coordinates [-100 -100] and [100 100] fit on the
graphics window, and so that the aspect ratio is 1:1, although some PC screens
have nonstandard aspect ratios.

The center of the graphics window (which may or may not be the entire
screen, depending on the machine used) is turtle location [0 0].  Positive
X is to the right; positive Y is up.  Headings (angles) are measured in
degrees clockwise from the positive Y axis.  (This differs from the common
mathematical convention of measuring angles counterclockwise from the
positive X axis.)  The turtle is represented as an isoceles triangle; the
actual turtle position is at the midpoint of the base (the short side).

Colors are, of course, hardware-dependent.  However, Logo provides partial
hardware independence by interpreting color numbers 0 through 7 uniformly
on all computers:

    0  black        4  red
    1  blue            5  magenta
    2  green        6  yellow
    3  cyan            7  white

Color numbers greater than 7 are interpreted by sending the value color-8
to the underlying graphics system.  Logo begins with a black background
and white pen.


TURTLE MOTION
-------------

FORWARD dist
FD dist

    moves the turtle forward, in the direction that it's facing, by
    the specified distance (measured in turtle steps).

BACK dist
BK dist

    moves the turtle backward, i.e., exactly opposite to the direction
    that it's facing, by the specified distance.  (The heading of the
    turtle does not change.)

LEFT degrees
LT degrees

    turns the turtle counterclockwise by the specified angle, measured
    in degrees (1/360 of a circle).

RIGHT degrees
RT degrees

    turns the turtle clockwise by the specified angle, measured in
    degrees (1/360 of a circle).

SETPOS pos

    moves the turtle to an absolute screen position.  The argument
    is a list of two numbers, the X and Y coordinates.

SETXY xcor ycor

    moves the turtle to an absolute screen position.  The two
    arguments are numbers, the X and Y coordinates.

SETX xcor

    moves the turtle horizontally from its old position to a new
    absolute horizontal coordinate.  The argument is the new X
    coordinate.

SETY ycor

    moves the turtle vertically from its old position to a new
    absolute vertical coordinate.  The argument is the new Y
    coordinate.

HOME

    moves the turtle to the center of the screen.  Equivalent to
    SETPOS [0 0].

SETHEADING degrees
SETH degrees

    turns the turtle to a new absolute heading.  The argument is
    a number, the heading in degrees clockwise from the positive
    Y axis.

ARC angle radius

    draws an arc of a circle, with the turtle at the center, with the
    specified radius, starting at the turtle's heading and extending
    clockwise through the specified angle.  The turtle does not move.

TURTLE MOTION QUERIES
---------------------

POS

    outputs the turtle's current position, as a list of two
    numbers, the X and Y coordinates.

XCOR                            (library procedure)

    outputs a number, the turtle's X coordinate.

YCOR                            (library procedure)

    outputs a number, the turtle's Y coordinate.

HEADING

    outputs a number, the turtle's heading in degrees.

TOWARDS pos

    outputs a number, the heading at which the turtle should be
    facing so that it would point from its current position to
    the position given as the argument.

SCRUNCH

    outputs a list containing two numbers, the X and Y scrunch
    factors, as used by SETSCRUNCH.  (But note that SETSCRUNCH
    takes two numbers as inputs, not one list of numbers.)


TURTLE AND WINDOW CONTROL
-------------------------

SHOWTURTLE
ST

    makes the turtle visible.

HIDETURTLE
HT

    makes the turtle invisible.  It's a good idea to do this while
    you're in the middle of a complicated drawing, because hiding
    the turtle speeds up the drawing substantially.

CLEAN

    erases all lines that the turtle has drawn on the graphics window.
    The turtle's state (position, heading, pen mode, etc.) is not
    changed.

CLEARSCREEN
CS

    erases the graphics window and sends the turtle to its initial
    position and heading.  Like HOME and CLEAN together.

WRAP

    tells the turtle to enter wrap mode:  From now on, if the turtle
    is asked to move past the boundary of the graphics window, it
    will "wrap around" and reappear at the opposite edge of the
    window.  The top edge wraps to the bottom edge, while the left
    edge wraps to the right edge.  (So the window is topologically
    equivalent to a torus.)  This is the turtle's initial mode.
    Compare WINDOW and FENCE.

WINDOW

    tells the turtle to enter window mode:  From now on, if the turtle
    is asked to move past the boundary of the graphics window, it
    will move offscreen.  The visible graphics window is considered
    as just part of an infinite graphics plane; the turtle can be
    anywhere on the plane.  (If you lose the turtle, HOME will bring
    it back to the center of the window.)  Compare WRAP and FENCE.

FENCE

    tells the turtle to enter fence mode:  From now on, if the turtle
    is asked to move past the boundary of the graphics window, it
    will move as far as it can and then stop at the edge with an
    "out of bounds" error message.  Compare WRAP and WINDOW.

FILL

    fills in a region of the graphics window containing the turtle
    and bounded by lines that have been drawn earlier.  This is not
    portable; it doesn't work for all machines, and may not work
    exactly the same way on different machines.

LABEL text

    takes a word or list as input, and prints the input on the
    graphics window, starting at the turtle's position.

TEXTSCREEN
TS

    rearranges the size and position of windows to maximize the
    space available in the text window (the window used for
    interaction with Logo).  The details differ among machines.
    Compare SPLITSCREEN and FULLSCREEN.

FULLSCREEN
FS

    rearranges the size and position of windows to maximize the space
    available in the graphics window.  The details differ among machines.
    Compare SPLITSCREEN and TEXTSCREEN.

    In the DOS version, switching from fullscreen to splitscreen loses
    the part of the picture that's hidden by the text window.  Also,
    since there must be a text window to allow printing (including the
    printing of the Logo prompt), Logo automatically switches from
    fullscreen to splitscreen whenever anything is printed.  [This design
    decision follows from the scarcity of memory, so that the extra memory
    to remember an invisible part of a drawing seems too expensive.]

SPLITSCREEN
SS

    rearranges the size and position of windows to allow some room for
    text interaction while also keeping most of the graphics window
    visible.  The details differ among machines.  Compare TEXTSCREEN
    and FULLSCREEN.

SETSCRUNCH xscale yscale

    adjusts the aspect ratio and scaling of the graphics display.
    After this command is used, all further turtle motion will be
    adjusted by multiplying the horizontal and vertical extent of
    the motion by the two numbers given as inputs.  For example,
    after the instruction "SETSCRUNCH 2 1" motion at a heading of
    45 degrees will move twice as far horizontally as vertically.
    If your squares don't come out square, try this.  (Alternatively,
    you can deliberately misadjust the aspect ratio to draw an ellipse.)

    For Unix machines and Macintoshes, both scale factors are initially 1.
    For DOS machines, the scale factors are initially set according to
    what the hardware claims the aspect ratio is, but the hardware
    sometimes lies.  In the UCBLOGO.EXE version, the values set by
    SETSCRUNCH are remembered in a file (called SCRUNCH.DAT) and are
    automatically put into effect when a Logo session begins.

REFRESH

    tells Logo to remember the turtle's motions so that they can be
    reconstructed in case the graphics window is overlayed.  The
    effectiveness of this command may depend on the machine used.

NOREFRESH

    tells Logo not to remember the turtle's motions.  This will make
    drawing faster, but prevents recovery if the window is overlayed.


TURTLE AND WINDOW QUERIES
-------------------------

SHOWNP

    outputs TRUE if the turtle is shown (visible), FALSE if the
    turtle is hidden.  See SHOWTURTLE and HIDETURTLE.

PEN AND BACKGROUND CONTROL
--------------------------

The turtle carries a pen that can draw pictures.  At any time the pen
can be UP (in which case moving the turtle does not change what's on the
graphics screen) or DOWN (in which case the turtle leaves a trace).
If the pen is down, it can operate in one of three modes: PAINT (so that it
draws lines when the turtle moves), ERASE (so that it erases any lines
that might have been drawn on or through that path earlier), or REVERSE
(so that it inverts the status of each point along the turtle's path).

PENDOWN
PD

    sets the pen's position to DOWN, without changing its mode.

PENUP
PU

    sets the pen's position to UP, without changing its mode.

PENPAINT
PPT

    sets the pen's position to DOWN and mode to PAINT.

PENERASE
PE

    sets the pen's position to DOWN and mode to ERASE.

PENREVERSE
PX

    sets the pen's position to DOWN and mode to REVERSE.
    (This may interact in hardware-dependent ways with use of color.)

SETPENCOLOR color
SETPC color
SETPENSIZE size
SETPENPATTERN pattern

    set hardware-dependent pen characteristics.  These commands are
    not guaranteed compatible between implementations on different
    machines.

SETPEN list                        (library procedure)

    sets the pen's position, mode, and hardware-dependent characteristics
    according to the information in the input list, which should be taken
    from an earlier invocation of PEN.

SETBACKGROUND color
SETBG color

    set the screen background color.


PEN QUERIES
-----------

PENDOWNP

    outputs TRUE if the pen is down, FALSE if it's up.

PENMODE

    outputs one of the words PAINT, ERASE, or REVERSE according to
    the current pen mode.

PENCOLOR
PENSIZE
PENPATTERN

    output hardware-specific pen information.

PEN                            (library procedure)

    outputs a list containing the pen's position, mode, and
    hardware-specific characteristics, for use by SETPEN.

BACKGROUND
BG

    outputs the graphics background color.



WORKSPACE MANAGEMENT
====================

PROCEDURE DEFINITION
--------------------

TO procname :input1 :input2 ...                (special form)

    command.  Prepares Logo to accept a procedure definition.  The
    procedure will be named "procname" and there must not already
    be a procedure by that name.  The inputs will be called "input1"
    etc.  Any number of inputs are allowed, including none.  Names
    of procedures and inputs are case-insensitive.

    Unlike 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.)

    This version of Logo allows variable numbers of inputs to a
    procedure.  Every procedure has a MINIMUM, DEFAULT, and MAXIMUM
    number of inputs.  (The latter can 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.  Example:

            to proc :inlist [:startvalue first :inlist]

    If the procedure is invoked by saying

            proc [a b c]

    then the variable INLIST will have the value [A B C] and the
    variable STARTVALUE will have the value A.  If the procedure
    is invoked by saying

            (proc [a b c] "x)

    then INLIST will have the value [A B C] and STARTVALUE will
    have 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 this input
    will be a list containing all of the actual inputs provided that
    were not used for required or optional inputs.  Example:

            to proc :in1 [:in2 "foo] [:in3]

    If this procedure is invoked by saying

            proc "x

    then IN1 has the value X, IN2 has the value FOO, and IN3 has
    the value [] (the empty list).  If it's invoked by saying

            (proc "a "b "c "d)

    then 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 will accept if 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.  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.

    Logo responds to the TO command by entering procedure definition
    mode.  The prompt character changes from "?" to ">" and whatever
    instructions you type become part of the definition until you
    type a line containing only the word END.

DEFINE procname text

    command.  Defines a procedure with name "procname" and text "text".
    If there is already a procedure with the same name, the new
    definition replaces the old one.  The text input must be a list
    whose members are lists.  The first member is a list of inputs;
    it looks like a TO line but without the word TO, without the
    procedure name, and without the colons before input names.  In
    other words, the members of this first sublist are words for
    the names of required inputs and lists for the names of optional
    or rest inputs.  The remaining sublists of the text input make
    up the body of the procedure, with one sublist for each instruction
    line of the body.  (There is no END line in the text input.)
    It is an error to redefine a primitive procedure unless the variable
    REDEFP has the value TRUE.

TEXT procname

    outputs the text of the procedure named "procname" in the form
    expected by DEFINE: a list of lists, the first of which describes
    the inputs to the procedure and the rest of which are the lines of
    its body.  The text does not reflect formatting information used
    when the procedure was defined, such as continuation lines and
    extra spaces.

FULLTEXT procname

    outputs a representation of the procedure "procname" in which
    formatting information is preserved.  If the procedure was defined
    with TO, EDIT, or LOAD, then the output is a list of words.  Each
    word represents one entire line of the definition in the form
    output by READWORD, including extra spaces and continuation lines.
    The last element of the output represents the END line.  If the
    procedure was defined with DEFINE, then the output is a list of
    lists.  If these lists are printed, one per line, the result will
    look like a definition using TO.  Note: the output from FULLTEXT
    is not suitable for use as input to DEFINE!

COPYDEF newname oldname

    command.  Makes "newname" a procedure identical to "oldname".
    The latter may be a primitive.  If "newname" was already defined,
    its previous definition is lost.  If "newname" was already a
    primitive, the redefinition is not permitted unless the variable
    REDEFP has the value TRUE.  Definitions created by COPYDEF are
    not saved by SAVE; primitives are never saved, and user-defined
    procedures created by COPYDEF are buried.  (You are likely to be
    confused if you PO or POT a procedure defined with COPYDEF because
    its title line will contain the old name.  This is why it's buried.)

    Note: dialects of Logo differ as to the order of inputs to COPYDEF.
    This dialect uses "MAKE order," not "NAME order."


VARIABLE DEFINITION
-------------------

MAKE varname value

    command.  Assigns the value "value" to the variable named "varname",
    which must be a word.  Variable names are case-insensitive.  If a
    variable with the same name already exists, the value of that
    variable is changed.  If not, a new global variable is created.

NAME value varname                    (library procedure)

    command.  Same as MAKE but with the inputs in reverse order.

LOCAL varname
LOCAL varnamelist
(LOCAL varname1 varname2 ...)

    command.  Accepts as inputs one or more words, or a list of
    words.  A variable is created for each of these words, with
    that word as its name.  The variables are local to the
    currently running procedure.  Logo variables follow dynamic
    scope rules; a variable that is local to a procedure is
    available to any subprocedure invoked by that procedure.
    The variables created by LOCAL have no initial value; they
    must be assigned a value (e.g., with MAKE) before the procedure
    attempts to read their value.

THING varname
:quoted.varname

    outputs the value of the variable whose name is the input.
    If there is more than one such variable, the innermost local
    variable of that name is chosen.  The colon notation is an
    abbreviation not for THING but for the combination

                thing "

    so that :FOO means THING "FOO.


PROPERTY LISTS
--------------

Note: Names of property lists are always case-insensitive.  Names of
individual properties are case-sensitive or case-insensitive depending
on the value of CASEIGNOREDP, which is TRUE by default.

PPROP plistname propname value

    command.  Adds a property to the "plistname" property list
    with name "propname" and value "value".

GPROP plistname propname

    outputs the value of the "propname" property in the "plistname"
    property list, or the empty list if there is no such property.

REMPROP plistname propname

    command.  Removes the property named "propname" from the
    property list named "plistname".

PLIST plistname

    outputs a list whose odd-numbered elements are the names, and
    whose even-numbered elements are the values, of the properties
    in the property list named "plistname".  The output is a copy
    of the actual property list; changing properties later will not
    magically change the list output by PLIST.


PREDICATES
----------

PROCEDUREP name

    outputs TRUE if the input is the name of a procedure.

PRIMITIVEP name

    outputs TRUE if the input is the name of a primitive procedure
    (one built into Logo).  Note that some of the procedures
    described in this document are library procedures, not primitives.

DEFINEDP name

    outputs TRUE if the input is the name of a user-defined procedure,
    including a library procedure.  (However, Logo does not know about
    a library procedure until that procedure has been invoked.)

NAMEP name

    outputs TRUE if the input is the name of a variable.


QUERIES
-------

CONTENTS

    outputs a "contents list," i.e., a list of three lists containing
    names of defined procedures, variables, and property lists
    respectively.  This list includes all unburied named items in
    the workspace.

BURIED

    outputs a contents list including all buried named items in
    the workspace.

PROCEDURES

    outputs a list of the names of all unburied user-defined procedures
    in the workspace.  Note that this is a list of names, not a
    contents list.  (However, procedures that require a contents list
    as input will accept this list.)

NAMES

    outputs a contents list consisting of an empty list (indicating
    no procedure names) followed by a list of all unburied variable
    names in the workspace.

PLISTS

    outputs a contents list consisting of two empty lists (indicating
    no procedures or variables) followed by a list of all unburied
    property lists in the workspace.

NAMELIST varname                    (library procedure)
NAMELIST varnamelist

    outputs a contents list consisting of an empty list followed by
    a list of the name or names given as input.  This is useful in
    conjunction with workspace control procedures that require a contents
    list as input.

PLLIST plname                        (library procedure)
PLLIST plnamelist

    outputs a contents list consisting of two empty lists followed by
    a list of the name or names given as input.  This is useful in
    conjunction with workspace control procedures that require a contents
    list as input.


Note:  All procedures whose input is indicated as "contentslist" will
accept a single word (taken as a procedure name), a list of words (taken
as names of procedures), or a list of three lists as described under
CONTENTS above.


INSPECTION
----------

PO contentslist

    command.  Prints to the write stream the definitions of all
    procedures, variables, and property lists named in the input
    contents list.

POALL                            (library procedure)

    command.  Prints all unburied definitions in the workspace.
    Abbreviates PO CONTENTS.

POPS                            (library procedure)

    command.  Prints the definitions of all unburied procedures in
    the workspace.  Abbreviates PO PROCEDURES.

PONS                            (library procedure)

    command.  Prints the definitions of all unburied variables in
    the workspace.  Abbreviates PO NAMES.

POPLS                            (library procedure)

    command.  Prints the contents of all unburied property lists in
    the workspace.  Abbreviates PO PLISTS.

PON varname                        (library procedure)
PON varnamelist

    command.  Prints the definitions of the named variable(s).
    Abbreviates PO NAMELIST varname(list).

POPL plname                        (library procedure)
POPL plnamelist

    command.  Prints the definitions of the named property list(s).
    Abbreviates PO PLLIST plname(list).

POT contentslist

    command.  Prints the title lines of the named procedures and
    the definitions of the named variables and property lists.
    For property lists, the entire list is shown on one line
    instead of as a series of PPROP instructions as in PO.

POTS                            (library procedure)

    command.  Prints the title lines of all unburied procedures
    in the workspace.  Abbreviates POT PROCEDURES.


WORKSPACE CONTROL
-----------------

ERASE contentslist
ER contentslist

    command.  Erases from the workspace the procedures, variables,
    and property lists named in the input.  Primitive procedures may
    not be erased unless the variable REDEFP has the value TRUE.

ERALL                            (library procedure)

    command.  Erases all unburied procedures, variables, and property
    lists from the workspace.  Abbreviates ERASE CONTENTS.

ERPS                            (library procedure)

    command.  Erases all unburied procedures from the workspace.
    Abbreviates ERASE PROCEDURES.

ERNS                            (library procedure)

    command.  Erases all unburied variables from the workspace.
    Abbreviates ERASE NAMES.

ERPLS                            (library procedure)

    command.  Erases all unburied property lists from the workspace.
    Abbreviates ERASE PLISTS.

ERN varname                        (library procedure)
ERN varnamelist

    command.  Erases from the workspace the variable(s) named in the
    input.  Abbreviates ERASE NAMELIST varname(list).

ERPL plname                        (library procedure)
ERPL plnamelist

    command.  Erases from the workspace the property list(s) named in the
    input.  Abbreviates ERASE PLLIST plname(list).

BURY contentslist

    command.  Buries the procedures, variables, and property lists
    named in the input.  A buried item is not included in the lists
    output by CONTENTS, PROCEDURES, VARIABLES, and PLISTS, but is
    included in the list output by BURIED.  By implication, buried
    things are not printed by POALL or saved by SAVE.

BURYALL                            (library procedure)

    command.  Abbreviates BURY CONTENTS.

BURYNAME varname                    (library procedure)
BURYNAME varnamelist

    command.  Abbreviates BURY NAMELIST varname(list).

UNBURY contentslist

    command.  Unburies the procedures, variables, and property lists
    named in the input.  That is, the named items will be returned to
    view in CONTENTS, etc.

UNBURYALL                        (library procedure)

    command.  Abbreviates UNBURY BURIED.

UNBURYNAME varname                    (library procedure)
UNBURYNAME varnamelist

    command.  Abbreviates UNBURY NAMELIST varname(list).

TRACE contentslist

    command.  Marks the named items for tracing.  A message is printed
    whenever a traced procedure is invoked, giving the actual input
    values, and whenever a traced procedure STOPs or OUTPUTs.  A
    message is printed whenever a new value is assigned to a traced
    variable using MAKE.  A message is printed whenever a new property
    is given to a traced property list using PPROP.

UNTRACE contentslist

    command.  Turns off tracing for the named items.

STEP contentslist

    command.  Marks the named items for stepping.  Whenever a stepped
    procedure is invoked, each instruction line in the procedure body
    is printed before being executed, and Logo waits for the user to
    type a newline at the terminal.  A message is printed whenever a
    stepped variable name is "shadowed" because a local variable of
    the same name is created either as a procedure input or by the
    LOCAL command.

UNSTEP contentslist

    command.  Turns off stepping for the named items.

EDIT contentslist
ED contentslist
(EDIT)
(ED)

    command.  Edits the definitions of the named items, using your
    favorite editor as determined by the EDITOR environment variable.
    If you don't have an EDITOR variable, edits the definitions using
    jove.  If invoked without an argument, EDIT edits the same
    temporary file left over from a previous EDIT instruction.
    When you leave the editor, Logo reads the revised definitions
    and modifies the workspace accordingly.

    Exceptionally, the EDIT command can be used without its default
    input and without parentheses provided that nothing follows it on
    the instruction line.

EDALL                            (library procedure)

    command.  Abbreviates EDIT CONTENTS.

EDPS                            (library procedure)

    command.  Abbreviates EDIT PROCEDURES.

EDNS                            (library procedure)

    command.  Abbreviates EDIT NAMES.

EDPLS                            (library procedure)

    command.  Abbreviates EDIT PLISTS.

EDN varname                        (library procedure)
EDN varnamelist

    command.  Abbreviates EDIT NAMELIST varname(list).

EDPL plname                        (library procedure)
EDPL plnamelist

    command.  Abbreviates EDIT PLLIST plname(list).

SAVE filename

    command.  Saves the definitions of all unburied procedures,
    variables, and property lists in the named file.  Equivalent to

            to save :filename
            local "oldwriter
            make "oldwriter writer
            openwrite :filename
            setwrite :filename
            poall
            setwrite :oldwriter
            close :filename
            end

SAVEL contentslist filename                (library procedure)

    command.  Saves the definitions of the procedures, variables, and
    property lists specified by "contentslist" to the file named
    "filename".

LOAD filename

    command.  Reads instructions from the named file and executes
    them.  The file can include procedure definitions with TO, and
    these are accepted even if a procedure by the same name already
    exists.  If the file assigns a list value to a variable named
    STARTUP, then that list is run as an instructionlist after the
    file is loaded.


CONTROL STRUCTURES
==================

Note: in the following descriptions, an "instructionlist" can be a list
or a word.  In the latter case, the word is parsed into list form before
it is run.  Thus, RUN READWORD or RUN READLIST will work.  The former is
slightly preferable because it allows for a continued line (with ~) that
includes a comment (with ;) on the first line.

RUN instructionlist

    command or operation.  Runs the Logo instructions in the input
    list; outputs if the list contains an expression that outputs.

RUNRESULT instructionlist

    runs the instructions in the input; outputs an empty list if
    those instructions produce no output, or a list whose only
    member is the output from running the input instructionlist.
    Useful for inventing command-or-operation control structures:

        local "result
        make "result runresult [something]
        if emptyp :result [stop]
        output first :result

REPEAT num instructionlist

    command.  Runs the "instructionlist" repeatedly, "num" times.

IF tf instructionlist
(IF tf instructionlist1 instructionlist2)

    command.  If the first input has the value TRUE, then IF runs
    the second input.  If the first input has the value FALSE, then
    IF does nothing.  (If given a third input, IF acts like IFELSE,
    as described below.)  It is an error if the first input is not
    either TRUE or FALSE.

    For compatibility with earlier versions of Logo, if an IF
    instruction is not enclosed in parentheses, but the first thing
    on the instruction line after the second input expression is a
    literal list (i.e., a list in square brackets), the IF is
    treated as if it were IFELSE, but a warning message is given.
    If this aberrant IF appears in a procedure body, the warning is
    given only the first time the procedure is invoked in each Logo
    session.

IFELSE tf instructionlist1 instructionlist2

    command or operation.  If the first input has the value TRUE, then
    IFELSE runs the second input.  If the first input has the value FALSE,
    then IFELSE runs the third input.  IFELSE outputs a value if the
    instructionlist contains an expression that outputs a value.

TEST tf

    command.  Remembers its input, which must be TRUE or FALSE, for use
    by later IFTRUE or IFFALSE instructions.  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.

IFTRUE instructionlist
IFT instructionlist

    command.  Runs its input if the most recent TEST instruction had
    a TRUE input.  The TEST must have been in the same procedure or a
    superprocedure.

IFFALSE instructionlist
IFF instructionlist

    command.  Runs its input if the most recent TEST instruction had
    a FALSE input.  The TEST must have been in the same procedure or a
    superprocedure.

STOP

    command.  Ends the running of the procedure in which it appears.
    Control is returned to the context in which that procedure was
    invoked.  The stopped procedure does not output a value.

OUTPUT value

    command.  Ends the running of the procedure in which it appears.
    That procedure outputs the value "value" to the context in which
    it was invoked.  Don't be confused: OUTPUT itself is a command,
    but the procedure that invokes OUTPUT is an operation.

CATCH tag instructionlist

    command or operation.  Runs its second input.  Outputs if that
    instructionlist outputs.  If, while running the instructionlist,
    a THROW instruction is executed with a tag equal to the first
    input (case-insensitive comparison), then the running of the
    instructionlist is terminated immediately.  In this case the CATCH
    outputs if a value input is given to THROW.  The tag must be a word.

    If the tag is the word ERROR, then any error condition that arises
    during the running of the instructionlist has the effect of THROW
    "ERROR instead of printing an error message and returning to
    toplevel.  The CATCH does not output if an error is caught.  Also,
    during the running of the instructionlist, the variable ERRACT is
    temporarily unbound.  (If there is an error while ERRACT has a
    value, that value is taken as an instructionlist to be run after
    printing the error message.  Typically the value of ERRACT, if any,
    is the list [PAUSE].)

THROW tag
(THROW tag value)

    command.  Must be used within the scope of a CATCH with an equal
    tag.  Ends the running of the instructionlist of the CATCH.  If
    THROW is used with only one input, the corresponding CATCH does
    not output a value.  If THROW is used with two inputs, the second
    provides an output for the CATCH.

    THROW "TOPLEVEL can be used to terminate all running procedures
    and interactive pauses, and return to the toplevel instruction
    prompt.  Typing the system interrupt character (normally ^C)
    has the same effect.

    THROW "ERROR can be used to generate an error condition.  If the
    error is not caught, it prints a message (THROW "ERROR) with the
    usual indication of where the error (in this case the THROW)
    occurred.  If a second input is used along with a tag of ERROR,
    that second input is used as the text of the error message
    instead of the standard message.  Also, in this case, the location
    indicated for the error will be, not the location of the THROW,
    but the location where the procedure containing the THROW was
    invoked.  This allows user-defined procedures to generate error
    messages as if they were primitives.  Note: in this case the
    corresponding CATCH "ERROR, if any, does not output, since the second
    input to THROW is not considered a return value.

    THROW "SYSTEM immediately leaves Logo, returning to the operating
    system, without printing the usual parting message and without
    deleting any editor temporary file written by EDIT.

ERROR

    outputs a list describing the error just caught, if any.  If there
    was not an error caught since the last use of ERROR, the empty list
    will be output.  The error list contains four members: an integer
    code corresponding to the type of error, the text of the error
    message, the name of the procedure in which the error occurred, and
    the instruction line on which the error occurred.

PAUSE

    command or operation.  Enters an interactive pause.  The user is
    prompted for instructions, as at toplevel, but with a prompt that
    includes the name of the procedure in which PAUSE was invoked.
    Local variables of that procedure are available during the pause.
    PAUSE outputs if the pause is ended by a CONTINUE with an input.

    If the variable ERRACT exists, and an error condition occurs, the
    contents of that variable are run as an instructionlist.  Typically
    ERRACT is given the value [PAUSE] so that an interactive pause will
    be entered on the event of an error.  This allows the user to check
    values of local variables at the time of the error.

    Typing the system quit character (normally ^\) will also enter
    a pause.

CONTINUE value
CO value
(CONTINUE)
(CO)

    command.  Ends the current interactive pause, returning to the
    context of the PAUSE invocation that began it.  If CONTINUE is
    given an input, that value is used as the output from the PAUSE.
    If not, the PAUSE does not output.

    Exceptionally, the CONTINUE command can be used without its default
    input and without parentheses provided that nothing follows it on
    the instruction line.

WAIT time

    command.  Delays further execution for "time" 60ths of a second.
    Also causes any buffered characters destined for the terminal to
    be printed immediately.  WAIT 0 can be used to achieve this
    buffer flushing without actually waiting.

BYE

    command.  Exits from Logo; returns to the operating system.

.MAYBEOUTPUT value                    (special form)

    works like OUTPUT except that the expression that provides the
    input value might not, in fact, output a value, in which case
    the effect is like STOP.  This is intended for use in control
    structure definitions, for cases in which you don't know whether
    or not some expression produces a value.  Example:

        to invoke :function [:inputs] 2
        .maybeoutput apply :function :inputs
        end

        ? (invoke "print "a "b "c)
        a b c
        ? print (invoke "word "a "b "c)
        abc

    This is an alternative to RUNRESULT.  It's fast and easy to use,
    at the cost of being an exception to Logo's evaluation rules.
    (Ordinarily, it should be an error if the expression that's
    supposed to provide an input to something doesn't have a value.)

IGNORE value                        (library procedure)

    command.  Does nothing.  Used when an expression is evaluated for
    a side effect and its actual value is unimportant.

` list                            (library procedure)

    outputs a list equal to its input but with certain substitutions.
    If a member of the input list is the word "," (comma) then the
    following member should be an instructionlist that produces an
    output when run.  That output value replaces the comma and the
    instructionlist.  If a member of the input list is the word ",@"
    (comma atsign) then the following member should be an instructionlist
    that outputs a list when run.  The members of that list replace the
    ,@ and the instructionlist.  Example:

        show `[foo baz ,[bf [a b c]] garply ,@[bf [a b c]]]

    will print

        [foo baz [b c] garply b c]

FOR forcontrol instructionlist                (library procedure)

    command.  The first input must be a list containing three or four
    members: (1) a word, which will be used as the name of a local
    variable; (2) a word or list that will be evaluated as by RUN to
    determine a number, the starting value of the variable; (3) a word
    or list that will be evaluated to determine a number, the limit value
    of the variable; (4) an optional word or list that will be evaluated
    to determine the step size.  If the fourth element is missing, the
    step size will be 1 or -1 depending on whether the limit value is
    greater than or less than the starting value, respectively.

    The second input is an instructionlist.  The effect of FOR is to run
    that instructionlist repeatedly, assigning a new value to the control
    variable (the one named by the first element of the forcontrol list)
    each time.  First the starting value is assigned to the control
    variable.  Then the value is compared to the limit value.  FOR is
    complete when the sign of (current - limit) is the same as the sign
    of the step size.  (If no explicit step size is provided, the
    instructionlist is always run at least once.  An explicit step size
    can lead to a zero-trip FOR, e.g., FOR [I 1 0 1] ...)  Otherwise, the
    instructionlist is run, then the step is added to the current value
    of the control variable and FOR returns to the comparison step.

        ? for [i 2 7 1.5] [print :i]
        2
        3.5
        5
        6.5
        ?

DO.WHILE instructionlist tfexpression            (library procedure)

    command.  Repeatedly evaluates the "instructionlist" as long as the
    evaluated "tfexpression" remains TRUE.  Evaluates the first input
    first, so the "instructionlist" is always run at least once.  The
    "tfexpression" must be an expressionlist whose value when evaluated
    is TRUE or FALSE.

WHILE tfexpression instructionlist            (library procedure)

    command.  Repeatedly evaluates the "instructionlist" as long as the
    evaluated "tfexpression" remains TRUE.  Evaluates the first input
    first, so the "instructionlist" may never be run at all.  The
    "tfexpression" must be an expressionlist whose value when evaluated
    is TRUE or FALSE.

DO.UNTIL instructionlist tfexpression            (library procedure)

    command.  Repeatedly evaluates the "instructionlist" as long as the
    evaluated "tfexpression" remains FALSE.  Evaluates the first input
    first, so the "instructionlist" is always run at least once.  The
    "tfexpression" must be an expressionlist whose value when evaluated
    is TRUE or FALSE.

UNTIL tfexpression instructionlist            (library procedure)

    command.  Repeatedly evaluates the "instructionlist" as long as the
    evaluated "tfexpression" remains FALSE.  Evaluates the first input
    first, so the "instructionlist" may never be run at all.  The
    "tfexpression" must be an expressionlist whose value when evaluated
    is TRUE or FALSE.


TEMPLATE-BASED ITERATION
------------------------

The procedures in this section are iteration tools based on the idea of a
"template."  This is a generalization of an instruction list or an
expression list in which "slots" are provided for the tool to insert varying
data.  Three different forms of template can be used.

The most commonly used form for a template is "explicit-slot" form, or
"question mark" form.  Example:

    ? show map [? * ?] [2 3 4 5]
    [4 9 16 25]
    ?

In this example, the MAP tool evaluated the template [? * ?] repeatedly,
with each of the members of the data list [2 3 4 5] substituted in turn
for the question marks.  The same value was used for every question mark
in a given evaluation.  Some tools allow for more than one datum to be
substituted in parallel; in these cases the slots are indicated by ?1 for
the first datum, ?2 for the second, and so on:

    ? show (map [word ?1 ?2 ?1] [a b c] [d e f])
    [ada beb cfc]
    ?

If the template wishes to compute the datum number, the form (? 1) is
equivalent to ?1, so (? ?1) means the datum whose number is given in
datum number 1.  Some tools allow additional slot designations, as shown
in the individual descriptions.

The second form of template is the "named-procedure" form.  If the template
is a word rather than a list, it is taken as the name of a procedure.  That
procedure must accept a number of inputs equal to the number of parallel
data slots provided by the tool; the procedure is applied to all of the
available data in order.  That is, if data ?1 through ?3 are available,
the template "PROC is equivalent to [PROC ?1 ?2 ?3].

    ? show (map "word [a b c] [d e f])
    [ad be cf]
    ?

    to dotprod :a :b    ; vector dot product
    op apply "sum (map "product :a :b)
    end

The third form of template is "named-slot" or "lambda" form.  This form is
indicated by a template list containing more than one element, whose first
element is itself a list.  The first element is taken as a list of names;
local variables are created with those names and given the available data
in order as their values.  The number of names must equal the number of
available data.  This form is needed primarily when one iteration tool must
be used within the template list of another, and the ? notation would be
ambiguous in the inner template.  Example:

    to matmul :m1 :m2 [:tm2 transpose :m2]    ; multiply two matrices
    output map [[row] map [[col] dotprod :row :col] :tm2] :m1
    end

These iteration tools are extended versions of the ones in Appendix B of the
book _Computer_Science_Logo_Style,_Volume_3:_Advanced_Topics_ by Brian
Harvey [MIT Press, 1987].  The extensions are primarily to allow for variable
numbers of inputs.


APPLY template inputlist

    command or operation.  Runs the "template," filling its slots with
    the members of "inputlist."  The number of members in "inputlist"
    must be an acceptable number of slots for "template."  It is
    illegal to apply the primitive TO as a template, but anything else
    is okay.  APPLY outputs what "template" outputs, if anything.

INVOKE template input                    (library procedure)
(INVOKE template input1 input2 ...)

    command or operation.  Exactly like APPLY except that the inputs
    are provided as separate expressions rather than in a list.

FOREACH data template                    (library procedure)
(FOREACH data1 data2 ... template)

    command.  Evaluates the template list repeatedly, once for each
    element of the data list.  If more than one data list are given,
    each of them must be the same length.  (The data inputs can be
    words, in which case the template is evaluated once for each
    character.

    In a template, the symbol ?REST represents the portion of the
    data input to the right of the member currently being used as
    the ? slot-filler.  That is, if the data input is [A B C D E]
    and the template is being evaluated with ? replaced by B, then
    ?REST would be replaced by [C D E].  If multiple parallel slots
    are used, then (?REST 1) goes with ?1, etc.

    In a template, the symbol # represents the position in the data
    input of the member currently being used as the ? slot-filler.
    That is, if the data input is [A B C D E] and the template is
    being evaluated with ? replaced by B, then # would be replaced
    by 2.

MAP template data                    (library procedure)
(MAP template data1 data2 ...)

    outputs a word or list, depending on the type of the data input,
    of the same length as that data input.  (If more than one data
    input are given, the output is of the same type as data1.)  Each
    element of the output is the result of evaluating the template
    list, filling the slots with the corresponding element(s) of the
    data input(s).  (All data inputs must be the same length.)  In the
    case of a word output, the results of the template evaluation must
    be words, and they are concatenated with WORD.

    In a template, the symbol ?REST represents the portion of the
    data input to the right of the member currently being used as
    the ? slot-filler.  That is, if the data input is [A B C D E]
    and the template is being evaluated with ? replaced by B, then
    ?REST would be replaced by [C D E].  If multiple parallel slots
    are used, then (?REST 1) goes with ?1, etc.

    In a template, the symbol # represents the position in the data
    input of the member currently being used as the ? slot-filler.
    That is, if the data input is [A B C D E] and the template is
    being evaluated with ? replaced by B, then # would be replaced
    by 2.

MAP.SE template data                    (library procedure)
(MAP.SE template data1 data2 ...)

    outputs a list formed by evaluating the template list repeatedly
    and concatenating the results using SENTENCE.  That is, the
    members of the output are the members of the results of the
    evaluations.  The output list might, therefore, be of a different
    length from that of the data input(s).  (If the result of an
    evaluation is the empty list, it contributes nothing to the final
    output.)  The data inputs may be words or lists.

    In a template, the symbol ?REST represents the portion of the
    data input to the right of the member currently being used as
    the ? slot-filler.  That is, if the data input is [A B C D E]
    and the template is being evaluated with ? replaced by B, then
    ?REST would be replaced by [C D E].  If multiple parallel slots
    are used, then (?REST 1) goes with ?1, etc.

    In a template, the symbol # represents the position in the data
    input of the member currently being used as the ? slot-filler.
    That is, if the data input is [A B C D E] and the template is
    being evaluated with ? replaced by B, then # would be replaced
    by 2.

FILTER tftemplate data                    (library procedure)

    outputs a word or list, depending on the type of the data input,
    containing a subset of the members (for a list) or characters (for
    a word) of the input.  The template is evaluated once for each
    member or character of the data, and it must produce a TRUE or
    FALSE value.  If the value is TRUE, then the corresponding input
    constituent is included in the output.

        ? print filter "vowelp "elephant
        eea
        ?

    In a template, the symbol ?REST represents the portion of the
    data input to the right of the member currently being used as
    the ? slot-filler.  That is, if the data input is [A B C D E]
    and the template is being evaluated with ? replaced by B, then
    ?REST would be replaced by [C D E].

    In a template, the symbol # represents the position in the data
    input of the member currently being used as the ? slot-filler.
    That is, if the data input is [A B C D E] and the template is
    being evaluated with ? replaced by B, then # would be replaced
    by 2.

FIND tftemplate data                    (library procedure)

    outputs the first constituent of the data input (the first member
    of a list, or the first character of a word) for which the value
    produced by evaluating the template with that consituent in its
    slot is TRUE.  If there is no such constituent, the empty list
    is output.

    In a template, the symbol ?REST represents the portion of the
    data input to the right of the member currently being used as
    the ? slot-filler.  That is, if the data input is [A B C D E]
    and the template is being evaluated with ? replaced by B, then
    ?REST would be replaced by [C D E].

    In a template, the symbol # represents the position in the data
    input of the member currently being used as the ? slot-filler.
    That is, if the data input is [A B C D E] and the template is
    being evaluated with ? replaced by B, then # would be replaced
    by 2.

REDUCE template data                    (library procedure)

    outputs the result of applying the template to accumulate the
    elements of the data input.  The template must be a two-slot
    function.  Typically it is an associative function name like "SUM.
    If the data input has only one constituent (member in a list or
    character in a word), the output is that consituent.  Otherwise,
    the template is first applied with ?1 filled with the next-to-last
    consitient and ?2 with the last constituent.  Then, if there are
    more constituents, the template is applied with ?1 filled with the
    next constituent to the left and ?2 with the result from the
    previous evaluation.  This process continues until all constituents
    have been used.  The data input may not be empty.

    Note: If the template is, like SUM, the name of a procedure that is
    capable of accepting arbitrarily many inputs, it is more efficient
    to use APPLY instead of REDUCE.  The latter is good for associative
    procedures that have been written to accept exactly two inputs:

        to max :a :b
        output ifelse :a > :b [:a] [:b]
        end

        print reduce "max [...]

    Alternatively, REDUCE can be used to write MAX as a procedure
    that accepts any number of inputs, as SUM does:

        to max [:inputs] 2
        if emptyp :inputs ~
           [(throw "error [not enough inputs to max])]
        output reduce [ifelse ?1 > ?2 [?1] [?2]] :inputs
        end

CROSSMAP template listlist                (library procedure)
(CROSSMAP template data1 data2 ...)

    outputs a list containing the results of template evaluations.
    Each data list contributes to a slot in the template; the number
    of slots is equal to the number of data list inputs.  As a special
    case, if only one data list input is given, that list is taken as
    a list of data lists, and each of its members contributes values
    to a slot.  CROSSMAP differs from MAP in that instead of taking
    members from the data inputs in parallel, it takes all possible
    combinations of members of data inputs, which need not be the same
    length.

        ? show (crossmap [word ?1 ?2] [a b c] [1 2 3 4])
        [a1 a2 a3 a4 b1 b2 b3 b4 c1 c2 c3 c4]
        ?

    For compatibility with the version in CSLS, CROSSMAP templates
    may use the notation :1 instead of ?1 to indicate slots.

CASCADE endtest template startvalue            (library procedure)
(CASCADE endtest tmp1 sv1 tmp2 sv2 ...)
(CASCADE endtest tmp1 sv1 tmp2 sv2 ... finaltemplate)

    outputs the result of applying a template (or several templates,
    as explained below) repeatedly, with a given value filling the
    slot the first time, and the result of each application filling
    the slot for the following application.

    In the simplest case, CASCADE has three inputs.  The second input
    is a one-slot expression template.  That template is evaluated
    some number of times (perhaps zero).  On the first evaluation,
    the slot is filled with the third input; on subsequent evaluations,
    the slot is filled with the result of the previous evaluation.
    The number of evaluations is determined by the first input.  This
    can be either a nonnegative integer, in which case the template is
    evaluated that many times, or a predicate expression template, in
    which case it is evaluated (with the same slot filler that will be
    used for the evaluation of the second input) repeatedly, and the
    CASCADE evaluation continues as long as the predicate value is
    FALSE.  (In other words, the predicate template indicates the
    condition for stopping.)

    If the template is evaluated zero times, the output from CASCADE
    is the third (startvalue) input.  Otherwise, the output is the
    value produced by the last template evaluation.

    CASCADE templates may include the symbol # to represent the number
    of times the template has been evaluated.  This slot is filled with
    1 for the first evaluation, 2 for the second, and so on.

        ? show cascade 5 [lput # ?] []
        [1 2 3 4 5]
        ? show cascade [vowelp first ?] [bf ?] "spring
        ing
        ? show cascade 5 [# * ?] 1
        120
        ?

    Several cascaded results can be computed in parallel by providing
    additional template-startvalue pairs as inputs to CASCADE.  In this
    case, all templates (including the endtest template, if used) are
    multi-slot, with the number of slots equal to the number of pairs of
    inputs.  In each round of evaluations, ?2 represents the result of
    evaluating the second template in the previous round.  If the total
    number of inputs (including the first endtest input) is odd, then
    the output from CASCADE is the final value of the first template.
    If the total number of inputs is even, then the last input is a
    template that is evaluated once, after the end test is satisfied,
    to determine the output from CASCADE.

        to fibonacci :n
        output (cascade :n [?1 + ?2] 1 [?1] 0)
        end

        to piglatin :word
        output (cascade [vowelp first ?] ~
                [word bf ? first ?] ~
                :word ~
                [word ? "ay])
        end

CASCADE.2 endtest temp1 startval1 temp2 startval2    (library procedure)

    outputs the result of invoking CASCADE with the same inputs.
    The only difference is that the default number of inputs is
    five instead of three.

TRANSFER endtest template inbasket            (library procedure)

    outputs the result of repeated evaluation of the template.
    The template is evaluated once for each member of the list
    "inbasket."  TRANSFER maintains an "outbasket" that is
    initially the empty list.  After each evaluation of the
    template, the resulting value becomes the new outbasket.

    In the template, the symbol ?IN represents the current element
    from the inbasket; the symbol ?OUT represents the entire
    current outbasket.  Other slot symbols should not be used.

    If the first (endtest) input is an empty list, evaluation
    continues until all inbasket members have been used.  If not,
    the first input must be a predicate expression template, and
    evaluation continues until either that template's value is TRUE
    or the inbasket is used up.


MACROS
======

.MACRO procname :input1 :input2 ...                (special form)
.DEFMACRO procname text
MACROP name

    A macro is a special kind of procedure whose output is evaluated
    as Logo instructions in the context of the macro's caller.
    .MACRO is exactly like TO except that the new procedure becomes
    a macro; .DEFMACRO is exactly like DEFINE with the same exception.
    MACROP returns TRUE if its input is the name of a macro.

    Macros are useful for inventing new control structures comparable
    to REPEAT, IF, and so on.  Such control structures can almost, but
    not quite, be duplicated by ordinary Logo procedures.  For example,
    here is an ordinary procedure version of REPEAT:

        to my.repeat :num :instructions
        if :num=0 [stop]
        run :instructions
        my.repeat :num-1 :instructions
        end

    This version works fine for most purposes, e.g.,

        my.repeat 5 [print "hello]

    But it doesn't work if the instructions to be carried out include
    OUTPUT, STOP, or LOCAL.  For example, consider this procedure:

        to example
        print [Guess my secret word.  You get three guesses.]
        repeat 3 [type "|?? | ~
              if readword = "secret [pr "Right! stop]]
        print [Sorry, the word was "secret"!]
        end

    This procedure works as written, but if MY.REPEAT is used instead
    of REPEAT, it won't work because the STOP will stop MY.REPEAT
    instead of stopping EXAMPLE as desired.

    The solution is to make MY.REPEAT a macro.  Instead of actually
    carrying out the computation, a macro must return a list containing
    Logo instructions.  The contents of that list are evaluated as if
    they appeared in place of the call to the macro.  Here's a macro
    version of REPEAT:

        .macro my.repeat :num :instructions
        if :num=0 [output []]
        output sentence :instructions ~
                (list "my.repeat :num-1 :instructions)
        end

    Every macro is an operation -- it must always output something.
    Even in the base case, MY.REPEAT outputs an empty instruction
    list.  To show how MY.REPEAT works, let's take the example

        my.repeat 5 [print "hello]

    For this example, MY.REPEAT will output the instruction list

        [print "hello my.repeat 4 [print "hello]]

    Logo then executes these instructions in place of the original
    invocation of MY.REPEAT; this prints "hello" once and invokes
    another repetition.

    The technique just shown, although fairly easy to understand,
    has the defect of slowness because each repetition has to
    construct an instruction list for evaluation.  Another approach
    is to make my.repeat a macro that works just like the non-macro
    version unless the instructions to be repeated include OUTPUT
    or STOP:

        .macro my.repeat :num :instructions
        catch "repeat.catchtag ~
              [op repeat.done runresult [repeat1 :num :instructions]]
        op []
        end

        to repeat1 :num :instructions
        if :num=0 [throw "repeat.catchtag]
        run :instructions
        .maybeoutput repeat1 :num-1 :instructions
        end

        to repeat.done :repeat.result
        if emptyp :repeat.result [op [stop]]
        op list "output quoted first :repeat.result
        end

    If the instructions do not include STOP or OUTPUT, then REPEAT1 will
    reach its base case and invoke THROW.  As a result, my.repeat's last
    instruction line will output an empty list, so the second evaluation
    of the macro result will do nothing.  But if a STOP or OUTPUT happens,
    then REPEAT.DONE will output a STOP or OUTPUT instruction that will
    be re-executed in the caller's context.

    The macro-defining commands have names starting with a dot because
    macros are an advanced feature of Logo; it's easy to get in trouble
    by defining a macro that doesn't terminate, or by failing to
    construct the instruction list properly.

    Lisp users should note that Logo macros are NOT special forms.
    That is, the inputs to the macro are evaluated normally, as they
    would be for any other Logo procedure.  It's only the output from
    the macro that's handled unusually.

    Here's another example:

        .macro localmake :name :value
        output (list "local        ~
                 word "" :name    ~
                 "apply        ~
                 ""make        ~
                 (list :name :value))
        end

    It's used this way:

        to try
        localmake "garply "hello
        print :garply
        end

    LOCALMAKE outputs the list

        [local "garply apply "make [garply hello]]

    The reason for the use of APPLY is to avoid having to decide
    whether or not the second input to MAKE requires a quotation
    mark before it.  (In this case it would -- MAKE "GARPLY "HELLO --
    but the quotation mark would be wrong if the value were a list.)

    It's often convenient to use the ` function to construct the
    instruction list:

        .macro localmake :name :value
        op `[local ,[word "" :name] apply "make [,[:name] ,[:value]]]
        end

    On the other hand, ` is pretty slow, since it's tree recursive and
    written in Logo.


ERROR PROCESSING
================

If an error occurs, Logo takes the following steps.  First, if there is
an available variable named ERRACT, Logo takes its value as an instructionlist
and runs the instructions.  The operation ERROR may be used within the
instructions (once) to examine the error condition.  If the instructionlist
invokes PAUSE, the error message is printed before the pause happens.
Certain errors are "recoverable"; for one of those errors, if the
instructionlist outputs a value, that value is used in place of the
expression that caused the error.  (If ERRACT invokes PAUSE and the user then
invokes CONTINUE with an input, that input becomes the output from PAUSE and
therefore the output from the ERRACT instructionlist.)

It is possible for an ERRACT instructionlist to produce an inappropriate value
or no value where one is needed.  As a result, the same error condition could
recur forever because of this mechanism.  To avoid that danger, if the same
error condition occurs twice in a row from an ERRACT instructionlist without
user interaction, the message "Erract loop" is printed and control returns
to toplevel.  "Without user interaction" means that if ERRACT invokes PAUSE and
the user provides an incorrect value, this loop prevention mechanism does not
take effect and the user gets to try again.

During the running of the ERRACT instructionlist, ERRACT is locally unbound,
so an error in the ERRACT instructions themselves will not cause a loop.  In
particular, an error during a pause will not cause a pause-within-a-pause
unless the user reassigns the value [PAUSE] to ERRACT during the pause.  But
such an error will not return to toplevel; it will remain within the original
pause loop.

If there is no available ERRACT value, Logo handles the error by generating
an internal THROW "ERROR.  (A user program can also generate an error
condition deliberately by invoking THROW.)  If this throw is not caught by
a CATCH "ERROR in the user program, it is eventually caught either by the
toplevel instruction loop or by a pause loop, which prints the error message.
An invocation of CATCH "ERROR in a user program locally unbinds ERRACT, so
the effect is that whichever of ERRACT and CATCH "ERROR is more local will
take precedence.

If a floating point overflow occurs during an arithmetic operation, or a
two-input mathematical function (like POWER) is invoked with an illegal
combination of inputs, the "doesn't like" message refers to the second
operand, but should be taken as meaning the combination.


ERROR CODES
-----------

Here are the numeric codes that appear as the first element of the list
output by ERROR when an error is caught, with the corresponding messages.
Some messages may have two different codes depending on whether or not
the error is recoverable (that is, a substitute value can be provided
through the ERRACT mechanism) in the specific context.  Some messages are
warnings rather than errors; these will not be caught.  The first two are
so bad that Logo exits immediately.

  0    Fatal internal error (can't be caught)
  1    Out of memory (can't be caught)
  2    PROC doesn't like DATUM as input (not recoverable)
  3    PROC didn't output to PROC
  4    Not enough inputs to PROC
  5    PROC doesn't like DATUM as input (recoverable)
  6    Too much inside ()'s
  7    I don't know what to do with DATUM
  8    ')' not found
  9    VAR has no value
 10    Unexpected ')'
 11    I don't know how to PROC (recoverable)
 12    Can't find catch tag for THROWTAG
 13    PROC is already defined
 14    Stopped
 15    Already dribbling
 16    File system error
 17    Assuming you mean IFELSE, not IF (warning only)
 18    VAR shadowed by local in procedure call (warning only)
 19    Throw "Error
 20    PROC is a primitive
 21    Can't use TO inside a procedure
 22    I don't know how to PROC (not recoverable)
 23    IFTRUE/IFFALSE without TEST
 24    Unexpected ']'
 25    Unexpected '}'
 26    Couldn't initialize graphics
 27    Macro returned VALUE instead of a list
 28    I don't know what to do with VALUE
 29    Can only use STOP or OUTPUT inside a procedure

SPECIAL VARIABLES
=================

Logo takes special action if any of the following variable names exists.
They follow the normal scoping rules, so a procedure can locally set one
of them to limit the scope of its effect.  Initially, no variables exist
except CASEIGNOREDP, which is TRUE and buried.

CASEIGNOREDP

    if TRUE, indicates that lower case and upper case letters should be
    considered equal by EQUALP, BEFOREP, MEMBERP, etc.  Logo initially
    makes this variable TRUE, and buries it.

ERRACT

    an instructionlist that will be run in the event of an error.
    Typically has the value [PAUSE] to allow interactive debugging.

PRINTDEPTHLIMIT

    if a nonnegative integer, indicates the maximum depth of sublist
    structure that will be printed by PRINT, etc.

PRINTWIDTHLIMIT

    if a nonnegative integer, indicates the maximum number of elements
    in any one list that will be printed by PRINT, etc.

REDEFP

    if TRUE, allows primitives to be erased (ERASE) or redefined (COPYDEF).

STARTUP

    if assigned a list value in a file loaded by LOAD, that value is
    run as an instructionlist after the loading.