S TOOLS-STx preprocessor

S_TOOLS-STx preprocessor

The S_TOOLS-STx preprocessor may be used for conditionally skipping parts of an S_TOOLS-STx macro depending on which preprocessor constants have been defined (and which haven't). In the S_TOOLS-STx script examples directory, you will find a script called "preprocessor.sts" showing several ways of using the preprocessor.

Every S_TOOLS-STx preprocessor command must start either with the character "!" (exclamation mark), or with the character "]" (closed square bracket). Although not strictly enforced (the preprocessor only issues a warning otherwise), either character should be placed in the very first column of the respective line.

For defining and undefining a preprocessor constant, there are the preprocessor commands "define" and "undef":

! define CONSTANT1
! define CONSTANT2
! undef CONSTANT1

Like S_TOOLS-STx item names, S_TOOLS-STx preprocessor constants are case-insensitive, meaning that "CONSTANT1", "constant1", and "CoNsTaNt1" are the same constant.

Note that (for the time being), the only property of preprocessor constants is their being defined or being undefined. It is currently not possible (since it would currently make no sense) to assign a value to a constant.

The conditional "ifdef", "elif", "else", and "endif" preprocessor statements cause the macro interpreter conditionally to skip part of the macro source code. See for yourself:

! ifdef CONSTANT       writelog 'This statement will be executed if CONSTANT is defined' ! else    writelog 'This statement will be executed unless CONSTANT is defined' ! endif

With the "if" command, there is also support for complex conditions:

! if defined(CONS1) || defined(CONS2) && defined(CONS3)        writelog 'This statement will be executed if either CONS1 or both of CONS2 and CONS3 are defined' ! elif defined CONS4 && ! defined CONS5   writelog 'This statement will be executed if the preceding statement is not, and if CONS4 is defined and CONS5 is not ! else        writelog 'This statement will be executed if neither of the preceding statements were' ! endif

Note that you may, but need not enclose the argument of the "defined" function (i.e. the name of a constant) in brackets. Also note that you may build up complex expressions with the &&, ||, and the ! operator. Also also note that you may group expressions with brackets:

! if (defined(CONS1) || defined CONS2) && (defined(CONS3) ||
defined(CONS4))

If you do not use brackets, "&&" will take precedence over "||", as it normally does (and contrary to what S_TOOLS-STx normally does due to historical reasons).

There are a few additional preprocessor statements you may find useful:

!include

With the "include" statement, you may textually merge some other files into the current macro (just like with the "#include" preprocessor statement in C, or with COBOL copy books). Note that it is (for obvious reasons) not possible for a file to include itself, or to include a file that includes a file that, in turn, includes a file including the first file. If you try to, macro interpretation will abort with an error message. If the file name supplied to the "include" statement is not an absolute path, the preprocessor will first look for the respective relative path in the current directory and, on failure, will look for it in directory where the including file is situated. Note that, for the time being, file inclusion may not be nested for more than forty-two levels.

!showdef

Without arguments, this command will print a list of all preprocessor constants currently defined. With an argument supplied, the command will show if the argument is a preprocessor constant that is currently defined.

!warn msg

This statement causes the S_TOOLS-STx script loader to display a user-defined warning message. Execution of the script is not impaired by issuing a warning.

!error msg

This statement causes the S_TOOLS-STx script loader to issue a user-defined error message and to cancel loading the macro.

The S_TOOLS-STx preprocessor was introduced in version 3.8.0.