Merge branch 'release/1.0'

Author: samharrison7

.gitignore

@@ -6,6 +6,7 @@ Makefile
 *.sublime-project
 *.sublime-workspace
 .vs/
+.vscode/
 .project
 Debug/
 *.sln

CMakeLists.txt

@@ -14,6 +14,8 @@ set(CMAKE_Fortran_FLAGS "${CMAKE_Fortran_FLAGS} ${FLAGS}")
 
 file(GLOB SOURCES_EXAMPLE src/*.f90 example/example_usage.f90)
 file(GLOB SOURCES src/*.f90)
+file(GLOB SOURCES_TEST src/*.f90 tests/*.f90)
 
 add_executable(example ${SOURCES_EXAMPLE})
+add_executable(test ${SOURCES_TEST})
 add_library(feh ${SOURCES})

README.md

@@ -14,13 +14,17 @@ Fortran error handling frameworks are few and far between, and those that do exi
 
 If you wish to use the Fortran Error Handler in a project, the simplest way to do so is to include the source files (in `src/`) at the start of your compilation setup. Source files should be compiled in this order: `ErrorInstance.f90`, `ErrorHandler.f90`, `ErrorCriteria.f90`, `Result.f90`. An example [Makefile.example](./Makefile.example) is included, which can be altered according to your compiler and preferences. 
 
-The code can also be compiled using `cmake`, which creates an executable using the `example/example_usage.f90` script as well as a library:
+The code can also be compiled using `cmake`, which creates an example executable (using `example/example_usage.f90`), an executable of unit tests (using `tests/run_tests.f90`), and a library of the framework:
 
 ```bash
 $ mkdir build
 $ cd build
 $ cmake ..
 $ make
+# To run the unit tests
+$ ./test
+# To run the example
+$ ./example
 ```
 
 Whether the library is shared or not is specified by the `BUILD_SHARED_LIBS` variable. If you wish to build a shared library, then pass the `BUILD_SHARED_LIBS` option as on:
@@ -29,6 +33,8 @@ Whether the library is shared or not is specified by the `BUILD_SHARED_LIBS` var
 $ cmake .. -DBUILD_SHARED_LIBS=ON
 ```
 
+The framework has been tested using GFortran 7 upwards and Intel Fortran 18.
+
 <a name="usage"></a>
 ## Usage
 

codemeta.json

@@ -0,0 +1,51 @@
+{
+  "@context": "https://raw.githubusercontent.com/codemeta/codemeta/master/codemeta.jsonld",
+  "@type": "Code",
+  "author": [
+    {
+      "@id": "0000-0001-8491-4720",
+      "@type": "Person",
+      "email": "[email protected]",
+      "name": "Sam Harrison",
+      "affiliation": "UK Centre for Ecology & Hydrology, Lancaster Environment Centre, Library Avenue, Bailrigg, Lancaster, LA1 4AP, UK"
+    },
+    {
+      "@id": "0000-0003-4489-5363",
+      "@type": "Person",
+      "email": "[email protected]",
+      "name": "Virginie D Keller",
+      "affiliation": "UK Centre for Ecology & Hydrology, Maclean Building, Benson Lane, Crowmarsh Gifford, Wallingford, OX10 8BB, UK"
+    },
+    {
+      "@id": "0000-0002-9876-0491",
+      "@type": "Person",
+      "email": "[email protected]",
+      "name": "Richard J Williams",
+      "affiliation": "UK Centre for Ecology & Hydrology, Maclean Building, Benson Lane, Crowmarsh Gifford, Wallingford, OX10 8BB, UK"
+    },
+    {
+      "@id": "0000-0003-3764-5331",
+      "@type": "Person",
+      "email": "[email protected]",
+      "name": "Michael Hutchins",
+      "affiliation": "UK Centre for Ecology & Hydrology, Maclean Building, Benson Lane, Crowmarsh Gifford, Wallingford, OX10 8BB, UK"
+    },
+    {
+      "@id": "0000-0002-3627-851X",
+      "@type": "Person",
+      "email": "[email protected]",
+      "name": "Stephen Lofts",
+      "affiliation": "UK Centre for Ecology & Hydrology, Lancaster Environment Centre, Library Avenue, Bailrigg, Lancaster, LA1 4AP, UK"
+    }
+  ],
+  "identifier": "",
+  "codeRepository": "https://github.com/samharrison7/fortran-error-handler",
+  "datePublished": "2020-06-05",
+  "dateModified": "2020-06-05",
+  "dateCreated": "2020-06-05",
+  "description": "Comprehensive error framework for applications requiring functional and robust error handling, utilising the power of modern object-oriented Fortran.",
+  "keywords": "Fortran, error handling",
+  "license": "MIT",
+  "title": "Fortran Error Handler",
+  "version": "v1.0.0"
+}

doc/Result.md

@@ -28,12 +28,10 @@ For example:
 ```fortran
 type(ErrorInstance) :: randomError
 type(ErrorInstance) :: anotherError
-type(Result) :: rNoData
 type(Result0D) :: r0D
 type(Result1D) :: r1D
 
 randomError = ErrorInstance(42, "A random error.")
-rNoData = Result(error=randomError)
 r0D = Result(data=1, errors=[randomError,anotherError])
 r1D = Result(data=[1,2], error=randomError)
 ```

paper.md

@@ -8,37 +8,41 @@ authors:
       orcid: 0000-0001-8491-4720 
       affiliation: 1
     - name: Virginie D Keller
-      orcid:
+      orcid: 0000-0003-4489-5363
       affiliation: 2
     - name: Richard J Williams
-      orcid: 
+      orcid: 0000-0002-9876-0491 
       affiliation: 2
     - name: Michael Hutchins
-      orcid:
+      orcid: 0000-0003-3764-5331
       affiliation: 2
     - name: Stephen Lofts
-      orcid:
-      affilication: 1
+      orcid: 0000-0002-3627-851X
+      affiliation: 1
 affiliations:
     - name: UK Centre for Ecology & Hydrology, Lancaster Environment Centre, Library Avenue, Bailrigg, Lancaster, LA1 4AP, UK
       index: 1
     - name: UK Centre for Ecology & Hydrology, Maclean Building, Benson Lane, Crowmarsh Gifford, Wallingford, OX10 8BB, UK
       index: 2
-date: 9 May 2020
+date: 5 June 2020
 bibliography: paper.bib
 ---
 
 # Summary
 
 Despite the rise of interpreted programming languages like Python and R in scientific programming, compiled languages are still the de-facto choice for computationally intensive modelling tasks, such as in climate sciences and theoretical physics. Fortran remains the top choice of many scientists, and Modern Fortran has brought great flexibility to the language in terms of object-oriented paradigms and polymorphism.
 
-Any modelling code needs robust error checking, yet Fortran error handling frameworks to provide these utilities are few and far between, and those that do exist often implement only part of the error handling process, or rely on pre-processors [@popper:2012, @lucking:2015]. Here, we present what we believe is the most comprehensive Fortran error handling framework to date, providing a universal and comprehensive solution for applications requiring functional and robust error handling, utilising the power of modern object-oriented Fortran.
+Any modelling code needs robust error checking, yet Fortran error handling frameworks to provide these utilities are few and far between, and those that do exist often implement only part of the error handling process, or rely on pre-processors [@poppe:2012; @lucking:2015]. Here, we present what we believe is the most comprehensive Fortran error handling framework to date, providing a universal and comprehensive solution for applications requiring functional and robust error handling, utilising the power of modern object-oriented Fortran.
 
 The framework implements the whole error handling process, including separate utilities for:
-- Managing the error handling environment, through an `ErrorHandler` class. This allows for queuing and triggering error events, storing pre-defined custom errors and customising error reporting.
-- Working with separate error instances, through an `ErrorInstance` class. Error instances include error metadata such as error code, message and whether the error is critical or just a warning. In addition, error instances (optionally) include a user-defined trace of where the error originated, enabling rapid debugging.
-- Passing errors between routines, through a `Result` class. Result objects contain a list of error instances as well as a data component, enabling errors to be returned from functions at the same time as the data which the function would traditionally return.
-- Common error checking criteria, through an `ErrorCriteria` class. This defines a number of common criteria used for error checking, such as equality and non-zero assertions.
+
+* Managing the error handling environment, through an `ErrorHandler` class. This allows for queuing and triggering error events, storing pre-defined custom errors and customising error reporting.
+
+* Working with separate error instances, through an `ErrorInstance` class. Error instances include error metadata such as error code, message and whether the error is critical or just a warning. In addition, error instances (optionally) include a user-defined trace of where the error originated, enabling rapid debugging.
+
+* Passing errors between routines, through a `Result` class. Result objects contain a list of error instances as well as a data component, enabling errors to be returned from functions at the same time as the data which the function would traditionally return.
+
+* Common error checking criteria, through an `ErrorCriteria` class. This defines a number of common criteria used for error checking, such as equality and non-zero assertions.
 
 These classes are extensible to enable, for example, custom error criteria by extending the `ErrorCriteria` class, or the passing of custom data types through extension of the `Result` object. They are designed to be modular, such that individual elements can be used separately to implement individual parts of the error handling process. The use of the whole framework enables robust error checking for the largest and most complex models and software.
 

tests/assert.f90

@@ -0,0 +1,87 @@
+!> Testing utilities for assertion
+module assert
+    use util
+    implicit none
+
+    interface assertEqual
+        module procedure :: assertEqualInteger
+        module procedure :: assertEqualReal
+        module procedure :: assertEqualDp
+        module procedure :: assertEqualQp
+        module procedure :: assertEqualLogical
+        module procedure :: assertEqualString
+        module procedure :: assertEqualComplex
+    end interface
+
+  contains
+
+    subroutine exitOut(msg)
+        character(len=*) :: msg
+        write(*, '(a)') trim(msg)
+        error stop 1
+    end subroutine
+
+    subroutine assertEqualInteger(a, b, msg)
+        integer, intent(in) :: a, b
+        character(len=*), optional :: msg
+        if (a /= b) then
+            if (present(msg)) write(*, '(a)') msg
+            call exitOut("Assertion error: Values " // trim(str(a)) // " and " // trim(str(b)) // " are not equal.")
+        end if
+    end subroutine
+
+    subroutine assertEqualReal(a, b, msg)
+        real, intent(in) :: a, b
+        character(len=*), optional :: msg
+        if (a /= b) then
+            if (present(msg)) write(*, '(a)') msg
+            call exitOut("Assertion error: Values " // trim(str(a)) // " and " // trim(str(b)) // " are not equal.")
+        end if
+    end subroutine
+
+    subroutine assertEqualDp(a, b, msg)
+        real(dp), intent(in) :: a, b
+        character(len=*), optional :: msg
+        if (a /= b) then
+            if (present(msg)) write(*, '(a)') msg
+            call exitOut("Assertion error: Values " // trim(str(a)) // " and " // trim(str(b)) // " are not equal.")
+        end if
+    end subroutine
+
+    subroutine assertEqualQp(a, b, msg)
+        real(qp), intent(in) :: a, b
+        character(len=*), optional :: msg
+        if (a /= b) then
+            if (present(msg)) write(*, '(a)') msg
+            call exitOut("Assertion error: Values " // trim(str(a)) // " and " // trim(str(b)) // " are not equal.")
+        end if
+    end subroutine
+
+    subroutine assertEqualLogical(a, b, msg)
+        logical, intent(in) :: a, b
+        character(len=*), optional :: msg
+        if (a .neqv. b) then
+            if (present(msg)) write(*, '(a)') msg
+            call exitOut("Assertion error: Values " // trim(str(a)) // " and " // trim(str(b)) // " are not equal.")
+        end if
+    end subroutine
+
+    subroutine assertEqualString(a, b, msg)
+        character(len=*), intent(in) :: a, b
+        character(len=*), optional :: msg
+        if (trim(a) /= trim(b)) then
+            if (present(msg)) write(*, '(a)') msg
+            call exitOut("Assertion error: Values '" // trim(a) // "' and '" // trim(b) // "' are not equal.")
+        end if
+    end subroutine
+
+    subroutine assertEqualComplex(a, b, msg)
+        complex, intent(in) :: a, b
+        character(len=*), optional :: msg
+        if (a /= b) then
+            if (present(msg)) write(*, '(a)') msg
+            call exitOut("Assertion error: Values " // trim(str(a)) // " and " // trim(str(b)) // " are not equal.")
+        end if
+    end subroutine
+
+end module

tests/run_tests.f90

@@ -0,0 +1,56 @@
+program run_test
+    use tests_Result
+    use tests_ErrorInstance
+    use tests_ErrorCriteria
+    implicit none
+
+    write(*, '(a)') "Starting tests for ErrorInstance..."
+    call createErrorWithDefaultCode()
+    call createErrorWithMessageHello()
+    call createErrorWithCode42()
+    call createCriticalError()
+    call createNonCriticalError()
+    call addMessageToTrace()
+    call addTwoMessagesToTrace()
+    call addTraceMessageSayingHello()
+
+    write(*, '(a)') "Starting tests for Result..."
+    call createResultWithNoError()
+    call createResultWith0DIntegerData()
+    call createResultWith0DRealData()
+    call createResultWith0DDPData()
+    call createResultWith0DQPData()
+    call createResultWith0DLogicalData()
+    call createResultWith0DCharacterData()
+    call createResultWith0DComplexData()
+    call createResultWith1DIntegerData()
+    call createResultWith1DRealData()
+    call createResultWith1DDPData()
+    call createResultWith1DQPData()
+    call createResultWith2DIntegerData()
+    call createResultWith2DRealData()
+    call createResultWith2DDPData()
+    call createResultWith2DQPData()
+    call createResultWith3DIntegerData()
+    call createResultWith3DRealData()
+    call createResultWith3DDPData()
+    call createResultWith3DQPData()
+    call createResultWith4DIntegerData()
+    call createResultWith4DRealData()
+    call createResultWith4DDPData()
+    call createResultWith4DQPData()
+
+    write(*, '(a)') "Starting tests for ErrorHandler and ErrorCriteria..."
+    call createErrorHandlerWithCustomError()
+    call checkErrorCriteriaNonZero()
+    call checkErrorCriteriaLessThan()
+    call checkErrorCriteriaGreaterThan()
+    call checkErrorCriteriaLimit()
+    call checkErrorCriteriaNotEqual()
+    call checkErrorCriteriaEqual()
+    call checkErrorCriteriaPositive()
+    call checkErrorCriteriaNegative()
+
+    write(*, '(a)') "Tests completed successfully!"
+
+end program