Terrapin Resources

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.

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 date 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 number that Logo uses for I/O. Usually, this is the channel number 0, which is the Input/Output 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 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.

Syntax

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.

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| “|Just water, thanks|) Result: MILK

CLOSE

Closes a stream.

Syntax

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 its storage location 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.

Syntax

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

Also: MKDIR

Creates a folder.

Syntax

Description

CREATE.DIR uses its input to create a path to a folder. The parent folders must all exist. Use SETCURDIR to set the current folder to the newly created folder.

CURDIR

Reports the current working directory.

Syntax

Description

CURDIR reports the user’s working directory for the current storage service. Use SETCURDIR to change the working directory.

Note that every storage service has its own working directory. Use the PATHNAME command to see a file’s full path, including the storage service 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. When Logo runs a Logo app, however, it sets the initial current directory to ”~FILES/“, because a typical Logo app works with data from within the Files panel.

Example

CURDIR Result: /LIBRARY

DELETE

Deletes a file or a folder.

Syntax

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

DIRECTORY

Also: DIR

Lists the contents of current working directory.

Syntax

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?

Also: EOFP

Outputs TRUE if the current stream is at EOF.

Syntax

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.

The Listener panel stream is always at EOF.

FILE?

Also: FILEP

Reports TRUE if a file or directory exists.

Syntax

Description

FILE? reports TRUE if the file or folder specified by its input exists on the storage; otherwise it reports FALSE.

FILE? skips all caching mechanisms and checks the storage directly. FILE? is therefore, a great tool to see if someone else has removed or added a file or folder to the storage.

Example

FILE? “NOTHING.NONAME Result: FALSE

FORM

Formats a number.

Syntax

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.

Example

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.

Syntax

Description

OPEN prepares for input or output the file specified by its input. When a file has been opened, OPEN returns a channel number which can be used for I/O. The channel number may be assigned to one of the built-in variables :STANDARD.INPUT or :STANDARD.OUTPUT. Data may then be read using READ, READCHAR, READLINE, READLIST, READQUOTE and other Logo primitives. Data may be written using all Logo commands that print, such as PRINT, or TYPE. If the specified file does not exist when opened for reading, OPEN returns -1. Many Logo commands that do I/O also accept a channel number as an optional, additional input. The I/O is made using that channel instead of the channel number stored in :STANDARD.INPUT or :STANDARD.OUTPUT. This makes it easier to perform I/O with multiple channels.

A file is opened for read access if no other inputs are given. The second input may be one 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.

Note that you cannot open files in binary mode; I/O with single bytes is not supported.

If you use a list of file extensions as the file name, Logo displays a Select File dialog with the list of files limited to the ones matching the list of extensions. Logo also supports old-style Terrapin Logo typelists, but their use is not recommended. See SELECT.FILE for more information.

See also CLOSE and CREATE.

PATHNAME

Reports the full path name for a file name.

Syntax

Description

PATHNAME reports the full path name for a given file name. If the optional second input is TRUE, PATHNAME reports the OS specific name of a file. This is not important in the Web version, but the desktop version outputs the OS specific path names.

A full path name has three parts: the name of the storage service, the names of the folders that the file is located within, and the file name. The storage service begins with a tilde character (as in ~FILES), followed by the names of the folders separated with slashes, finally a slash and the file name. An example: ~FILES/A/B/C.LGO would contain the storage service ~FILES, the folder /A/B and the file C.LGO.

Each storage service has a current directory, which can be set with the SETCURDIR command. If a folder list does not begin with a slash as in A/B/C.LGO, Logo assumes that the folder list refers to the current directory, and inserts that directory at the beginning of the path.

If you, for example, issue the command SETCURDIR ~FILES/A/B , then the current directory would be exactly that directory. Now, the path C.LGO would output ~FILES/A/B/C.LGO, because the storage service and the list of folders would be missing, and Logo would insert the current directory. The path C/D.LGO would become ~FILES/A/B/C/D.LGO and so on.

The special directory .. refers to the parent directory. This makes it possible to refer to directory that are not part of the current directory. The path ../HI.LGO, for example, would, with the current directory set to ~FILES/A/B, output ~FILES/A/HI.LGO. You can use this special directory as any part of the directory list.

Also note that SETCURDIR also refers to the current directory if the list of folder does not start with a slash. You can switch between storage services with the command SETCURDIR storagename if you use the storage name only without any folders.

Example

CREATE.DIR “TEST SETCURDIR “TEST CURDIR Result: ~FILES/TEST PATHNAME “HELLO.LGO Result: ~FILES/TEST/HELLO.LGO PATHNAME “../HELLO.LGO Result: ~FILES/HELLO.LGO SETCURDIR “~HOME/TOOLBOX CURDIR Result: ~HOME/TOOLBOX SETCURDIR “~FILES CURDIR Result: ~FILES/TEST

PRINT

Also: PR

Prints text with a line feed.

Syntax

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.

     
8 “\b toggles between raw HTML mode and translated mode; HTML and WEBLINK use this character.
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 and SHOW, and FORM to format numbers.

Example

PRINT “HI HI (PRINT) (outputs an empty line) (PRINT “HI “JOE) HI JOE

PRINTLINE

Prints a list of numbers as Unicode characters.

Syntax

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.

Example

PRINTLINE [71 65 82 66 76 69] GARBLE

PRINTQUOTE

Also: PQ

Prints its input and a newline.

Syntax

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.

Example

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

PROGRESSBAR

Displays a progress bar.

Syntax

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.

Example

FOR [I 0 1 0.1] [PROGRESSBAR :I WAIT 1000] PROGRESSBAR -1

READ

Reads one Logo word.

Syntax

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.

Syntax

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

Example

; Click Stop to stop. FOREVER [PRINT READCHAR] A LEFT SHIFT

READFILE

Reads and parses the contents of a file.

Syntax

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:

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.

If you use a list of file extensions as the file name, Logo displays a Select File dialog with the list of files limited to the ones matching the list of extensions. Logo also supports old-style Terrapin Logo typelists, but their use is not recommended. See SELECT.FILE for more information.

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 ot the JSON file, and the even elements are the values. The above file, for example, would output the following list:

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:

For exmaple, if the above JSON file would reside on a server, the following code would print the name:

PPROPS “RECORD READFILE “|https://my.example.com/person.json| “JSON.UPPER PRINT GPROP “RECORD “NAME John Doe

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:

See also WRITEFILE.

Example

WRITEFILE “PI.LGO PI “WORD READFILE “PI.LGO “WORD Result: 3.14

READLINE

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

Syntax

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 was an empty line, READLINE outputs an empty list.

To output characters from the Unicode codes, use PRINTLINE. See also READWORD, READCHAR, READLINE, and READQUOTE.

READLIST

Also: RL

Reads a line and outputs it as a list.

Syntax

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.

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

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. If the “PREFS property 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 cancelled the dialog, the result is FALSE.

Example

READPROMPT “|Please enter a name|

READQUOTE

Also: RQ

Reads a line.

Syntax

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 was an empty line, READQUTOE 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.

Example

READQUOTE

READWORD

Also: RW

Reads the next word of a line.

Syntax

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.

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

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.

RENAME “~DROPBOX/MYFILE.LGO “TEST.LGO

SELECT.FILE

Displays a dialog to select a file.

Syntax

Description

SELECT.FILE displays a file picker 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 extensions that limits the files that the user sees. The special extension “*” displays all files. To be backwards compatible with Terrapin Logo, old-style file type descriptors may be used as well; Logo ignores the description of these types.

Examples: [LGO LOGO] lists all Logo source files, and [GIF JPG PNG BMP] lists images with these extensions. Note, however, that “*” overrides all other extensions; the value [LOGO LGO *] lists all files; the empty list also lists all files.

Images have such a variety of file extensions that it does not make sense to list them all. For images, Logo recognizes the special “extension” IMAGES. If you use this extension, Logo lists all image files.

Finally, if you are Internet savvy, you can specify MIME types along with extensions. This lets Logo display files based on their content, not on their extension:

An optional second input is the title of the 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. This also includes storage names like ~FILES.

SELECT.FILE [] Result: FALSE

SELECT.FOLDER

Displays a dialog to select a folder.

Syntax

Description

SELECT.FOLDER displays a folder picker 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 an optional prompt text that the folder picker dialog displays. SELECT.FOLDER displays the folder tree of the storage system that the CURDIR commands reports, which is usually ~FILES, but you can use the SETCURDIR command to a different storage like ~HOME to display its folders.

(SELECT.FOLDER “|Please select a folder|) Result: FALSE

SETCURDIR

Changes the current working directory.

Syntax

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 storage exists; it does not check if the folder exits, 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 storage service only like e.g. SETCURDIR ”~FILES, SETCURDIR switches to the current directory of that storage service. 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.

Syntax

Description

SHOW prints its inputs to the standard 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, and FORM to format numbers.

Example

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

SUBDIR

Lists the contents of current working directory.

Syntax

Description

SUBDIR reports a list of sub-directory names in the current working directory. If SUBDIR is used with an input pattern, 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

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.

Example

TYPE “HI TYPE “JOE HIJOE TYPE “One\nTwo\nThree ONE TWO THREE

WRITEFILE

Stores a Logo word or list into a file.

Syntax

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.

If you use a list of file extensions as the file name, Logo displays a Select File dialog with the list of files limited to the ones matching the list of extensions. Logo also supports old-style Terrapin Logo typelists, but their use is not recommended. See SELECT.FILE for more information.

Use the READFILE command to read a file written with the WRITEFILE command.

Example

WRITEFILE “PI.LGO “WORD PI READFILE “PI.LGO “WORD Result: 3.14