README for rf-4.44.5			M.J.Harrison 02/20/2022


General Description
-------------------

The rf package provides an implementation of a preprocessor for the
Ratfor language, written (except for a few primitives) in the Ratfor
language. It also contains a bootstrap set of files in FORTRAN (produced
by applying rf to its own source) so that an initial version of rf can
be built in the absence of an existing copy of its executable.

Since it is unlikely that any new code is being or will be written in
Ratfor, the main intent of this package is to allow the maintenance of
existing code in the language. 

The most accessible reference for Ratfor is the book "Software Tools" by
Kernighan and Plauger (Addison-Wesley, 1976, ISBN 0-201-03669-X). There
is also the paper "RATFOR - a preprocessor for rational Fortran" by
Kernighan in "Software - Practice and Experience" (October, 1975).


Building and Installing
-----------------------

Detailed instructions for building and installing the package are
contained in the file INSTALL.


A Useful Feature
----------------

Any of the GNU FORTRAN compilers will attempt to use a Ratfor preprocessor on
any files it is given to compile having the .r suffix. If you wish to use rf
in this way, all you have to do is put a link named "ratfor" in any directory
in your PATH with its target being your copy of rf.

Note: this feature was accidentally dropped from GNU f95/gfortran. It is
unclear whether it will be reinstated.


Language Features Supported
---------------------------

Comment
	#

Data declaration statements:
	string

Control flow statements:
	break
	do
	for
	if [else]
	next
	repeat until
	while

Preprocessor statments:
	define
	endif
	ifdef
	ifndef
	include
	undef


Implementation Details
----------------------

Any feature not described here has the syntax and semantics defined in
the "Software Tools" reference given above.

1. string

The string statement has the syntax:

	string name "<string>" [, name "<string>"]...

for example:
	string one "One",
	       two "Two"

If your FORTRAN compiler requires all DATA statements to follow all
declarations and to precede all executable statements, use one string
declaration and position it between the other declarations and the
executable statements.

2. define

The define statment has the syntax:

	define name [value-expression]

where
	value-expression ::= term | term + term | term - term
	term ::= factor | factor * factor | factor / factor
	factor ::= symbol | +symbol | -symbol | (value-expression)

where `symbol' can be an integer, or a name (subject to the FORTRAN
rules for valid names) that has been defined to a value that resolves to
an integer. Arithmetic is done on 32-bit integers. Any symbol that does
not resolve to an integer is given the value 0.

Symbol resolution is delayed until the last possible moment. The literal
value of `value-expression' is stored as the defined value of `name',
and resolved and evaluated only when `name' is referenced. The maximum
depth of symbol reference is 10. References that would lead to infinite
recursion are detected and the recursion prevented.

It is an error to attempt to define a symbol that is already defined.

3. undef

The undef statement has the syntax:

	undef name

This removes the definition for `name' and causes `name' to be
undefined. It is an error to undef a name that is undefined.

4. include

The include statement has the syntax:

	include file | "file"

If the quotes are omitted, `file' must not contain any non-alphanumeric
characters, and the suffix `.i' is implicitly added. With quotes, any
filename that is valid for the operating system may be specified.

The search path uses the environment variable INCLUDE. If INCLUDE is not
defined, only the current directory is searched; if INCLUDE is defined,
only those directories specified in the path given in the INCLUDE
definition are searched (i.e. the current directory is not searched
unless it is part of the INCLUDE path). The INCLUDE path uses the same
syntax as the PATH variable in the operating system (e.g. for Linux,
colons separate the components of the path).

Nested includes are limited only by the limit (10) on the number of
files open at once.

5. ifdef, ifndef, endif

The syntaxes for these are:

	ifdef name
	...
	endif

	ifndef name
	...
	endif

An ifdef or ifndef must always be followed by a matching endif, but
ifdef/endif and ifndef/endif pairs may be nested to any depth.

An ifdef is TRUE if and only if `name' is defined; an ifndef is TRUE if
and only if `name' is undefined. If the ifdef or ifndef is not TRUE, all
text between the ifdef or ifndef and the endif is removed from the input
stream as seen by the parser; ifdef, ifndef and endif themselves are
always removed.

There is no `else' because this would clash with the existing Ratfor
keyword `else'.