Turbo Pascal Formatter V3.3 Distribution is with the kind permission of Oregon Software who wrote the original version of the program on which this version is based. This software may be copied and distributed provided that this notice is included and no charge is made other than reasonable media costs. The source is provided on an 'as is' basis, and no warranty is either given or implied. No responsibility is accepted for any damage done to programs or data or any other consequential loss caused either directly or indirectly as a result of using this software. I would be pleased to hear of any bugs, solutions, or suggested enhancements at the address below. Chris Sharman, CCA Stationery, Eastway, Fulwood, Preston, Lancs, ENGLAND Version There is a /VERSION qualifier which may be used instead of all the parameters and qualifiers listed below. It causes PASMAT to identify itself. Command Line Parameters and Qualifiers There is one parameter: the input file spec. This may be a list and/or contain wildcards. This parameter is required. Use the qualifier /OUTPUT=filespec to specify the output file. The default will be a file of the same name and type as the input file, in the current default directory. This qualifier may be specified on the input file (in which case it is effective only for that input file, not others in the list), or on the verb (where it is effective for all other input files). Wildcards are not allowed on the output filespec. You may also specify /NOOUTPUT. You may use the qualifier /LISTING if you wish to specify a different listing file name. /LISTING will be enabled or disabled according to the setting of /SOURCE and /CROSS__REFERENCE. You may use the qualifier /OPTIONS="[options]" to control the format (for the syntax see below). The placement of this qualifier is identical to that for the /OUTPUT qualifier. Using /OPTIONS overrides the qualifiers below. /FETCH forces the formatter to attempt to read any units which are used if they have not yet been processed. Default = TRUE. This makes /UNITS more or less redundant. No output or listing files are generated for units read in this way. Units and include files are read from TURBO_AREA (= TURBO_PATH, TURBO_SYSTEM). TURBO_DIR is defined to be the directory which the main input file being formatted was read from. To add directories to be searched, define TURBO_PATH yourself. Defining TURBO_AREA, TURBO_SYSTEM, or TURBO_DIR is not recommended. The default is SYS$DISK:,TURBO_DIR: - this matches the V3.2 behaviour. The rest of the qualifiers affect all the input files, no matter where they are placed. /PAGE - controls the listing file page size. Default is width 132, length 60. Specify /PAGE=(WIDTH=80,LENGTH=24) or /PAGE=NOLEN or whatever. Minimum length is 20 - less than this gets a continuous listing (like NOLENGTH). NB: If a source listing is requested, this will contain the lines exactly as read from the source file, including form feeds, extra long lines, etc. /SOURCE - generates a source listing in the listing file. Default = FALSE. Note that this is a listing of the INPUT, NOT the OUTPUT. /CROSS_REFERENCE - generates cross-reference tables in the listing file. If this is specified then units will be preprocessed. This qualifier accepts a list of keywords. Default = FALSE. If just /CROSS_REFERENCE is specified then the default is /CROSS_REFERENCE=(VARIABLES,ROUTINES). /CROSS_REFERENCE keywords: NONE - equivalent to /NOCROSS_REFERENCE. CONSTANTS VARIABLES LABELS TYPES ROUTINES ALL - all the above keywords. A valid use would be /CROSS=(ALL,NOLAB,NOTYPE). /SHOW_STATISTICS - displays a line after each file and after all files showing PASMAT performance statistics. /DEBUG - primarily intended for debugging PASMAT itself, this enables certain messages during processing, and prevents deletion of the output file on detection of a syntax error. The output file has the type .PASMAT_TEMPORARY. /INCLUDE - read include files. If no device/directory is specified then the search list TURBO_AREA is used. If a relative dirspec is used, it must be relative to the current default. If an explicit dirspec is used, and no disk is specified, PCDisk: is used. If a PC (single-character) drive is specified then PCDisk_x: is used, where x is the name of the drive. PC style file specs (containing "\") are translated automatically. It is the users' responsibility to define PCDisk and PCDisk_x as appropriate. The default definition is: $ define PCDisk disk$app_disk:[pccommon.]/tran=conc Note the trailing "." - this is essential. /ADJUST_SPELLING - all identifiers are spelt as they first appear (ie in the same case). This overrides /LITERAL. Default = FALSE. /BUNCH_STATEMENT - the statement following a THEN, ELSE, FOR, WITH, WHILE, or CASE label is placed on the same line if there is room. Default = TRUE. /CAPITALIZE_IDENTIFIER - identifiers have their first character capitalized and the rest in lowercase. Default = FALSE. /COMMENT_INDENT - comments on separate lines are indented to match the rest of the block they are in, as opposed to being pushed to the left margin. Default = FALSE. /CONVERT_TO_TABS - leading spaces are converted to tabs where possible. Default = TRUE. /FORMAT - formatting is done. Default = TRUE. /LITERAL - the case of identifiers and reserved words is not changed. This overrides /RESERVED_UPPER, /UPPER_IDENTIFIER, and /CAPITALIZE_IDENTIFIER. Default = FALSE. /NEW_LINES - inserts new lines as required by formatting. Default = TRUE. /PARAMETER_ALIGN_NAMES - aligns parameter names in a procedure declaration, instead of aligning the parameter declaration. This means that VAR and value parameters are aligned differently. Default = TRUE. /RESERVED_UPPER - reserved words are uppercase. Default = TRUE. /STANDARD - converts alternate symbols to standard form (eg (* becomes {). Default = TRUE. /STATEMENTS_PER_LINE=number - puts up to the given number of statements on each line if they fit. Default = 1. /TABSPACES=number - uses the given number of spaces for each indentation. Default = 4. /IDENTIFIER_UPPER - identifiers are uppercase. Default = lowercase. /VARIABLE_BUNCH - in declaration, list identifiers on a single line if they fit. The alternative is to list one per line. Default = TRUE. /WIDTH=number - sets the output width. Default = 80, Max = 132. Options syntax The options syntax is a string enclosed in square brackets, either on the command line or embedded in a comment. If options are embedded in comments in the program, they may not be overridden on the command line, which defeats the object of a formatter. Each option is specified by a letter, followed by either + to turn the option on, - to turn it off, or =number to change the value. The letters correspond to the qualifiers as follows: b : Bunch statement c : Convert to tabs f : Formatting m : Standard n : No new lines o : Width r : Reserved upper s : Statements per line t : Tab spaces Usage If you want cross-reference information generated for most or all units in an image, specifying a unit before all its users on the command line will save it having to be read twice. If you prefer your files formatted differently, you can set up a symbol to invoke TPMAT with your favourite qualifiers by putting: $ MYTPMAT :== 'TPMAT'/DEBUG/SHOW or whatever into your LOGIN.COM. However you should always put files back into the standard format by running TPMAT without qualifiers before replacing them in CMS libraries. Failure to do this will result in a serious overhead when using CMS, as it keeps a list of changed lines for each version. Examples $ TPMAT file1/OUT=.pasmat,file2 This will format file1 (output file1.pasmat), then file2 (output file2.pas). Any errors on file1 will not affect file2. $ TPMAT/OUT=.pasmat file1,file2 As above, except both output files will have a file type .pasmat. $ TPMAT a*,b* All files with type .pas beginning with a or b will be formatted. PASMAT will continue with the next file in the event of an error. Known Problems and Restrictions The formatter will not detect all syntax errors in a Pascal program. In particular, it cannot tell a constant (compile-time) expression from one which must be calculated at run-time. It is also fairly relaxed about missing semicolons. The formatter does not recognise character constants of the form ^C. This format is not documented in Turbo so use the #n notation which is supported. The cross-referencer does not fully understand type-casts. If a variable is 'cast' into a type which contains a record, and record fields are referenced, they will be reported as unknown. The cross-referencer correctly handles record constants in assignment statements and in constant declarations. However it does not know the types of procedure arguments and so will be unable to locate the field names if a record constant is passed directly to a procedure. It does correctly handle nested record constants. The nesting limit for include files and expressions is currently at least 8, depending on context. This can easily be raised (by me) if required. The cross-referencer does not permit run-time assignments to constants, although the Turbo compiler does in some circumstances. Since this is contrary to the concept of constants, this restriction will not be removed. Offending programs must be changed. Circular 'uses' clauses are correctly handled, but the interface sections of required units are read separately, and the whole file must be read again for cross-referencing. This prevents detection of references to undeclared types until all required units have been read, and currently when unresolved references are finally detected the cross-referencer does not know which unit(s) are in error. It also wrongly reports any unresolved types when a unit has been aborted for some other reason. If anyone has a Pascal source file which the formatter wrongly rejects, please let me know. I would also be pleased to know of any invalid syntax which it accepts. If the formatter crashes, or if formatting is affected in any way by preceding files, please give me full details. The formatter should accept all the files which the Turbo Pascal compiler does. There are currently no other known exceptions. Changes from the original PASMAT Dollars are valid and significant characters in identifier names. The original PASMAT just ignored underscores, and removed them in portability mode. Portability mode (p) no longer exists. The ELSE kluge (k) has also been removed. Defaults have been changed - the default is now: PASMAT /NOADJUST_SPELLING /BUNCH_STATEMENT /NOCAPITALIZE_IDENTIFIER - /NOCOMMENT_INDENT /CONVERT_TO_TABS /FORMAT /NOLITERAL /NEW_LINES - /PARAMETER_ALIGN_NAMES /RESERVED_UPPER /STANDARD /STATEMENTS_PER_LINE=1 - /TABSPACES=4 /NOUPPER_IDENTIFIER /VARIABLE_BUNCHING /WIDTH=80 Changes from previous Versions New for V3.3 The defaults have been changed to /BUNCH_STATEMENT /NOLITERAL /PARAMETER_ALIGN_NAMES /RESERVED_UPPER /TABSPACES=4. Multiple blank lines have been removed and EXTERNAL/FORWARD directives will be put on the same line as the rest of the procedure. Problems with nesting units have been removed - now units used by a unit which is itself used by the input file will be read as necessary to resolve type references in the interface. This was the intended behaviour of V3.0, but it wasn't working correctly. /CAPITALIZE_IDENTIFIER has been added - this puts the first character of identifiers in uppercase and the rest in lowercase. /IDENTIFIER_UPPER has been renamed to /UPPER_IDENTIFIER. Options letters 'A','L','U' have been removed as use of these during processing could cause the cross-referencer to fail because of optimizations within it. Use /ADJUST_SPELLING, /LITERAL, /UPPER_IDENTIFIER on the command line instead. /UNITS is obsolete and need no longer be used - its use was as follows: use the qualifier /UNITS=(unitlist) to preprocess units required by the files you want cross-references for. SYSTEM is always read. Default = /NOUNITS. /FETCH now reads units as necessary. New for V3.2 The Turbo V5.5 new reserved words (OBJECT, VIRTUAL, CONSTRUCTOR, and DESTRUCTOR) are now rejected by TPMAT. This is to highlight any source code incompatible with V5.5. The new syntax is not yet supported. The '@' symbol was treated as equivalent to '^', and if /STANDARD was used (the default), '@' was replaced by '^' in the output. This is incorrect for Turbo Pascal, and no longer happens under V3.2. Programs formatted before 21-AUG-1989 containing '@' symbols will probably have been incorrectly modified by the formatter. New for V3.0 /SOURCE /CROSS_REFERENCE= CONSTANTS VARIABLES TYPES LABELS ROUTINES ALL NONE /FETCH /UNITS If cross-referencing is being done, use of unknown units will result in a warning message. If there are unknown units, any references to them will result in a further warning message and an entry in a special unit. The entry may not be correct - the cross-referencer cannot distinguish between references to constants, variables and functions for example. If there are no unknown units, references to undeclared objects will cause a syntax error. New for V2.0 /DEBUG /SHOW_STATISTICS /COMMENT_INDENT /PARAMETER_NAME_ALIGN /VARIABLE_BUNCH /INCLUDE /LISTING /NOOUTPUT Untyped files permitted. Discards garbage after END.