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.

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.

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

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.

See also SUBDIR and CURDIR.

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

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:

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

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

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.

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

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.

See also PEEKBYTE, UNGETBYTE, and PUTBYTE.

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:

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”.

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.

See GETBYTE, UNGETBYTE, and PUTBYTE.

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.

See also TYPE and SHOW.

PRINT "HI
HI
(PRINT)

(PRINT "HI "JOE)
HI JOE

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.

PRINTLINE [71 65 82 66 76 69]
GARBLE

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.

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

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.

See also GETBYTE, PEEKBYTE, PRINTLINE, and READLINE.

PUTBYTE 65
E

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

PUTBYTES [68 69 70 01] 0
DEFG

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.

See also READCHAR, READLINE, READLIST, and READQUOTE.

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.

See also READWORD, READLINE, READLIST, and READQUOTE.

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.

READPROMPT "|Please enter a name|

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.

READQUOTE

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.

See also :DATADIR and CURDIR.

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.

See also TYPE and PRINT.

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

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.

See also DIRECTORY and CURDIR.

SUBDIR
Result: [Music Sounds]

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.

See also PRINT and SHOW.

TYPE "HI TYPE "JOE
HIJOE

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.

See also ASCII, GETBYTE, PEEKBYTE, and PUTBYTE.