Revised 6/12/82

                               Soap80: A Program for Formatting IMP80 Source Programs

                    Soap80 is a program for formatting IMP80 source programs.  It takes as input
                    a character file (the IMP80 source program), and produces from it another
                    character file (an exactly equivalent IMP80 source program).  The precise
                    format of each IMP80 statement in the output file is determined by various
                    options; for example, there is an option, SEPKEY, whose setting determines
                    whether compound keywords like %integerfnspec are to be separated into their
                    component keywords - %integer %fn %spec - or left unchanged.  The complete
                    set of options and their meanings are given below.

                    Soap80 is accessible via directory CONLIB.GENERAL.  Thus it is necessary to
                    give the command


                    before calling it.  This need only be done once.

                    The form of a call of Soap80 is as follows:

                               Command:SOAP80(input file, output file, option settings)

                    'input file' is the name of the character file containing the IMP80 program
                    to be formatted.  It must be given, and the file must exist.

                    'output file' is the name of the output file which is to contain the
                    formatted program.  An output device can also be specified.  If an output
                    file is not specified then the input file is overwritten by the output,
                    unless Soap80 detects syntax errors in the input source program, in which
                    case the output is left in a workfile whose name is given in a message
                    printed on the user's terminal.

                    'option settings' relate to the setting of the program options referred to
                    above.  Each of these options has a preselected setting, and if this setting
                    is satisfactory then no action regarding the option need be taken by the
                    user.  Where the preselected setting is not satisfactory, the user can
                    change it by specifying the desired setting in the format

                                  ...,option name=setting,...

                    Any of the options can be changed in this way; the order of specification is

                    The user can ask Soap80 to prompt him for option settings, instead of (or as
                    well as) giving them in the command line.  If the list of option settings is
                    terminated by an asterisk, or consists solely of an asterisk, then Soap80
                    will prompt the user for further option settings.  Each should be given on a
                    separate line.  The prompt will then be repeated.  When all the desired
                    option settings have been given the user should respond to the next prompt
                    with END or GO, when Soap80 will proceed to generate the output file.  The
                    user can also reply with STOP, which causes Soap80 to terminate immediately,
                    i.e. without generating an output file.

                    If the list of option settings given with the call of Soap80 is terminated
                    by a question mark, or consists solely of a question mark, then Soap80
                    starts by printing out a complete list of options together with their
                    settings and the meaning of these settings.  Thereafter it prompts the user
                    for option settings, as described above.

                    When the user is prompted by Soap80 for an option setting, he can instead
                    reply with a question mark.  This causes Soap80, as before, to print out
                    details of the current settings of all the options.  Another possible reply
                    from the user is of the form

                                     option name=?

                    In this case Soap80 responds with the current setting of the option

                    There are 14 options in total, and it is extremely tedious to change more
                    than a few of them.  For this reason a facility is provided whereby the user
                    can define, for his own personal use of Soap80, the preselected settings of
                    the options.  He does this by changing the option settings as he wishes,
                    then replying to the next prompt with SAVE.  This causes the current
                    settings of all the options to be copied to a file, SS#PROFILE, in his own
                    process.  He can then proceed as before, i.e. giving further option settings
                    or specifying END or GO or STOP.  Thereafter, whenever he invokes Soap80,
                    the options will be set automatically to the values which were saved.  He
                    can later change his mind about the best initial values for the options, by
                    using SAVE again.  Only the latest set of saved values is used by Soap80.

                    If prompting for input is not selected by the user, Soap80 starts processing
                    the input file as soon as the command line has been analysed.


                    If a user called Soap80 for the first time with the following command line:


                    Soap80 would first check for the existence of file INPUT and then print:

                            Option name:{current setting}Meaning of current setting

                            LINE   :{80}Maximum line length
                            ICONTIN:{3}Indentation of continued lines
                            POSCOM :{41}Right hand comment position
                            MOVECOM:{Y}Whole line comments moved to POSCOM
                            UCKEY  :{Y}Keywords output in upper case
                            SEPKEY :{N}Keywords not split
                            LCASNAM:{Y}Case of names left alone
                            SPACNAM:{Y}Spaces preserved within names
                            SPACASS:{Y}Spaces added round assignment operators
                            SPACOP :{N}No spaces round operators
                            LCLIST :{Y}Constant lists left alone
                            IBLOCK :{Y}Block indented w.r.t. block heading
                            ISTAT  :{N}Statements aligned with declarations
                            SEPLAB :{N}Labels not on lines by themselves
                            SPCOMMA:{N}No space character after commas
                            TAB    :{3:6:9:12:15:18:21:24:27:30:35:40:45:50:55:60:65:70:75:80}
                                    Indenting values
                            Other valid responses:
                            SAVE     : Save current option settings, for defaults henceforth.
                            GO or END: Cause SOAP80 to start processing the input.
                            STOP     : Cause SOAP80 to stop immediately.
                    This output gives the initial settings, and the names of all the options.
                    The last line is the prompt for option settings from the user.

                    The details of the options listed above are as follows:

                    LINE    (Default: 80) The maximum LINE length used in the output.  Any value
                            in the range [30-160] is permitted.

                    ICONTIN (Default: 3) The Indentation of CONTINued statements, i.e. the
                            number of column positions by which the text of a continued line is
                            indented with respect to the current left hand margin.

                    POSCOM  (Default: 41) The POSition of right hand COMments, i.e. the column
                            at which comments following statements on a line are positioned, if
                            the text on the output line has not yet reached that position.
                            Setting POSCOM to 1 effectively suppresses the movement of such

                    All the other options, apart from TAB, have the values 'Yes' or 'No'.

                    MOVECOM (Default: Yes) 'Yes' means MOVE whole-line COMments to the column
                            position specified by POSCOM (see above).
                            'No' means that whole-line comments are indented to the current
                            left-hand margin.
                            Note that comments starting in column 1 in the input file are always
                            placed in column 1 in the output file - they are never indented.

                    UCKEY   (Default: Yes) 'Yes' means that KEYwords are given in Upper Case in
                            the output file.
                            'No' means that keywords are given in lower case in the output file.

                    SEPKEY  (Default: No) 'Yes' means that compound KEYwords are SEParated into
                            their component parts in the output file; thus %realarrayname is
                            given as %real %array %name.
                            'No' means that any adjacent keywords in the program are compounded
                            in the output file; thus %real %array %name is given as

                    LCASNAM (Default: Yes) 'Yes' means 'Leave CASe of NAMes', i.e. the case of
                            letters in names in the output will be the same as in the input.
                            'No' means that the case of letters of names in the output file is
                            determined by UCKEY, i.e. they will be the same as the keywords.

                    SPACNAM (Default: Yes) 'Yes' means that SPACes within NAMes in the input
                            file are preserved in the output file.
                            'No' means that such spaces are not preserved in the output file.

                    SPACASS (Default: Yes) 'Yes' means that a SPACe character is given before
                            and after every ASSignment operator ('=', '->', '<-', '==').
                            'No' means that such operators are not surrounded by spaces in the
                            output file.

                    SPACOP  (Default: No) 'Yes' means that a SPACe character is given before and
                            after every OPerator (apart from assignment operators, which are
                            controlled by SPACASS).
                            'No' means that such operators are not surrounded by spaces in the
                            output file.

                    LCLIST  (Default: Yes) 'Yes' means 'Leave Constant LISTs', i.e. lists of
                            constant expressions used to initialise %own or %constant arrays are
                            transferred unchanged from the input to the output.
                            'No' means that such lists are formatted, in accordance with the
                            prevailing left hand margin, etc.

                    IBLOCK  (Default: Yes) 'Yes' means that the contents of each BLOCK are
                            Indented by one tab position with respect to its first line (which
                            is %begin, or a procedure heading).  The actual indentation is
                            determined by the setting of the TAB option, described below.
                            Declarations at the outermost level of a block are always placed in
                            accordance with this option.
                            'No' means that the contents of each block are aligned with the
                            block's first line.

                    ISTAT   (Default: No) 'Yes' means that the executable STATements in a block
                            are Indented by one tab position with respect to the position of
                            declaration statements within the block.  The actual indentation is
                            determined by the setting of the TAB parameter, described below.
                            'No' means that the executable statements in a block are aligned
                            with the declaration statements.

                    SEPLAB  (Default: No) 'Yes' means that each LABel is SEParated from the
                            statement which it labels by being placed on a line by itself.
                            'No' means that a label is followed, on the same line, by the next
                            statement of the program, if that is how it is given in the input

                    SPCOMMA (Default: No) 'Yes' means that a SPace character is given after
                            every COMMA in the program, apart from those within comments or
                            string or symbol constants.
                            'No' means that commas are not followed by a space character.

                    TAB     (Default: 3:6:9:12:15:18:21:24:27:30:35:40:45:50:55:60:65:70:75:80)
                            This option is made up of 20 column positions, in ascending order.
                            It is used by Soap80 whenever it needs to indent a line with respect
                            to the previous line.  This is always done within %cycle/%repeat and
                            %start/%finish and is optionally done within blocks and procedures,
                            depending on the values of the options IBLOCK and ISTAT.
                            When tab values are specified by the user they must be separated by
                            colons.  Fewer than 20 values may be given, in which case the
                            remainder are calculated by extrapolation, up to the existing line
                            limit; thereafter, values are fixed at the line limit.  Thus,
                                              TAB=3:6    or just    TAB=3
                            is equivalent to

                    Error messages

                    The error messages produced by Soap80 are self-explanatory.  Note that most
                    problems in the use of Soap80 are caused by syntax faults in the given


                    Soap80 was written by E.N. Gregory, University of Kent at Canterbury.
                    The syntax directed sections were rewritten by P.D. Stephens, ERCC.
                    The user interface was modified and this document written by J.M. Murison,