PASMAT User Manual PAScal source-text reforMATer A Public-Domain Program Pascal MT+ Version 1. Introduction. Pasmat is a utility which reformats a Pascal source program into a standard format. Its features include: a. The program may be converted to uniform case conventions. This is under the control of the user. b. The program is indented to show its logical structure, and will be fitted into a specified output line length. c. Comment delimiters are all changed to '{ }'. d. If requested, underscore characters will be removed from the identifiers for use on systems which do not support them. e. All non-printing characters except for tabs are removed, and the hi-bit of all characters is turned off. This can be useful after glitches with some editors -- notably when using WordStar. The user has considerable control over the form of the output using "formatter directives" inserted in a special form of Pascal comment. Pasmat accepts full programs, modules, single procedures, and groups of statments. It may complain about arbitrary collections of program fragments, such as incomplete procedures. When a syntax error is detected, Pasmat copies the remainder of the file unchanged to the output. Pasmat accepts all of standard Pascal, plus the extensions of Pascal MT+. 2. Formatting Details. In general, the formatting is straightforward, and requires no control from the user. The best way to find out how Pasmat formats something is to try it out and see. There are, however, some ways in which the user can affect the formatting rules, and this sections covers them. 2.1 Comments. Comments in Pascal are hard to format, and Pasmat tries to be clever about it. The rules should allow you to use comments to achieve almost any effect you would like, but you do have to know the rules. If you find that Pasmat scrambles your comments, re- read this section. .CP2 a. A comment which stands alone on a single line will be passed to the output unaltered. It will have its left end set to the current indentation level, so that it will be aligned with the statements before and after it. If it is too long to fit with this alignment, it will be placed on the page as far right as it will go. b. A comment which begins as the first thing on a line, and continues on another line, will be passed to the output unaltered, including the indentation. This type of comment (a "block comment") is assumed to be carefully formatted by the author, and so is untouched. c. If a comment which is covered by one of the above rules will not fit within the defined output line length, the output line will be extended as necessary to accomodate the comment and a message will be written at the end of the formatting. d. A comment which is not the first thing on a line will be formatted in with the rest of the code. Words within it will be moved around freely to make it fit, so nothing which has a fixed format may be used in such a comment. Such a comment will be broken only at blanks, and if there is no way to break a comment and still fit the output within the output line length, that line will be extended as necessary, and a message written at the end of the formatting. 2.2 Statement Bunching. The normal formatting rules for a "case" statment place the selected statments on a separate line from the case labels. The "B" directive (see below) tells the formatter to place these statements on the same line as the case labels if it will fit. Similarly, the rules for "if-then-else" place the controlled statements on separate lines. The "B" directive tells the for matter to place the controlled statements on the same line as the "then" or "else" if it will fit. 2.3 Tables. In many Pascal programs there are long lists of initialization statments or constant declarations which are logically a single action or declaration. The author may want to fit them into as few lines as possible. The "S" directive (see below) allows this. If this is used, the equivalent of tab stops are set up on the line, and successive statments or constant declarations are aligned to these tab stops instead of beginning on new lines. There will always be at least one blank between statements or constant declarations, so if tab stops are set up at every char acter location, statements will be packed on a line. Structured statements which normally format on more than one line will not be affected by this directive. 3. Usage. Pasmat is invoked as follows: pasmat is the original Pascal source file name and extension, with optional drive specifier, in normal CP/M fashion. This file will remain unchanged. is the name and extension (and optional drive speci fier) of the file to which to write the reformatted output. It must not be the same as the input file name, or the file will be lost. are any directives to be initially supplied to Pasmat. No special characters (except an initial blank) are needed to separate the options from the file names. The enclosing brackets used in the text (see below) are not needed. Blanks may be used if desired to separate options, but not within an option. Example: A>pasmat myprog.src b:myprog.new b+r- o=72 This will use myprog.src from the default drive as input, producing a file on drive B called myprog.new which contains the reformatted program. The B option is turned on, the R options is turned off, and the O option is set to 72. 4. Directives. Directives can be supplied on the command line as above, and can be included in the text in special comments. The special com ments have the form: {[directives] text} or {$ text [directives] text} The directives themselves are either switches or numeric. Switch directives consist of an uppercase or lowercase letter immediately followed by a '+' or '-'. Examples: B+, r- Numeric directives consist of an uppercase or lowercase letter, an optional '=', and a number. Examples: O=72, s=2, t4 Multiple directives may be separated by commas or blanks, but blanks are not allowed within a directive. Portions of a direc tive which are malformed or unrecognized are quietly ignored. .CP4 Examples: {[b+] turn on statement bunching} {[o=79, s2] make line width 79, 2 statements per line} {$P eject a page [r+] make reserved words uppercase} But not: {this will not be recognized [o=79] due to initial text} The recognized directives are as follows: B (Default B-) B+ specifies that the statement following a "then" or "else" or case label will be put on the same line if it will fit. This makes a smaller output file. Some find it easier to read, some don't. It is harder to make corrections. C (Numeric, default C=1) This specifies the number of blanks preceding and following inline comments. If there is not enough room on a given line for C spaces preceding the comment, T spaces will be used (see below). F (Default F+) Turns formatting on (+) or off (-), commencing on the line after the directive in which it is placed. This is useful for preserving carefully hand-formatted sections of a program. L (Default L-) L+ specifies that the case of reserved words and identifiers is a literal copy of the input. This over rides the 'R' and 'U' directives. This directive is dis abled by the 'P' directive. O (Numeric, default O=72) This specifies the width of the output line. The maximum value allowed is 132 characters. If a particular item will not fit in this width, that line will be widened and a warning message will be issued. P (Default P-) P+ specifies "portability mode" formatting, which removes underscore (_) characters from identifiers. The first letter of each identifier, and the first letter following each underscore will be in uppercase. The remain ing characters will be in lowercase. This overrides the 'L' and 'U' directives. The case of reserved words is unaf fected by 'P' (it is set with 'R'). Q (Default Q-) Q+ specifies quiet mode, in which all console messages are suppressed, including all error messages. This is useful in detached mode under MP/M. R (Default R-) R+ specifies that all reserved words will be in all uppercase. R- sets all reserved words to lowercase. S (Numeric, default S=1) Specifies the number of statements per line. The space from the current indentation level to the end of the line is divided into equal pieces, and suc cessive statements are started at the boundary of a piece (like tabbing on a typewriter). A statement which will not fit on one line will not be affected, but the following statements may look strange. This directive affects only the constant declaration and statement portions of a pro gram, and is intended for use in intializing variables. T (Numeric, default T=2) Specifies the amount to "tab" for each indentation level. Statements which continue on successive lines will be additionally indented by half this amount. U (Default U-) U+ specifies that identifiers are converted to uppercase. They will otherwise be converted to lowercase. This directive is overridden by the 'L' and 'P' directive. 5. Limitations. a. Maximum input line length is 132 characters. b. Maximum output line length is 132 characters. c. Only syntactically correct programs can be formatted. d. Input files are currently limited to 32K bytes. Larger files will cause an internal counter to overflow and ter rible things to happen. 6. Errors Detected and Reported. a. Any detected syntax error in the code will cause the format ting to abort, with a message to the console. The remainder of the file will be copied unchanged. The syntax checking is not complete, meaning that Pasmat will allow some things that the compiler will not. If possible, use the syntax checker in the Speed Programming Package to verify syntax before running Pasmat, to avoid formatter aborts. b. There is a limit to the number of indentation levels Pasmat can handle, but it should be able to handle anything that Pascal MT+ can handle. If the limit is exceeded, processing will be aborted. This should never happen. c. If a comment would require more than the maximum output line length (132), processing will be aborted. This should never happen. d. If a token (identifier or string) is too long for the output line length, the length will be extended for that line. A message will written to the console at the end of processing giving the number of times this occurred and the line number of the first occurrence. e. If a comment line is extended according to rule "c" in the comments section above, a message will be written to the console at the end of the formatting giving the number of times this occurred and the output line number of the first occurrence.