Page Numbers: Yes First Page: 17 X: 527 Y: 10.5"
Margins: Binding: 13
Odd Heading:
Formatter
Even Heading: Not-on-first-page
Formatter
Appendix B: Formatter
The Formatter transforms Mesa source files into a standard format. It establishes the horizontal and vertical spacing of the program in a way which reflects its logical structure.
This appendix describes the formatting rules and the operation of the formatter, including the runtime options and messages.
Preparing Source Files
See this section in Appendix A: Compiler. Since the formatter uses the scanner and parser of the compiler in order to determine structure, only syntactically correct programs may be formatted.
Examples
The formatter takes commands only from the command line: follow "Formatter" with a list of filenames, separated by spaces. For example, the command
>Formatter ProgName
will read the file ProgName.mesa, will copy its old contents to Formatter.scratch$, and will produce a new, plain text, consistently formatted version of ProgName.mesa.
The command
>Formatter ProgName/-tk
will read the file ProgName.mesa and produce a two column landscape listing of the module in the file ProgName.press. The program will be formatted using multiple fonts and faces.
There are numerous other options described below.
Command Line Description
The simplest form of command is just the name of a source file to be formatted. If you supply the command sourcefile with no period and no extension, the formatter assumes you mean sourcefile.mesa.
During formatting, the display is turned off and the compiler’s pass-one die is displayed in the cursor.
The formatter reports the result of each command in Formatter.log with a message having one of the following forms (each * is replaced by an appropriate number; bracketed items appear only when relevant):
file.mesa -- source tokens: *, time: *
Formatting was successful. The source file has been rewritten. The original can be found in Formatter.scratch$. If several files are formatted in the same run, the original of only the last file will be in Formatter.scratch$.
file.mesa -- aborted, * errors [and * warnings] on file.errlog
Formatting was unsuccessful. The output of the formatter is undefined if syntax errors exist in the input file. The original file is undisturbed.
File error
The formatter could not find the specified file.
If any error or warning messages were issued, it brings this to your attention by putting "Type Key" into the cursor. The formatter will not return to the executive or run another subsystem until you acknowledge the message. (You can change this behavior by using switches, described below.)
Formatting rules
General Rule
As a general rule, the Formatter changes only the white space in the program. It does not insert or delete any printing characters. On the other hand, it may insert white space where there previously was none. It does throw away any Bravo formatting in the input file, and only puts it into the output file if asked.
Spacing
Indentation is done by a combination of tabs and spaces in plain-text mode (assuming that a tab equals eight spaces), and by spaces alone in Bravo formatted mode.
The decision as to where to break lines is made independently of the output mode: press file, plain text, or Bravo looks.
A logical unit will be placed on a single line if it fits.
A simple carriage return in the input file is treated as a space. The occurrence of two consecutive carriage returns (a blank line) is preserved in the output file. Three or more consecutive returns (two or more blank lines) result in two blank lines in the output file. Since all Bravo looks are discarded by the scanner, paragraph leading done with looks is not preserved.
For output files that contain fonts and faces (Press or Bravo) these additional rules apply:
Comments are set in italics.
The names of procedures are bold where they are defined.
Reserved words and predeclared identifiers are in Font 1 (or 7).
Font 1 should be smaller than font 0. The fonts Helvetica 10 and Helvetica 8 work well in Bravo mode. For press files, the formatter choses Helvetica 10 and 8 for portrait listings and Helvetica 8 and 6 for landscape listings.
In general there are no spaces before or after atoms containing only special characters. Exceptions to this rule are as follows:
A space or carriage return follows (but does not precede) a comma, semicolon, or colon.
A space precedes a left square bracket when the bracket follows any of the keywords RECORD, MACHINE CODE, PROCEDURE, RETURNS, SIGNAL, PORT, and PROGRAM.
Spaces surround the left-arrow operator.
The exclamation point (enabling) and equal-greater (chooses) operators are always surrounded by spaces. This is also true for equal signs used in initialization and for asterisks used in place of variant record tags.
Some arithmetic operators, depending on their precedence, are surrounded by spaces.
The equivalent of two spaces is used for each level of indenting.
Structure
The formatter determines the indenting structure of the program by the brackets that surround the bodies of compounds. The brackets include {}, (), [], BEGIN-END, DO-ENDLOOP, and FROM-ENDCASE. An attempt is made to maximize the amount of information on a page. For example, consider:
Record: TYPE = RECORD [Record: TYPE = RECORD
field: Type,[
field: Type];field: Type,
field: Type,
];
In both cases, the structure is clear; it is indicated by the indenting, not the placement of the brackets. The formatter generates the form on the left.
The body of each compound, assuming it does not fit on a single line, is indented one nesting level. The placement of the brackets depends on the bracket and on its prefix and its suffix. For example, a loop statement has the following possible prefixes, brackets, and suffixes:
PrefixesBracketsSuffixes
FOR, WHILEDOOPEN
UNTIL, (empty)ENDLOOPENABLE
The following paragraphs contain a number of examples. They observe the following rules for the placement of opening and closing brackets:
The opening brackets {, [, FROM, and DO appear on the same line as their prefixes; BEGIN starts on a new line.
If the remainder of the statement fits on a single line (with its closing bracket), it is placed there, indented one level. Otherwise, all closing brackets except ] and } appear on lines by themselves. If } is preceded by a semicolon, then it is also placed on a line by itself.
The statement following a THEN or ELSE is indented one level, unless it fits on the same line. THEN is on the same line as its matching IF and ELSE is indented the same amount as IF.
IF bool THENIF bool THEN statement
BEGINELSE {body}
body
END
ELSEIF bool THEN {
BEGIN statement;
body statement}
END
The labels of a SELECT (and its terminating ENDCASE) are indented one level, and the statements a second level, unless they fit on the same line with the label.
SELECT tag FROM
case => statement;
case =>
 long statement;
ENDCASE
Each compound BEGIN-END, DO-ENDLOOP, or bracket pair is indented one level. When the rules for IF and SELECT call for indenting a statement, a BEGIN is not indented an extra level.
These rules are not exhaustive, but are intended to give the flavor of the formatter output.
Formatter Switches
Switches allow you to modify command input. A command has the general form
file[/s] {file2[/s] . . .}
where [ ] indicates an optional part and s is a sequence of switch specifications. A switch specification is a letter, identifying the switch, optionally preceded by a ’-’ or ’~’ to reverse its sense. The valid switches are
gdon’t close press file at end of input file
hgenerate a press file (does not force ~t)
kgenerate a two-column landscape press file (does not force ~t)
ppause after formatting if there are errors
rterminate formatting and run the program contained in file
toverwrite input file with plain text formatted version (default)
voverwrite input file with bravo looks using fonts 6 and 7
zoverwrite input file with bravo looks using fonts 0 and 1
Each switch has a default setting, The command sourcefile is equivalent to sourcefile/~g~h~k~p~rt~v~z if you use the standard defaults, i.e., the formatter only generates a plain text file to replace the original source. Note that the "r" switch changes the interpretation of file, which should name a subsystem.
You can change the default setting of any switch by using a global switch. Switches given with no sourcefile establish the default setting. Unless overridden or reset, that default applies to all subsequent commands. See, for example, the multiple program Press output example below.
Some additional information about the options:
gIf a press file is being generated, it is not closed at the end of the current input file. It is expected that another file in the command list will also be generating press file output and a single press file will contain multiple input files. The name of the press file will be that of the first to which press output is being generated. If the type of press file (landscape versus portrait) changes, the first will be closed and another press file will be started. Be careful not to generate a press file larger than will be accepted by your printer.
v, z These switches cause the formatted version of the source file to contain Bravo looks. The "z" switch is intended to be used on a standard Mesa Programming disk that has Helvetica 10 and Helvetica 8 as fonts 0 and 1. The "v" switch uses fonts 6 and 7 and produces output that is more convenient for including in documentation. Indenting is handled slightly differently for Bravo format output files. In plain text mode, indentation is done by a combination of tabs and spaces: the font is assumed to be fixed pitch and the tab is assumed to be 8 times the width of a space. The z switch causes all indentation to be done with spaces only. For v, each level of indentation is done with a single tab.
Examples:
>Formatter foo
Format foo using all the default switch settings (standard or established by a global switch).
>Formatter foo/-tk
Formats foo into a two-column, landscape press file, leaving the original source unchanged.
>Formatter /-tkg ProgA ProgB ProgC ProgD/-g
Produces a two-column, landscape press file ProgA.press that contains listing of all four programs, each starting on a new page.
The r (run) and p (pause) switches have identical semantics as in the compiler.
Formatter Failures
The message reporting a formatter failure has the following form:
FATAL COMPILER ERROR, at id[index]:
(source text)
Pass = 1, signal = s, message = m
Such a message indicates that the formatter has noticed some internal inconsistency. Note that the above message is not a typo, the message comes from a module shared with the compiler. The formatter will skip the remainder of the command line if this happens. If you get such a message (or encounter other formatter problems), you should submit a change request as described in Section 1.8. Be sure to preserve the relevant files and to mention the octal codes identifying the signal (s) and message (m) in your change request. If you were overwriting the input file (i.e. not saying /-t) you can find the original contents of the file in Formatter.scratch$.
Handling of Files by the Formatter
In the absence of fatal errors,
1. The file is copied to Formatter.scratch$,
2. The original file is overwritten while parsing Formatter.scratch$,
3. If no syntax errors, go on to next file, else copy Formatter.scratch$ back onto original source file first.