EDINBURGH REGIONAL COMPUTING CENTRE
9/7/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
Command:OPTION(SEARCHDIR=CONLIB.GENERAL)
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 immaterial.
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
specified.
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.
PARAMETERS
If a user called Soap80 for the first time with the following command
line:
Command:SOAP80(INPUT,OUTPUT,?)
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.
Soap80:
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 comments.
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 %realarrayname.
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 file.
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,
specifying
TAB=3:6 or just TAB=3
is equivalent to
TAB=3:6:9:12:15:18:21:24:.....:54:57:60
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 program.
AUTHOR
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, ERCC.