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:

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.

More Algernon documentation.


This page was created by

Micheal Hewett