.NA "SOAP80 - An IMP80 program formatter" "R.D. Eager" .HD August 1982 DOC/EMAS/K3.1/3 .RV "December 1982 (1)" .KE "IMP80,PROGRAM FORMATTING,SOAP,SOAP80" .S1 Introduction .PG 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. .S1 "Access" .PG Before SOAP80 can be used for the first time, the following command must be issued: .sp .CP INSERT(CONLIB.SOAP80Y) .EC .sp This need only be done once. .S1 "Using SOAP80" .PG The form of a call of SOAP80 is as follows: .sp .CP 5 SOAP80(input,output,options) .EC .sp .LB .LP "input" is the name of the character file containing the IMP80 program to be formatted. It must be given, and the file must exist. .sp .LP "output" 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. .sp .LP "options" relates 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 .sp .CP \&...,option name=setting,... .EC .PG Any of the options can be changed in this way; the order of specification is immaterial. .LE .PG 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. .PG 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. .PG 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 .sp .CP option name=? .EC .sp In this case SOAP80 responds with the current setting of the option specified. .PG There are 15 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. .PG 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. .S1 "Parameters" .PG If a user called SOAP80 for the first time with the following command line: .sp .CP SOAP80(INPUT,OUTPUT,?) .EC .sp SOAP80 would first check for the existence of file INPUT, and then print: .sp .CP 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: .EC .sp 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. .PG The details of the options listed above are as follows: .sp .LB .LP LINE (Default:\ 80) The maximum LINE length used in the output. Any value in the range [30-160] is permitted. .sp .LP 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. .sp .LP 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. .LE .sp All the other options, apart from TAB, have the values 'Yes' or 'No'. .sp .LB .LP MOVECOM (Default:\ Yes) 'Yes' means MOVE whole-line COMments to the column position specified by POSCOM (see above). .br \&'No' means that whole-line comments are indented to the current left-hand margin. .br 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. .sp .LP UCKEY (Default:\ Yes) 'Yes' means that KEYwords are given in Upper Case in the output file. .br \&'No' means that keywords are given in lower case in the output file. .sp .LP 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. .br \&'No' means that any adjacent keywords in the program are compounded in the output file; thus %real\ %array\ %name is given as %realarrayname. .sp .LP 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. .br \&'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. .sp .LP 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. .sp .LP SPACASS (Default:\ Yes) 'Yes' means that a SPACe character is given before and after every ASSignment operator ('=', '->', '<-', '=='). .br \&'No' means that such operators are not surrounded by spaces in the output file. .sp .LP 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). .br \&'No' means that such operators are not surrounded by spaces in the output file. .sp .LP 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. .br \&'No' means that such lists are formatted, in accordance with the prevailing left hand margin, etc. .sp .LP 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. .br \&'No' means that the contents of each block are aligned with the block's first line. .sp .LP 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. .br \&'No' means that the executable statements in a block are aligned with the declaration statements. .sp .LP SEPLAB (Default:\ No) 'Yes' means that each LABel is SEParated from the statement which it labels by being placed on a line by itself. .br \&'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. .sp .LP 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. .br \&'No' means that commas are not followed by a space character. .sp .LP TAB (Default:\ 3:6:9:12:15:18:21:24:27:30:35:40:45:50:55:60:65:70:75:80) .br 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. Thus, specifying .sp .CP TAB=3:6 or just TAB=3 .EC .sp is equivalent to specifying .sp .CP TAB=3:6:9:12:15:18:21:24:.....:54:57:60 .EC .LE .S1 "Error messages" .PG 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. .S1 "Acknowledgements" .PG SOAP80 was written by E.N. Gregory, University of Kent at Canterbury. The syntax directed sections were rewritten by P.D. Stephens of Edinburgh Regional Computing Centre. The user interface was modified by J.M. Murison, also of ERCC. This document is based on one written by J.M. Murison.