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

ALERT message
(ALERT message button1)
(ALERT message button1 button2)
(ALERT message button1 button2 button3)

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

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

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.

See also :DATADIR.

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.

See also SUBDIR and CURDIR.

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]

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.

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.

See also PEEKBYTE, UNGETBYTE, and PUTBYTE.

KEY

Reports the code of the last key that the user typed.

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

OPEN filename
(OPEN filename mode)
OPEN []
(OPEN [] mode)
OPEN type-descriptors
(OPEN type-descriptors mode)

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.

See GETBYTE, UNGETBYTE, and PUTBYTE.

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.

PRINT uses the channel number stored in :STANDARD.OUTPUT.

See also TYPE and SHOW.

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.

See also GETBYTE, PEEKBYTE, PRINTLINE, and READLINE.

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.

See also READCHAR, READLINE, READLIST, and READQUOTE.

READCHAR (RC)

Reads a character from the input stream.

Syntax

READCHAR
(READCHAR channel)

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.

See also READWORD, READLINE, READLIST, and READQUOTE.

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

TO GREETING
    PR [WHAT'S YOUR NAME?]
    MAKE "RESPONSE READWORD
    PR SENTENCE [HI THERE,] WORD :RESPONSE "!
END
GREETING

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.

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

SETCURDIR

Changes the current working directory.

Syntax

SETCURDIR directoryname

Description

SETCURDIR changes the user's working directory to the given directory name. On startup, this directory is set to the user's data directory.

See also :DATADIR and CURDIR.

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.

See also TYPE and PRINT.

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.

See also DIRECTORY and CURDIR.

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.

See also PRINT and SHOW.

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.

See also ASCII, GETBYTE, PEEKBYTE, and PUTBYTE.