UCM version v5_1

KPP: Generic Preprocessor

Contents:
Command Line Syntax: Arguments and options.
KPP Directives: Description of KPP directives.
See the Table of Contents for more information.

KPP is a preprocessor written in generic C, which is designed to replace the more important functions of Expand. Specifically, it handles includes files and conditional source. Include files can be imbedded to any depth and a full array of logical operators are available for use in the conditional commands.

KPP has been designed to be totally language insensitive. This means that it does not contain the Expand concept of built in environment identifiers and hence does not perform any of the modifications associated with the different FORTRAN environments recognized by Expand. The advantages are that:- (1) KPP will work just as well on C code as on FORTRAN, or for that matter any other text file. (2) It is much easier to support and maintain.

Unlike Expand KPP does not recognize any sort of mapping from input file names to output file names; in particular KPP does not automatically map .CIN files to .INC files. This means that whereas Expand will search for an external file called FILE.CIN extension to satisfy an include reference to FILE.INC, KPP will search for an external file called FILE.INC.

The lack of any default mapping of input file names into output file names means that KPP will not handle wild card file specifications that result in multiple input files.

UCM version v5_1

Command Line Syntax

kpp input [output] [-f option [-f option [..] ] ]

input

The name of the input file. The input file is assumed to be a standard ASCII text file containing imbedded KPP directives which control the processing. Each directive occupies a single line of text (i.e. ends with a carriage return). Note that wild card specifications will not work if multiple files match the pattern.

output

The name of the output file. If omitted, the output will be directed to the standard output stream, stdout. This usually corresponds to the terminal screen for interactive use.

-i directory or -i directory_1 directory_2 ...

Specifies alternative directories in which to search for include files. KPP searches for include files first in the users default directory and then in any directories specified with -i argument flags in the order in which they occur on the command line. KPP does not check the syntax of either the directory specifications or of the file names specified in imbedded INCLUDE directives (see below). It simply appends the directory specification to the front of the include file name and tries to open the file. The one exception to this rule is when the directory specification ends with an alphanumeric character; in which case a / is appended to the directory specification. (This enables a more natural directory specification on UNIX platforms.) If an include file cannot be found, KPP will abort with an error.
The second form of this argument exists to enable wild card directory specifications to work on UNIX platforms. If used, it should follow the input and output file specifications or else they will be interpreted as include directories.

-I file

Specifies a file which contains a list of alternative directories in which to search for include files. This provides a more convenient alternative to the -i option for situations in which the list of directories is large. The text file "file" is assumed to contain a directory list consisting of one line per directory.
One disadvantage of this method on UNIX systems is that path name abbreviations are not passed to the environment shell for interpretation. To partially offset this limitation kpp will scan each entry in "file" for environment variables and translate them with the getenv function. KPP recognizes environment variables as any character string preceded by a $ and terminated by a /, :, or end of line and which can be translated by the getenv function. Though inserted for use on UNIX platforms this feature is not machine specific and thus can also be used in VMS contexts.

-d option

Defines the option identifier, "option", as "true". In evaluating the logic expressions associated with imbedded IF and ELSEIF directives (see below), all option identifiers will have the value "false" unless they have been defined as "true" with a -d argument flag. Option identifiers can contain any ASCII characters except spaces, tabs, carriage returns, parentheses, or logic operators and are case insensitive. Any number of option identifiers can be defined.

-m macro[:value]

Redefines the value of the macro with identifier, "macro", to "value". The value of a macro defined with the -m option can contain any ASCII character except carriage returns, double quotes, and colons. If the value contains spaces, it must be enclosed in double quotes. Macro identifiers can contain any ASCII characters except spaces, tabs, carriage returns, curly braces, or colons and are case insensitive. Any number of macro identifiers can be defined.

-C string

Causes KPP to add comment lines to the output file which identify the source of included text. The comment lines will begin with string and the first line will contain the name of the included file (including the directory name). In some cases string may need to be imbedded in double quotes (e.g. to prevent the shell from trying to expand a * character.)

-c string

Causes comments generated with the -C option to be terminated with string. In some cases string may need to be imbedded in double quotes in order to be interpreted correctly. (e.g. to prevent the shell from trying to expand a * character.)

-P string

Redefines the prefix for KPP directives. (Default is "$$").

-A string

Redefines the logical AND operator. (Default is "&").

-O string

Redefines the logical OR operator. (Default is "|").

-N string

Redefines the logical NOT operator. (Default is "!").

UCM version v5_1

KPP Directives

$${identifier:default} or $${identifier}

Macro definition. This directive will be replaced by the string "default" unless it has been redefined with a -m option. The macro identifier is case insensitive and imbedded spaces or tabs are ignored. If it exists, the default value consists of all characters between the ":" and "}". If no default value is given then it is assumed to be null. Macros are evaluated before any other command directives and hence can be used to modify them.

$$INCLUDE 'filename' comment

Case "insensitive" include file. This directive will be replaced by the text in the include file specified by "filename". The file name will automatically be converted to lower-case before attempting to open the file. The processing is recursive in that the include file will also be processed and therefore can itself contain include directives. There is no built-in limit on the level to which this can occur. At least one space or tab must precede the first single-quote. The comment is not copied to the output.

$$INCLUDE "filename" comment

Case-sensitive include file. This directive works just like the previous one except that it does not alter the case of the file name. This is useful on systems in which file specifications are case sensitive.

$$IF logic_expression
$$ELSEIF logic_expression
$$ELSE
$$ENDIF

These directives form an IF block structure to create conditional text in the same way as in Expand. As one would expect, there can be zero or more ELSEIF directives and zero or one ELSE directive in the IF block. Note that the evaluation of other KPP directives (such as INCLUDE directives and imbedded IF blocks) within the conditional text are also conditional on the evaluation of the logic expression(s). Thus it is possible to make the inclusion of a file conditional The logic expressions must be preceded by at least one space or tab and can be any legal combination of option identifiers, logic operators, and parentheses. The usual operator order of precedence is assumed when evaluating these expressions.