User's Guide to the Algernon I/O Library
Description
The Algernon I/O Library is a machine and LISP-independent set of
input and output routines that can be used with Algernon, with any
LISP program, or with any socket-capable program.
The I/O library currently consists of a set of LISP client routines
and a Java-based server program. When the client needs to ask
the user a question, it contacts the server. The server pops up
a window to ask the question and returns the answer to the client.
The server is contacted via a socket, so client routines written in
other languages could also communicate with the server, although
no other languages are supported yet.
The LISP client routines support both GUI and non-GUI interaction.
If the client can not contact the server, it will use equivalent
text-based interaction routines. This enhances the portability of
the routines.
Compatibility
The server was implemented using JDK 1.02 on a Sun workstation.
The LISP client runs under Allegro CL v4.3 on Sun workstations.
We have not tested the routines on other machines, although
both the server and the text-based interaction should be
platform-independent.
Using the I/O library
In a distributed system, the user will want one server program
running. Each LISP program will contact the server as necessary
to service I/O requests. In a non-distributed system, the user will
start the server, run their program that uses the GUI server, and
then shut down the server when their program ends.
Functions in the LISP I/O Client
In the functions below, a title or message is given by a string.
Each function accepts a format string and arguments, to which the
function format is applied to generate the title or
message. In the descriptions below, a title or
title-format-string must not contain newline characters,
while a format-string may contain newline characters.
Control Functions
(algy-io :OPEN)
- Opens a connection to the I/O server. If the connection can not be made,
it changes internal settings so as to use the text version of the I/O library.
(algy-io :CLOSE)
- Closes the connection to the I/O server. If the connection was not open,
this call does nothing.
(algy-io :RESET)
- Tells the server to close all open windows and return to its initial state.
(algy-io :STATUS)
- Prints information about the type of connection open and how many
I/O operations have been performed.
Input Functions
(algy-y-or-n-p "format-string" args...)
- Returns T or NIL, depending on the user's response. The format
function is applied to the format string and the arguments. The result is
used to prompt the user.
(algy-read-number "format-string" args...)
- Returns a number (real or integer) as entered by the user.
(algy-read-number-with-bounds min max "format-string" args...)
- Returns a number (real or integer) bounded inclusively by the given min and max.
(algy-read-atom "format-string" args...)
- Returns an atom as entered by the user.
(algy-read-string "format-string" args...)
- Returns a string as entered by the user.
(algy-read-list "format-string" args...)
- Returns a well-formed LISP list of items entered by the user.
Currently, the text version does not require surrounding parentheses,
while the GUI version does. Need to fix this!
(algy-choose list-of-selections "format-string" args...)
- Returns one of the value entries of list-of-selections as
selected by the user. List-of-selections is a list of items. Each
item is either a value or a (value . label) pair.
If the entry is not a pair, it is treated as (value . value) as
described below. The label is used to prompt the user, while the
value is returned to the caller if that entry is selected by the user.
Label is normally a string, however it may be anything.
(algy-choose-multiple list-of-selections "format-string" args...)
- Returns a list of one or more members of list-of-selections as
selected by the user. The format of list-of-selections is described
above in the algy-choose command.
Output Functions
(algy-show-message timeout "format-string" args...)
- Displays a small message in a popup window. The window will
automatically be dismissed in timeout seconds. A timeout
of 0 indicates that the message will remain visible
until the user dismisses the window.
(algy-show-text "title" "format-string" args...)
- Displays one or more lines of text in a popup text window that
remains visible until the user dismisses it. To generate multiple
lines of text, the format-string must contain newline
characters.
(algy-show-frame frame-name)
- Uses algy-show-text to display the contents of a frame.
(algy-open-log "title")
- Opens a log (e.g. transcript) window that can be
display lines of text sent to it over time. It is used,
for example, to display a session transcript. Returns
a log window ID to be used with other log windows functions.
(algy-log log-window-id "format-string" args...)
- The message generated by applying format to the
arguments is displayed in the given log window. If the
log window named by log-window-id is not active,
the message is ignored.
(algy-clear-log log-window-id)
- Clears the log window named by log-window-id.
arguments is displayed in the given log window. If the
log window named by log-window-id is not active,
the message is ignored.
(algy-close-log log-window-id)
- Closes the log window named by log-window-id.
Further Information
Those wishing to implement a client will need to reference the
Server documentation.
Algernon home page.
This page was created by
Micheal Hewett