Input and Output

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.

ALERT

Displays an alert box.

Syntax

Description

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.

Example

CLEARINPUT

Clears all input from a stream.

Syntax

CLEARINPUT
(CLEARINPUT channel)

Description

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.

CLOSE

Closes a stream.

Syntax

CLOSE channel
(CLOSE)

Description

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.

CREATE

Creates a file.

Syntax

CREATE filename

Description

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.

CREATE.DIR

Creates a folder.

Syntax

CREATE.DIR foldername

Description

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.

CURDIR

Reports the current working directory.

Syntax

CURDIR

Description

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.

Example

CURDIR
Result: /C/Users/John/Documents/Terrapin Logo

DELETE

Deletes one or more files from disk.

Syntax

DELETE filename

Description

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.

DIRECTORY (DIR)

Lists the contents of current working directory.

Syntax

DIRECTORY
(DIRECTORY pattern)

Description

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.

Example

(DIR "*.LGO)
Result: [Init.lgo]

EOF? (EOFP)

Outputs TRUE if the current stream is at EOF.

Syntax

EOF?
(EOF? channel)

Description

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.

FILE.INFO

Reports information about a file.

Syntax

FILE.INFO filename

Description

FILE.INFO reports a nine element list containing the following information about the specified file:
[Attributes Size Year Month Day Hour Minute Second Type]

If the files does not exist or is inaccessible, FILE.INFO reports FALSE.

Example

FILE.INFO FIRST DIR
Result: [0 925 2013 29 8 12 27 39 TEXT]

FILE? (FILEP)

Reports TRUE if a file or directory exists.

Syntax

FILE? filename

Description

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.

Example

FILE? "INIT.LGO
Result: TRUE
FILE? "NOTHING.NONAME
Result: FALSE

GETBYTE

Reads one byte from the input stream.

Syntax

GETBYTE
(GETBYTE channel)

Description

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.

KEY

Syntax

KEY

Description

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.

OPEN

Opens a file and returns the channel number.

Syntax

Description

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.

OPEN.PORT

Opens a serial port for I/O.

Syntax

OPEN.PORT portnumber

Description

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.

PEEKBYTE

Returns the next character from the input stream without reading it.

Syntax

PEEKBYTE
(PEEKBYTE channel)

Description

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.

PRINT (PR)

Prints text with a line feed.

Syntax

PRINT object
(PRINT)
(PRINT object1 object 2 ...)

Description

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.

Example

PRINT "HI
HI
(PRINT)
(PRINT "HI "JOE)
HI JOE

PRINTLINE

Prints a list of numbers as Unicode characters.

Syntax

PRINTLINE integerlist
(PRINTLINE integerlist channel)

Description

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.

Example

PRINTLINE [71 65 82 66 76 69]
GARBLE

PRINTQUOTE (PQ)

Prints its input and a newline.

Syntax

PRINTQUOTE object
(PRINTQUOTE object channel)

Description

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.

Example

PRINTQUOTE "HELLO
HELLO
PQ [HI HOW ARE YOU?]
HI HOW ARE YOU?

PUTBYTE

Writes a data byte or a Unicode character to the output stream.

Syntax

PUTBYTE number
(PUTBYTE number channel)

Description

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.

Example

PUTBYTE 65
E

PUTBYTES

Writes data bytes or characters to the output stream and reads a reply.

Syntax

PUTBYTES integerlist integer
(PUTBYTES integerlist integer channel)

Description

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

Example

PUTBYTES [68 69 70 01] 0
DEFG

READ

Reads one Logo word.

Syntax

READ

Description

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.

READCHAR (RC)

Syntax

Description

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.

READLINE

Reads a line and outputs it as a list of numbers.

Syntax

READLINE
(READLINE channel)

Description

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.

READLIST (RL)

Reads a line and outputs it as a list.

Syntax

READLIST
(READLIST channel)

Description

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.

Example

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

READPROMPT (RP)

Opens a dialog box and reads a line.

Syntax

READPROMPT text
(READPROMPT)

Description

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.

Example

READPROMPT "|Please enter a name|

READQUOTE (RQ)

Reads a line.

Syntax

READQUOTE
(READQUOTE channel)

Description

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.

Example

READQUOTE

READWORD

Reads the first word of a line.

Syntax

READWORD
(READWORD channel)

Description

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.

Example

RENAME

Renames a disk file.

Syntax

RENAME oldname newname

Description

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.

SELECT.FILE

Displays a dialog to select a disk file.

Syntax

SELECT.FILE filetypes
(SELECT.FILE filetypes title)

Description

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

SELECT.FOLDER

Displays a dialog to select a disk folder.

Syntax

SELECT.FOLDER
(SELECT.FOLDER prompt)

Description

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.

Description

SHOW

Prints text with a line feed.

Syntax

SHOW object
(SHOW)
(SHOW object1 object 2 ...)

Description

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.

Example

PRINT [HI JOE]
HI JOE
SHOW [HI JOE]
[HI JOE]

SUBDIR

Lists the contents of current working directory.

Syntax

SUBDIR
(SUBDIR pattern)

Description

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.

Example

SUBDIR
Result: [Music Sounds]

TYPE

Prints text.

Syntax

TYPE object
(TYPE object1 object 2 ...)

Description

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.

Example

TYPE "HI TYPE "JOE
HIJOE

UNGETBYTE

Pushes back one character to the input stream.

Syntax

UNGETBYTE value
(UNGETBYTE value channel)

Description

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.