
Command Reference
Working with Data
Put data together
Access data
Test data or data contents
Create and manipulate arrays
Structured contents lists
Read, write, and print data
Working with Properties
Put data together
Access data
Test data or data contents
Create and manipulate arrays
Structured contents lists
Read, write, and print data
Working with Properties
Read and write data.
This section contains all commands that input or output data. The most used command
is probably the PRINT
command. Other commands work with files, or directories.
All I/O goes through streams or channels. A channel has a number, which is used to
reference the channel when doing I/O. The Listener stream has the channel number 0,
and the Output output stream has the channel number 1. The OPEN
command opens
a file, and returns a channel number which can be used in
subsequent I/O.
The :STANDARD.INPUT
and :STANDARD.OUTPUT
variables contain the channel number
that Logo uses for I/O. Usually, this is the channel number 0, which is the Listener channel.
You can use the OPEN
command to obtain a channel number to a file, and assign that
channel number to above variables to make all I/O commands work with that file. Also, many
I/O commands accept a channel number as an additional, optional input, so you can use I/O
commands for multiple channels if you wish.
Displays an alert box.
ALERT message (ALERT message button1) (ALERT message button1 button2) (ALERT message button1 button2 button3)
ALERT pops up a small message window and displays the text given as its input. It accepts up to three optional inputs which are used as the labels for up to three buttons. ALERT displays one button labeled “OK” as default. The output of ALERT is the label of the clicked button. ALERT attempts to translate the displayed button labels to the current language, but always returns the original button labels.
If the message contains an exclamation mark or a question mark, the format of the message changes to display a question or an error.
ALERT "|Please click me!| Result: OK (ALERT [DO YOU WANT SUGAR AND MILK?] "YES "NO) Result: NO (ALERT [DO YOU WANT SUGAR OR MILK?] "SUGAR "MILK "NOTHING) Result: MILK
Clears all input from a stream.
CLEARINPUT (CLEARINPUT channel)
CLEARINPUT clears all input from the current input stream. Any further attempt to read
from that stream will result in a Logo error. For the Listener, CLEARINPUT has no effect.
A channel number may be entered as an optional input. If present, CLEARINPUT clears that
channel instead of the input stream. This makes it unnecessary to switch among multiple
input streams by changing the value of :STANDARD.INPUT
. CLEARINPUT is most convenient
for serial communication channels and the keyboard.
Closes a stream.
CLOSE channel (CLOSE)
CLOSE concludes any pending operations with the stream number specified and releases
the stream for reuse. CLOSE is necessary for all file output operations, since data
is automatically buffered in memory and not sent to the disk drive until a large
quantity is ready to go. If an output stream is not closed, you may lose data.
If CLOSE is used without any inputs, all open data streams are closed and I/O will
revert to the Listener. See also OPEN
and CREATE
.
Creates a file.
CREATE filename
CREATE first deletes an existing file with the name specified by its input if it exists.
A new, empty file is prepared for output. The output of CREATE is a channel number which
may be assigned to the built-in variable :STANDARD.OUTPUT
. Data may then be written
to the stream using the PRINT
, TYPE
and other Logo stream output primitives.
CREATE file is equivalent to OPEN
FILE “W.
Creates a folder.
CREATE.DIR foldername
CREATE.DIR uses its input to create a path to a folder. The input may contain multiple path entries; if the path does not exist, it is created. Use SETCURDIR
to set the current folder to the newly created folder.
Reports the current working directory.
CURDIR
CURDIR reports the user's working directory. On startup, this directory is set to the
user's data directory. Use SETCURDIR
to change the working directory.
See also :DATADIR
.
Deletes one or more files from disk.
DELETE filename
DELETE removes the file specified by its input from the disk. The instruction DELETE ”????.LGO erases all files with four-character names with the file extension .LGO. The instruction DELETE “*.LGO erases all files with names of any length with the file extension .LGO. Logo tries to move the file to the Recycle Bin. Warning: Use caution when deleting files. Items in the Recycle Bin can be restored but there is no guarantee that DELETE will put them there.
Lists the contents of current working directory.
DIRECTORY (DIRECTORY pattern)
DIRECTORY reports a list of file names in the current working directory. If DIRECTORY is used with an input, it reports the file names specified by its input. A ? may be used to match a single character except a period and a * may be used to match a group of characters not including a period. DIRECTORY preserves the case of the name of the files it finds.
Outputs TRUE if the current stream is at EOF.
EOF? (EOF? channel)
EOF? checks whether there are more characters available for input in the
current input stream. The result is TRUE if there are no more characters
to read, FALSE otherwise. A channel number may be entered as an optional
input. If present, EOF? checks that channel instead of checking the input stream.
This makes it unnecessary to switch among multiple input streams by changing the
value of :STANDARD.INPUT
. If you do not test for the EOF (end-of-file)
condition while reading, Logo will throw a runtime error when you try to read
and there are no more characters available. You may use CATCH
to catch that error,
however. The Listener is never at EOF.
Reports information about a file.
FILE.INFO filename
FILE.INFO reports a nine element list containing the following information about the specified file: [Attributes Size Year Month Day Hour Minute Second Type]
See also DIRECTORY
.
The attributes are a combination of the following values:
1 | hidden file |
2 | read-only file |
4 | system file |
8 | file is a sub-directory |
If the files does not exist or is inaccessible, FILE.INFO reports FALSE.
Reports TRUE if a file or directory exists.
FILE? filename
FILE? reports TRUE if the file specified by its input exists on the disk; otherwise it reports FALSE. Specify the pathname to access a directory that is not currently selected. You may use the forward slash ”/“ instead of the backwards slash as a path separator.
Reads one byte from the input stream.
GETBYTE (GETBYTE channel)
GETBYTE reports the binary value of the first character in the input stream. If no character is waiting to be read, GETBYTE waits for input from the Listener if the channel number is omitted or zero.
A channel number may be entered as an optional input. If present, GETBYTE reads
from that channel instead of reading from the channel designated by the :STANDARD.INPUT
variable. This makes it easier to switch among multiple input streams.
Reports the code of the last key that the user typed.
KEY
KEY reports the key code of the last key that the user typed. If you call KEY multiple times, the reported value is -1. Thus, you can call KEY only once for each key that the user typed.
KEY reports these keys as ASCII character values. Many keys on the keyboard do not produce characters, like the ENTER key. KEY reports these keys as special numeric values; these may vary between different keyboard layouts.
Opens a file and returns the channel number.
OPEN filename (OPEN filename mode) OPEN [] (OPEN [] mode) OPEN type-descriptors (OPEN type-descriptors mode)
OPEN prepares for input or output the file specified by its input. When a file has been opened,
OPEN returns a channel number which can be used for I/O. The channel number may be assigned to
one of the built-in variables :STANDARD.INPUT
or :STANDARD.OUTPUT
. Data may then be
read using READ
, READCHAR
, READLINE
, READLIST
, READQUOTE
and
other Logo primitives. Data may be written using all Logo commands that print, such as PRINT
,
or TYPE
. If the specified file does not exist when opened for reading, OPEN returns -1.
Many Logo commands that do I/O also accept a channel number as an optional, additional input.
The I/O is made using that channel instead of the channel number stored in :STANDARD.INPUT
or :STANDARD.OUTPUT
. This makes it easier to perform I/O with multiple channels.
The operating systems disallows certain characters in a file name. Additionally, the name of a file cannot contain any of the characters =
, ;
, or ;
. These three characters are reserved for type descriptors in File Open dialogs. see below for details.
A file is opened for read access in text mode if no other inputs are given. The second input may be a combination of the following characters:
r | Opens for reading. If the file does not exist or cannot be found, the call fails. |
w | Opens an empty file for writing. If the given file exists, its contents are destroyed. |
a | Opens for writing at the end of the file (appending); creates the file first if it does not exist. |
r+ | Opens for both reading and writing. (The file must exist.) |
w+ | Opens an empty file for both reading and writing. If the given file exists, its contents are destroyed. |
a+ | Opens for reading and appending; creates the file first if it does not exist. When a file is opened with the “a” or “a+” access type, all write operations occur at the end of the file. The file pointer can be repositioned, but is always moved back to the end of the file before any write operation is carried out. Thus, existing data cannot be overwritten. |
t | Open in text (translated) mode. In this mode, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading/writing with “a+”, OPEN checks for a CTRL+Z at the end of the file and removes it, if possible. Also, carriage return/linefeed combinations are translated into single linefeeds on input, and linefeed characters are translated to carriage return/linefeed combinations on output. This is the default I/O mode. |
b | Open in binary (untranslated) mode; translations involving carriage-return and linefeed characters are suppressed, and I/O is limited to single bytes regardless of the file's Unicode encoding. Logo's special escape characters like the tilde (~) or the backslash () are ignored. |
Type descriptors: OPEN can also displaying a standard file open/save dialog box. In order to open a dialog box instead of a file, the file name contains a list of file type descriptors.
A file type descriptor is one or more file types, separated with semicolons, optionally
followed by an ”=“ and a description. The text lgo;logo=Logo source file
would be a
valid file type descriptor for all files ending with ”.lgo“ or ”.logo“. More than one
file descriptor may be supplied; in this case, separate the descriptors with commas.
The file open/save dialog would display all files ending with the given file type.
The Logo command OPEN “|lgo;logo=Logo source file,txt=Text file|
would, for example,
display all files ending with ”.lgo”, “.logo”, or “.txt”.
If you use the empty word or
the empty list as a file name, Logo automatically opens a file open/save dialog displaying
all available files. Clicking the Cancel button in a file open/save dialog makes the OPEN
command return -1 as the channel number.
See also CLOSE
and CREATE
.
Opens a serial port for I/O.
OPEN.PORT portnumber
OPEN.PORT opens a serial port. The opening modes for a serial port are quite different from disk files. Logo uses these settings if any values are missing: “BAUD=9600,DATA=8,STOP=0,PARITY=N,HANDSHAKE=OFF,TIMEOUT=-1,BINARY=N”.
BAUD=value | The baud rate. This is the number of bits per second. Windows allows for settings of up to 256000. |
DATA=5,6,7,8 | The number of bits per byte. |
STOP=0,1,2 | The number of stop bits (1, 1 1/2 or 2). |
PARITY=N,O,E,M,S | The parity (None, Odd, Even, Mark, or Space). |
HANDSHAKE=OFF,ON,X | The handshaking protocol (OFF, ON (CTS/RTS), or X (XOn/XOff). |
TIMEOUT=value | The time to wait for an I/O request in milliseconds. If this time elapses while Logo is waiting for more bytes to be transmitted or received, Logo throws an I/O error. If the timeout is 0, Logo does not wait for any data, but returns pending data immediately. If the timeout is -1, Logo waits forever for pending data. When writing, Logo writes as many characters as possible and then returns if the timeout is 0. |
BINARY=Y,N | Binary mode (Yes or No). In binary mode, CR/LF character pairs are left untranslated. |
Returns the next character from the input stream without reading it.
PEEKBYTE (PEEKBYTE channel)
PEEKBYTE reports the numeric value of the first character in the input stream. If no character is waiting to be read, PEEKBYTE reports the value -1. A channel number may be entered as an optional input. If present, PEEKBYTE reads from that channel instead of reading from the input stream. This makes it easier to switch among multiple input streams. PEEKBYTE leaves the character in the stream.
For files opened in binary mode, PEEKBYTE always returns the next byte. If the file is not open in binary mode, PEEKBYTE returns the next character value according to the encoding of the file.
Note: In Logo 3, PEEKBYTE
waited for input at the Listener if there was no input
available from the Listener. PEEKBYTE
does not check the keyboard; it checks the
last line entered to see if there are any characters remaining to be read.
Prints text with a line feed.
PRINT object (PRINT) (PRINT object1 object 2 ...)
PRINT prints its inputs to the output stream and adds a line feed. If the input is a list, PRINT removes the brackets. With no input, (PRINT) prints a blank line. With multiple inputs, PRINT and its inputs must be enclosed in parentheses.
PRINT uses the channel number stored in :STANDARD.OUTPUT
.
Prints a list of numbers as Unicode characters.
PRINTLINE integerlist (PRINTLINE integerlist channel)
PRINTLINE prints to the output stream the Unicode characters corresponding to the elements of its input list. A line feed is not inserted, so if the output of PRINTLINE is printed on the screen, the prompt appears after the last character of the input list. A channel number may be entered as a second, optional input. If present, PRINTLINE writes to that channel instead of writing to the output stream. This makes it easier to switch among multiple output streams.
Prints its input and a newline.
PRINTQUOTE object (PRINTQUOTE object channel)
PRINTQUOTE prints its input to the output stream and adds a carriage return.
If the input is a list, PRINTQUOTE removes the brackets. PRINTQUOTE is much like
PRINT
, but it can only print a single input. A channel number may be entered
as a second, optional input. If present, PRINTQUOTE writes to that channel instead
of writing to the output stream. This makes it easier to switch among multiple output
streams. See also TYPE
and SHOW
.
Writes a data byte or a Unicode character to the output stream.
PUTBYTE number (PUTBYTE number channel)
PUTBYTE writes to the output stream the character corresponding to its binary input. The input number can be from 0 through 255. PUTBYTE does not insert a carriage return after writing its output.
A channel number may be entered as a second, optional input. If present, PUTBYTE writes to that channel instead of writing to the output stream. This makes it easier to switch among multiple output streams.
Writes data bytes or characters to the output stream and reads a reply.
PUTBYTES integerlist integer (PUTBYTES integerlist integer channel)
PUTBYTES writes to the output stream the characters corresponding to the elements of its
input list. A carriage return is not inserted, so if the output of PUTBYTES is printed on the
screen, the prompt appears after the last character of the input list. Legal input values are
values between 0 and 255. PUTBYTES works like the PRINTLINE
command. If a negative value
is found, Logo waits for the specified time in milliseconds after converting the number into
a positive value. This makes it possible to send a few bytes, wait for a specified time, and then
send more bytes.
A second input is a number that tells Logo to read the given number of bytes from the stream after the bytes have been output. These input bytes are output as a list of integers between 0 and 255. This feature makes PUTBYTES ideal for programming robots or other devices, where a stream of command bytes usually is followed by a reply from the robotic device.
A channel number may be entered as a third, optional input. If present, PUTBYTES writes to that channel instead of writing to the output stream and reads the reply from that channel as well. This makes it easier to switch among multiple output streams
Reads one Logo word.
READ
READ reports the first object from the input stream. If no object is waiting to be read, READ waits for input from the keyboard if the input stream is the Listener. If the input contains more than one word, the remainder is evaluated by Logo as commands. READ throws an I/O error if the end of the file is reached.
A channel number may be entered as an optional input. If present, READ reads from that channel instead of reading from the input stream. This makes it easier to switch among multiple input streams.
Unlike READWORD
, READ does not accept the empty list as input. It continues to wait until a
response is made that is not empty.
Reads a character from the input stream.
READCHAR (READCHAR channel)
READCHAR reports the first character from the input stream. If no character is waiting to be read and the input stream is the Listener, READCHAR waits for input from the Listener.
A channel number may be entered as an optional input. If present, READCHAR reads from that channel instead of reading from the input stream. This makes it easier to switch among multiple input streams.
Reads a line and outputs it as a list of numbers.
READLINE (READLINE channel)
READLINE reports the next line (up to a newline character) from the input stream as a
list of Unicode characters. If no line is waiting to be read and the input stream is
the Listener, READLINE waits for input from the keyboard. A channel number may be
entered as an optional input. If present, READLINE reads from that channel instead
of reading from the input stream. This makes it easier to switch among multiple
input streams. To output characters from the corresponding Unicode codes, use PRINTLINE
.
See also READWORD
, READCHAR
, READLINE
, and READQUOTE
.
Reads a line and outputs it as a list.
READLIST (READLIST channel)
READLIST reports in the form of a list the next line (up to a newline character)
from the input stream. If no line is waiting to be read and the input stream is
the Listener, READLIST waits for input from the keyboard. A channel number may
be entered as an optional input. If present, READLIST reads from that channel
instead of reading from the input stream. This makes it easier to switch among
multiple input streams. See also READWORD
, READCHAR
, READLINE
,
and READQUOTE
.
TO ASKIT PR [WHAT ARE YOUR FAVORITE FOODS?] MAKE "FOODS READLIST PR [I KNOW A RESTAURANT WHERE THEY SERVE] PR :FOODS PR [THAT WOULD MAKE YOUR MOUTH WATER.] END ASKIT
Opens a dialog box and reads a line.
READPROMPT text (READPROMPT)
READPROMPT opens a dialog box and lets the user type a line which is reported
as a single Logo word. Its input is displayed as text. If READPROMPT is used
without any inputs, a default message appears. When :CASE
is set to FALSE,
READPROMPT retains the case of letters that are entered. See also READWORD
,
READCHAR
, READLINE
, READQUOTE
, and READLIST
. If the
user cancelled the dialog, the result is FALSE.
Reads a line.
READQUOTE (READQUOTE channel)
READQUOTE reports the next line (up to a newline character) from the input stream
as a single Logo word. If no line is waiting to be read and the input stream is the
Listener, READQUOTE waits for input from the keyboard. READQUOTE is useful to define
names that contain delimiters or characters that would otherwise need to be quoted
with | and for retaining the case of characters entered by the user. When :CASE
is set to FALSE, READQUOTE retains the case of letters that are entered. A channel
number may be entered as an optional input. If present, READQUOTE reads from that
channel instead of reading from the input stream. This makes it easier to switch
among multiple input streams. See also READWORD
, READCHAR
, READLINE
,
READPROMPT
, and READLIST
.
Reads the first word of a line.
READWORD (READWORD channel)
READWORD reports the first object from the input stream. If no object is waiting
to be read and the input stream is the Listener, READWORD waits for input from the
keyboard. If the input consists of more than one word, the remainder of the input
is ignored. READWORD reports the empty list if <Enter> is pressed as input.
Compare with READ
, which does not accept the empty list as input, but waits
for a response that is not empty. A channel number may be entered as an optional
input. If present, READWORD reads from that channel instead of reading from the
input stream. This makes it easier to switch among multiple input streams.
See also READCHAR
, READLINE
, READLIST
, READPROMPT
, and READQUOTE
.
TO GREETING PR [WHAT'S YOUR NAME?] MAKE "RESPONSE READWORD PR SENTENCE [HI THERE,] WORD :RESPONSE "! END GREETING
Renames a disk file.
RENAME oldname newname
RENAME changes the name of the file specified by its first input to its second input. If the file specified does not exist, the first and second inputs are the same, or the second file already exists, RENAME throws an I/O error.
Displays a dialog to select a disk file.
SELECT.FILE filetypes (SELECT.FILE filetypes title)
SELECT.FILE displays a standard File Open dialog and lets the user select a file. It reports the name of the selected file, or FALSE
if the user clicks the Cancel button.
SELECT.FILE's input is a list of file type descriptors. See the OPEN
command for a detailed explanation.
An optional second input is the title of the File Open dialog.
The initial folder displayed is the current folder. Use the SETCURDIR
command to change the current folder to the desired folder before calling SELECT.FILE.
SELECT.FILE "|LGO=Logo files| Result: FALSE
Displays a dialog to select a disk folder.
SELECT.FOLDER (SELECT.FOLDER prompt)
SELECT.FOLDER displays a standard Select Folder dialog and lets the user select a folder. It reports the name of the selected folder, or FALSE
if the user clicks the Cancel button.
SELECT.FOLDER takes a prompt text that the Select Folder dialog displays.
The initial folder displayed is the current folder. Use the SETCURDIR
command to change the current folder to the desired folder before calling SELECT.FOLDER.
(SELECT.FOLDER "|Please select a folder|) Result: FALSE
Changes the current working directory.
SETCURDIR directoryname
SETCURDIR changes the user's working directory to the given directory name. On startup, this directory is set to the user's data directory.
Prints text with a line feed.
SHOW object (SHOW) (SHOW object1 object 2 ...)
SHOW prints its inputs to the output channel and adds a carriage return. If the input is a list, SHOW does not remove the brackets, as opposed to PRINT. With no input, (SHOW) prints a blank line. With multiple inputs, SHOW and its inputs must be enclosed in parentheses.
Lists the contents of current working directory.
SUBDIR (SUBDIR pattern)
SUBDIR reports a list of sub-directory names in the current working directory. If SUBDIR is used with an input, it reports the directory names specified by its input. A ? may be used to match a single character except a period and a * may be used to match a group of characters not including a period. SUBDIR preserves the case of the name of the directories it finds.
Prints text.
TYPE object (TYPE object1 object 2 ...)
TYPE prints its inputs to the output stream without adding a line feed. If the input is a list, TYPE removes the brackets. With no input, (TYPE) prints nothing. With multiple inputs, TYPE and its inputs must be enclosed in parentheses. Usually, TYPE prints its inputs on the Listener, and the user may type commands after the last character printed.
Pushes back one character to the input stream.
UNGETBYTE value (UNGETBYTE value channel)
UNGETBYTE pushes the character corresponding to its input onto the input stream so that the next character input primitive will pick up the character. Only one character can be pushed back at a time, so the character must be removed from the input stream before UNGETBYTE can be used again. A channel number may be entered as a second, optional input. If present, UNGETBYTE writes to that channel instead of writing to the output stream. This makes it easier to switch among multiple output streams.