%OP%JUY
%OP%DFT
%OP%GRN
%OP%TM2
%OP%BM2
%OP%LM4
%OP%FO/Using IC-Hope on the Archimedes//Page @P/
%CO:A,5,75%%C%%H1%%H2%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




%H2%%H4%1.   %H1%Introduction and disclaimer%H2%%H4%

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

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



%H2%%H4%2.   %H1%Running the interpreter%H2%%H4%

%JR%After invoking the interpreter, the current directory will be displayed at 
%JL%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.



%H2%%H4%3.   %H1%Character set%H2%%H4%

     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:     ` | \ ~ @ # $ %PC% ^ & * - + = : . ? /

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

     layout:        space tab newline 
%P0%
%H2%%H4%4.   %H1%Lexical conventions%H2%%H4%

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

%JR%Adjacent words formed from the same class of non-punctuation characters 
%JL%must be separated by a layout character.  Layout characters are 
%JR%significant within double quotes except that newline is treated as a 
%JL%space.  A comment is a sequence of characters starting with an exclamation 
%JR%mark and ending with a newline or another exclamation mark.  Comments are 
%JL%treated as layout characters and ignored.  The following words have 
%JR%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



%H2%%H4%5.   %H1%Program order%H2%%H4%

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

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

%JR%The following declarations may be assumed to be made when the interpreter 
%JL%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 ) ;
%P0%
%JR%The full set of constructors for data type "char" is the set of ASCII 
%JL%characters defined in section 3 above.  The relational operators <=, , =<, 
%JR%>, >= and /= have their usual meanings for "num" and "char" parameters, 
%JL%with ASCII ordering for characters.  They are not defined for other types, 
%JR%except for =, which is also defined over structured types.  Functions and 
%JL%types which are not mentioned in the "Hope tutorial" are described in 
section 9 below.



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

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



%H2%%H4%8.   %H1%Error messages%H2%%H4%

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



%H2%%H4%9.   %H1%Additional features%H2%%H4%

%JR%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.

     %H2%type%H2% word == list ( char ) ;

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


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

--- f ( l & ( h :: t ) ) <= %H2%if%H2% h = 10 %H2%then%H2% g ( t ) %H2%else%H2% g ( l ) ;
%P0%
(c)  Mutually recursive types may be declared using "with", e.g.

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


%JR%(d) A restricted form of lazy evaluation is provided by the 'lazy cons' 
%JL%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 )

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


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

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

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











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












%P0%
%H2%%H4%10.  %H1%System commands%H2%%H4%
     
%JR%The interpreter provides a set of commands to assist with program entry, 
%JL%debugging and modification.  All commands start with the command name, 
%JR%followed by zero or more parameters separated by spaces and end with a 
semicolon.


     %H2%display%H2%      causes the interpreter to list the program.

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

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


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

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


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

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


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

%JR%The name of the function is given as the parameter of the command.  There 
%JL%is no way to alter typevar, data or infix priority declarations except by 
editing a saved version of the program and reloading it.
%P0%
%JR%The "modify" command is interactive and all replies may be abbreviated to 
%JL%a single letter, shown by brackets in the message.  The interpreter first 
%JR%displays the function declaration and asks if you want to change it; reply 
%JL%"(y)es" if you do. Other replies are taken as "(n)ext" and the recursion 
%JR%equations are displayed.  You will be prompted for the type part of the 
%JL%declaration.  Terminate the type with a semicolon in the usual way.  When 
%JR%you change a declaration the whole program is re-typechecked when the 
%JL%"modify" command is complete, and type errors may appear for other 
functions.

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

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


     %H2%echo%H2%           controls the listing of loaded programs.

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


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

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


     %H2%notrace%H2%      suppresses the tracing of specified functions.

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


     %H2%time%H2%           controls the timing of programs.

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

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


     %H2%system%H2%         enters an Archimedes operating system command.

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


     %H2%width%H2%         controls the line width for terminal output.

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
















































































































































































































































minus
intersect
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 
size        number of elements in a set






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
%CO:C,12,59%
















































































































































































































































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






identity function printing its argument on the terminal
print a list of characters on the terminal
end-of-line character sequence
open an external file by name and return an input stream
open an external file by name and return an output stream
read a character and advance the input stream
write a character and advance the output stream
write a list of lists of characters to an output stream
close the file associated with a stream
end-of-file character sequence; returned as last character 
of an input file, closes an output file when written.
%CO:D,12,47%%CO:E,12,35%%CO:F,12,23%%CO:G,12,11%