.;-*-text,readall-*-
.paper size 56,80
.left margin 8
.right margin 72
.autoparagraph
.spacing 1
.upper case
#
.blank 8
.center ;The New Ratfor Preprocessor
.blank 12
.center ;Gary Beckmann
.center ;Joint Center for Radiation Therapy
.center ;Harvard Medical School
.center ;52 Binney Street
.center ;Boston, Massachusetts 02115
.center ;(617) 732-8508
.blank 3
.center ;Marty Sasaki
.center ;Department of Radiology
.center ;Brigham and Women's Hospital
.center ;75 Francis Street
.center ;Boston, Massachusetts 02115
.center ;(617) 732-6683
.blank 7
.note
This document does not describe the language RATFOR, but describes
changes and enhancements made in the original RATFOR described in
"Software Tools". Anecdotes and other useless information also
included.
.end note
.chapter Introduction and stuff
.left margin 8
.right margin 72

.hl 1 The Introduction
	Sometime ago, in the dark depths of history, Marty Sasaki became tired
of the tediousness that programming in FORTRAN sometimes required.
Having read "Software Tools", and being a hack of some skill, he built
a RATFOR preprocessor (RATFOR comes from RATional FORtran).
The original preprocessor was very similar to the one
in "Software Tools" and was large and cumbersome, but it worked.
	Then entered Gary Beckmann. Bright eyed and eager to learn, he set
about the task of programming (a task which, to him, was new and exciting).
But he too was affected by the tediousness that FORTRAN exacted from
its programmers, and so he turned to Marty for help and guidance, and so
he was exposed to the wonders of structured programming and the accessability
of RATFOR (since so much of it is FORTRAN-like already, a programmer familiar
with FORTRAN need only learn a few more conventions).
	To both programmers' dismay, it was soon discovered that the original
preprocessor (written in DEC FORTRAN Four Plus for the RSX-11D operating
system) would not work on RT-11 with FORTRAN Four.
About then a paper appeared in "Software, Practice and Experience" on the
design of a preprocessor for RATFOR which was more efficient and only
slightly more complicated than the original*. This preprocessor incorporates
the suggestions of Comer with a new table lookup as suggested by Lurie and
Vandoni**.
.footnote 8
.center ;________________________________________________________________________
.lm 11
.rm 72
.blank
.indent -2
* D.Comer 'MOUSE4: An improved Implementation of the Ratfor Preprocessor',
Software - Practice and Experience, 8, 35-40 (1978)
.blank
.indent -3
** D.Lurie and C.Vandoni, 'Statistics for FORTRAN Identifiers and Scatter
Storage Techniques, Software - Practice and Experience, 171-177 (1973)
.lm 8
!
.hl 1 The Programmers
	Short histories follow for those of you who are interested.
.hl 2 Gary Beckmann
	Gary hails from St.Louis, Missouri where he attended the University of
Missouri. In between Shakespeare and Milton (he was studying for 
a degree in English Literature), he played around with the various
computers on campus. He has found this hobby more economically sound
than the degree.
.note
The unusual part is that everyone I have worked for has at one time or another
commented that: "I hired you because of your English degree" or some
variation on that theme.
.end note
.hl 2 Marty Sasaki
	Marty is an almost graduate from the prestigious Massachusetts
Institute of Technology. Originally from Hawthorne, California (home
of the Beach Boys), Marty has settled in the Boston area (although he hates
the weather) and runs a zoo with a dog, a rabbit, 2 Guinea pigs (now 
residing in an elementary school),
and a variable number of fish (tropical, marine, and gold).
.hl 1 Disclaimer
	We both have strong feelings about our work. Many conversations
have occurred over the goals that this preprocessor should strive to meet.
This preprocessor is the result of much "blood, sweat and tears" (apologies
to W. Churchill). No doubt many others will find bugs
(features!) and things that upset them. We provide source code for those
who must (and who will) change things. We are also open to suggestions
and wouldn't mind hearing from you, whether the news be good or bad.
	We do not believe that RATFOR is the "END ALL AND BE ALL" (EABA?)
in computer languages. Rather, RATFOR seems to provide much of what FORTRAN
is lacking, without being expensive or large. Other "features"
might have been (and still might be) added, but we restrained ourselves to
something that was manageable. The resulting processor contained
surprisingly few bugs and was written in a short amount of time.

.hl 1 Acknowledgements and Other Thanks
	RATFOR was invented by Brian Kernighan, and of course we owe him
quite a lot. The code uses most of the algorithms in the "Software
Tools" processor.
	Further thanks to Michael Patton, who looked over our shoulders
and provided bug fixes. Michael also wrote a new keypad macro for our
version of TECO and enthusiastically added new commands that made our
life easier.
	One of the main "breakers" of RATFOR has been Tony Parker, who
has the unusual talent of doing things that are legal, but that we would
never have thought of doing.

.hl 1 The Future of FORTRAN and RATFOR
	We seldom use FORTRAN anymore, except as the second pass of the
RATFOR compiler. We don't miss the arithmetic if statement.  Many times
we find ourselves rewriting a buggy FORTRAN program in RATFOR since
RATFOR is so much easier to read.
	The RATFOR presented here has changed very little recently. We
have been talking about adding internal proceedures (like FLECS) and
structured data, but no definite action is being taken.
	Rumor has it that there is a new preprocessor from Brian Kernighan
that incorporates some data structuring. Someone is also talking about
writing a "real compiler" rather than just a preprocessor. There is obviously
much interest in RATFOR.
	The present preprocessor is running on RSX-11M, RSX-11D, RT-11 and
VMS. It runs on IAS version 3, but we don't really have extensive experience
on IAS. We are relatively certain that it will run on RSTS/E.
There are slight differences in the preprocessors on the different
systems. Most of these are in the handling of
command lines, and the opening and closing of files, and exit status. The
preprocessor is compilable using DEC F4P and FORTRAN Four.
	The preprocessor does not take advantage of FORTRAN 77 features. We
do not plan on altering the preprocessor to take advantage of enhancements in
FORTRAN until DEC has released FORTRAN 77 compilers on PDP-11 operating
systems.

.chapter The Language
.left margin 8
.right margin 72

.hl 1 All About RATFOR
	A very good description of RATFOR, and other very good thoughts
about programming in general can by found in "Software Tools" by Brian W.
Kernighan and P.J.Plauger (published by Addison-Wesley, 1976) The
preprocessor described in the book (chapter 9) is the basic model
for our preprocessor. We have made several improvements (?) in the design
of the table searches (hash coding) and in the flexibility of RATFOR which
are all documented below. There are also several added "features" incorporated
into the language. They are also documented.

.hl 1 Reserved Words (different)
	Unlike FORTRAN, RATFOR has several reserved words which, if used in
other than the recommended way, will cause unpredictable results.  The
reserved words are contained in Appendix A.

.hl 1 Variable Names (new)
	Variable names must begin with an alpha (A-Z or a-z) or an underscore
("__", sometimes represented as a backarrow) or a dollar sign ("$"), the rest
of the name may be made up of any number of alpha-numerics, underscores or
dollar signs. These variable names are treated specially if needed (see
below). While a variable name could theoretically be of any length, please
note that the maximum size of a token accepted by this preprocessor is 80
characters. 

.hl 2 Long Variable Names on RSX/IAS/RT
	The long name (> 6 characters, or containing an underscore or dollar
sign) is converted into a name that is six (6) characters long.
This conversion is done automatically. 
.note
Please note that FORTRAN has several keywords that are longer
than six characters and that those words are also
included in the Reserved Word list in appendix A.
.end note
 The variable
names created begin with the same letter as the original names, allowing
"implicit" type statements to continue functioning properly. If a name
begins with an underscore or dollar sign, the underscore or dollar sign is
converted to an "A". This first character is then followed by 5 numerics,
which are pulled off of a counter in the preprocessor. Because of this
method of treating long names, it may be a good idea not to use variable
names which consist of an initial alpha followed by 5 numerics. (would
anyone really do that anyway?)

.hl 2 Long Variable Names on VMS
	Long names are handled on VMS in much the same way as on the
other systems with the exception that on VMS variables can be 15 characters
long (32 characters in version 2), and can begin with underscore or dollar
sign. Long names in VMS are still converted to the initial character followed
by 5 numerics to ease the way of those using the symbolic debugger (just
imagine trying to type 31 numerics correctly several times).

.hl 2 Subroutines and Functions with Long Names
	It is not recommended that subroutines and functions have long names.
It is entirely possible to compile routines with different long names
that RATFOR has translated into the same name. RATFOR does not
remember long names across translations. If you must have long names for
subroutines and functions, then you should include all of the source into
one large file and run it through RATFOR all at one time.

.hl 2 Following long name conversions
	Some of the preprocessors (11M and VMS for sure) allow a flag in the
command line that will cause a file to be created which holds the long name
and the name it is converted into. Check your implementation to see if you
have this option, if not you might look at the 11M or VMS implementation
to see how it is done. (If your version works, we will distribute it in
the next release of this processor).

.hl 1 Spaces, Tabs and Cosmetics (different)
	In RATFOR spaces are important. Spaces or tabs must separate words
from other words. By words, we mean any contiguous string of alphabetic
characters and digits that begins with an alphabetic character. If there
is no separation the preprocessor will probably convert the string from
what it thinks is a long variable name, to a short name. A good example
is the following code fragment.
.break
		if(a = B)goto1000
.blank
RATFOR will replace the string "goto1000" with a short variable name of the
format "G00001".
	Except for these restrictions (and the continuation conventions)
a program may be entered with statements anywhere on the line. Usually
the layout is chosen to reflect visually the structure of the program.
This is a suggested format rather than a restriction.

.hl 2 Comments (enhanced)
	The character "_#" begins a comment. The comment continues to the
end of the line on which the "_#" appears. In addition characters
appearing between "/*" and "*/" are also comments. A comment of the
second type is treated as white space and can appear anywhere a space or tab
may appear. The comment enclosed in "/*" and "*/" may not nest.

.hl 2 Character Set and Strings
	The preprocessor will take as input either lower case or upper case
characters. Lower case characters are translated to their upper case
equivalents. The exception to this rule is in strings where no
translation occurs. Certain F4P routines expect capitals in strings,
so be careful.
	Strings can either be enclosed in single or double quotes. 
	The use of hollerith constants is not supported and will generally
produce errors.
	Strings may not have imbedded new-lines or returns. Trying to
include a carriage return will generate an error. (See the notes on the
STRING statement for a suggestion on how to over come this problem.)

.hl 2 Continuation Conventions (different)
	RATFOR will automatically continue any line that ends with ",",
"*", "+", "-", "(", "_&", "|", or "_\". Comments, spaces and tabs
are ignored at the end of lines.
	If a line ends in "_\" the backslash and the newline are thrown
away, and the line continues the next line as if the backslash and newline
were not there.
.hl 2 The % Character (different)
	The "%" (percent sign) is treated specially in RATFOR. If it appears
at the beginning of a line, the characters in the line are shifted
left one character position(eliminating the "%"), and the resulting line
is written directly
to the output without translation. This is useful for control cards or
special FORTRAN statements that can't  be passed through the pre-processor.
	If a "%" is in a string, nothing special happens.
	Anywhere else, the "%" signals that the following character is to be
passed through the preprocessor without modification. The "%" is
thrown away and does not appear in the output. This is useful for
enclosing expressions in "_<" AND ">" in F4P format statements and
for the "'" used in direct access i/o statements.

.hl 1  Octal constants -- The _@ Character (new)
	The "_@" (at sign) is treated specially in RATFOR. It replaces the
double quote character as signifier of an octal constant. The preprocessor
translates the constant and inserts it into the generated code as a decimal
constant.

.hl 1 RATFOR statements
	A RATFOR statement is any normal RATFOR statement or a compound
statement. Compound statements consist of any number of RATFOR
statements enclosed in "{" and "}". Compound statements may
be nested. The symbols "[" and "]" may also be used to  delimit compound
statements.

.hl 1 The INCLUDE statement (changed)
	The include statement replaces itself with the contents of the file
specified in the INCLUDE statement. The include statement must
be the only statement of the line. The file name must follow the conventions
of the system the preprocessor is on.
.break
	include foo.bar		_#useful foo information
.blank
causes the file "foo.bar" to be included.

.hl 1 The DEFINE statement (changed)
	The define statement allows a programmer to set literal constants
in a program. The syntax of the statement is:
.break
	define  _<LITERAL>  _<CONSTANT>
.blank
While processing the program the preprocessor will replace the literal
with the constant. It is possible to define a literal as a previously
defined literal.
.break
	define	foo	10	_#will replace "foo" with "10"
	define	bar	foo+15	_#will replace "bar" with "10+15"
	If you try to define a literal twice, an error will be printed and
the second definition will be ignored. This is because it is our feeling
(and experience) that when using large definitional files one can
inadvertantly redefine something that one does not want to change.
Because of this rather major change in approach to the definition of
literals one will notice that we have also changed the syntax of the
define statement, from the syntax used in most other RATFOR preprocessors.

.hl 1 The UNDEFINE statement (new)
	Kernighan and Plauger's preprocessor would re-define a
literal without checking to see if it had previously been defined. This
preprocessor checks for previous definitions and will return a warning if
the user attempts to redefine a literal. If the user wishes to redefine a 
literal this may be done by first undefining it. The syntax of the statement 
is:
.break
	undefine	_<literal>
.blank
	If a literal has not been defined, and is used in an undefine
statement, no error is generated.

.hl 1 The LABEL statement (new)
 The label statement allows the programmer to declare labels in the program.
The syntax for the statement is:
.break
	label  _<label name>[,_<label name>]
.blank
There may not be newlines or returns
in the label list (that is, continuation lines are not allowed).
Label names are the same as identifier names. After a label statement
the label defined may be used wherever a label may be used.
	The labels are generated from the internal label generator that the
preprocessor uses. This generator starts at the numeric label of "23000", it
is not recommended that a programmer use labels greater than 23000.
.hl 1 The FOR Statement (enhanced)
	One of the features of the preprocessor is the complex "for"
statement.
Both the initialization and the re-initialization parts of the for may be
compound statements (enclosed in { } or [ ]). The condition part of the
statement must still be a single valid FORTRAN test statement.
This feature will
allow the programmer to establish several variables inside the for
statement, including the conditional varying of variables (with the if or
a while or even another for!), as opposed to the old method of establishing
and controlling other variables within the for loop.
 An example:
.nofill
	for ({i=1 ; j=1} ; i < MAX_I & j < MAX_J ; {i=i+1 ; j=j+1})
		foo (i) = bar (j)

.fill
.hl 1 The STRING Statement (new?)
	The original RATFOR didn't have it, but "Software Tools" used
it. We decided to put it in. The syntax is:
.break
	string <string name> "<character string>"
.blank
The <character string> is any sequence of characters within quotes. The
backslash character in a <character string> is special. It signifies that
the next character(s) are a representation of otherwise difficult to
print characters.
.b
.nofill
	_\b	back space
	_\e	escape
	_\f	form feed
	_\l	line feed
	_\n	newline (carriage return, then line feed)
	_\r	carriage return
	_\t	tab
	_\_\	_\
	_\_^*	control-* (* represents an alpha "a-z")
	_\ddd	ddd, ddd is in octal
.b
.fill
If the character following the backslash is not one of the ones listed
in the table, the backslash is thrown away, and the character is just
whatever it is.
	The length of a string defined in a string statement is 
available to the programmer. It is defined as <string_ name>__length,
so that if a string is defined with the name "str", the length of that
string is "str__length".
	The string statement checks to see if the literal "character"
has been defined. If the literal has not been defined an warning message
is printed, and the array allocation will not be correct.

.hl 1 The SWITCH Statement (new)
	The switch statement is like the switch statement in "C".
.break
	switch(<expression>) <statement>
.b
The statement is usually compound. Any statement within the <statement>
may be labeled with one or more case labels.
.b
.nofill
	case <integer> :
	case default :
	case '<character>' :
.fill
.b
The expression is evaluated. If one of the case labels' <integer> value
is the same as the value of <expression>, control is transferred to the
statement following the case label. If none of the case labels match,
and there is no "case default:" control continues after <statement>. If
there is a "case default:" control is transferred after it.
The <character> is a single character, and may take the form of a
character in a STRING statement (backslash characters are allowed, see above).
	It should be noted that cases "flow" into each other, that is, unless
a "break" is specified all the following cases are executed. For more
information see a reference manual on "C".

.hl 1 DO Statment (enhanced)
	To increase compatibility with the other looping statements (for and
while) the syntax for the DO statement has been changed. Old style DO
statements still work, and will probably continue to do so. The story here is
to write all new programs using the new format.
	DO ( <loop-control> ) <statement>
.blank
where <statement> is any RATFOR statement and <loop-control> is what you
normally put at the top of a DO loop. Example:
	do (i = 1,9) foo(i) = bar(i+1)


.appendix Reserved Words
 These are the reserved words for this RATFOR preprocessor:
.nofill
		break		case
		define		do
		else		for
		if		include
		label		next
		repeat		string
		switch		undefine
		until		while

.c;FORTRAN words which are more than 6 characters long
.c;(may not be reserved on some VMS implementations)
		associatevariable	backspace
		blockdata		blocksize
		buffercount		carriagecontrol
		complex			continue
		definefile		dimension
		dispose			doubleprecision
		endfile			equivalence
		extendsize		external
		function		implicit
		initialsize		integer
		logical			nospanblocks
		parameter		precision
		program			readonly
		recordsize		subroutine
		virtual
.fill
.left margin 8
.right margin 72
	It may be noted that some of the FORTRAN key words might have
been written with embedded spaces, thus making them less than six
characters long  (and thus preventing the long name handler from
processing them). The choice is simply a matter of taste. Do whatever
you want.

.appendix The "NO PATH TO THIS STATEMENT" warning.
.left margin 8
.right margin 72
	FORTRAN will, at times, generate a "NO PATH TO THIS STATEMENT"
warning. This is almost always the result of an "else" following a "break",
"next", or "return"; or a "break" at the end of the switch statement.
The resultant code will run with no errors. Only result of this error is
the trauma one experiences when errors are reported. One can easily learn
the causes of this warning and avoid them (unless you don't mind having
the warnings printed at you).

.appendix The shape of the generated code
.left margin 8
.right margin 72
	The preprocessor generates FORTRAN code with no spaces and all the
comments in the original RATFOR stripped. This makes for rather unreadable
code. (But you are using RATFOR to get away from FORTRAN, right?) Each line
of FORTRAN code is followed by a comment and a number. The number is the
absolute line number of the code in the RATFOR source that caused the
generation of the line of FORTRAN source in question. This should allow for
easy relating of the source to the generated code. (Either in TECO, or in a
small utility that reads a file and outputs it with its line number, first
line is line #1. Such a utility (call it flist) might make a good first
project to learn the usefulness of RATFOR)

.appendix Incompatibilities with ANSI Standard Fortran
.left margin 8
.right margin 72
	Our RATFOR preprocessor uses DEC FORTRAN, and as such suffers
from the same incompatibilities with the ANSI standard that DEC suffers
from. It is not compatible with either of the ANSI standard FORTRANs or
TOPS-10 or TOPS-20 FORTRANs. Future versions might be compatible with
other systems, if interest is great enough (as it certainly appears to be).