General-Purpose Fortran Repository

Shortcut

The majority of the documentation is in HTML at the Documentation page.

Intro

This repository concentrates on those "other" Fortran procedures that solve the day-to-day non-numeric(mostly) issues in programming. Large repositories of numeric algorithms written in Fortran exist at such sites as the netlib repository.

Modern Fortran is quite capable of accessing many commonly available C libraries or expressing many commonly desired utility procedures directly, but the standard language does not define many of these basic interfaces. Because of Fortran's expressiveness and power in HPC environments ( Coarrays, MPI, OpenMP, matrix operators and the many numeric libraries available in Fortran) I prefer we bring these general-purpose utilities to Fortran instead of bringing Fortran to other languages. With that in mind I placed some such modules I have here. I hope others will find them useful (and expand upon them).

Alternate stand-alone modules

GPF(General Purpose Fortran) is the main repository that contains man(1) pages, utility programs, extended examples and unit tests. As generally useful modules mature simpler stand-alone versions are created from this base. That is because the full GPF (General Purpose Fortran repository) has many interdependencies. The extracated stand-alone individual modules are more appropriate if only a specific module is required, and can be found as additional repositories at the GPF site.

But if you want to work with the entire repository this is where new development (and a lot more functionality) is concentrated!

Cloning the repository

    git clone https://github.com/urbanjost/general-purpose-fortran
    cd general_purpose-fortran/src
    # you might have to change "-lncurses" to "-lncurses -ltinit"
    # depending on how ncurses(3c) was built on your machine, and
    # have ncurses(3c), readline(3c), sqlite3(3c), X11(3c) and lua(3c) 
    # installed for all the interfaces to build, but the most 
    # commonly used interfaces should build without problems.

    make -k

for building optional GPF

To build some of the optional components you may have to install several packages. Starting from a base MINT 20.1 platform (2021-03-07), for example:

   sudo apt-get install gfortran
   sudo apt-get install libx11-dev
   sudo apt-get install sqlite3 libsqlite3-dev
   sudo apt-get install libcurl4-gnutls-dev 
   sudo apt-get install libreadline libreadline-dev

If interested in the graphics routines ...

you might want to edit hershey.sh to select where hershey font files will be installed (default is /usr/share/hershey), and then enter ...

bash hershey.sh

if you do not have bash(1) or a Posix shell you will have to run the h2v program for each font, as illustrated by the simple hershey.sh script.

Dependencies

By default, the graphics routines require X11, the ncurses interface assumes libncurses is installed, the SQLite3 interface needs the libsqlite3 library, and the readline interface needs libreadline. These libraries are commonly available on many platforms but you may have to remove some of the files from Makefile if you do not want to build those interfaces.

Overview

The GPF (General-Purpose Fortran) repository consists of Fortran modules and libraries (and in some cases their associated C support routines) providing

• command line parsing
• string operations
• a date and time module
• a module that supports basic integrated unit testing
• simple numeric expression parsing
• command line history editing
• The low-level M_draw graphics library, and the beginnings of a pixel graphics module -- both similar to the VOGLE graphics library interface
• libraries for message handling and debugging
• a growing number of Fortran interfaces to common C routines, including
  • many POSIX system routines
  • a module for reading and writing lines to a process (a popen(3c) interface)
  • an interface to the ncurses(3c) terminal screen handling library
  • an interface to the sqlite3(3c) SQL file library
  • an interface to the regex(3c) Regular Expression library
  • routines for controlling the X11 Windows attributes of an xterm(1) terminal emulator, including the program setxt(1)

The majority of these routines come with a man(1) page in *roff and HTML format. An index into the documentation is contained in this distribution and available on the home page

• [overview]
• A collection of programs that use the repository code are included. These range from useful utilities (a pre-processor, an SCCS-style meta-data reader, regression testing utilities, ...) to simple example programs that exercise the modules.

Code additions are strongly encouraged (This is intended to be a development of the Fortran community).

The Fortran Wiki fortranwiki.org contains information on many Fortran resources (If you do not see a link there to your favorites please add them.)

A modern Fortran compiler is assumed. This code has been tested using gfortran GNU Fortran (GCC) 8.3.1 .

Routine Categories and Descriptions

command line arguments

M_KRACKEN(3fm): command line arguments

The M_KRACKEN(3f) module makes cracking Unix-like arguments off the command line easy. This version is expanded to allow use in configuration files and interactive input as well, and incorporates additional modules. It requires many other components from the GPF collection, and is used to generate programs that use shell-like input as well as crack command lines.

M_ARGS(3fm)

The M_args(3fm) module supports cracking Unix-like arguments off the command line as a string that can be read as a NAMELIST, eliminating the typical additional steps needed to convert the strings found on the command line to other types.

M_GETOPT(3fm): command line arguments

The M_GETOPT(3fm) module by Mark Gates supports cracking Unix-like arguments off the command line in much the same way as the C getopt(3c) procedure.

M_GETOPT_LONG(3fm): command line arguments

The M_GETOPT_LONG(3fm) module by Joe Krahn supports cracking Unix-like arguments off the command line in much the same way as the SunOS getopt_long(3c) procedure.

strings

M_STRINGS(3fm)

convert case, change numbers to strings, strings to numbers, parse on delimiters,edit strings, ... .

date and time

M_TIME(3fm)

Calculate and display date and time values

expression parsers

M_CALCULATOR(3fm),

M_calculator(3fm) is a module for evaluating expressions. The primary routine is JUCALC(3f). JUCALC(3f) evaluates simple numeric and string expressions. This allows your input to use expressions and variable names instead of simple values. You will have to comment out or supply some of the functions called, depending on how f2003-compliant your compiler is.

command line recall and editing

M_HISTORY(3fm): An interactive input editor module

Acting much like a line-mode editor, the REDO(3f) procedure lets you list, edit, save, and modify your interactively entered program input. Built-in help and no dependence on terminal control sequences makes this a simple-to-master and portable input history editor.

M_READLINE(3fm): calling readline(3c) from Fortran

The readline(3c) routine lets you edit and then execute previously entered commands. An interface using a small C routine and the standard ISO_C_BINDING module lets the commonly available C routine be called from Fortran. The readline(3c) library is required.

messages

M_JOURNAL(3fm), M_MESSAGES(3fm)

journaling, logging, and general messaging routines that let you have a single routine filter output to journal files; display attention-grabbing messages or reformat messages.

unit testing and debugging

M_DEBUG(3fm)

These routines are useful for constructing unit tests for code and for adding debug modes to routines and applications.

Paranoid Compiler Test

The PARANOID program converted into subroutines that can be called from your programs to verify compiler behavior.

flow control

M_LOGIC(3fm): conditionally select input

The M_LOGIC(3f) module allows you to use if/else/elseif/endif directives in your input; allowing conditional selection of input lines. Requires an expression parser. It uses JUCALC(3f) by default.

I/O

M_IO(3fm)

Input/Output

hot keys

GETKEY(3f): read a character from the keyboard in "immediate mode"

A simple C routine for most Unix and GNU/Linux systems that immediately reads a single character keystroke from the keyboard without waiting for a carriage return. An interface using the ISO_C_BINDING interface allows the routine to be called from Fortran.

Fortran/C calls

Read or Write from a system process

M_PROCESS(3fm)

Read and write from a process using popen(3c)

Many POSIX interface routines

M_SYSTEM(3fm)

• Environment
• Directories
• File status and attributes
• Error code
• Process management

And other commonly called C system routines interfaced to Fortran. Makes heavy use of the ISO_C_BINDING module introduced as part of Fortran 2003.

Call the POSIX Regular Expression library

M_REGEX(3fm)

Call the POSIX regular expression library.

Fortran(2008) interface to the SQLite3 library

M_SQLITE(3fm)

A basic interface to the SQLite3 library using the ISO_C_BINDING module and C/Fortran interoperability modeled iniitially on the FLIB interface.

Fortran(2003) interface to the ncurses(3c) library

M_NCURSES(3fm), M_FIXEDFORM(3fm)

A Fortran module and a few related files create an interface from Fortran to the C ncurses(3c) library; allowing Fortran programs to read function keys and characters one at a time and to control the characters on the screen on a character-cell by character-cell basis.

File characteristics

Input/Output

Signal management

Sockets

database

encryption

internet

runtime

opengl

parallel

overloading

structures

Additional Utilities

Routine Categories Descriptions

numeric utilities that are aware of their accuracy

M_COMPARE_FLOAT_NUMBERS(3fm)

A Fortran module containing routines to perform equality and relational comparisons on floating point numbers. That is, you can more safely compare real numeric values.

Types and Kinds

Fortran KIND definitions used by other parts of the basic utilities

ACCDIG(3f)

compare two real numbers only up to a specified number of digits

Graphics

M_DRAW(3fm)

The M_draw module is an interface to a C library based on the VOGLE graphics library. It is supplemented by higher level modules.

M_PIXEL(3fm)

The M_pixel module is a PRELIMINARY collection of routines that use 2D- vector routines to create or modify a pixel array, which can then be written as a GIF file.

Color

M_COLOR(3fm)

The M_color module is a collection of color-related procedures. Routines to convert between different color models, return RGB values given common X11 color names, and other simple color-related operations.

xterm(1) attributes

M_XTERM(3fm)

The M_xterm module is a collection of routines that use escape sequences to set and query xterm(1) X11 Windows attributes such as window size, background and foreground color, font, and cursor color. The program setxt(1), included in the GPF distribution, allows for easily using the module capabilities from the command line.

Sort

M_SORT(3fm)

sorting routines encapsulated in a module

sort_shell(3f)

simple generic sort procedure

M_SWAP(3fm)

swap two variables

General Mathematics

M_MATH(3fm)

A collection of routines for basic geometry, curve fitting and interpolation, basic statistics, ...

Unit Conversions

M_UNITS(3fm)

A collection of unit conversions and constants. Allow degrees instead of radians in trig functions; convert between Celcius and Fahrenheit, ...

An example program that combines many of the components into a simple calculator-like utility that parses command line arguments, evaluates Fortran- like expressions, draws in pixel arrays, allows calls to ncurses, has interactive command history recall and editing, and supports if/else/elseif/endif directives can be found in shell.ff.

---

Build with fpm(1)

GPF is bundled as an fpm package. Download the github repository and build it with fpm ( as described at Fortran Package Manager )

     git clone https://github.com/urbanjost/general-purpose-fortran.git
     cd general-purpose-fortran
     fpm test  # build and then run unit tests

or just list it as a dependency in your fpm.toml project file.

     [dependencies]
     general-purpose-fortran = { git = "https://github.com/urbanjost/general-purpose-fortran.git" }

• A ford configuration file is available to build documentation
• A doxygen configuration file is available to build documentation

Tests

#!/bin/bash
(
exec 2>&1
#@(#) Run fpm tests
# M_time tests require a specific timezone
export TZ='UTC+04:00'

gfortran --version
ifort --version
ifx --version

fpm test '*' --compiler gfortran -profile release 2>&1
fpm test '*' --compiler ifx      -profile release -flag -coarray=single 2>&1
fpm test '*' --compiler ifort    -profile release -flag -coarray=single -c-compiler cc  2>&1
fpm test '*' --compiler ifort    -profile release -flag -coarray=single -c-compiler icx 2>&1

)|tee /tmp/x.out