



      U S I N G   I C - H O P E   O N   T H E   A R C H I M E D E S




1.   Introduction and disclaimer

The Imperial College HOPE interpreter (IC-HOPE) is  an  experimental  tool
originating  in  the  Functional  Programming  Group  of the Department of
Computing.  Neither the implementation nor the documentation are  complete
yet.   The  interpreter  should  be  regarded  only  as an introduction to
functional  programming  and  the  HOPE  language,  not  as  a  basis  for
developing large items of software.

This document describes how to use the IC-HOPE interpreter  on  the  Acorn
Archimedes,  under RISC OS.  It does not document the IC-HOPE language and
should be read in conjunction with the "Hope Tutorial" in the August  1985
edition  of  BYTE  Magazine,  a copy of which is on the distribution disk,
entitled 'HopeTutorl'.



2.   Running the interpreter

After invoking the interpreter, the current directory will be displayed at
the  top of the screen.  Beneath this, a banner with the version number of
the interpreter will be printed, followed by the prompt ">:".

     ************** IC-HOPE version 4.02A (c) ICST 1989 **************
     **                                                             **
     **     Welcome to the functional programming language HOPE     **
     **                                                             **
     ************* Warning - incomplete implementation! **************
>:

You can now start entering programs as described below.



3.   Character set

     The interpreter recognises the following character set:

     letters:       _ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
                      a b c d e f g h i j k l m n o p q r s t u v w x y z

     digits:        0 1 2 3 4 5 6 7 8 9

     operators:     ` | \ ~ @ # $ % ^ & * - + = : . ? /

     punctuation:   ! ( ) { } [ ] ; , " '

     layout:        space tab newline






Using IC-Hope on the Archimedes                                      Page 1






4.   Lexical conventions

An IC-HOPE program is a sequence of  words.   A  word  is  a  sequence  of
digits, one character in single quotes, a sequence of characters in double
quotes, a single  punctuation  character,  an  identifier  or  a  comment.
Single-quote  within  single  quotes and double quote within double quotes
are self-escaped and must be doubled.  An  identifier  is  a  sequence  of
letters  and  digits  starting  with  a  letter  or a sequence of operator
characters; only the first 240 characters are significant.

Adjacent words formed from the same class  of  non-punctuation  characters
must   be   separated  by  a  layout  character.   Layout  characters  are
significant within double quotes except  that  newline  is  treated  as  a
space.  A comment is a sequence of characters starting with an exclamation
mark and ending with a newline or another exclamation mark.  Comments  are
treated  as  layout  characters  and  ignored.   The  following words have
predefined  meanings  to  the  interpreter  and  should  not  be  used  as
identifiers:

    <  <>  <=  +  ++  |  &  *  -  ---  ->  /=  _  >  >=   :   ::   :::
    #  =  =<  =>  ==  alpha  and  beta  bisect  char  close  data  dec
    display  div  echo  else   empty  end  eof   exit  false   getchar
    in   infix  intersect  isin   lambda  let  list   load  minus  mod
    modify   nil  nl   nonop  not   notrace  num   openin  openout  or
    print   putchar  putlist   save  set   size  show   split   stream
    subset  succ   system   then   time   trace   true   truval   type
    typevar  union  void  where  width  with  X



5.   Program order

Infix declarations must appear before the  operations  are  used  in  data
definitions,  recursion  equations or expressions.  Type variables must be
declared before they are used in data definitions.  Function  declarations
must  appear  before  any of their recursion equations and before they are
used in expressions.  Mutually recursive data types can be declared  using
the  "with"  connective.   Provided  these  constraints  are observed, the
elements of the program can be entered in any order.

The interpreter does not check that the patterns on the left-hand sides of
recursion equations are unique.  At run-time they are checked in the order
they were entered and the  first  equation  with  a  matching  pattern  is
evaluated.  Programs should not be written to take advantage of this.















Using IC-Hope on the Archimedes                                      Page 2






6.   Standard facilities

The following declarations may be assumed to be made when the  interpreter
is  loaded  and  the types, type variables, functions and operations which
they introduce may be used without further formality.

typevar alpha, beta ;


type stream == num ;


infix isin                                : 3 ;
infix <>, ::, :::, or, union              : 4 ;
infix +, -, and, intersect, minus, subset : 5 ;
infix =, <, >, /=, =<, >=, *, div, mod    : 6 ;


data num            == 0    ++ succ ( num ) ;
data truval         == true ++ false ;
data char           == 'A'  ++ 'B' ++ 'C' ++ ... ;

data set ( alpha )  == empty ;
data list ( alpha ) == nil ++ alpha :: list ( alpha ) ++
                        alpha ::: list ( alpha ) ;


dec  +, -, *, div, mod   : ( num # num ) -> num ;
dec  =, <, =<, >, >=, /= : ( alpha # alpha) -> truval ;
dec  and, or             : ( truval # truval ) -> truval ;
dec  not                 : truval -> truval ;
dec  <>                  : ( list ( alpha ) # list ( alpha ) ) ->
                           list ( alpha ) ;

dec close      : stream -> void ;
dec eof        : char ;
dec getchar    : stream -> char ;
dec nl         : char ;
dec show       : alpha -> alpha ;
dec openin     : list ( char ) -> stream ;
dec openout    : list ( char ) -> stream ;
dec print      : list ( char ) -> void ;
dec putchar    : ( stream # char ) -> void ;
dec putlist    : ( list ( list ( char ) ) # stream ) -> void ;

dec bisect     : set ( alpha ) -> ( set ( alpha ) # set ( alpha ) ) ;
dec intersect  : ( set ( alpha ) # set ( alpha ) ) -> set ( alpha ) ;
dec isin       : ( alpha # set ( alpha ) ) -> truval ;
dec minus      : ( set ( alpha ) # set ( alpha ) ) -> set ( alpha ) ;
dec size       : set ( alpha ) -> num;
dec split      : set ( alpha ) -> ( alpha # set ( alpha ) ) ;
dec subset     : ( set ( alpha ) # set ( alpha ) ) -> truval ;
dec union      : ( set ( alpha ) # set ( alpha ) ) -> set ( alpha ) ;






Using IC-Hope on the Archimedes                                      Page 3






The full set of constructors for data type "char"  is  the  set  of  ASCII
characters defined in section 3 above.  The relational operators <=, , =<,
>, >= and /= have their usual meanings for "num"  and  "char"  parameters,
with ASCII ordering for characters.  They are not defined for other types,
except for =, which is also defined over structured types.  Functions  and
types  which  are  not  mentioned  in the "Hope tutorial" are described in
section 9 below.



7.   Binding conventions

The  comma  binds  most  weakly,  followed  by  conditionals,  the   "let"
qualifier,  the "where" qualifier, all infix operators in numeric priority
order (highest first), function application (represented by juxtaposition)
and list and set construction using quotes, brackets and braces.

In patterns,  "&"  binds  more  tightly  than  comma  or  any  infix  data
constructor.   When  a  program is displayed or saved on disk (see section
10), all priorities will be shown explicitly by extra parentheses.



8.   Error messages

There are three kinds of error messages. Syntax errors are detected as the
program  is  entered. A carot (^) character is printed beneath the word in
error.  When a syntax error has been  found,  the  interpreter  skips  all
words  up  to  the  next  semicolon.   If  there are no syntax errors, the
expression is type-checked.  If  a  type  error  is  found  the  incorrect
subexpression,  its  actual type, and the type expected by the interpreter
are displayed.  Statements or expressions with syntax or type  errors  are
not  stored  by  the  interpreter  and must be reentered.  Run-time errors
cause the interpreter to abandon the current evaluation and return to  the
top level.  The program is retained and may be corrected.



9.   Additional features

The interpreter supports a number  of  language  features  which  are  not
described in the "Hope Tutorial".  These are as follows:

(a)  Synonyms may be declared for user-defined or built-in data types, e.g.

     type word == list ( char ) ;

Objects  of  type  "word"  will  be  treated  as  "list  (  char  )"   for
type-checking and when printing the type of results.


(b)  Synonyms may also be declared for objects matched in  patterns  using
the  "&" connective.  The synonym name must precede the "&".  This is used
to  avoid  repeating  complex  expressions  on  the  right-hand-sides   of
recursion equations e.g.

--- f ( l & ( h :: t ) ) <= if h = 10 then g ( t ) else g ( l ) ;


Using IC-Hope on the Archimedes                                      Page 4






(c)  Mutually recursive types may be declared using "with", e.g.

     data LispList == NIL ++ CONS ( LispItem # LispList )
     with LispItem == ATOM ( num ) ++ LIST ( LispList ) ;


(d) A restricted form of lazy evaluation is provided by  the  'lazy  cons'
list constructor ":::".  This does not evaluate its second argument unless
its value is required (this includes pattern-matching).  E.g.

     >: 1 ::: [ 2 div 0 ] ;
     >: 1 ::: [ ( 2 div 0 ) ] : list ( num )

This allows infinite lists to be constructed and manipulated.   There  are
no  other  lazy operations and other types of data may only be constructed
eagerly.


(e) The data type "set ( alpha )"  is  supported.   Sets  are  denoted  by
sequences of expressions within braces; duplicated values will only appear
once:

     >: { 1, 1+1, 2-1, 3, 3-1 } ;
     >: { 1 , 3 , 2 } : set ( num )

The empty set is denoted by empty  braces  or  by  using  the  constructor
"empty".  No other set constructors are provided, and functions should not
pattern-match on nonempty sets.  The following built-in  functions  (types
and fixities in section 6 above) are provided over sets:

     minus      set difference
     intersect  set intersection
     union      set union
     isin       is specified item in set?
     subset     is first set a subset of second?
     bisect     split set into two equal-sized subsets and return both
     split      remove arbitrary item from nonempty set and return both
     size       number of elements in a set


(f) The following functions (types given in section 6  above)  allow  more
control  over  input-output.   Most have side-effects on files and are not
referentially transparent:

     show       identity function printing its argument on the terminal
     print      print a list of characters on the terminal
     nl         end-of-line character sequence
     openin     open an external file by name and return an input stream
     openout    open an external file by name and return an output stream
     getchar    read a character and advance the input stream
     putchar    write a character and advance the output stream
     putlist    write a list of lists of characters to an output stream
     close      close the file associated with a stream
     eof        end-of-file character sequence; returned as last character
                of an input file, closes an output file when written.




Using IC-Hope on the Archimedes                                      Page 5






10.  System commands

The interpreter provides a set of commands to assist with  program  entry,
debugging  and  modification.   All  commands start with the command name,
followed by zero or more parameters separated by spaces  and  end  with  a
semicolon.


     display      causes the interpreter to list the program.

The text is reconstructed from the stored internal  form  and  may  differ
from  what  was  originally  entered  in  layout  and in the bracketing of
expressions. It is displayed in the  order:  operator  declarations;  type
variable  declarations;   data  definitions; function definitions with the
equations grouped together after the declaration.

The priorities of all operations are shown explicitly by the insertion  of
extra  parentheses.   Comments  are not stored and are not displayed.  The
listing can be made more selective by following "display" with one of  the
parameters  "typevar", "operator", "data" or "function", or by the name of
a single function.


     save           causes the interpreter to save the complete program in
                    source form on an external file.

The filename is given as the parameter of the "save" command, enclosed  in
double  quotes,  and should be 240 characters long or less.  The format of
the saved source is the same as for "display"  except  that  all  function
declarations  are saved before any recursion equations.  This ensures that
all functions will be declared before they  are  used  when  the  file  is
reloaded.


     load           causes the interpreter to read in a program contained
                    in an external file.

The filename is given as the parameter of the "load" command  and  follows
the  conventions  given above for "save".  The source file can be produced
by an earlier "save" command, or by  a  text  editor,  allowing  top-level
applications  to  be  included.   They will be executed immediately as the
file is loaded.  If a source file produced by a text editor is loaded  and
resaved, it will be reformatted and any comments will be lost.


     modify         allows the stored internal form of a single function
                    to be edited.

The name of the function is given as the parameter of the command.   There
is  no way to alter typevar, data or infix priority declarations except by
editing a saved version of the program and reloading it.








Using IC-Hope on the Archimedes                                      Page 6






The "modify" command is interactive and all replies may be abbreviated  to
a  single letter, shown by brackets in the message.  The interpreter first
displays the function declaration and asks if you want to change it; reply
"(y)es"  if  you do. Other replies are taken as "(n)ext" and the recursion
equations are displayed.  You will be prompted for the type  part  of  the
declaration.   Terminate the type with a semicolon in the usual way.  When
you change a declaration the whole  program  is  re-typechecked  when  the
"modify"  command  is  complete,  and  type  errors  may  appear for other
functions.

The recursion equations are then  displayed  one  at  a  time.   For  each
equation  you have the option of deleting or replacing it, or adding a new
equation before or after it.  Reply "(d)elete",  "(r)eplace",  "(b)efore",
or  "(a)fter"  respectively.   Other replies are taken as "(n)ext" and the
following equation is displayed.   For  "delete"  you  will  be  asked  to
confirm  your  intention; reply "(y)es" to confirm the deletion.  In other
cases you  will  be  prompted  for  a  new  equation  without  the  "---".
Terminate the equation with a semicolon.

If the new declaration or recursion equation which you  enter  has  syntax
errors  you  will  be  asked  whether  you  want to enter it again.  Reply
"(a)gain" to try again.  Other replies are taken as "(n)ext" and  the  old
version is kept.


     echo           controls the listing of loaded programs.

The parameter "off" suppresses the listing of programs entered  by  "load"
commands,  speeding up loading.  Any lines containing errors will still be
displayed.  Listings can be restored by the parameter "on".  The state  of
the switch is displayed if the parameter is omitted.


     trace          causes the interpreter to display information about
                    the evaluation of selected functions.

The names of the functions to be traced are given as parameters  or  "all"
can  be  specified  to trace all functions in the program.  Tracing of the
selected functions is started  by  entering  "trace  on"  and  stopped  by
entering  "trace  off".  If the parameter is omitted, the interpreter will
display the currently selected  functions  and  the  state  of  the  trace
switch.


     notrace      suppresses the tracing of specified functions.

The names of the functions which  are  not  to  be  traced  are  given  as
parameters  or  "all"  can  be  specified  to  suppress the tracing of all
functions in the program.


     time           controls the timing of programs.

The parameter "on" causes the interpreter to give the evaluation  time  of
top-level  expressions.   Use  "off"  to  turn  off  timing  and  omit the
parameter to show the state of the timing  switch.   Execution  times  are
given in milliseconds.


Using IC-Hope on the Archimedes                                      Page 7






     exit           gets out of the interpreter.

You can also get out of the interpreter if it is expecting terminal  input
by  entering control-D as the FIRST character of the input line, to signal
end-of-file.   Runaway  recursion  in  user-defined  functions  cannot  be
stopped except by pressing <reset> or <control><break>.


     system         enters an Archimedes operating system command.

The command must be enclosed in double quotes, and care  should  be  taken
not to overwrite any of the Hope system's workspace.  It is  intended  for
such things as viewing directories, changing the current directory and  so
on.  Running any disk-based utilities is likely to  cause  the  system  to
crash.  Commands need not be prefixed with an asterisk, and are restricted
to 240 characters.  If double quotes need to be included in the command  a
pair of double quotes  should  be  used  for  each  double  quote  in  the
command string.


     width         controls the line width for terminal output.

The parameter sets the point at which Hope will split lines of output.  If
no parameter is given, the current width value is returned.  The parameter
"off" (set by default) disables the width  control  and  uses  the  entire
screen width - only wrapping round at the edge of the screen.

































Using IC-Hope on the Archimedes                                      Page 8


