flibs/tools(n) 1.0 "flibs"

NAME

flibs/tools - Modify program code

    TABLE OF CONTENTS
    DESCRIPTION
    EXAMPLES
    COPYRIGHT

DESCRIPTION

The editcode program is a specialised preprocessor for Fortran code: its purpose is to transform the code according to certain simple rules:

Add an "IMPLICIT NONE" statement at the beginning of a module or routine.
Replace one type by another (for instance: real ==> real(dp)).
Instrument the code (add extra statements).
Enable preconditions/postconditions/assertions.

It reads an input file called "editcode.inp" which should contain keywords and possibly parameters, steering the transformation of the code.

Here is a list of the keywords and their parameters:

INPUT-DIRECTORY dirname - Directory to expect the input source files
OUTPUT-DIRECTORY dirname - Directory to put the output source files in
FILE filename - Name of the source file to process
ADD-CODE-START code - Line of code to add at the start of a routine.
If more than one line is required, then just use several such keywords ADD-CODE-END code - Ditto at the end of a routine (this includes: RETURN, STOP and END)
ADD-CODE-STATEMENT code - Line of code to add _after_ each statement
ADD-USE code - Add a USE statement
REPLACE-TYPE old new - Replace variable type "old" by variable type "new"
REPLACE-STRING old new - Replace any string "old" by string "new"
ENABLE-IMPLICIT-NONE yes/no - Add an IMPLICIT NONE statement if none is present
ENABLE-PRECONDITIONS yes/no - Enable preconditions
ENABLE-POSTCONDITIONS yes/no - Ditto for postconditions
ENABLE-ASSERTIONS yes/no - Ditto for assertions
CLEAR-ALL-SETTINGS - Re-initialise the preprocessing information (everything is set to the default again)
INCLUDE filename - Read keywords from the given file before processing the rest of this input file (multiple levels possible)
__FILE__ - Macro replaced by the name of the current source file
__LINE__ - Macro replaced by the current line number
__ROUTINE__ - Macro replaced by the current routine name
__MODULE__ - Macro replaced by the current module name

Preconditions, postconditions and assertions are implemented as special comments:

! pre: x > 0.0 ! post: x > 0.0 ! assert: x > 0.0

If a condition is longer than one line, simply use & like any ordinary continuation line:

! assert: x > 0.0 .and. & ! y < 0.0

If the condition type is enabled, the condition is transformed into code like this:

if ( .not. ( & x > 0.0 .and. & y > 0.0 & ) then write(*,*) 'Assertion failed at line 10 in file myprog.f90:' write(*,*) 'x > 0.0 .and. &' write(*,*) 'y > 0.0' endif

The program also handles a simple form of exceptions via try/catch statements:

try ... code to handle the ordinary case ... catch ... code to handle an exception ... endtry

(Within a catch section you can use the routines of the exception_handling module)

Note:

Each argument must be surrounded by " or ' if it contains spaces. (The lines are read via list-directed input)
The INCLUDE statement is treated in the main program, all the others are treated by the preprocessor module.
Comment lines begin with !
The default settings are such that _nothing_ is done.

To make this preprocessing facility flexible, it consists of a main program and a module that does the actual work:

preprocess_init sets or resets the preprocessor data
preprocess_input takes a line of code and handles the information it contains
preprocess_file processes the given input file

EXAMPLES

The tests/tools directory contains several examples and a detailed explanation, but here is the input file editcode.inp for these examples:

INPUT-DIRECTORY in OUTPUT-DIRECTORY out ADD-CODE-START "write(*,*) 'In __ROUTINE__ (__MODULE__)'" ADD-CODE-END "write(*,*) 'Leaving __ROUTINE__'" ADD-CODE-STATEMENT "write(*,*) 'At __LINE__'" ADD-USE "use exceptions" REPLACE-TYPE "real" real(dp) REPLACE-STRING X Y ENABLE-IMPLICIT-NONE yes ! ! Does this cause an error? ENABLE-PRECONDITIONS ENABLE-PRECONDITIONS yes FILE example.f90 ! ! Now the check_init/check_reals example ! CLEAR-ALL-SETTINGS INPUT-DIRECTORY in OUTPUT-DIRECTORY out REPLACE-TYPE real type(checked_real) ADD-USE "use check_reals" ADD-CODE-STATEMENT "call check_assignment( __LINE__, '__FILE__' )" ! ! List of files to treat ! FILE "check_init.f90"

While mainly meant to test the correct working of the program, it does in fact illustrate its capabilities. The README file contains more information.