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
Also: 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?
Also: 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?
Also: 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.
Also: 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.
PRINT uses the channel number stored in :STANDARD.OUTPUT.
Example
PRINT “HI HI (PRINT)
(PRINT “HI “JOE) HI JOE </span>
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
Also: 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
Also: 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
Also: 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
Also: 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
Also: 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.
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.
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.
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.