# flibs/tools(n) 1.0 "flibs"

## NAME

flibs/tools - Modify program code

## TABLE OF CONTENTS

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.

## COPYRIGHT

Copyright © 2008 Arjen Markus <arjenmarkus@sourceforge.net>