Programmer's Guide to the Algernon I/O Server

Description

The Algernon I/O Library is a set of input and output routines that can be used with Algernon, with any LISP program, or with any socket-capable program. The server is written in Java and communicates with the client via a socket (Socket communication NYI, 23 Jan 1997). Thus, it is usable by any program capable of communicating via sockets. One client currently exists for the I/O server. It is written in LISP and runs in Allegro CL v4.3.

Compatibility

The server was implemented using JDK 1.02 on a Linux workstation and has been tested on a Sun workstation.

Using the I/O library

Once the server is running, the client sends commands (described below) to the server, which displays windows as needed to interact with the user. Any return values passed back to the user are in the form: (msg-id data). In order to fully understand the commands you need to look at the examples because we rely on the "obvious" nature of the examples to make the details clear.

Notes on Syntax

In specifying the syntax of the commands that the server supports and the messages it returns we adopt the following conventions:

In the displayed command/message formats, fields are separated by commas, but the commas do not appear in actual commands.
A field containing SP indicates the space character (ASCII 0x20).
A field containing NULL indicates the null character (ASCII 0x00).
A field containing NL indicates the newline character. Under Unix this indicates (ASCII 0x0A), but under Windows 95 this may be something else (ASCII linefeed followed by ASCII carriage return?)
A field containing CMD indicates that the string naming the command whose format is being described should be placed at that field position. When specifying command names case is not important.
A field containing TITLE indicates a string of printable characters not containing newline characters (ASCII 0x0A). Typically such a field indicates the title of a window.
A field containing TEXT indicates a string of printable characters possibly containing newline characters. Typically such a field indicates a prompt or message to be displayed in a window as several lines of text (broken at the embedded newlines).
A field containing ID, LOG-ID or INT indicates a string of digits representing a positive integer.
A field containing NUM indicates a string of digits representing a number. Textual representations of real numbers and integers can be placed in such a field including numbers represented by scientific notation.
A field containing RESPONSE stands for the text of a user's response in a message from the server.
All other strings in a field position should be taken to indicate the string itself.
In order to help make the syntax and semantics clear we give an example of each command. In these examples, the string "\0" indicates the null character and "\n" indicates the newline character (or characters).

Control Functions

kill-input-window

Kills the current input window (if one exists) even if the user is in the midst of supplying a response. Does not return any values.

Format: CMD,NULL
Example: kill-input-window\0

reset

Closes all open windows except log windows. This includes closing the current input window (if one exists) even if the user hasn't yet responded.

Format: CMD,NULL
Example: reset\0

terminate

Closes all open windows, sends a final message ":QUIT" to the client, closes the connection and shuts down the server program.

Format: CMD,NULL
Example: terminate\0

Functions for Getting User Input

choose

Opens a window with a prompt and a list of items to choose from. The user is forced to choose a single item, and the position of the selected item is returned. Positions are counted from the beginning of the list starting at one. The "..." in the command format indicates repetition not the string "..." The INT field in the command format should indicate the number of times the sequence TEXT,NULL is repeated following the INT field.

Format: CMD,SP,ID,SP,TEXT,NULL,SP,INT,SP,TEXT,NULL,...,TEXT,NULL
Example: choose 1018 Favorite color?\0 3 Red\0Green\0Blue\0
Returns: (,ID,SP,RESPONSE,),NL
Example: If the user chooses "Green" then (1018 2)\n

choose-multiple

Same as choose, but now the user can choose one or more items from the list of possibilities.

Format: See choose.
Example: choose-multiple 1019 Favorite colors?\0 3 Red\0Green\0Blue\0
Returns: (,ID,SP,(,SP,RESPONSE,...,SP,RESPONSE,),),NL
Example: If the user chooses "Red" and "Blue" then (1019 ( 1 3))\n

y-or-n-p

Opens a window with a prompt (presumably asking a question) and yes and no buttons. Returns the user's response.

Format: CMD,SP,ID,SP,TEXT,NULL
Example: y-or-n-p 1013 Are you a college student?\0
Returns: (,ID,SP,:YES,),NL or (,ID,SP,:NO,),NL
Example: (1013 :YES)\n

read-atom

Opens a window with a prompt and a field for entering text. Right not it accepts any random text the user can type in the text field, but that should change. The returned response includes any leading or trailing whitespace.

Format: See y-or-n-p.
Example: read-atom 1015 What is your favorite atom?\0
Returns: (,ID,SP,RESPONSE,),NL
Example: (1015 LITHIUM)\n

read-list

Opens a window with a prompt and a text area for entering a well-formed Lisp list. It does some rudimentary syntax checking, but it is not guaranteed to accept all well-formed Lisp lists or reject all syntax errors. The returned response includes any leading or trailing whitespace.

Format: See y-or-n-p.
Example: read-list 1016 Enter a call to CONS.\0
Returns: (,ID,SP,RESPONSE,),NL
Example: (1016 (cons 'a '(b c)))\n

read-number

Opens a window with a prompt and a field for entering a number. Forces the user to enter a number not any random text. It will accept scientific notation.

Format: See y-or-n-p.
Example: read-number 1014 What is your age in years?\0
Returns: (,ID,SP,RESPONSE,),NL
Example: (1014 27)\n

read-number-with-bounds

Same as read-number except the command also specifies upper and lower bounds (inclusive) on the numbers you are willing to except from the user.

Format: CMD,SP,ID,SP,NUM,SP,NUM,SP,TEXT,NULL
Example: read-number-with-bounds 1017 0 10 Enter a number from 0 to 10\0
Returns: (,ID,SP,RESPONSE,),NL
Example: (1017 3.14)\n

read-string

Opens a window with a prompt and a text field for entering an arbitrary one line string. If the user types a string containing the double quote character, then this could confuse the reader of the return value. Some mechanism for escaping embedded quotes needs to be adopted.

Format: See y-or-n-p.
Example: read-string 1015 What is your name?\0
Returns: (,ID,SP,",RESPONSE,",),NL
Example: (1015 "Methuselah")\n

Functions for Showing Output

open-log

Opens a persistent log window to which you can add text with log commands or clear with the clear-log command. You can have several log windows open at the same time so in order to distinguish among the windows you must supply a unique log window ID indicating the one on which you want to operate. The server supplies these log window IDs as a response to the open-log command.

Format: CMD,SP,ID,TITLE,NULL
Example: open-log 2048 Error Log\0
Returns: (,ID,SP,LOG-ID,),NL
Example: (2048 7)\n

clear-log

Clears all the text from the specified log window.

Format: CMD,SP,ID,SP,LOG-ID,NULL
Example: clear-log 2049 7\0

log

Format: CMD,SP,ID,SP,LOG-ID,SP,TEXT,NULL
Example: log 2050 7 Oh no, an error occured!\n\0

close-log

Closes the specified log window.

Format: See clear-log.
Example: close-log 2051 7\0

show-msg

Displays a window showing a message. The INT field in the command supplies a timeout in seconds after which the window will disappear. If you supply a timeout of 0, the window will remain until the user explicitely dismisses it or it is closed due to a reset command.

Format: CMD,SP,ID,SP,INT,SP,TEXT,NULL.
Example: show-msg 2052 10 This message will disappear in 10 sec.\0

show-text

Displays a window showing a long message in a scrollable text area. The window persists until the user explicitely dismisses it or it is closed due to a reset command.

Format: CMD,SP,ID,SP,TITLE,NULL,TEXT,NULL
Example: show-text 2053 My Title\0The body of the text to display.\0

Further Information

There is documentation on the LISP client for the Algernon I/O Library.

Algernon home page.