.CH "Ratfor Language Reference"
This section contains a summary of the Ratfor syntax and source
program format.
In addition to serving as a reference for Ratfor, it
can also be used by someone who is familiar with Fortran
and wants to quickly gain a reading knowledge of Ratfor.
.MH "Differences Between Ratfor and Fortran"
.SH "Source Program Format"
.in +5
.rm -5
.lt +5
.ta 6
.tc \
.rc
.ti -5
-\'Rp' is sensitive to letter case.  Keywords must appear in
lower case.  Case is significant in identifiers.
.sp
.ti -5
-\'Rp' is blank sensitive in that words
(sequences of letters, digits, dollar signs, and underscores)
must be separated by special characters
[ul or]
blanks.
.sp
.ti -5
-\'Rp' is not sensitive to card columns.  Statements may begin
at any position on a line.
.sp
.ti -5
-\'Rp' allows multiple statements per line by separating the
statements with semicolons.
.sp
.ti -5
-\A Ratfor statement may be labeled by placing the numeric
label in front of the statement.  The label must be separated
from the statement by at least one space.
.sp
.ti -5
-\'Rp' will expect a continuation line if it encounters a line
ending with a trailing
comma, a condition with unbalanced parentheses, a missing statement
following a control statement, or a line ending with a trailing
underscore.
.sp
.ti -5
-\Any line may contain a comment.
Comments begin with a sharp sign ("#") and continue until the
end of the line.
.sp
.in -5
.rm +5
.SH "Identifiers"
Ratfor identifiers consist of letters, digits, underscores, dollar signs,
and may be up to 100 characters long.  An identifier must
begin with a letter.  Underscores may be included for readability,
but are completely ignored.
An identifier may not be the same as a Fortran or Ratfor keyword.
'Rp'
transforms all long Ratfor identifiers into unique Fortran
identifiers.
.SH "Integer Constants"
'Rp' allows integer constants of the form "<base>r<number>"
where <base> is an integer between 2 and 16. The
letters "a" - "f" are used for digits in bases greater than 10.
.SH "String Constants"
String constants in Ratfor consist of a string body and a string
format indicator.  The string body is a group of strings,
bounded by quotes, and possibly separated by blanks.  The
string format indicator designates the data representation to
be used for the characters in the string body.  It has one
of the following values:
.sp
.in +9
.ta 10
.ti -9
omitted\Fortran Hollerith string.
A standard Fortran
Hollerith constant is generated.  Characters are left-justified,
packed in words (two characters per word on the Prime), and unused
positions on the right are filled with blanks.
.sp
.ti -9
c\Single character constant.
A single character constant is generated.
The character is right-justified and zero-filled on the left in
a word.
Only one character is allowed in the body of the constant.
This is the preferred format for all single characters
in the Software Tools Subsystem.
.sp
.ti -9
p\Packed (Hollerith) period-terminated string.
The 'p' format indicator causes the generation of a Fortran Hollerith
constant.
All periods in the string body
are preceded by an escape character ("@@").
.sp
.ne 3
.ti -9
v\PL/I character varying string.
Fortran declarations are generated to create a PL/I character varying
string.  "V" format string constants may only be used in executable
statements.
.sp
.ti -9
s\EOS-terminated unpacked string.
Fortran declarations are generated
to construct an array in which each element contains one
character of the string body, right-justified
and zero-filled (each character is in the same format as is
generated by the "c" format indicator).  Following the characters
is a word containing the value EOS.
EOS-terminated strings are the
preferred format for multi-character strings in the Subsystem.
"S" format string constants may only be used in
executable statements.
.in -9
.SH "Logical and Relational Operators"
Ratfor allows the use of graphic characters
to represent logical and relational
operators instead of the Fortran ".EQ." and such.
These characters will be replaced by their Fortran
equivalents during preprocessing.
The following
table shows the equivalent syntaxes:
.sp 2
.in +10
.nf
.ta 10 20
.ne 12
.ul
Ratfor\Fortran\Function
.sp
>\.GT.\Greater than
>=\.GE.\Greater or equal
<\.LT.\Less than
<=\.LE.\Less or equal
==\.EQ.\Equal to
~=\.NE.\Not equal to
.sp
~\.NOT.\Logical negation
&\.AND.\Logical conjunction
|\.OR.\Logical disjunction
.sp
&&\(none)\Short-circuited conjunction
||\(none)\Short-circuited disjunction
.fi
.in -10
.sp 2
Note that the digraphs shown in the table must appear
in the Ratfor program with no imbedded spaces.
The short-circuited operators may appear only in the <condition>
part of Ratfor control statements.
.SH "Assignment Operators"
Assignment operators provide a shorthand for the common Fortran
idiom "<v> = <v> <op> <expr>".  Assignment operators may appear
anywhere a Fortran assignment statement may appear.  The
following assignment operators are available in Ratfor:
.ne 12
.be
.ta 10 26
.ti -3
.ul
Operator\      Use\      Result

+=\<v> += <e>\<v> = <v> + (<e>)
-=\<v> -= <e>\<v> = <v> - (<e>)
*=\<v> *= <e>\<v> = <v> * (<e>)
/=\<v> /= <e>\<v> = <v> / (<e>)
%=\<v> %= <e>\<v> = mod (<v>, <e>)
&=\<v> &= <e>\<v> = and (<v>, <e>)
|=\<v> |= <e>\<v> = or (<v>, <e>)
^=\<v> ^= <e>\<v> = xor (<v>, <e>)
.ee
.SH "Escape Statements"
Escape statements can be used to output Fortran statements
that will not be touched by the Ratfor preprocessor.
The escape statement has three possible forms.
In the first form listed below, the first non-blank character
of the Fortran statement is output in column seven.  In the second
form, the first non-blank character of the Fortran statement is
output in
column seven, but column six contains a "$" to continue a previous
Fortran statement to that stream.  In the third form, the Fortran
statement is output starting in column one, so that the user has
full control of the placement of items on the line.  The following
is a summary of this description:
.be 5
.ul
Escape Statement Format            Output Column
.sp
%<stream><Fortran statement>             7
%<stream>&<Fortran statement>            6
%<stream>%<Fortran statement>            1
.ee
"Stream" can take on the following values:
.be 3
1           declaration
2           data
3           code
.ee
If no stream value is given, it is assumed to be the code stream.
[cc]mc |
Escaped statements have to come between a [bf function] or
[bf subroutine] statement and the corresponding
[bf end] statement.
[cc]mc
.SH "Incompatibilities"
Even with the great similarities between Fortran and
Ratfor, an arbitrary Fortran program is
[ul not]
necessarily a correct Ratfor program.  Several areas of
incompatibilities exist:
.in +5
.rm -5
.lt +5
.ta 6
.tc \
.sp
.ti -5
-\Blanks are significant -- at least one space or special
character must separate adjacent keywords and identifiers.
.sp
.ti -5
-\The Ratfor
[bf do]
statement does not contain a statement number following the
"do".  Its range always extends over the next statement.
.sp
.ti -5
-\Two word Fortran key phrases such as
[bf double precision]
must be presented as a single Ratfor identifier (e.g.
"doubleprecision" or "double_precision").
.sp
.ti -5
-\Fortran statement functions must be preceded by the
Ratfor keyword
[bf stmtfunc.]
To assure that they will
appear in the correct order in the Fortran, they should
immediately precede the
[bf end]
statement of the program unit.
.sp
.ti -5
-\Hollerith literals (i.e. 5HABCDE) are not allowed anywhere
in a Ratfor program.  Instead, 'rp' expects all Hollerith
literals to be enclosed in single or double quotes (i.e. "ABCDE" or
'ABCDE').
.sp
.ti -5
-\'Rp' does not allow Fortran comments.  Ratfor
comments must be introduced by a sharp sign ("#").
.sp
.ti -5
-\'Rp' does not accept the Fortran continuation convention.
Continuation is implicit for any line ending with a comma, or
any conditional statement containing unbalanced parentheses.
Continuation between arbitrary words may be indicated by placing
an underscore, preceded by at least one space, at the end of
the line to be continued.
.sp
.ti -5
-\'Rp' does not ignore text beyond column 72.
.sp
.ti -5
-\Fortran and Ratfor keywords may not be used as identifiers
in a Ratfor program.  Their use will result in unreasonable
behavior.
.in -5
.rm +5
.MH "Ratfor Text Substitution Statements"
.sh "define (<identifier> [(<formal params>)], <replacement text>)"
.Sh "Define"
When a
[bf define]
statement is encountered in a source program, <replacement text>
is recorded as the replacement for <identifier>.
If <identifier> is encountered later in the program, it
will be replaced by <replacement text>.
If <formal params> was present in the definition of <identifier>,
and the subsequent occurrence of <identifier> is followed by
a parenthesized, comma-separated list of strings, occurrences
of the formal parameters in <replacement text> will be replaced
by the corresponding strings in the actual parameter list.
.pp
<Identifier>
must be an alphabetic Ratfor identifier, while <replacement
text> may contain any characters except unmatched quotes
or parentheses.
<Formal params> must be a comma-separated list of identifiers;
corresponding actual parameters may contain any characters
except unmatched quotes, unbalanced parentheses, or unnested
commas.
During replacement, <replacement text> is also examined
for occurrences of
[bf defined]
identifiers.  Formal parameter replacement occurs on
identifiers in <replacement text>, even if the identifiers
are surrounded by quotes or parentheses.
Redefinition of an <identifier> causes
the new <replacement text> to replace the old.
.sh "undefine (<identifier>)"
.Sh "Undefine"
The
[bf undefine]
statement removes the definition of <identifier> from the
list of defined identifiers.  Subsequent occurrences of
<identifier> in the program will not be replaced unless
<identifier> appears in a subsequent
[bf define]
statement.
.sh "include '<path name>'"
.Sh "Include"
An
[bf include]
statement instructs 'rp' to begin taking input from
the file specified by <path name>.
When the end of the file is reached, 'rp' resumes taking input from
the file containing the
[bf include]
statement.
The path name may be surrounded by either single or double quotes.
The file specified by <path name>
may contain further
[bf include]
statements, up to a maximum depth of 5.
.MH "Ratfor Declarations"
.sh "linkage <identifier> { , <identifier> }"
.Sh "Linkage"
The
[bf linkage]
declaration is used to guarantee that long external names are
transformed into the same unique Fortran name.
Names are transformed as they are presented in the
[bf linkage]
declaration.  The same
[bf linkage]
statement should appear as the first statement of each
separately compiled source module, and should contain the
names of all subroutines, functions, and common blocks in
the program.
.sh "local <identifier> { , <identifier> }"
.Sh "Local"
The
[bf local]
declaration allows the declaration of variables with names
local to the scope of a compound statement (block).  The
[bf local]
declaration should appear inside a compound statement and
must precede all occurrences of the identifiers to be declared
local to the block.  All identifiers appearing in a
[bf local]
declaration must subsequently appear in a type declaration in
the same compound statement.
.sh "string <name> <quoted string>"
.Sh "String"
The
[bf string]
statement generates declarations to produce an EOS-terminated
string in the integer array <name>.  <Quoted string> must
be surrounded by either single or double quotes.
.sh "stringtable <index>, <body>, [ / ] <item> { / <item }"
.Sh "Stringtable"
The
[bf stringtable]
declaration creates a marginally indexed array of integers
and character strings.  <Index> and <body> are variables to
be declared as the index and body arrays respectively.
<Body> is a one-dimensional array in which the values generated
by the <item>s are stored consecutively.
The first element of <index> contains the number of
remaining elements in <index>; subsequent elements each contain
the index in <body> of the first position of the corresponding
<item>.
.sp
<Item>s are comma-separated lists of integers, single-character
constants, and strings (with no string format indicators).  Integers
and EOS-terminated strings are generated and stored consecutively
in <body>.  The first position of each <item> in <body> is stored
in the corresponding entry of <index>.
.MH "Ratfor Control Statements"
.sp
.sh "break [<integer>]"
.Sh Break
The
[bf break]
statement allows the user to terminate the execution of
a for, while, or repeat loop and resume control at the first statement
following the loop.  The <integer> specifies the number of loops to
terminate; if absent, 1 is assumed (only the innermost loop is terminated).
If the integer is N, then the N innermost loops currently active are
terminated.
.sh "do <limits>; <statement>"
.Sh Do
The
[bf do]
statement provides a means of accessing the local Fortran
do-statement.  <Limits> includes whatever parameters are necessary to
satisfy Fortran, minus the statement number of the last statement to
be performed, which is generated by Ratfor.
The semicolon must not be used
if the statement to be iterated does not appear on the same line as the
[bf do.]
.sh "for '(' <init>; <condition>; <reinit> ')' <statement>"
.Sh For
The
[bf for]
statement is a very general looping construct.  <init> is
a statement to be executed before loop entry; it is frequently used
to initialize a counter.  <Condition> is a condition to be satisfied
for every iteration; the condition is tested at the top of the loop.
<Condition> becoming false is the most often used method of terminating
the loop.  <Reinit> is a statement to be executed at the bottom
of the loop, just before a jump is made to the top to test the <condition>.
<Reinit> is usually used to increment or decrement a counter.
<Statement> may be any legal Ratfor statement.
.sh "if '(' <condition> ')' <statement> [else <statement>]"
.Sh If
[bf If]
is a generalization of the Fortran logical-if statement.
If the condition is true, the first <statement> is executed.  If the
optional
[bf else]
clause is missing, control is then passed to the
statement following the
[bf if;]
otherwise, the <statement> following
the
[bf else]
is executed before passing control.
.sh "next [<integer>]"
.Sh Next
The
[bf next]
statement complements the
[bf break]
statement.  It is used
to force the next iteration of a for, repeat or while loop to occur.
The parameter <integer> specifies the number of levels of nested loops
to jump out; if omitted, the innermost loop is continued; otherwise,
for <integer> = 2, the next-to-innermost loop is continued, etc.
.ti [in]
.sp 2
.ne 6
.bf 10
procedure <procid> [ '(' <id> {, <id> } ')' ]
      [recursive <integer>]
      ( forward | <compound statement> )

[call] <procid> [ '(' <expr> {, <expr> } ')' ]
.bf 0
.Sh "Procedure"
.pp
The
[bf procedure]
declaration allows the declaration of internal Ratfor procedures.
<Procid> is the name of the internal procedure.  Formal parameters
(scalar, pass-by-value) are declared following the <procid>.
Formal parameters must appear in a type declaration in the
body of the procedure.
If the procedure is to be called recursively, the
[bf recursive <integer>]
clause must be included;  <integer> is the maximum number of recursive
calls in process at any given time.  Following the heading,
either a compound statement or the word
[bf forward]
must appear.  If the
[bf forward]
option is used, a
[bf procedure]
declaration containing <compound statement> must follow at
some point in the program unit.  Formal parameters specified on
the second declaration may be present, but are ignored.
.pp
A <procid> must be defined before it is referenced by a call.  The
call can appear exactly as a Fortran call, or the word
[bf call]
can be omitted.  Actual parameters must correspond in number
to formal parameters.  If the formal parameters list is omitted
in the declaration, no actual parameter list may be present.
.sh "repeat <statement> [until '(' <condition> ')']"
.Sh Repeat
The
[bf repeat]
statement is used to generate a loop with the iteration
test at the bottom.  The <statement> is performed, then the <condition>
checked; if false, the <statement> is repeated.  If true, control
passes to the statement following the
[bf until.]
If the
[bf until]
is
omitted, the loop is repeated indefinitely, and must be terminated
with a
[bf stop, break,]
or
[bf goto.]
.sh "return ['(' <expression> ')']"
.Sh Return
The [bf return] statement behaves exactly like its Fortran
counterpart, except that if the optional parenthesized expression
is included inside a function subprogram, the value of <expression>
will be assigned to the function name as the function value before
the return is executed.
.ti [in]
.sp 2
.ne 8
.bf 10
select
    {when '(' <condition> {, <condition>} ')' <statement> }
    [ifany <statement>] [else <statement>]

select '(' <integer expr> ')'
    {when '(' <integer expr> {, <integer expr>} ')' <statement>
    [ifany <statement>] [else <statement>]
.bf 0
.Sh "Select"
.pp
[bf Select]
is a generalization of the
[bf if]
statement.  In its first alternative, the
[bf when]
<conditions>s
are evaluated in order;  the <statement> associated with the
first one found to be true is executed.
If any <condition> is
found true, the <statement> associated with
[bf ifany]
is executed; if none are found true, the <statement> associated with
[bf else]
is executed.
.pp
Similarly, in the second alternative, the <integer expr> associated
with
[bf select]
is evaluated.  The result is then compared to the <integer expr>s
associated with the
[bf when]
parts in an unspecified order.  When an equal comparison is made,
the <statement> following the corresponding
[bf when]
is executed.
If an equal comparison is made, the <statement> following
[bf ifany]
is executed; if no equal comparison is made, the <statement>
following
[bf else]
is executed.
.sh "while '(' <condition> ')' <statement>"
.Sh While
The
[bf while]
statement is the basic test-at-the-top loop.  The <condition>
is evaluated; if true, the <statement> is executed and the loop is repeated,
otherwise control passes to the statement following the loop.
.sp