ZstdFortranLib: Zaak's (missing) Standard Fortran Library
Implements missing functionality such as error handling, strings manipulation, system/environment interface & testing utilities.
Table of contents
⚠️ Warning ⚠️
This is currently pre-alpha software. Development is ongoing and the API is not yet stable. It is possible that documented functionality is not yet implemented.
Motivation
Certain tasks in Fortran can be awkward and there is no standard library. One often ends up re-inventing the wheel to solve common tasks. Selected pain points include:
- String manipulation
- File operations & IO
- Error handling
- Assertions
- Interfacing with the OS, file system & environment
- Writing tests quickly and expressively
For string, file, and OS/system/environment interfacing other languages, in particular Ruby and Python
provide great expressiveness and built in functionality. These capabilities, as implemented in
ZstdFortraLib are inspired by and aim to replicate the corresponding functionality in Ruby and Python,
but in an idiomatic Fortran way, and only the features & functions that make sense.
Additionally unit testing and assertions should be expressive, quick to write and implement, and some assertions should be able to easily be turned off for production builds, or used to signal errors that are handled later.
Error Stack Object
By providing an error stack object, either as a singleton module variable, or as a component of a derived type, the programmer can maintain a call-stack, complete with line numbers and file names, and raise or signal exceptions deep in the call stack in pure or elemental procedures, but return control and handle any exceptions in less performance-critical, non-pure, higher-level program units.
Features
- Dynamically sized error stack
- Convenience macro for injecting line number and file-name into call-stack
- Built in error types
- Custom error messages
- Pretty output to terminal, dynamically formatted
- Raise fatal or deferred exceptions
- Check if exceptions are signaling
- Handle exceptions
- Signal handler hooks
- Introspective CMake build system, with exported targets
Unit Testing
Syntactic Sugar
Floating point comparisons are common in scientific computing and Fortran. Special operators are provided to
hand floating point comparisons for any real kind:
if ( ( (100 - 10*epsilon(1.0_RK)) .is. one_hundred ) .within. tolerance ) ...
! Same as above, absolute is default
if ( ( (100 - 10*epsilon(1.0_RK)) .is. one_hundred ) .within. .absolute. tolerance ) ...
! R.H.S. value is taken to be truth
if ( ( (100 - 10*epsilon(1.0_RK)) .is. one_hundred ) .within. .relative. rel_olerance ) ...Furthermore, when a test fails, you want to know where/why:
OUTPUT = gsub(qbf, CK_"the", CK_"a")
call assert_delayed ( &
OUTPUT == CK_"a quick red fox jumped over a lazy dog", __LINE__ , &
"character(kind=CK) gsub 'the --> a' substitution failed")(Sub)Test Summarizing
If a failure occurs the output will look like:
Documentation
High level user documentation is published (from the docs directory) to
Read the Docs https://zstdfortranlib/readthedocs.io.
User/client API documentation (protected & public scope) as well as project developer documentation
(private scope & public/protected)will be generate via FORD and published
via GitHub pages to https://izaakbeekman.com/ZstdFortranLib (
Templating
This project uses templating and compile-time polymorphism (procedure overloading) for improving the functionality of operators on intrinsic types. Templating functionality is provided via the Jin2For tool, which adds functionality to the Jinja2 templating enginep specific to writing Fortran programs.
generated DIRECTORY!
