mppl - More Productive Programming Language [ ] [ ... ] -Dname[=def] allows programmers to write in a language more convenient and powerful than Fortran 77. transforms statements written in the language into standard Fortran 77. is an extension to Fortran 77 that provides free-form input and structured constructs such as ``while'' and ``for'' loops. It provides most Fortran 90 syntax for real and integer declarations, literal constants, and intrinsic functions, making it easy to write portable code for machines with different wordsizes. macro preprocessor and file-inclusion facility encourages structured, easy-to-read programs with fewer labels. is available for most Unix variants. Options are entered first on the command line. Options and filenames may not be interspersed. If no files are given, or if a `-' alone is given, reads from stdin. All output is written to stdout, and error output to stderr. Where is a 1-5 digit integer, specifies the beginning value for mppl-generated statement labels. The value should be chosen to prevent duplication of existing labels in your code. Mppl restarts the sequence in each subroutine. The default value of is 23000. Turn off the output of blank lines and comments. The default is to pass blank and comment lines to the output. Set the column 1 comment character to be any of the characters in (up to three characters may be specified). The default value of this option is "cC*". Specify the compiler to be used on the mppl output. This sets the macro COMPILER to have the value Convert literal character constants enclosed with quotation (") characters to Fortran 77 standard constants using the apostrophe character (') for quoting. Define the macro to have the value as if mppl had read the statement define name def This option may be repeated. Careful quoting is required to embed blanks into def: -Dname="'this is a string'" is typical. Set free-form input. This disables the usual column 1 comment convention and the column 6 continuation convention. MPPL "#" comments may still be used in any column. If you only want to disable the column 6 continuation convention, specify a "-ccC*" (or similar "-c" option) after the "-f" option. Set the IntegerSize to N. Legal values are 2, 4, or 8, and imply that an integer variable without kind-selector, or literal integer constant will be stored in at least 2, 4, or 8 bytes, respectively. Insert into the search path for include files. Usage is similar to the UNIX C preprocessor. For instance, the options -I.. -I/usr/local/vbasis/pkg tells mppl to search the parent directory and /usr/local/vbasis/pkg for include files, in addition to the current directory. The current directory is always searched first. Set the length limit for output lines to 80 instead of the standard 72 columns. This limit does not apply to comment lines. Prevent mppl from activating the Basis definitions. Non-Basis users of mppl should use this option if problems develop from the Basis definitions. See mppl.BASIS in the FILES section below. Specify the machine we intend to compile on. This sets the value of the macro MACHINE to and may affect the definition of other predefined macros. Set the RealSize to N. Legal values are 4, 8, or 16, implying that a real variable with no kind-selector (see Type Conversions below) or literal floating point constant of the form 0.0e0 will be stored in an element of at least 4, 8, or 16 bytes, respectively. Set the intrinsic macro SYSTEM to Sys, and set the value of other intrinsic macros to the default values for the system named. This allows you to ``cross-compile'' source for a Fortran compiler on another system. This option sets the macros MACHINE, COMPILER, TYPE, CHAR_PER_WORD, LOCS_PER_WORD, and WORDSIZE to the defaults for the target system. Use the -C, -D, or -M options to over-ride these defaults as required. Provide "case insensitivity" for macro names. Either all upper or all lower case (not a mixture) may be used to invoke a macro. This option is required if Fortran keywords in your source code are in upper case. Turn on verbose output. Note each input file as it is processed. Turn on extra warning messages. In particular, warn if Size requests cannot be satisfied in the given target compiler. E.g., if the compiler has no 16 byte wide floating point type, then a request for a Size16 real object will be mapped into Size8, and, if the flag was given, a warning message will be printed to stderr. Convert mppl language macros into Fortran 77. (default) Convert mppl language macros into Fortran 90 using the free source form. Do not convert mppl language macros. Most Fortran 77 conforming programs are also legal MPPL input files. (However, MPPL is whitespace- and case-sensitive, see below.) In addition, MPPL extends Fortran in several areas.

Comments
The characters `#' and `!' may appear anywhere, and mark the beginning of a comment which extends to the end of the physical line. Comments which appear on a line after meaningful program text are output before the statement itself. Within a macro definition body, such comments are discarded. However, a comment which is made using the "column 1" convention is kept in a macro definition body. Dollar-sign substitution does not occur within such a comment when the macro body is expanded. The Immediate macro can be used to force inclusion of anything, including a comment, in a macro body.

Continuation Characters
MPPL recognizes the following characters as continuation characters (indicating that the logical input line extends over more than one physical line) when they occur as the last non-blank token on a line: \ + - * ( , & | ~ > < = Forward slash (/) is not a continuation character because it is normally the final character in a DATA statement. The semi-colon character (;) is a logical newline in MPPL, and may be used to place more than one statement on a physical line.

Quoting
MPPL allows character strings in its input to be quoted with either the quote character (") or the apostrophe character ('), and they may be alternated - e.g., 'Quoth he, "what a mess!"' It normally passes literal character constants without change to the target compiler. Use the -d option if your Fortran compiler does not allow quoted strings.

Relational Operators
MPPL recognizes the following relational operators, and translates them as shown:
Symbol | Translation
> | .gt.
>= | .ge.
< | .lt.
<= | .le.
~= | .ne.
<> | .ne.
~ | .not.
 | .eq.
== | .eq.
| | .or.
& | .and.

Other Special Characters
The left and right square bracket characters [ ] are legal in MPPL, and are generally used to quote (delay expansion of) macro names or arguments. Each time brackets are encountered, the outermost pair is stripped off, with no further evaluation of their contents at that time. It is not possible to change the quote characters to other than square brackets. The dollar sign character $ is used to interpolate arguments when macros are expanded. A dollar sign followed by digits 1-9 in a define statement (see below) is replaced by the corresponding argument when the macro is expanded. $0 is the name of macro being expanded. $* expands to the complete, comma-separated argument list. $- is all arguments save the first. This can be useful for recursive definitions. $$ is replaced with a literal dollar-sign. Dollar-sign followed by any other character results in the insertion of that character into the expansion text. The combination of an at sign @ followed by a digit 1-9 is replaced by the next available automatically generated label number, and generally is used in macro definitions. Each occurrence of @n is replaced by the same number within a particular expansion of the macro.

Incompatibilities With Fortran
Whitespace (space, tab, or newline with continuation) is generally significant in MPPL. Input tokens (keywords, literal constants, macro names, etc.) must not have embedded white space nor be broken across a continuation line. In Fortran 77, keywords (if, do, etc.) are not reserved. In contrast, MPPL treats many Fortran keywords as reserved words. For example, the statement ``real if'' is a legal variable declaration in Fortran 77, but is an error in MPPL. A macro name is a string of upper or lowercase letters, digits, or underscore characters, beginning with a non-digit. The maximum length of a macro name and definition are limited by available memory.

Fortran Keywords
The following Fortran keywords are incorporated as macros in MPPL, and may not be used in any other than their normal context: block, do, else, elseif, end, endif, function, if, program, return, subroutine, then.

New Keywords
MPPL has additional (reserved) keywords which are not part of Fortran 77. They are translated into one or more standard Fortran statements during processing. See Statements below for details on their use. They are treated as macros during processing and are listed as follows: break, case, default, enddo, endfor, endselect, endwhile, for, next, select, until, while.

Built-in Macros
The remaining built-in macros extend the MPPL language by allowing the user to create and manipulate their own macros, test their values, incorporate external files, and so on. define name value
define(name,value)
Undefine([name]) In the first form, the next token after define is taken as the macro name. Its translation is taken as value, with leading and trailing whitespace removed. Neither name nor value are scanned for further macros to expand. The second form is expanded and then rescanned for additional macros in the expansion. Also, value may extend over several physical input lines. When a macro is expanded, quoted strings in the macro definition do not protect arguments ($1,$2, etc.) inside them. However, quoted strings in the input (outside of a macro) do protect macro names inside of them from expansion. The third form removes name from the list of known macros. The square brackets are required. Any macro may be undefined, including built-in macros, but undefined built-ins cannot be restored. Macros can also be redefined at any point, and the new definition will replace the old. ifdef([a],b,c)
ifelse(a,b,c,d) The first form is replaced by b, if a is currently a defined macro name, otherwise the result is c. Either b or c may be null, and either may incorporate additional macros. The square brackets are required. In the second form, if a is identical to b (possibly after macro expansion and stripping leading or trailing whitespace), then the result is c, otherwise the result is d. The second argument may be of the form b1|b2, which implies comparison of a successively against b1,b2, etc. Errprint(message)
Infoprint(message)
Immediate([comment]) Errprint writes the message to stderr along with extra information detailing the current location in the input file, and increments an internal error counter, which will normally cause the mppl process to exit later with a non-zero status value. Infoprint simply writes its argument to stderr. The Immediate macro writes its argument to stdout and is typically used to embed Fortran comment lines in the body of a macro expansion. Dumpdef([macroname]) With no argument, display all current macro names and their definitions to stderr. Otherwise, show the definition of the given name. The square brackets are required. Evaluate(arg) If arg is an integer expression, the output is the value of that expression. Otherwise the argument is emitted verbatim. include filename Include the named file at the current point in the input stream. The new file is then processed immediately, and may itself have include statements, to a depth of five files. The current working directory is always searched first for filename, after which any additional directories given via the -I option are searched. Module This is an internal macro which always contains the name of the current subroutine, function, or program module being processed. It can be incorporated into user-defined macros as desired. Prolog The value of Prolog is interpolated by MPPL immediately after the first line of each Fortran module, and is by default simply a comment. The user may re-define it as desired.

Invocation-Specific Manifest Constants
Mppl defines many additional macros for use in making source code more portable. These are read in when mppl starts up; their values change according to the operating system and other parameters. (See FILES below.) Some of the more important constants are listed here. To see all the pre-defined macros, run mppl interactively and enter Dumpdef, followed by a newline and Control-D. Each pair of lines printed is a macro and its definition.
Fortran 90 allows declarators, real and integer literal constants, and some intrinsic functions to receive an optional kind-selector argument to indicate which "kind" (size or width) of object is desired. The kind-selector is a non-negative integer which may vary from compiler to compiler and therefore is usually written with a parameter. Mppl accepts the symbols "Size4", "Size8", "Size16" (or "4", "8", "16") as kind-selectors for the real and complex data types, and "Size2", "Size4", "Size8" (or "2", "4", "8") for the integer type. The kind-selector states that an object of the given size will be stored in a space of at least that many bytes, or possibly more.

Declarations
Declarations of type real, complex, and integer accept an optional kind-selector:
	real(Size4) x
	complex(Size8) z
	integer(Size4) i
These forms are translated by mppl into equivalent Fortran 77 statements, or possibly into syntax specific to the target compiler (e.g., real*16) if there is no standard Fortran 77 representation of the desired form. If no kind-selector is given, translation depends upon the target SYSTEM and the prevailing RealSize (see the -r flag discussion under OPTIONS).

Literal Constants
Literal constants of type real, integer, or complex may have an optional kind-selector appended with a trailing underscore character:
	x = 1.0e23_Size4
	z = (1.0_Size8, 2.0_Size8)
	i = -123_Size4
Mppl translates the real form into a standard single- or double-precision Fortran 77 literal constant. If no kind-selector is given, translation depends upon the target machine and the prevailing RealSize. At the present time, there are no alternative output forms for literal integer constants - translation simply removes the kind-selector, if present. Mppl will complain about literal double-precision constants in its input if the -w flag is given, and request the user to convert them to the machine-independent forms shown above. (Output to stdout is not affected by the -w flag, however.)

Intrinsic Functions
Currently, the following (generic) intrinsic functions are accepted with an optional kind-selector as a final argument to denote the return type of the function:
	aint()	# Truncation to whole number
	anint()	# Nearest whole number
	cmplx()	# Conversion to complex type
	int()	# Conversion to integer type
	nint()	# Nearest integer
	real()	# Conversion to real type
Two functions which are specific intrinsic names in Fortran 77, aimag and conjg, have become the generic names in Fortran 90. In order to support the double complex type, mppl will translate these names to dimag and dconjg if the target compiler accepts them and the RealSize is greater than 4. No kind-selector is required or accepted for those two.

Bit Manipulation Functions
Mppl provides translation from (a subset of) the Fortran 90 bit manipulation procedures into target-specific forms, as listed:

Iteration
do dolist; block; enddo
while(lexp); block; endwhile
do; block; until(lexp)
for(init_block,lexp,iter_block); block; endfor These four statements expand the range of looping constructs available to the Fortran programmer. The first form is a label-less do loop, where dolist is an expression of the form ``k=start,end[,stepsize]''. Block is any sequence of executable statements up to the enddo statement. As a special case, dolist can be empty, in which case the loop is infinite, (but see break below). The do...enddo construction is translated to a standard Fortran labeled doloop by mppl. The while statement implies execution of the enclosed block zero or more times, as long as the logical expression lexp evaluates to TRUE. It is translated to a block-if statement with an enclosing goto by mppl. Its alternate form is the do...until construct, which always executes its block at least one time. The for statement is essentially equivalent to the sequence
	init_block
	while(lexp)
	block
	iter_block
	endwhile
Either init_block or iter_block may be empty, or may have multiple statements separated by semi-colons.

Conditional Execution
select(iexp); case ilist: block; ...; default: ; endselect The select statement compares the integer expression iexp to the values listed in the case statements following, and executes at most one case. The default: section is optional, and will be executed only if all other cases fail to match. The ilist is a single integer, a range (e.g., 1-5), or a comma-separated list of integers and ranges. The trailing colon is required. Select is translated to either a series of if statements or to a "computed goto", depending on the number of consecutive case values.

Branching
break [(N)]
next [(N)]
return [(value)] The break and next statements can be used inside any of the looping constructs above. Break causes execution to be transferred to the first statement following the N'th enclosing loop. The value of N defaults to 1 if not given. Parentheses are optional. The next statement causes the next iteration of the N'th enclosing loop to begin immediately. If used in a for loop, the iter_block is executed before beginning the next iteration. It may also be used inside a traditional Fortran do-loop, but note that control transfers to the labeled statement, which may or may not be a continue statement. Return is used inside a function to return a value to the caller. For convenience, MPPL allows the two enhanced usages shown below:
	return(expression)
	if(condition) return(expression)
Paul F. Dubois, Lee Busby, Peter Willmann, Janet Takemoto, Lawrence Livermore National Laboratory. The following files are normally located in the same directory as the executable. mppl.sys Macros for initializing values dependent on the SYSTEM. This file is read first. In particular, the WORDSIZE parameter must be set in this file, and nowhere else. mppl.std Standard startup macros, and macros for emulating Fortran 90 declaration syntax, MIL-STD-1753 bit operations, and several other things that don't fit anywhere else. mppl.BASIS MPPL macros which customize for use with the Basis code development system. BASIS_VERSION This file is optional. If it exists and is readable (and the -m flag is not present), opens it and reads it as MPPL input. It typically defines three macros, BASIS_MAJOR_VERSION, BASIS_MINOR_VERSION, and BASIS_VERSION. works at the source code level, by translating real to double precision, or implicit real to implicit double precision, etc., before the Fortran compiler ever sees the code. Mppl can't translate anything that's not explicitly present. You cannot use default implicit declarations if you want to take advantage of mppl's automatic type interpretation. This requires that, at a minimum, you insert the following implicit statement into any module which previously used default implicit typing: implicit real(a-h,o-z),integer(i-n) (If you use the Prolog macro of mppl to automatically insert the requisite statement, note that you will need to hide the parentheses within square brackets: define Prolog implicit real[(a-h,o-z)],integer[(i-n)] The requirement for explicit declarations carries over into the input files which are processed by the Basis utility mac. will apply the default Fortran typing rules for variables, function parameters and function names. You will need to over-ride these defaults in order for to make an appropriate translation. This means that the input line which previously was f(a,b,c) function will need to have explicit declarations added: f(a:real,b:real,c:real) real function Now the word real will be translated by mppl according to the setting of the -r command line flag as stated above. Sometimes it is useful to declare certain variables or function arguments within an otherwise Size8 mac input file as Size4. To do this, add the line usertype real4 immediately after the package name, which is normally on line 1 of the file. Then add the two lines
	%define real4 real(Size4)
	%define _real4 real4
to the parameter section of the file. (The parameter section is enclosed in curly braces, typically near the top of your .v file. In the example above, if parameter b and the function f itself are known to be Size4, then the proper declaration statement reads as f(a:real,b:real4,c:real) real4 function. This approach can be extended in the obvious way to handle explicit declarations for complex(Size4) or other requirements. Mppl is useful for translating a single precision code to double precision, typically using the -r8 flag and the Prolog macro as described above. You may also need to translate single precision versions of library functions to their double precision counterparts. Typical code to do that looks like this:
	ifelse(WORDSIZE,32,[
	ifelse(RealSize,8,
	[define([saxpy],[ifelse([$*],,[daxpy],[daxpy([$*])])])]
	[define([scopy],[ifelse([$*],,[dcopy],[dcopy([$*])])])]
	]))
Mppl has the ifdef macro to match that command in the C pre-processor. It does not have any ifndef macro. However, you can easily achieve this by making the first clause null:
	ifdef([foo],,[
	(This is what happens if foo is NOT defined.)
	])
Cannot read tokens split across a continuation line or with embedded white space. (Note, however, that mppl will cheerfully write its own output with tokens split across lines.) Programs which equivalence real with integer or logical types may break after type conversion by mppl. does not check the argument and return types of externally compiled or Fortran specific intrinsic functions. As always in Fortran, "it is the programmer's responsibility" to verify correct type matching across subprogram interfaces. If for some twisted reason you want to write an expression using the intrinsic function real with an argument which is the same as one of the built-in kind-selectors, e.g. "a = real(8)", you will have to use the 2-argument form: "a = real(8, Size8)". The particular kind-selectors Size4, Size8, etc. are hard wired in and cannot be redefined by the user. It might have been better to use names like Prec6, Prec15 to indicate directly the number of decimal digits of precision desired. Certain unusual, but legal Fortran statements run afoul of the fact that Fortran keywords are macros in MPPL. For example, if(x .eq. y) if(a)1,2,3 will be translated incorrectly. Use square brackets around the second "if" in order to prevent this problem. Comment lines interspersed between an initial line and a continuation line must begin in column 2 or greater.