RAT4 06/12/80 RAT4 NAME rat4 - Ratfor preprocessor SYNOPSIS rat4 [files ...] >outfile DESCRIPTION rat4 translates the ratfor programs in the named files into Fortran. If no input files are given, or the filename '-' appears, the standard input will be read. A file containing general purpose software tools definitions (e.g. EOF, NEWLINE, EOS, etc.) will be automatically opened and processed before any of the files specified are read. Syntax: Ratfor has the following syntax: prog: stmt prog stmt stmt: if (expr) stmt if (expr) stmt else stmt while (expr) stmt repeat (expr) stmt repeat stmt until (expr) for (init expr; test expr; incr expr) stmt do expr stmt do n expr stmt break break n next next n return (expr) switch (expr) { case expr: stmt .... default: stmt } digits stmt { prog } or [ prog ] anything unrecognizable (i.e. fortran) where 'stmt' is any Fortran or Ratfor statement. A statement is terminated by an end-of-line or a semicolon. -1- RAT4 06/12/80 RAT4 Character Translation: The following character translations are performed: < .lt. <= .le. == .eq. != .ne. ^= .ne. ~= .ne. >= .ge. > .gt. | .or. & .and. ! .not. ^ .not. ~ .not. Included files: The statement include file or include "file" will insert the contents of the specified file into the ratfor input in place of the 'include' statement. Quotes must surround the file name if it contains characters other than alphanumerics, underscores, or dots. Macro Definitions: The statement define(name,replacement text) defines 'name' as a macro which will be replaced with the indicated text when encountered in the source files. Any occurrences of the strings '$n' in the replacement text, where 1 <= n <= 9, will be replaced with the nth argument when the macro is actually invoked. For example: define(bump, $1 = $1 + 1) will cause the source line bump(i) to be expanded into i = i + 1 The names of macros may contain letters, digits, periods and underline characters, but must start with a letter -2- RAT4 06/12/80 RAT4 (e.g. B.FLAG). Upper case is not equivalent to lower case in macro names. The replacement text is copied directly into the lookup table with no intepretation of the arguments, which differs from the procedure used in the macro utility. This "deferred evaluation" has the effect of eliminating the need for quoting strings to get them through the macro processor unchanged. A side effect of the deferred evaluation is that defined names cannot be forced through the processor - i.e. the string define will never be output from the preprocessor. The inequivalence of upper and lower case in macro names may be used in this case to force the name of a user defined macro onto the output - i.e. if the user has defined a macro named mymac, the replacement text may contain the string MYMAC, which is not defined, and will pass through the processor. In addition to define, four other built-in macros are provided: arith(x,op,y) performs the "integer" arithmetic specified by op (+,-,*,/) on the two numeric operands and returns the result as its replacement. incr(x) converts the string x to a number, adds one to it, and returns the value as its replacement (as a character string). ifelse(a,b,c,d) compares a and b as character strings; if they are the same, c is pushed back onto the input, else d is pushed back. substr(s,m,n) produces the substring of s which starts at position m (with origin one), of length n. If n is omitted or too big, the rest of the string is used, while if m is out of range the result is a null string. Note: the statement define name text may also be used, but will not always perform correctly for macros with parameters or multi-line replacement text. It is suggested that the functional form be preferred. -3- RAT4 06/12/80 RAT4 Conditional Preprocessing: The statements ifdef(macro,text) ifnotdef(macro,text) conditionalize the preprocessing upon whether the macro has been previously defined or not. String Data Types: The statements string name "character string" or string name(size) "character string" declare 'name' to be a character array long enough to accomodate the ascii codes for the given character string, one per array element. The array is then filled by data statements. The last word of 'name' is initialized to the symbolic parameter EOS, and indicates the end of a string. EOS must be defined either in the standard definitions file or by the user. If a size is given, name is declared to be a character array of 'size' elements. If several string declarations appear consecutively, the generated declarations for the arrays will precede the data statements that initialize them. Escape sequences are recognized in string declarations, such that @n maps into the NEWLINE character and @t maps into the TAB character. @c for any other character simply maps into the character c. In particular, to embed an atsign '@' in a string, one must type '@@'. String Literals: Conversion of in-line quoted strings to hollerith constants is performed in the following manner: "str" nHstr 'str' nHstr (where 'n' is the number of characters in str) String literals can be continued across line boundaries by ending the line to be continued with an underline. The underline is not included as part of the literal. Leading blanks and tabs on the next line are ignored. Integer Constants: -4- RAT4 06/12/80 RAT4 Integer constants in bases other than decimal may be specified as n%dddd... where 'n' is a decimal number indicating the base and 'dddd...' are digits in that base. For bases > 10, letters are used for digits above 9. Examples include: 8%77 (=63), 16%2ff (=767), 2%0010011 (=19). The number is converted to the equivalent decimal value using multiplication; this may cause sign problems if the number has too many digits. Lines and Continuation: Input is free-format; that is, statements may appear anywhere on a line. Lines ending with a comma, +, -, or * are assumed to be continued on the next line. An exception to this rule is within a condition; the line is assumed to be continued if the condition does not fit on one line. Explicit continuation is indicated by ending a line with an underline character (_). The underline character is not copied to the output file. Comments: Comments are preceded by '#' signs and may appear anywhere in the code. Literal (unprocessed) Lines: Lines can be passed through rat4 without being processed by preceding and following the blocks of lines with a line containing only a '%'. The '%' lines will not be copied to standard output. CHANGES This ratfor preprocessor differs from the original (as released by Kernighan and Plauger) in the following ways: The code has been rewritten and reorganized for clarity. A hash table has been added for increased efficiency in searching the definitions list. The 'string' data type has been included. The define processor has been augmented to support macros -5- RAT4 06/12/80 RAT4 with arguments. Conditional preprocessing upon the definition (or lack therof) of a symbol has been included. Many extraneous gotos have been avoided. Some blanks have been included in the output for increased readability. Multi-level 'break' and 'next' statements have been included. The Fortran 'DO' is allowed, as well as the ratfor one. The capability of specifying integer constants in bases other than decimal has been added. Underscores and dots have been allowed in defined names. The 'define' syntax has been expanded to include the form: define name value The 'return(value)' feature has been added. Quoted file names following 'include' statements have been added to allow for special characters in file names. A toggle for allowing lines to pass through un-processed has been added. The 'switch' control statement has been included. Continuation lines have been implemented. Brackets have been allowed to replace braces. FILES A generalized definition file (e.g. 'ratdef') is automatically opened and read. SEE ALSO Kernighan and Plauger's "Software Tools" Kernighan's "RATFOR - A Preprocessor for a Rational Fortran" The Unix command rc in the Unix Manual The tools 'incl' and 'macro' -6- RAT4 06/12/80 RAT4 DIAGNOSTICS (The errors marked with asterisk '*' are fatal; all others are simply warning messages.) * arg stack overflow The argument stack for the macro processor has been exceeded. The size of the stack is determined by the symbol ARGSIZE in the file macsym. * buffer overflow One of the preprocessor's internal buffers overflowed, possibly, but not necessarily, because the string buffers were exceeded. The definition SBUFSIZE in the preprocessor symbols file determines the size of the string buffers. * call stack overflow The call stack (used to store call frames) in the macro processor has been exceeded. The definition CALLSIZE in the file macsym determines the size of this stack. can't open standard definitions file The special file containing general purpose ratfor definitions could not be opened, possibly because it did not exist or the user did not have access to the directory on which it resides. can't open include File to be included could not be located, the user did not have privilege to access it, or the file could not be opened due to some problem in the local primitives. * definition too long The number of characters in the name to be defined exceeded Ratfor's internal array size. The size is defined by the MAXTOK definition in the preprocessor symbols file. * EOF in string The macro processor detected an EOF in the current input file while evaluating a macro. * evaluation stack overflow The evaluation stack for the macro processor has been exceeded. This stack's size is determined by the symbol EVALSIZE in the file macsym. * for clause too long The internal buffer used to hold the clauses for the 'for' statement was exceeded. Size of this buffer is determined by the MAXFORSTK definition in the preprocessor symbols file. * getdef is confused There were horrendous problems when attempting to access the definition table illegal break Break did not occur inside a valid "while", "for", or -7- RAT4 06/12/80 RAT4 "repeat" loop illegal else Else clause probably did not follow an "if" clause illegal next "Next" did not occur inside a valid "for", "while", or "repeat" loop illegal right brace A right brace was found without a matching left brace includes nested too deeply There is a limit to the level of nesting of included files. It is dependent upon the maximum number of opened files allowed at a time, and is set by the NFILES definition in the preprocessor symbols file. invalid for clause The "for" clause did not contain a valid init, condition, and/or increment section invalid string size The string format 'string name(size) "..."' was used, but the size was given improperly. * missing comma in define Definitions of the form 'define(name,defn)' must include the comma as a separator. missing function name There was an error in declaring a function missing left paren A parenthesis was expected, probably in an "if" statement, but not found missing parenthesis in condition A right parenthesis was expected, probably in an "if" statement, but not found missing quote A quoted string was not terminated by a quote missing right paren A right parenthesis was expected in a Fortran (as opposed to Ratfor) statement but not found missing string token No array name was given when declaring a string variable * non-alphanumeric name Definitions may contain only alphanumeric characters, dots, and underscores. * stack overflow in parser Statements were nested at too deep a level. The stack depth is set by the MAXSTACK definition in the preprocessor symbols file. token too long A token (word) in the source code was too long to fit into one of Ratfor's internal arrays. The maximum size is set by the MAXTOK definition in the preprocessor symbols file. * too many characters pushed back -8- RAT4 06/12/80 RAT4 The source code has illegally specified a Ratfor command, or has used a Ratfor keyword in an illegal manner, and the parser has attempted but failed to make sense out of it The size of the push-back buffer is set by BUFSIZE in the preprocessor symbols file. too many definitions Ratfor's internal arrays could not hold all the definitions. The size of the definition table is determined by the MAXTBL and MAXPTR definitions in the preprocessor symbols file. unbalanced parentheses Unbalanced parentheses detected in a Fortran (as opposed to Ratfor) statement unexpected brace or EOF A brace occurred after a Fortran (but not Ratfor) statement or an end-of-file was reached before the end of a statement unexpected EOF An end-of-file was reached before all braces had been accounted for. This is usually caused by unmatched braces somewhere deep in the source code. warning: possible label conflict This message is printed when the user has labeled a statement with a label in the 23000-23999 range. Ratfor statements are assigned in this range and a user-defined one may conflict with a Ratfor-generated one. "file": cannot open Ratfor could not open an input file specified by the user on the command line. AUTHORS Original by B. Kernighan and P. J. Plauger, with rewrites and enhancements by David Hanson and friends (U. of Arizona), Joe Sventek and Debbie Scherrer (Lawrence Berkeley Laboratory). BUGS/DEFICIENCIES The line numbers given in error messages are NOT correct. They indicate only a general area in which to look for the error. Missing parentheses or braces may cause erratic behavior, including a read-past-eof message. Eventually Ratfor should be taught to terminate parentheses/brace checking at the end of each subroutine. Extraneous 'continue' statements are generated within Fortran 'do' statements. -9- RAT4 06/12/80 RAT4 There is no way to explicitly cause a statement to begin in column 6 (i.e. a Fortran continued statement), although implicit continuation is performed. -10-