Programmer's Guide to the Algernon I/O Server
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.
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
- A field containing NULL indicates the null character
- 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
- 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
- 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
- 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).
- 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.
- Closes all open windows except log windows. This includes closing the
current input window (if one exists) even if the user hasn't yet
- Closes all open windows, sends a final message ":QUIT" to the client,
closes the connection and shuts down the server program.
Functions for Getting User Input
- 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
Example: choose 1018 Favorite color?\0 3 Red\0Green\0Blue\0
Example: If the user chooses "Green" then (1018 2)\n
- 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
Example: If the user chooses "Red" and "Blue" then (1019 ( 1 3))\n
- Opens a window with a prompt (presumably asking a question) and
yes and no buttons. Returns the user's response.
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
- 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
Example: (1015 LITHIUM)\n
- 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
Format: See y-or-n-p.
Example: read-list 1016 Enter a call to CONS.\0
Example: (1016 (cons 'a '(b c)))\n
- 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
Format: See y-or-n-p.
Example: read-number 1014 What is your age in years?\0
Example: (1014 27)\n
- 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.
Example: read-number-with-bounds 1017 0 10 Enter a number from 0 to 10\0
Example: (1017 3.14)\n
- 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
Example: (1015 "Methuselah")\n
Functions for Showing Output
- 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.
Example: open-log 2048 Error Log\0
Example: (2048 7)\n
- Clears all the text from the specified log window.
Example: clear-log 2049 7\0
Example: log 2050 7 Oh no, an error occured!\n\0
- Closes the specified log window.
Format: See clear-log.
Example: close-log 2051 7\0
- 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
Example: show-msg 2052 10 This message will disappear in 10 sec.\0
- 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.
Example: show-text 2053 My Title\0The body of the text to display.\0
There is documentation on the
for the Algernon I/O Library.
Algernon home page.
More Algernon documentation.
This page was created by