A jinja2-based template engine for FORTRAN projects
Project description
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.