TTYIO			Revised 13-May-84


TTYIO  is  a package containing a number of functions built on top of TTYIN
that  enable  you  to  prompt a user for files, functions, reals, integers,
dotted pairs, and atoms with defaults and flexible restriction handling.

When  using  these  functions  in sequence, you may type responses ahead by
including  the  responses  to  successive questions on the same line as the
response to the current question.

TTYIO  also  contains a "text" pointer facility, based on INTERLISP comment
pointers, that enables you to store help messages on a file without storing
them as strings in memory.



Interaction Functions:


(ASKFLE MODE PROMPT HELP CONFIRMFLG DEFAULT NULFLG FILE)

ASKFLE  asks  for  a  filename  using  TTYINC with PROMPT and HELP. MODE is
either  INPUT  or  OUTPUT  (defaults  to  INPUT).   CONFIRMFLG is T if user
confirmation  is  required.  DEFAULT  is returned if <cr> is entered as the
response.  NULFLG  is  T if a null response is permitted. If FILE is given,
then  it  is taken as the response without user interaction. However, it is
still  checked  for  validity (and user interaction will occur if it is not
valid).


(ASKFN PROMPT DEFAULT HELP SPLST FN CONFIRMFLG NULFLG)

ASKFN  asks  for  a  function  name  or LAMBDA expression using TTYINC with
PROMPT  and HELP. CONFIRMFLG is T if user confirmation is required. DEFAULT
is  returned  if  <cr>  is  entered  as the response. NULFLG is T if a null
response  is  permitted.   SPLST (if given) is a list of suggested function
names.  The  list  is used strictly for <esc> completion. The response does
not  have  to  be a member of the list. If FN is given, then it is taken as
the  response  without  user  interaction. However, it is still checked for
validity  (and user interaction will occur if FN is not a valid function).



(ASKINT PROMPT DEFAULT HELP LOWERBOUND UPPERBOUND INTEGER CONFIRMFLG NULFLG)

ASKINT asks for an integer using TTYINC with PROMPT and HELP. CONFIRMFLG is
T  if user confirmation is required. DEFAULT is returned if <cr> is entered
as  the  response.  NULFLG is T if a null response is permitted. LOWERBOUND
and  UPPERBOUND  are  the lower and upper bounds on acceptable answers. The
response  must be greater than or equal to the lower bound and less than or
equal  to  the upper bound. Both bounds may be defaulted to NIL. If INTEGER
is  given,  then  it  is  taken  as  the response without user interaction.
However,  it is still checked for validity (and user interaction will occur
if it fails to meet the requirements).


(ASKITEM RESTRICTION PROMPT HELP CONFIRMFLG DEFAULT NULFLG ITEM)

ASKITEM  asks for an item using TTYINC with PROMPT and HELP. RESTRICTION is
either  a  list  of  allowable  responses  or  a  function that returns the
response  if  it  is  valid  and  NIL  otherwise.  CONFIRMFLG  is T if user
confirmation  is  required.  DEFAULT  is returned if <cr> is entered as the
response.  NULFLG  is  T if a null response is permitted. If ITEM is given,
then  it  is taken as the response without user interaction. However, it is
still  checked for validity (and user interaction will occur if it fails to
meet the requirements).

If  a restriction list is provided and the first element of the list is "*"
then new items are allowed. Otherwise, the response must be a member of the
restriction list.


(ASKITEMS RESTRICTION PROMPT HELP CONFIRMFLG ITEMS)

ASKITEMS  asks  for  a  list  of  items  using TTYINC with PROMPT and HELP.
RESTRICTION  is  either  a  list  of allowable responses or a function that
returns  the  response if it is valid and NIL otherwise. CONFIRMFLG is T if
user  confirmation  is required. If ITEMS is given, then it is taken as the
response  without  user  interaction.  However,  it  is  still  checked for
validity  (and  user  interaction  will  occur  if  it  fails  to  meet the
requirements).

If  a restriction list is provided and the first element of the list is "*"
then  new  items are also allowed. Otherwise, the response must be a member
of the restriction list.

Once  the  list  of  items has been entered, ASKITEM is called to check the
validity of each item.


(ASKPAIR RESTRICTION PROMPT HELP CONFIRMFLG DEFAULT NULFLG ITEM)

ASKPAIR  asks  for  a  dotted  pair  using  TTYINC  with  PROMPT  and HELP.
RESTRICTION  is  either  a  list  of allowable responses or a function that
returns  the  response if it is valid and NIL otherwise. CONFIRMFLG is T if
user  confirmation  is  required. DEFAULT is returned if <cr> is entered as
the  response.  NULFLG  is  T  if  a null response is permitted. If ITEM is
given,  then it is taken as the response without user interaction. However,
it  is  still  checked  for validity (and user interaction will occur if it
fails to meet the requirements).

If  a restriction list is provided and the first element of the list is "*"
then  new  items are also allowed. Otherwise, the response must be a member
of the restriction list.

If  the  value  is  expected  as  (A  . B), the user should type A B.  If a
default  is  supplied, the user can type A alone, and the default B will be
supplied.


(ASKRL PROMPT DEFAULT HELP LOWERBOUND UPPERBOUND REAL CONFIRMFLG NULFLG)

ASKRL  asks  for  a floating point number using TTYIN with PROMPT and HELP.
CONFIRMFLG  is  T  if user confirmation is required. DEFAULT is returned if
<cr>  is  entered  as  the  response.  NULFLG  is  T  if a null response is
permitted.  LOWERBOUND  and  UPPERBOUND  are  the lower and upper bounds on
acceptable answers. The response must be greater than or equal to the lower
bound  and  less  than  or  equal  to  the  upper bound. Both bounds may be
defaulted  to  NIL.  If  REAL  is  given,  then it is taken as the response
without  user  interaction.  However, it is still checked for validity (and
user interaction will occur if it fails to meet the requirements).


(ASKYN PROMPT DEFAULT HELP RESPONSE)

ASKYN asks for a Yes/No answer using TTYIN with PROMPT and HELP. DEFAULT is
returned if <cr> is the response (any non-NIL default is taken as Yes).  If
RESPONSE  is  given,  then  it  is  taken  as  the  response  without  user
interaction.   However,   it  is  still  checked  for  validity  (and  user
interaction  will  occur  if  it  fails  to  meet the requirements).  ASKYN
returns T for Yes and NIL for No.


(TTYINC PROMPT SPLST HELP OPTIONS ECHOTOFILE TABS UNREADBUF RDTBL NOSTOREFLG)

TTYINC is used in conjunction with TTYIN to allow the user to type a number
of  commands  ahead  to a prompt. It is typically used with the TTYIN modes
COMMAND  and  STRING.  If the global variable TTYIN-COMMAND-LINE is non-NIL
upon  entry  then  it is concatenated with UNREADBUF and a line terminator.
TTYIN  is  then called. CDR of the line returned by TTYIN is stored back in
TTYIN-COMMAND-LINE unless NOSTOREFLG is non-NIL.



Text Pointer Functions:

Text  pointers  are  variations  on  comment pointers. A text pointer is an
s-expression  of  the  form  (;  "text  string").  ";" is defined as a read
macro.  When  the  global  variable TTYIO-TXT-FLG is NIL, only pointers are
loaded.  When  T,  the  full  text  is loaded. Upon printing to the primary
output  file, the leading parenthesis, semi-colon, and trailing parenthesis
are stripped off. GET; is a user macro similar to GETCOMMENT. Regardless of
the TTYIO-TXT-FLG setting, it loads the actual text.


(DISPLAYHELP KEY)

DISPLAYHELP  copies  the  help message indexed by KEY to the primary output
file.  KEY can either be a text pointer  (with TTYIO-TXT-FLG T or NIL) or a
string  or  an atom (T is ignored).  DISPLAYHELP returns NIL if nothing was
printed;  T  if the entry was found, or user typed ^O. The function SPRINTT
is advised to ensure that DISPLAYHELP is called from TTYIN in response to ?
or HELP.



Simple Output Functions:

The  following  functions  were  written  by  Bill  VanMelle  for the MYCIN
environment.


(WRITE  . N)

WRITE  takes  an arbitrary number of arguments, each of which is PRIN1ed to
the  primary  output file, followed by EOL. If an argument is a list, it is
MAPRINTed; i.e., the outer parentheses will not appear.


(WRITE1  . N)

WRITE without the final EOL.


(WRITEARG X FILE)

WRITEARG  PRIN1's X to FILE if it is not a list. Otherwise it uses MAPRINT.
If X is not a list, WRITEARG PRIN1's it to FILE, otherwise MAPRINT's it, so
that the outer parentheses will not appear.


(TTYOUT  . N)

WRITE to the tty display stream.


(TTYOUT1  . N)

TTYOUT without the final EOL.



Reid Smith
SDR