

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
       (e.g. B.FLAG).  Upper case is not equivalent to lower case
       in macro names.


                               -2-                               


RAT4                        06/12/80                         RAT4


       
       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:
       
       Integer  constants  in  bases  other  than  decimal may be


                               -4-                               


RAT4                        06/12/80                         RAT4


       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
       with arguments.
       
       Conditional  preprocessing  upon  the  definition (or lack
       therof) of a symbol has been included.


                               -5-                               


RAT4                        06/12/80                         RAT4


       
       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'

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


                               -6-                               


RAT4                        06/12/80                         RAT4


            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
            "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


                               -7-                               


RAT4                        06/12/80                         RAT4


       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
            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.


                               -8-                               


RAT4                        06/12/80                         RAT4


       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.
       
       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.










                               -9-                               

