Trailing-Edge
-
PDP-10 Archives
-
decuslib20-07
-
decus/20-0172/blfusrgde.mem
There are no other files named blfusrgde.mem in the archive.
PRETTY - BLISS LANGUAGE FORMATTER
User's Guide
PRETTY
1.0 Overview
PRETTY is a utility program that reformats BLISS source files and
require files so that they correspond to generally accepted formatting
standards. PRETTY is a valuable tool in standardizing the appearance
of BLISS code, for it promotes readability while permitting
flexibility in program structure.
PRETTY is more than a reformatter. It also performs a cursory syntax
check of your program and reports obvious errors that should be fixed
prior to compilation, such as mismatched BEGIN and END statements.
2.0 Command Line Format
PRETTY is invoked in very much the same way as the BLISS compiler.
The command syntax for each host is:
=>10
.R PRETTY
*{out-spec} {,list-spec} = in-spec
=>20
@PRETTY
BLF>in-spec {/OUTPUT:out-spec} {/LISTING:list-spec} {/EXIT}
=>VAX
$ PRETTY:==$PRETTY
$ PRETTY in-spec {/OUTPUT:out-spec} {/LISTING:list-spec},...
PRETTY User's Guide Page 2
Command Semantics
The output file contains the reformatted source program or REQUIRE
file. Some of the operations performed by PRETTY are:
o To force routines to the top of a new page (if they are not
nested within other routines).
o To align BEGIN-END pairs.
o To indent blocks.
o Where possible, to align end-of-line comments (remarks) to a
standard column.
o To align block comments with the enclosing blocks.
o To realign control structures to one or more lines in a
standard way.
Several options are available to enable a user to specify different
kinds of formatting; defaults for all options are described.
The listing file differs from the output file in three ways:
o Each line is appended with a slash (/), the SOS page number,
and the SOS line number as in:
/ 4. 200
o Each logical tab is preceded by a colon (:), so that the
indentation level is obvious as in:
IF .A / 1. 1200
THEN / 1. 1300
: / 1. 1400
: IF .B / 1. 1500
: THEN / 1. 1600
: : / 1. 1700
: : IF .C / 1. 1800
: : THEN / 1. 1900
: : : / 1. 2000
: : : D=5; / 1. 2100
PRETTY User's Guide Page 3
o There is a three line heading on each page:
. %TITLE information (which starts a new page)
. %SBTTL information
. Module and routine names and page number
The listing file cannot be used as input to the BLISS compiler.
On the DECSYSTEM-20, an output-file is always produced. The
output-file specification has the same name and extension as the input
file specification. Thus, the input-file is overwritten by the
output-file unless a different file name is specified by the /OUTPUT
switch. A listing-file is produced only if the /LISTING switch is
present. The listing file extension defaults to .LIS on the VAX,
and to .LST on DECsystem-10 and -20 machines. After the reformatting
has taken place, PRETTY prompts for another command unless the /EXIT
switch is present, which causes PRETTY to return to the monitor.
On the DECsystem-10 and VAX, if no output or listing files are
specified, only terminal error messages will be produced. Otherwise,
an output file is created, if specified, and a listing file is
created, if specified. If no input file extension is specified the
extension defaults to .BLI.
Producing both an output file and listing file doubles the execution
time of PRETTY. However, PRETTY's typical execution time is only a
fraction of the BLISS compiler's.
PRETTY User's Guide Page 4
3.0 FORMATTING RULES
3.1 General Strategy
The basic guidelines for the formatting rules are derived from
generally accepted formatting standards. Where the choice of a format is
unclear, PRETTY will choose a format on the basis of the type of the
enclosing block: If BEGIN-END are used, PRETTY will choose an open
format, while if the block is bounded by parentheses, a closed format
will be used. For example:
BEGIN
expression1; expression2; expression3;
END;
would be formatted as
BEGIN
expression1;
expression2;
expression3;
END;
while the input text
(expression1;
expression2;
expression3;)
would be output as simply
(expression1; expression2; expression3;)
To do its job, PRETTY reads only the specified input file and, if
used, a REQUIRE file consisting of user-specified PRETTY control
directives. As PRETTY reads the input file, it throws away all
spaces, tabs, linefeeds, formfeeds, and other nonprinting characters
(comments, character strings, and specifically unformatted text
excepted) and replaces them according to the rules that follow. In
general, anything that PRETTY can insert it will first throw away
(including PRETTY error messages.) An implication of this approach is
that a coding style which is dependent on vertical alignment or
multiple blank lines may be defeated by PRETTY.
In some situations, especially in macro definitions and in tables, the
reformatting actions performed by PRETTY may impair the readability of
the text. Provision is made for explicitly overriding the formatting
process so that where the input format is especially helpful in
understanding the code, it can be retained permanently.
PRETTY does not expand conditional code (%IF, %THEN, etc.) or macro
references. As a result, it is possible that the code that PRETTY
processes may appear to be syntactically incorrect. Some practice in
the use of PRETTY will help the user to avoid coding styles which
cause PRETTY to misinterpret the intent of the syntax. In general,
the interpretation of conditionally compiled code will be correct
PRETTY User's Guide Page 5
whenever the text would be correctly interpreted if the conditional
"%IF expr %THEN", "%ELSE" and "%FI" were missing.
Where PRETTY issues error messages due to references to macros defined
as partial control structures, e.g.
MACRO
ORIF = ELSE IF %;
a means is provided to allow PRETTY to parse the macro reference as
though it were the macro expansion, i.e. to interpret the macro name
as a "synonym" for the control structure in the macro definition.
PRETTY produces an output file, which contains all the lexemes of the
input file in the same order, and a listing file with the same
information displayed in expanded form (including vertical alignment
guides, SOS page and line numbers, and page headings). In order to
flag errors, comment lines of the form
!!ERROR!! ... message ...
are produced. (These comments appear both in the output and listing
text and, slightly revised, at the terminal.) In general, an error
message line is immediately followed by the lexeme that PRETTY
considered anomalous. Several error messages may be produced by a
single line of code. In general, the first is most important: the
rest may have been triggered by the first error found.
3.2 General Rules
1. Every semicolon (except within a comment or quoted string, or
within the immediate context of a block delimited by
parentheses) terminates the line on which it appears;
however, a trailing remark will also appear on the same line.
2. The outermost level of control in the BLISS input text is
output without indentation; as sublevels of control
(Routines and other declarations, expressions, blocks, etc.)
are introduced they are indented by one 'logical tab', i.e.
4 spaces, so that the deepest control levels appear farthest
to the right in the output file. The conditions under which
a given expression is evaluated at run time can be determined
by examining the language constructs which cause the changes
in indentation level above the expression in question.
(Multiple logical tabs consist of a sequence of physical tabs
followed by either 4 spaces or none, depending on whether the
number of logical tabs is odd or even.)
3. Indentation is limited by the number of tabs that are issued
and by the right margin of the page. Lexemes too long for
the right margin are printed on following lines, using the
indentation level of the current expression. Whenever a
lexeme is moved to a new line because of right-margin
violation, any immediately preceding '.' lexemes appear on
the next line also. Thus '.' will not be separated from the
following lexeme by the end of the line.
PRETTY User's Guide Page 6
4. Certain operators, e.g. "+", "-", and "=", are always
bounded by spaces. "*" and "/" usually are not; commas and
semicolons are always followed by at least one space.
5. Certain occurences of commas (e.g. within declarations)
cause new lines; others (e.g. in argument lists) do not.
However, if a list of items is too long for one line, then
the line will be broken after the last comma that fits on the
line. (The appearance of an open parenthesis between the
comma and the end of the line inhibits this break.)
6. End-of-line remarks, which always cause a new line to start,
can be used by the coder to enhance the capabilities of
PRETTY in certain cases, e.g. in long expressions or lists,
where style cannot readily be translated by PRETTY formatting
rules.
7. All names and all numeric constants are separated by white
space.
3.3 Rules For Formatting Lexical Functions
1. The lexical function %TITLE always appears at the top of a
new page.
2. The lexical function %SBTTL appears at the top of a new page
unless it follows %TITLE more recently than ROUTINE. Thus,
for example, %SBTTL'...' ROUTINE ... will appear on the same
page, but ROUTINE ... %SBTTL '...' will not.
3. The lexical control expressions %IF, %THEN, %ELSE, and %FI
are handled in one of two ways: occuring within a macro
definition, They are either left alone or indented to the
level of the block in which they occur, depending on whether
the macro definition is being left alone or formatted as a
block body; otherwise, they are left-justified on separate
lines. %IF and its associated expression appear on the same
line. The text separating %THEN, %ELSE, and %FI will be
indented one level and be interpreted as if the lexical
controls were missing, and will be formatted correctly if
that interpretation is consistent with the surrounding text.
4. The arguments of the built-in compiler-selection macros
%BLISS16, %BLISS32, etc. are parsed and formatted as if they
were block bodies. This may in certain cases result in error
messages.
PRETTY User's Guide Page 7
3.4 Rules For Formatting Declarations
1. Declared names, and accompanying subelements of declarative
expressions, are indented. All declarations within a BEGIN
block are indented to the level of the innermost enclosing
block.
2. Each MODULE and Module-level ROUTINE declaration appears on a
separate page. Each may be preceded on the page by a
"%TITLE" or "%SBTTL". MODULE may be preceded by comments.
Any other declaration is preceded by a blank line. Every
declaration is followed by a blank line.
3. Unless PRETTY is specifically requested to make the attempt,
macro-body definitions are not reformatted, but are simply
reproduced in the output stream. This treatment provides for
the arbitrary usage of lexemes in macro-bodies. If PRETTY is
directed to reformat them, macro-bodies are treated as
block-bodies. In any event, the sequence "MACRO name
(<list>) =" is formatted according to conventional rules for
declarations.
3.5 Rules For Formatting Expressions
In the following discussion, the following definitions are used:
"P-block" means a block bounded by parentheses.
"B-block" means a block bounded by BEGIN and END.
1. Except within a P-block, all control expressions are preceded
and followed by blank lines. BEGIN and END always appear on
separate lines.
2. IF-THEN-ELSE may be handled in any of three ways:
1. Within a P-block, the entire expression tends to appear
on one line. This tendency is overcome only by the
occurence of other control expressions, by remarks, or if
the line is too long.
2. Within B-blocks, IF-THEN-ELSE will appear on one line
under the same conditions as in the P-block context. If
the IF-THEN-ELSE will not fit on the line for any reason,
then:
3. The IF-THEN-ELSE is expanded to several lines, in the
general format
IF conditional-expression
THEN
true-action-expression
ELSE
false-action-expression
PRETTY User's Guide Page 8
3. In post-tested loops, DO appears on its own line, as does the
terminating WHILE or UNTIL clause; however, in pre-tested
loops the conditional clause precedes the DO on the same
line.
4. SET and TES, as well as each of the alternative specifiers,
appear on separate lines. SELECT and CASE also appear on
separate lines, along with the conditional expression and
range, etc. expressions. Except within a P-block, instances
in a SET/TES will be separated by blank lines.
5. INCR or DECR appears, with its index, FROM, BY, and TO
expressions, on one line preceding the body of the loop. If
the body is a P-block, it will start on the same line;
otherwise, the body will appear on subsequent lines.
6. The indentation level is increased whenever a new expression
is encountered and decreased when each expression is
completed. As a result, expressions too long for one line
are continued on the following line, indented from the
beginning of the expression. However, BEGIN and END appear
at the same indentation level as their contained expression
list.
7. Macro references may, of course, occur anywhere after the
macros are defined. They will be interpreted without
indication of error if they appear in the place of
expressions, declarations, or the names or values of
attributes being declared, and in a few isolated other cases.
References to macros which include partial control
expressions, e.g.
MACRO
ELSEIF =
ELSE IF %;
usually cause both error messages and inappropriate
formatting.
The effect of such macro definitions can usually be overcome
by use of the SYNONYM control described later, which permits
the definition of the macro name as a synonym for the
principal sequence of lexemes in the macro definition, for
the purposes of formatting.
PRETTY User's Guide Page 9
3.6 Rules For Formatting Comments
1. Embedded comments "%(...)%" are left alone unless they extend
beyond the right margin, in which case they are split after
the "%(" prefix.
2. All full-line comments are left alone. (Error messages,
however, are deleted.) Block comments, that is, sequences of
comments of the form
!+ ...
! ...
!- ...
are set off by blank lines before and after the sequence.
3. Comments starting beyond column 1 are indented to either of
two points on the text line: either to the Remark Column, a
number of physical tabs to the right; or to the indentation
level of the surrounding program text. A remark (i.e., a
comment appearing on the same line as program text) is always
indented to the remark column unless that column is preempted
by program text, in which case it will either appear one tab
position to the right of that text or (only if it won't fit)
on a separate line.
Other comments will appear in the remark column if
1. The "!" character is immediately followed by "."
2. The comment appears near the remark column in the input
text and is not affected by the following rule
Block Comments, and other comments appearing to the left of
the remark column in the input text, are indented to the
level of the surrounding program text.
The following example illustrates these rules:
! This is a full-line comment, starting in column 1.
IF expr
THEN ! Remark
BEGIN ! Another remark
! Non-block comments input to the left of
! the remark column
! Input as a remark
!+ Preceded by blank line.
! Block Comment ...
!. Forced by "."
!- Followed by blank line.
...
PRETTY User's Guide Page 10
3.7 Case Conversion
Except within comments and character strings, all identifiers,
including BLISS reserved words (BEGIN, WHILE, etc.) are recognized and
subject to upper-lower case control.
4.0 Formatting Options
A number of options can be specified in the source input. These
options give you flexibility in deciding how to format your code.
Formatting options are supplied by means of directives inserted as
full-line comments in the input source text. The format of the
formatting option directive is:
!<BLF/option>
The exclamation point that starts the command must begin in column 1.
Options may be typed in uppercase or lowercase characters. Commands
are passed to PRETTY in this fashion without modification to both
the output and the listing files. Since the directives begin with an
exclamation point, they are interpreted as comments by the BLISS
compiler.
Formatting option directives are described below. An asterisk (*)
identifies the default.
ERROR*
Enables the insertion of error messages (that is, lines
beginning with "!!ERROR!!") into the output file. Error messages
are automatically deleted from source files on subsequent runs.
Errors displayed on the terminal are preceded by "?!ERROR!!".
Example: !<BLF/ERROR>
NOERROR
Disables the insertion of error messages into the output
file. Error messages are always output to the terminal.
FORMAT*
Causes resumption of formatting by PRETTY.
NOFORMAT
Inhibits formatting by PRETTY until the next !<BLF/PAGE> or
!<BLF/FORMAT> is encountered.
PRETTY User's Guide Page 11
LOWERCASE
Causes all identifiers and keywords to be converted to
lowercase.
LOWERCASE_KEY
Causes BLISS keywords, builtins, and predefined names to be
converted to lowercase.
LOWERCASE_USER
Causes user identifiers to be converted to lowercase.
MACRO
Causes macros to be formatted. Use of this option may cause
error messages that do not appear when formatting with macros is
disabled.
NOMACRO*
Disables formatting of macros.
NOCASE*
Causes all identifiers and keywords to remain unchanged.
NOCASE_KEY
Causes all BLISS keywords, builtins, and predefined names to
remain unchanged.
NOCASE_USER
Causes all user identifiers to remain unchanged.
PAGE
A page break (formfeed) is generated.
PLIT
Causes formatting of PLIT bodies to occur. Since the
content of PLITs is difficult to analyze, PRETTY may format the
PLIT differently than you had intended.
PRETTY User's Guide Page 12
NOPLIT
Inhibits formatting of PLIT bodies. Only the first line of
a PLIT body is formatted; the remaining lines remain unchanged.
REMARK:n (Default = 6)
Causes subsequent comments to begin at column 8*n+1, where
2 < n < 16. The default comment starts at column 49.
REQUIRE'file-spec'
The specified file is read for further formatting option
directives. Everything in the REQUIRE file other than legal
directives is ignored. Directives in the REQUIRE file are not
reproduced in the output or listing files. The REQUIRE file must
not contain another REQUIRE directive.
Example: !<BLF/REQUIRE'COMMAND.REQ'>
SYNONYM name = lexeme...
This option describes to PRETTY macros that you have defined to
substitute for keywords. SYNONYM causes subsequent occurrences
of "name" to be treated as a sequence of other tokens for
formatting purposes. The special token "*" can be used to
indicate where to position "name" with regard to the normal
position of the tokens that it replaces.
Example: !<BLF/SYNONYM ELIF = ELSE IF *>
permits the sequence:
IF expr THEN expr ELIF expr THEN expr;
to be formatted without error. Only the name ELIF is output, but
it is indented as though ELSE IF had occurred in the text.
In the above example, formatting would occur as follows:
IF expr
THEN
expr
ELIF expr
THEN
expr;
PRETTY User's Guide Page 13
If !<BLF/SYNONYM ELIF = ELSE * IF> had been specified, formatting
would occur as:
IF expr
THEN
expr
ELIF
expr
THEN
expr;
UPPERCASE
This causes all identifiers and keywords to be converted to
uppercase.
UPPERCASE_KEY
This causes all BLISS keywords, builtins, and predefined names to
be converted to uppercase.
UPPERCASE_USER
This causes all user identifiers to be converted to uppercase.
WIDTH:n (Default = 110)
This causes subsequent output lines to have a width of "n"
columns, where 71 < n <141.
Example: !<BLF/WIDTH:80>
Hints on Using Pretty
Because of the great flexibility possible in the use of the BLISS
language, specification of fixed formatting rules for the language is
difficult. In order to construct a formatting tool like PRETTY, a
reasonable idealized model of a BLISS program has to be used. This
model may be quite different from your particular style of manual
formatting.
Several features of the language can be used in such a way as to make
formatting difficult without very extensive semantic analysis. In
order to meet its goals of executing many times faster than the
compiler, PRETTY does not perform this kind of extensive analysis, but
rather relies on hints from the programmer.
PRETTY User's Guide Page 14
Breaking Lines - PRETTY attempts to break lines by certain
general rules. In a begin-block, every semicolon terminating a main
line expression causes a line break except if a remark follows. A
remark, therefore, can be used to force a line break.
Operator-expressions that are too long to fit on a single line will be
broken around an operator. A programmer can specify an alternate line
break strategy by using the exclamation point as a break character.
Consider a (visually) long expression of the form:
E1 OR ... AND EN
where Ei denotes an expression.
If the programmer wishes to control how this line is broken, the
following can be written:
E1 OR ! comment
E2 OR !
... AND !
EN !
PRETTY attempts to place an if-expression on a single line if it fits.
If it does not, PRETTY will automatically place the 'THEN' under the
'IF', and the 'ELSE' if present, under the 'THEN'.
Comments - While BLISS recognizes only two kinds of comments,
embedded comments ( %( ... )% ) and trailing comments ( !... ),
PRETTY distinguishes several subtypes of trailing comments:
o Remarks:
...! comment
These are lined up in the remark column, but otherwise not
analyzed. They cause a line break.
o Full line comment:
! rest of line ...
This occurs in column 1. The entire line is passed to the
output file without further processing.
o Offset Block comments:
...
!+
! comment
!-
...
These are preceded and followed by a blank line, and indented
to the current indentation level.
PRETTY User's Guide Page 15
o Non-offset BLOCK comments:
...
!
! comment
!
...
These are similar to offset block comments in that they are
similarly indented, but are not offset from the surrounding
text by blank lines. They are recognized as block comments
rather than remarks only if they appear more than one tab to
the left of the remark column.
MACROs - Because it is possible to write macros in BLISS that
are not expressions or lists of expressions, PRETTY conservatively
makes no attempt to format macro bodies, and treats macro invocations
in the same way as routine calls. Thus, the macro body appears in the
output file the same way it appeared in the input file, and therefore
may be formatted quite differently from surrounding text in the
output file.
Experience has shown, however, that the great majority of macro bodies
can be successfully formatted by PRETTY. Because of this, you may
want to change the default to:
!<BLF/MACRO>
for your programs by preceding each source file with the above
command. Macro formatting can be turned off before any offending
macro declaration, and turned on after it, should there be any.
The SYNONYM facility allows users a limited way of telling PRETTY to
interpret certain macro invocations as other than routine calls, as in
the ELIF macro given above.
PLITs - PLITs are used to construct initialized tables in
BLISS, and in practice, the programmer-specified formatting of a table
gives a good indication to the reader of the structure and meaning of
the table. Rather than try to guess the structure of a PLIT, PLIT
formatting is turned off by default.
The initial-attribute of a declaration is handled exactly as a PLIT.