jin2for 0.1.0

A jinja2-based template engine for FORTRAN projects

jin2for - Generate FORTRAN source files from jinja2 templates

Why

The FORTRAN programing language has not a built-in templating engine like C++ does. In concequence, it is not unusual to end-up needing to write code like this one

function sum_i2(a,b) result (c)
  implicit none
  integer(2), intent(in) :: a
  integer(2), intent(in) :: b
  integer(2) :: c
  c = a + b
end function

function sum_i4(a,b) result (c)
  implicit none
  integer(4), intent(in) :: a
  integer(4), intent(in) :: b
  integer(4) :: c
  c = a + b
end function

function sum_i8(a,b) result (c)
  implicit none
  integer(8), intent(in) :: a
  integer(8), intent(in) :: b
  integer(8) :: c
  c = a + b
end function

The standard approach to circumvent code repetition is to use pre-processor directives. However, the functionality of the preprocessor is quite limited and this approach often leads to criptic code that is difficult to read.

The goal of jin2for is to facilitate the usage of jinja2 as a more flexible preprocessor in FORTRAN projects. jinja2 is a mature, powerful, and flexible templeting engine that allows to write templates like this one:

{% for ip in [2, 4, 8] %}
function sum_i{{ip}}(a,b) result (c)
  implicit none
  integer({{ip}}), intent(in) :: a
  integer({{ip}}), intent(in) :: b
  integer({{ip}}) :: c
  c = a + b
end function
{% endfor %}

If you store this templated code in a file, say foo.t90, and compile it with jin2for

$ jin2for foo.t90

you will obtain a file foo.f90 that contains piece of FORTRAN code shown at the beginning of this README file. Internally, jin2for uses the jinja2 engine to render the templates. So, any valid jinja2 template can be processed in this way.

jin2for is environment aware

jin2for predefines a number of useful python objects that can be used as template parameters.

For instance, if we want to generate the previous sum function for all the integer types available in the installed gfortran compiler, we can use the predefined integer_types object. Create a file sum_ints.t90 containing this template:

{% for t in integer_types %}
function sum_{{t.alias}}(a,b) result (c)
  implicit none
  {{t.decl}}, intent(in) :: a
  {{t.decl}}, intent(in) :: b
  {{t.decl}} :: c
  c = a + b
end function
{% endfor %}

and compile it with

$ jin2for --generate-for gfortran sum_ints.t90

jin2for will find out for you which are the supported integer kinds of the installed gfortran compiler and render the template only for those kinds.

Installation

jin2for is a command line application written in Python 3 and distributed via pypi.org.

It can be installed using pip:

$ pip install jin2for

If you obtain any installation error, make sure that you are using Python 3, e.g.,

$ python3 -m pip install jin2for

The latest development version can be installed manually from soruce:

$ git clone https://gitlab.com/fverdugo/jin2for
$ cd jin2for
$ python3 setup.py test # optional
$ python3 setup.py install

Usage

Basic usage

The basic command line interface (CLI) ressembles to the one of the GNU and Intel compilers. For instance,

$ jin2for file1.t90 file2.t90

will "compile" (i.e., render) the jinja2 template files file1.t90 and file2.t90 into the FORTRAN source files file1.f90 and file2.f90. By default, jin2for will replace the extension of the input files to .f90 to generate the output file names.

The files file1.t90 and file2.t90 are allowed to include or import some other jinja2 templates containing, e.g., macros or definitions. If these included template files are located in a folder, namely folder/for/included/templates, different from the current working directory, jin2for has to be informed with the -I flag:

$ jin2for -I folder/for/included/templates file1.t90 file2.t90

More advanced usage

See documentation

Documentation

For the template syntax, see the official jinja2 documentation.

For the full CLI reference:

$ jin2for -h