



          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 32 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


