Page Numbers: Yes First Page: 17 X: 527  Y: 10.5"
Margins: Binding: 13
Odd Heading:x2qjk40(635)
Formattery756qck40\b9B
Even Heading: Not-on-first-pagex2qjk40
Formattery756qck40\b9B
Appendix B: Formattery692x2e36ck108\f5b
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.x2e24jk40(1799)
This appendix describes the formatting rules and the operation of the formatter, including the runtime options and messages.x2e12jk40
Preparing Source Filese24jk60\b22B
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.x2e12jk40\20b20B
Examplese24jk60\b8B
The formatter takes commands only from the command line:  follow "Formatter" with a list of filenames, separated by spaces.  For example, the commandx2e12jk40\66f8 9f0
>Formatter ProgNamel4269x2e12jk40\f8 19f0
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.x2e12jk40\19f8 13f0 32f8 18f0 72f8 13f0
The commandx2e12jk40
>Formatter ProgName/-tkl4269x2e12jk40\f8 23f0
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.x2e12jk40\19f8 13f0 70f8 14f0
There are numerous other options described below.x2e12jk40
Command Line Descriptione24jk60\b24B
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.x2e12jk40\107f8 10f0 65f8 15f0
During formatting, the display is turned off and the compiler's pass-one die is displayed in the cursor.x2e12jk40
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):x2e12jk40\52f8 13f0
file.mesa -- source tokens: *, time: *l3528x2e12jk40\i4f8I24f0 1f8 8f0 1f8
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$.l4269x2e12jk40\94f8 18f0 97f8 18f0 1f8
file.mesa -- aborted, * errors [and * warnings] on file.errlogl3528x2e12jk40\i4f8I18f0 1f8 13f0 1f8 14f0i4f8I
Formatting was unsuccessful.  The output of the formatter is undefined if syntax errors exist in the input file.  The original file is undisturbed.l4269x2e12jk40\112f8 2f0 33f8
File errorl3528x2e12jk40\f8
The formatter could not find the specified file.l4269x2e12jk40\48f8
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.)x2e12jk40
Formatting rulese24jk60\b16B
General Rulee12jk60\i12I
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.x2e12jk40
Spacinge24jk60\i7I
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.x2e12jk40
The decision as to where to break lines is made independently of the output mode: press file, plain text, or Bravo looks.x2e18jk40
A logical unit will be placed on a single line if it fits.x2e18jk40
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.x2e12jk40
For output files that contain fonts and faces (Press or Bravo) these additional rules apply:x2e18jk40
Comments are set in italics.l4268x2e6jk40
The names of procedures are bold where they are defined.l4268x2e6jk40
Reserved words and predeclared identifiers are in Font 1 (or 7).l4268x2e6jk40
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.l4268x2e6jk40
In general there are no spaces before or after atoms containing only special characters.  Exceptions to this rule are as follows:x2e18jk40
A space or carriage return follows (but does not precede) a comma, semicolon, or colon.l4268x2e6jk40
A space precedes a left square bracket when the bracket follows any of the keywords RECORD, MACHINE CODE, PROCEDURE, RETURNS, SIGNAL, PORT, and PROGRAM.l4268x2e6jk40\84f7 6f0 2f7 12f0 2f7 9f0 2f7 7f0 2f7 6f0 2f7 4f0 6f7 7f0
Spaces surround the left-arrow operator.l4268x2e6jk40
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.l4268x2e6jk40
Some arithmetic operators, depending on their precedence, are surrounded by spaces.l4268x2e6jk40
The equivalent of two spaces is used for each level of indenting.x2e18jk40
Structuree24jk60\i9I
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:x2e12jk40\141f6b2f0B2f6b2f0B2f6b2B1f0 1f7 5f0 1f7 3f0 2f7 2f0 1f7 7f0 6f7 4f0 1f7 7f0
	Record: TYPE = RECORD [	Record: TYPE = RECORD
		field: Type,		[
		field: Type];		field: Type,
				field: Type,
				];x2e12jk40(0,5292)(1,5792)(2,12347)(4,12841)\1f6b8f7B4f6b3f7B6f6b11f7B4f6b3f7B6f0 1f6b
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.x2e18jk40(1799)
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:x2e12jk40
	Prefixes	Brackets	Suffixes
	FOR, WHILE	DO	OPEN
	UNTIL, (empty)	ENDLOOP	ENABLEx2e12jk40(0,5292)(1,8819)(4,65535)\1u8U1u8U1u8U2f7 3f0 2f7 5f0 1f7 2f0 1f7 4f0 2f7 5f0 10f7 7f0 1f7 6f0
The following paragraphs contain a number of examples.  They observe the following rules for the placement of opening and closing brackets:x2e12jk40(1799)
The opening brackets {, [, FROM, and DO appear on the same line as their prefixes; BEGIN starts on a new line.l4268x2e6jk40\21f6b1f0B2f6b1f0B2f7 4f0 6f7 2f0 44f7 5f0
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.l4268x2e6jk40\164f6b1f0B5f6b1f0B36f6b1f0B
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.x2e12jk40\26f7 4f0 4f7 4f0 58f7 4f0 37f7 2f0 5f7 4f0 32f7 2f0
	IF bool THEN	IF bool THEN statement
		BEGIN	ELSE {body}
		body
		END
	ELSE	IF bool THEN {
		BEGIN	  statement;
		body	  statement}
		ENDx2e12jk40(0,5292)(1,5792)(2,8832)\1f7 2f0 1f6b4f0B1f7 4f0 1f7 2f0 1f6b4f0B1f7 4f0 1f6b9f0B3f7 5f0 1f7 4f0 1f6b7f0B2f6b4f0B3f7 3f0 2f7 4f0 1f7 2f0 1f6b4f0B1f7 4f0 1f6b1f0B3f7 5f0 3f6b31f0B2f7 3f0
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.x2e12jk40(1799)\16f7 6f0 22f7 7f0
	SELECT tag FROM
		case => statement;
		case =>
		  long statement;
		ENDCASEx2e12jk40(0,5292)\1f7 6f0 1f6b3f0B1f7 4f0 3f6b4f0B4f6b11f0B2f6b4f0B8f6b16f0B2f7 7f0
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.x2e12jk40(1799)\14f7 5f0 1f7 3f0 2f7 2f0 1f7 7f0 61f7 2f0 5f7 6f0 35f7 5f0
These rules are not exhaustive, but are intended to give the flavor of the formatter output.x2e12jk40
Formatter Switchese24jk60\b18B
Switches allow you to modify command input.  A command has the general formx2e12jk40
	file[/s] {file2[/s] . . .}x2e6jk40\f8
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 arex2e6jk40\41f6 1f0 128f8 1f0 6f8 1f0
g		don't close press file at end of input file
h		generate a press file (does not force ~t)
k		generate a two-column landscape press file (does not force ~t)
p		pause after formatting if there are errors
r		terminate formatting and run the program contained in file
t		overwrite input file with plain text formatted version (default)
v		overwrite input file with bravo looks using fonts 6 and 7
z		overwrite input file with bravo looks using fonts 0 and 1l4269x2e12jk40\f8 1f0t1 1t0 45f8 1f0t1 1t0 29i3I7f8 2f0 2f8 1f0t1 1t0 50i3I7f8 2f0 2f8 1f0t1 1t0 44f8 1f0t1 1t0 55f8 4f0 1f8 1f0t1 1t0 66f8 1f0t1 1t0 59f8 1f0t1 1t0
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.x2e12jk40\48f8 10f0 18f8 26f0 136f8 1f0 39f8 4f0
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.x2e12jk40
Some additional information about the options:x2e12jk40
g	If 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.l4704d3520x2e12jk40(0,4704)(1,65535)(2,65535)\f8 2f0 556i1I
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.l4704d3520x2e12jk40\f8 4t1 2f0t0
Examples:x2e12jk40(1799)
>Formatter fool3528x2e12jk60\f8 14f0
Format foo using all the default switch settings (standard or established by a global switch).l4268x2e6jk40\7f8 3f0
>Formatter foo/-tkl3528x2e12jk60\f8 18f0
Formats foo into a two-column, landscape press file, leaving the original source unchanged.l4268x2e6jk40\8f8 3f0
>Formatter /-tkg ProgA ProgB ProgC ProgD/-g l3528x2e12jk60\f8
Produces a two-column, landscape press file ProgA.press that contains listing of all four programs, each starting on a new page.l4268x2e6jk40\44f8 11f0
The r (run) and p (pause) switches have identical semantics as in the compiler.x2e12jk60(2116)\4f8 1f0 11f8 2f0 60f1
Formatter Failurese24jk60(1799)\b18B
The message reporting a formatter failure has the following form:x2e12jk40
FATAL COMPILER ERROR, at id[index]:
  (source text)
Pass = 1, signal = s, message = ml3528x2e12jk60(2116)\f8 25f0i2f8I1f0i5f8I5f0i12f8I4f0 10f8 7f0i1f8I12f0i1f8I
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$.x2e12jk40(1799)\86f1 102f0 194b11B97i1I15i1I83f8 3f0 52f8 18f0
Handling of Files by the Formatterx2e24jk72\b34B
In the absence of fatal errors, x2e12jk40
1. The file is copied to Formatter.scratch$,l4269x2e6jk40\25f8 18f0 1f8
2. The original file is overwritten while parsing Formatter.scratch$,l4269x2e6jk40\50f8 18f0
3. If no syntax errors, go on to next file, else copy Formatter.scratch$ back onto original source file first.l4269x2e6jk40\54f8 18f0