Skip to content

Latest commit

 

History

History
160 lines (116 loc) · 6.75 KB

README.md

File metadata and controls

160 lines (116 loc) · 6.75 KB

ZstdFortranLib: Zaak's (missing) Standard Fortran Library

CI Status Coverage status Documentation Status GitHub license Download as PDF Tweet this button

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:

Failed test

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 (:warning: not yet operational :warning:)

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.

⚠️NEVER MANUALLY EDIT SOURCES IN THE generated DIRECTORY! ⚠️


GitHub forks GitHub stars GitHub watchers Tweet this button