Input and Output
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.
Most commands use so-called streams internally. If a file is opened for reading or appending (see OPEN), Logo fetches the contents and makes the data available for subsequent reading. If you write to a file, the CLOSE command transfers the data to its storage location.
Streams have channel numbers. Logo matches Listener panel to channel #0.
The :STANDARD.INPUT and :STANDARD.OUTPUT variables contain the channel numbers that Logo uses for I/O. Usually, this is the channel number 0, which is the Listener’s Input/Output channel. You can use the OPEN command to obtain a channel number for a file, and assign that channel number to above variables to make most 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.
Note that all I/O commands always transfer Unicode characters, not single bytes. Depending on the channel’s encoding, a Unicode character may consist of several bytes. Logo supports the extended Unicode character set with character code values of up to 1,114,111. Logo assumes UTF-8 encoding when reading or writing files.
ALERT
Displays an alert box; expects a minimum of one input, but parentheses are needed if not called with one input.
Syntax
ALERT message
(ALERT message button1 button2 ...)
Description
ALERT pops up a small message window and displays the text given as its input. It accepts any reasonable number of optional inputs which are used as the labels for as many buttons buttons. ALERT displays one button labeled “OK” as default. The output of ALERT is the label of the clicked button.
Examples
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| “|Just water, thanks|) Result: MILK
CLOSE
Closes a stream; expects between zero inputs and one input, but parentheses are needed if not called with one input.
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 saved until the file is closed.
If an output stream is not closed, you will lose your data!
If CLOSE is used without any inputs, all open data streams are closed and I/O will revert to the Listener panel. See also OPEN and CREATE.
CREATE
Creates a file; one input.
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).
Note that the file is not created at its final location until it is saved.
CURDIR
Reports the current working directory; no inputs.
Syntax
CURDIR
Description
CURDIR reports the user’s working directory. Use SETCURDIR to change the working directory.
Note that every file system has its own working directory. Use the PATHNAME command to see a file’s full path, including the file system name and the working directory if appropriate. That command also has more details about path names.
When Logo starts up, its current directory is set to “~PC/”, making all Load and Save commands work with the local disk.
Examples
CURDIR Result: /LIBRARY
DELETE
Deletes a file or a folder; one input.
Syntax
DELETE filename
Description
DELETE deletes a file or folder. The command cannot be undone, so please use it with caution.
Note that if you DELETE a folder, the folder and all of its contents are deleted.
It is possible to use wildcards to delete multiple files at once. The command DELETE “~FILES/ART/*.PNG, for example, deletes all PNG files in the ART folder of the ~FILES file system.
Most file systems do not permit the deletion of a file, however.
DIR
Also: DIRECTORY
Lists the contents of current working directory; expects between zero inputs and one input, but parentheses are needed if not called with any inputs.
Syntax
DIRECTORY
(DIRECTORY pattern)
Description
DIRECTORY reports a list of file names in the current working directory. DIRECTORY preserves the case of the name of the files it finds. An optional input (which was a search pattern in previous version of Logo) is ignored.
Note that some file systems may not support directory listings; in that case the output is an empty list.
Examples
(DIR “*.LGO) Result: [Init.lgo]
EOF?
Also: EOFP
Outputs TRUE if the current stream is at EOF; expects between zero inputs and one input, but parentheses are needed if not called with any inputs.
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 standard 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.
FILE?
Also: FILEP
Reports TRUE if a file or directory exists; one input.
Syntax
FILE? filename
Description
FILE? reports TRUE if the file or folder specified by its input exists on the file system; otherwise it reports FALSE.
FILE? skips all caching mechanisms and checks the file system directly. FILE? is therefore a great tool to see if someone else has removed or added a file or folder to the file system.
Examples
FILE? “NOTHING.NONAME Result: FALSE
FORM
Formats a number; three inputs.
Syntax
FORM number width precision
Description
FORM outputs a word containing a formatted version of “number”, possibly preceded by spaces, with at least “width” characters, including exactly “precision” digits after the decimal point, rounding if necessary. If “precision” is 0 then there will be no decimal point in the output.
Examples
FORM 1.2345 3 3 Result: 1.235 FORM 1.2345 8 2 Result: 1.23
OPEN
Opens a file and returns the channel number; expects between one input and two inputs, but parentheses are needed if not called with one input.
Syntax
OPEN filename
(OPEN filename mode)
OPEN [extensions-list]
(OPEN [extensions-list] 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.
A file is opened for read access if no other inputs are given. The second input may be one of the following characters:
| Character | Meaning |
|---|---|
| “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. |
Note that you cannot open files in binary mode; I/O with single bytes is not supported. Also, opening a file for reading on the PC will most often open a Select File dialog.
Examples
TO WRITE.TO.FILE :WHAT LMAKE “CHANNEL (OPEN “FILE.TXT “W) MAKE “STANDARD.OUTPUT :CHANNEL PRINT :WHAT CLOSE :CHANNEL END Result: WRITE.TO.FILE defined WRITE.TO.FILE [HI MICHAEL] Result: File FILE.txt saved in the Downloads folder
PATHNAME
Reports the full path name for a file name; expects between one input and two inputs, but parentheses are needed if not called with one input.
Syntax
PATHNAME filename
Description
PATHNAME reports the path name of a file. In many cases, or if the file does not exist, this will just be the input to PATHNAME, but with some file systems like ~HTTPS or ~HOME, it may also be a combination of the file system’s current folder and the file name.
See also CURDIR for the current folder.
Examples
SETCURDIR “~HOME/TOOLBOX/SHAPES PATHNAME “DOG1.PNG Result: ~HOME/TOOLBOX/SHAPES/DOG1.PNG PATHNAME “../BIRDS/DUCK1.PNG Result: ~HOME/TOOLBOX/BIRDS/DUCK1.PNG PATHNAME “../DUCK1.PNG Result: ../DUCK1.PNG
Also: PR
Prints text with a line feed; expects a minimum of zero inputs, but parentheses are needed if not called with one input.
Syntax
PRINT object
(PRINT)
(PRINT object1 object2 ...)
Description
PRINT prints its inputs to the standard 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.
PRINT recognizes a few special characters that support simple text formatting. Use the command “CHAR value” to print these characters, or use a backslash-escaped character as described below.
| Value | Character | Description |
|---|---|---|
| 8 | “\b | Toggles between normal output and HTML output; HTML and WEBLINK use this character. Use with caution, as wrong HTML may corrupt the entire page! |
| 9 | “\t | Prints a tab character, which advances the caret to the next tab stop position. See also :TAB. |
| 10 | “\n | Ends the line and moves the caret to the beginning of the next line. |
| 11 | “\v | The same as the character 10, except that the caret is not advanced if the line is empty. |
| 12 | “\f | Clears all text and moves the caret to the upper left corner. |
| 13 | “\r | Erases the current line and moves the caret to the beginning of the line. |
See also TYPE, SHOW, and FORM to format numbers.
Examples
PRINT “HI HI (PRINT) ; outputs an empty line (PRINT “HI “JOE) HI JOE
PRINTLINE
Prints a list of numbers as Unicode characters; expects between one input and two inputs, but parentheses are needed if not called with one input.
Syntax
PRINTLINE integerlist
(PRINTLINE integerlist channel)
Description
PRINTLINE prints the Unicode characters corresponding to the elements of its input list. A line feed is not inserted, so PRINTLINE acts like the TYPE command.
PRINTLINE uses the channel number stored in :STANDARD.OUTPUT. You can supply a channel number as an optional, second input.
Examples
PRINTLINE [71 65 82 66 76 69] GARBLE
PRINTQUOTE
Also: PQ
Prints its input and a newline; expects between one input and two inputs, but parentheses are needed if not called with one input.
Syntax
PRINTQUOTE object
(PRINTQUOTE object channel)
Description
PRINTQUOTE prints its input 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 standard output stream. This makes it easier to switch among multiple output streams. See also TYPE and SHOW.
Examples
PRINTQUOTE “HELLO HELLO PQ [HI HOW ARE YOU?] HI HOW ARE YOU?
PROGRESSBAR
Displays a progress bar; expects between one input and two inputs, but parentheses are needed if not called with one input.
Syntax
PROGRESSBAR value
(PROGRESSBAR value message)
PROGRESSBAR -1
Description
PROGRESSBAR displays a progress bar. Its input is a value between 0 and 1, where 0 is an empty progress bar, and 1 is a full progress bar. An optional second input can be used to display a message on top of the progress bar.
An input value less than zero hides the progress bar.
Examples
FOR [I 0 1 0.1] [PROGRESSBAR :I WAIT 1000]
PROGRESSBAR -1
READ
Reads one Logo word; expects between zero inputs and one input, but parentheses are needed if not called with any inputs.
Syntax
READ
(READ channel)
Description
READ reports the first object from the standard input stream. If no object is waiting to be read, READ waits for input from the keyboard if the standard input stream is the Listener panel. 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 standard input stream. This makes it easier to switch among multiple input streams.
Unlike all other READ commands, 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
Read a character from the standard input stream; expects between zero inputs and one input, but parentheses are needed if not called with any inputs.
Syntax
READCHAR
(READCHAR channel)
Description
READCHAR reports the first character from the standard input stream. If no character is waiting to be read and the standard input stream is the Listener panel, READCHAR waits for input from the Listener panel.
A channel number may be entered as an optional input. If present, READCHAR reads from that channel instead of reading from the standard input stream. This makes it easier to switch among multiple input streams.
A keyboard has lots of special keys, like the keys F1 to F12, the ENTER key and more. READCHAR converts all of these keys to words with more than one character. The left-arrow key, for example, causes READCHAR to report LEFTARROW. Try for yourself to see the different key names.
Logo does not recognize all special keys. Some of these keys, especially punctuation keys, have different locations on different keyboards. These keys return characters whose ASCII value is higher than 128. In fact, relying on punctuation keys may cause trouble with different keyboards.
See also READWORD, READLINE, READLIST, and READQUOTE.
Examples
; Click Stop to stop. FOREVER [PRINT READCHAR] A LEFTARROW SHIFT
READFILE
Reads and parses the contents of a file; two inputs.
Syntax
READFILE pathname format
READFILE [extensions-list] format
Description
READFILE reads a text file, parses the contents, and outputs the contents as a Logo word or list. The second input tells READFILE which format to output:
Logo may display a dialog that lets you select a file name.
JSON and JSON.UPPER formats:
The JSON data format is a universal format to exchange static data. A typical JSON data record could be the following:
{ "name": "John Doe", "age": 43, "email": "john@example.com" }
READFILE reads such a file in PLIST format, which means that the output is a list where the odd elements are the keys of the JSON file, and the even elements are the values. The above file, for example, would output the following list:
[|name| |John Doe| |age| 43 |email| |john@example.com|]
| Format | Description |
|---|---|
| WORD | Output the entire contents of the file as a single word, including newline characters and whitespace. |
| LINES | Reads the file line by line and outputs a list where each element is a word containing an entire line without the line feed character. You can use the SPLIT command to split up the line into separate words if necessary. |
| LOGO | Parses the entire file as if it was valid Logo code and returns a list containing entire parsed lines as Logo would parse them; multi-line statements and string are parsed into a single line. The file must only contain valid Logo language elements, or Logo throws a syntax error. |
| JSON | Parses the file as a JSON-formatted data file (see below). |
| JSON.UPPER | Parses the file as a JSON-formatted data file (see below), and converts all keys to upper case. |
You can use the PPROPS command to create a property list out of such a list.
The format JSON.UPPER converts the keys to upper case so Logo can handle them more easily:
[NAME |John Doe| AGE 43 EMAIL |john@example.com|]
For example, if the above JSON file would reside on a server, the following code would print the name:
MAKE "JSON READFILE "|https://my.example.com/person.json| "JSON.UPPER
PPROPS "RECORD :JSON
PRINT GPROP "RECORD "NAME
If the JSON data contains an array, its elements are returned as a list. This JSON file, for example:
[{ "name": "John Doe", "age": 43, "email": "john@example.com" }, { "name": "Jack Smith", "age": 38, "email": "jack@example.com" }]
would cause READFILE output this list if read in JSON.UPPER format:
[[NAME |John Doe| AGE 43 EMAIL |john@example.com] [NAME |Jack Smith| AGE 38 EMAIL |jack@example.com]]
See also WRITEFILE.
Examples
WRITEFILE “PI.LGO “WORD PI READFILE “PI.LGO “WORD Result: 3.14
READLINE
Reads a line and outputs it as a list of numbers; expects between zero inputs and one input, but parentheses are needed if not called with any inputs.
Syntax
READLINE
(READLINE channel)
Description
READLINE reports the next line (up to a newline character) from the standard input stream as a list of Unicode characters. If no line is waiting to be read and the standard input stream is the Listener panel, 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 standard input stream. This makes it easier to switch among multiple input streams.
If the input is an empty line, READLINE outputs an empty list.
To output characters from the Unicode codes, use PRINTLINE. See also READWORD, READCHAR, and READQUOTE.
Examples
READLINE ; enter the text ADIEU Result: [65 68 73 69 85]
READLIST
Also: RL
Reads a line and outputs it as a list; expects between zero inputs and one input, but parentheses are needed if not called with any inputs.
Syntax
READLIST
(READLIST channel)
Description
READLIST reports in the form of a list the next line (up to a newline character) from the standard input stream. If no line is waiting to be read and the standard input stream is the Listener panel, READLIST waits for input from the keyboard. If the end of a file is reached, READLIST outputs the empty list.
A channel number may be entered as an optional input. If present, READLIST reads from that channel instead of reading from the standard input stream. This makes it easier to switch among multiple input streams.
If the input was an empty line, READLIST outputs an empty list.
See also READWORD, READCHAR, READLINE, and READQUOTE.
Examples
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 Result: ASKIT defined ASKIT
READPROMPT
Also: RP
Opens a dialog box and reads a line; expects between zero inputs and three inputs, but parentheses are needed if not called with one input.
Syntax
READPROMPT text
(READPROMPT text preset)
(READPROMPT text preset TRUE/FALSE)
(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. If READPROMPT has a second input, this input is used to initialize the input line of the dialog box with this input. This input cannot be a list.
If :CASE is set to TRUE (which is the default), Logo converts the input to upper case. If a third input is present, this input controls whether Logo converts the input to upper case.
See also READWORD, READCHAR, READLINE, READQUOTE, and READLIST. If the user cancels the dialog, the result is FALSE.
Examples
PRINT READPROMPT “|Please enter a name|
READQUOTE
Also: RQ
Reads a line; expects between zero inputs and one input, but parentheses are needed if not called with any inputs.
Syntax
READQUOTE
(READQUOTE channel)
Description
| READQUOTE reports the next line (up to a newline character) from the standard input stream as a single Logo word. If no line is waiting to be read and the standard input stream is the Listener panel, READQUOTE waits for input from the keyboard. If the end of a file is reached, READQUOTE reports an empty word. 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. |
If the input is an empty line, READQUOTE reports an empty word.
A channel number may be entered as an optional input. If present, READQUOTE reads from that channel instead of reading from the standard input stream. This makes it easier to switch among multiple input streams. See also READWORD, READCHAR, READLINE, READPROMPT, and READLIST.
Examples
MAKE “THISQUOTE READQUOTE PRINT :THISQUOTE Result: HELLO WORLD
READWORD
Also: RW
Reads the next word of a line; expects between zero inputs and one input, but parentheses are needed if not called with any inputs.
Syntax
READWORD
(READWORD channel)
Description
READWORD reports the first word from the standard input stream. If no word is waiting to be read and the standard input stream is the Input panel, READWORD waits for input from the keyboard. READWORD reports the empty list if the end of a file has been reached. Compare with READ, which does not accept empty lines 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 standard input stream. This makes it easier to switch among multiple input streams.
If the input was an empty line, READWORD outputs an empty word.
See also READCHAR, READLINE, READLIST, READPROMPT, and READQUOTE.
Examples
TO GREETING PR [WHAT’S YOUR NAME?] MAKE “RESPONSE READWORD PR SENTENCE [HI THERE,] WORD :RESPONSE “! END Result: GREETING defined GREETING Result: Prints a greeting
RENAME
Renames a file; two inputs.
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. Note that you can only change the name of the file or folder. You cannot change the path pointing to the file or folder.
Note that most file systems do not support the renaming of a file or folder for secutrity reasons, including local disk files.
Examples
RENAME “~FILES/MYFILE.LGO “TEST.LGO
SETCURDIR
Changes the current working directory; one input.
Syntax
SETCURDIR directoryname
Description
SETCURDIR changes the user’s working directory to the given directory name.
Use SETCURDIR to set the directory to use for all commands that accept a file or directory name.
Note that SETCURDIR only checks if the file system exists; it does not check if the folder exists, or whether it is a file or a directory. If the directory that you entered as input does not exist, or if it is a file instead of a directory, later file commands will throw an error.
If you use SETCURDIR with the name of a file system only like e.g. SETCURDIR “~FILES, SETCURDIR switches to the current directory of that file system. Use SETCURDIR with a full path name, like e.g. SETCURDIR “~FILES/ to switch to the root directory of “~FILES.
For details about path names, see PATHNAME.
See also CURDIR.
SHOW
Prints text with a line feed; expects a minimum of zero inputs, but parentheses are needed if not called with one input.
Syntax
SHOW object
(SHOW)
(SHOW object1 object2 ...)
Description
SHOW prints its inputs to the standard output channel and adds a line feed. 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, and FORM to format numbers.
Examples
PRINT [HI JOE] HI JOE SHOW [HI JOE] [HI JOE]
SUBDIR
Lists the contents of current working directory; expects between zero inputs and one input, but parentheses are needed if not called with any inputs.
Syntax
SUBDIR
(SUBDIR path/pattern)
Description
SUBDIR reports a list of sub-directory names in the current working directory. SUBDIR preserves the case of the name of the directories it finds. An optional input (which was a search pattern in previous version of Logo) is ignored.
Note that some file systems may not support directory listings; in that case the output is an empty list.
See also DIRECTORY and CURDIR.
Examples
SUBDIR Result: [Music Sounds]
TYPE
Prints text; expects a minimum of one input, but parentheses are needed if not called with one input.
Syntax
TYPE object
(TYPE object1 object2 ...)
Description
TYPE prints its inputs to the standard 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. In that case, TYPE does not print any spaces between each input. This is different from Terrapin Logo, where TYPE printed each input separated by a space.
TYPE, as well as PRINT and SHOW recognize a few special characters that support simple text formatting. See PRINT for details.
See also PRINT and SHOW, and FORM to format numbers.
Examples
TYPE “HI TYPE “JOE HIJOE TYPE “One\nTwo\nThree ONE TWO THREE
WRITEFILE
Stores a Logo word or list into a file; three inputs.
Syntax
WRITEFILE pathname format wordorlist
WRITEFILE [extensions-list] format wordorlist
Description
WRITEFILE writes a Logo word or list into a file. The second input tells WRITEFILE which format to create:
| Format | Description |
|---|---|
| WORD | Writes the data as-is without inserting line feeds. If the data is a list, the outer brackets are not written. |
| LINES | If the data is a list, write each list element as a separate line. If an element is a list, the outer brackets are not written. |
| LOGO | Writes the data as valid Logo data that READFILE can read again. |
Logo may display a dialog that lets you select a file name.
Use the READFILE command to read a file written with the WRITEFILE command.
Examples
WRITEFILE “PI.LGO “WORD PI READFILE “PI.LGO “WORD Result: 3.14