Findent is a computer program to indent Fortran sources. Findent can also be used to convert from fixed format to free format and vice versa. The program findent became more complex than originally foreseen, that is why I wrote this document covering the inner workings of findent.
Findent: Design objectives
Assuming that findent will be used in serious projects, involving large Fortran programs, the code of findent should be as reliable as possible, therefore it is kept as simple as possible:
Findent handles only two files: standard input and standard output. The input contains the Fortran program to be handled, the output contains the modified program.
The programming language is C++, a well maintained and documented language.
No multithreading is used.
Parsing the input is done with the aid of
flex: well known and maintained tools.
Findent mostly works on a line-by-line basis. (Exceptions: labelled
DO-loops require a simple administration, and relabelling needs the complete source of a program unit.)
Findent uses no configuration files: it is steered by command-line parameters and an environment variable containing command-line parameters.
A comprehensive test-suite is part of the distribution.
Findent is easy to use, yet offers the possibility to tweak the indentation to the user's taste:
All options have reasonable defaults, for example, usage can be as simple as:
findent < program.f90 > newprogram.f90
Furthermore, the findent distribution comes with a wrapper script wfindent that can be used like (to indent all .f90 files):
Normally, findent detects if the input in fixed or free form.
All types of indentation (
SUBROUTINE, ...) can be specified on the command line, for example to use 5 spaces after
findent --indent-do=5 <program.f90 > newprogram.f90
Findent ignores white space outside strings and label fields.
Fixed and free format Fortran are supported.
Conversion from fixed to free form is implemented, as well as the other way around.
All kinds of
DO-loops are recognized, even nested
DO-loops using the same label.
Findent has been tested on legacy Fortran sources, going back to Fortran IV. Hollerith's are parsed correctly.
Unrecognized constructions are allowed and are written on the output as-is. Incomplete Fortran sources are handled gracefully.
Findent can relabel the Fortran source. The man page contains a warning: 'use this only on correct programs'. If findent detects a problem (missing label definition; incomplete program unit; ...), relabelling is abandoned.
High speed: findent indents about 100.000 lines per second.
Building findent is easy and is based on standard tools:
The distribution tar ball is based on
autoconf, a mature program suite to distribute program sources.
The distribution tar ball contains the output files of
bison, so the user doesn't need to install these programs. (If they are installed, they will be used).
On Linux findent is built by unpacking the tar-ball, and issue the commands:
cd findent-xx.yy.zz ./configure make make check # to run the test-suite sudo make install
MacOS, building findent is the same as for Linux.
Windowsversion can be obtained by specifying the flag
configurecommand. You need to have
i686-w64-mingw32-g++or something like that available. Probably, using
Windowsshould make it possible to do the build on the Windows system.
If building as presented above does not succeed, the script
simplemake.sh, containing usage instructions, can be used.
Program development and maintenance
The following is for developers and maintainers:
autoreconf, replaces the copyright statements in nearly all sources and generates the output of the
bison. This output will be contained in the distribution tar ball, generated with
An esoteric option is
--with-esope. This causes findent to recognize
esopeconstructs, see http://www-cast3m.cea.fr/html/esope/esope.html.
In the files
src/debug.cppmacros and functions are defined to be used when debugging. There is comment in those files how to use them.
Findent comes with a comprehensive test suite, located in the directory
test. The tests will exercise every flag, and check if solved bugs are still solved. Testing is activated by running:
Flags to influence the working of findent
Options to findent can be given on the command line, like:
findent -ifixed -ofree -i2 < prog.f > prog.f90
and/or in the environment variable FINDENT_FLAGS, like:
export FINDENT_FLAGS='-i4 -I8' findent -ifixed -ofree < prog.f > prog.f90
Most flags relate to the format of the input file and
output file. However, some options arrange that
findent does not output an indented Fortran
source, but other information. These flags are marked in
the man page with the string
[NO_ENV] and are
ignored when present in the environment variable
FINDENT_FLAGS. Invalid flags, both on the
command line and in the environment, are silently
ignored2. Flags are read first
FINDENT_FLAGS and secondly from the
command line. The flags are handled in the files
See the man page for a description of the flags.
Findent can generate the following documentation:
A text file ('help-file'), describing all flags.
A man page, suitable for processing with the program
A text file, containing the ChangeLog.
Text files, describing the usage in an editor.
Text file describing how to use findent in editor, for example
Miscellaneous other functions
Print version of findent.
Print 'free' or 'fixed', depending on what findent deduces from the input.
Print dependency information, based on:
Usage and definitions of modules.
Print a shell script to be used in combination with the dependencies.
Print the amount of indentation of the last line read.
Print the line number of the last usable line as a start for indenting.
Print a report of defined and used labels.
Print scripts to incorporate findent in the editors
Detailed overview of the internals of findent
Starting the machinery
The main program is in
flags are read (
get_flags()), and if some kind
of documentation has to be produced
docs.print()), the program prints the
documentation and returns. Otherwise, the class
The main driver: fortran.run()
fortran.run executes the following tasks
(trivia are omitted here):
If standard input is connected to a terminal, take appropriate actions.
Read all of the input and store the lines in a buffer (
If the input format is not forced to be fixed or free, call
determine_fix_or_free()to determine the format.
class indentto either
Fixedas appropriate. These are subclasses of class
fortran.hto define the free or fixed alternatives of certain functions. See
Take actions if the user wants to relabel the input.
Enter the indenting loop (trivia omitted here):
get_full_statement()to create full Fortran line
full_statementby collating the possible continuation lines to the first (see below).
indent_and_output()to determine the indentation and output the lines that define the full Fortran line.
Collecting a full Fortran statement
Collecting a full Fortran statement from the first line
and continuation lines is done in
get_full_statement(). This function looks
surprisingly complex at first sight. This is because
continuation lines can contain:
findentfixlines (see the man page).
Furthermore, attention must be paid if we are
relabelling or not. The full Fortran statement is stored in
src/fortranline.h functions are defined to
handle lines with Fortran code. Care has been taken that
for fixed format, a tab at the start of a line is handled
The call to
build_statement() has a
different implementation for free and fixed format, see
respectively. This function performs the following
Add the input
c-lines(a list of
Add the line, stripped from all non-fortran stuff to
Signal if there are continuation lines to be expected. This is easy in the free-form case, but in the fixed-form case a look-ahead is necessary. See
Preprocessing the full Fortran statement
full_statement has been obtained,
this line is preprocessed to make it suitable for parsing
bison. This is
Line_prep::set_line(), in file
src/line_prep.cpp. An example may clarify
s - The full statement.
sl - Spaces removed, except in strings and Hollerith's, and after the statement label.
sv - Strings, Hollerith's, operators and statement label replaced by a space.
sc - Strings etc. replaced by
space number space, the number is the index in
scis used for parsing with
wv - A list, length =
sv.size(). Each entry consists of a
line_prep.h) which tells (
type) what this entry contains:
operator. In case of
stringtypewhich discriminates between Hollerith (
h), single quoted string (
') or double quoted string (
"). The value of the entry is contained in
s: [123 call sub(5habcde , 5, 'f oo', 'ab c' .concat. "def")] sl: [123 callsub(5habcde,5,'f oo','ab c'.concat."def")] sv: [ callsub( ,5, , )]  ! these are index numbers in sv sc: [ 0 callsub( 9 ,5, 13 , 15 16 17 )] wv: statement label  wv: hollerith string [abcde] wv: single quoted string [f oo] wv: single quoted string [ab c] wv: operator [concat] wv: double quoted string [def] The other entries have type=none.
Parsing the preprocessed full statement
Parsing the preprocessed full statement is done using
flex. Things are
arranged that one line at a time is parsed, see
lexer_set(Line_prep p, const int state) in
lexer.l. The string
above) is used for parsing. Parsing is initiated in
fortran.cpp by a call to
parseline(). This function, returning a
containing the results, parses the full statement in two
The lexer is brought in a state that does not recognize Fortran keywords. For example:
subroutinesub(x)=10will return kind=
If parsing does is not successful (kind =
UNCLASSIFIED), full statement is parsed again, but now the lexer is in a state to recognize relevant Fortran keywords. For example:
subroutinesub(x)will succeed and returning kind=
Keeping track of indents
fortran.cpp), a stack is maintained
containing the indents, along with the current index. The
actions are in principle quite simple: if after parsing a
relevant keyword is found (
DO, ...) the indent is changed as appropriate
and put on the stack. If a kind of
END SUBROUTINE, ...) is
found, the indent is pulled from the stack. Some constructs
deserve extra attention:
DO-loops: if a labelled
DO-loop is encountered, the label involved is stored on a stack. When a corresponding statement label is encountered, appropriate action is taken, also in the case of nested
DO-loops sharing to the same label.3
MODULE PROCEDUREstatements: at encountering a
MODULE PROCEDURE, indentation if the next full statement is classified as an executable statement.
MODULEPROCEDUREmyprocShould this be interpreted as:
MODULE PROCEDURE myprocFindent assumes the last is correct.4
Handling cpp and coco preprocessor statements
It was a design goal that findent should handle macro's more or less intelligent.
The following preprocessor statements (defined in
lexer.l) are recognized:
Note1: the rest of the preprocessing line is ignored,
so, for example,
#if has the same effect as
include's are only used when
generating dependencies, and are ignored when
Most of the preprocessor-handling code is reached via
pre_analyzer.cpp. The strategy is as
A stack is maintained to store the relevant items (e.g. the indentation level and the stack of indentations) (see
The relevant items are pushed on this stack after
The relevant items are popped off the stack if appropriate after
Handling the preprocessor statements is done recursively.
After a construct like
#if ... <fortran statements> #endif
the indentation continues from the state before the
#if, but after a construct like
#if ... <fortran statements> #else <fortran statements> #endif
the indentation continues from the state after the
In this way, most of the times findent will
generate sensible indentation. If findent makes an
error, this can easily be fixed by inclusion of a
findentfix statement, for example (admittedly
Relabelling (renumbering of labels) is done in the following stages:
Scan the input until a complete program unit (
FUNCTION) is obtained, collecting the defined and used labels.
Regenerate the program unit, now with the renumbered labels.
Indent and output the renumbered program unit.
Go to step 1.
If some error is detected, (not defined label, label
spanning continuation lines, ...) relabelling is abandoned
for the current and following program units, however,
indentation proceeds as normal. If relabelling fails, one
can run findent with the flag
--query-relabel, to see the reason of
Generate miscellaneous text files
Help files, man page, scripts for usage in editors
etc. are generated in the file
src/docs.cpp. For generating the man page and
the help-file, the function
manout() is used
so that generating these files is based on the same
The other files are include files, generated from the
original text files. For example:
vim_fortran.inc is generated from
vim/fortran.vim, using the script
src/tocpp. Details are available in the file
Findent comes with the BSD-3 license:
Copyright: 2015,2016,2017,2018,2019,2020,2021,2022,2023 Willem Vermin License: BSD-3-Clause Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Since findent only writes to standard output, error messages would clutter the indented Fortran program.↩︎
Shared DO-termination is flagged as a 'deleted feature' by gfortran.↩︎
This ambiguity arises from the fact that all spaces are removed in the preprocessing phase. In fixed format (where spaces do not count), this ambiguity is also present for the compiler.↩︎