Add notes

Author: znicholls

meson.build

@@ -68,6 +68,7 @@ if pyprojectwheelbuild_enabled
     'src/example_fgen_basic/fpyfgen/derived_type_manager_helpers.f90',
     'src/example_fgen_basic/get_wavelength.f90',
     'src/example_fgen_basic/kind_parameters.f90',
+    'src/example_fgen_basic/result/result.f90',
   )
 
   # All Python files (wrappers and otherwise)

src/example_fgen_basic/error_v/error_v.f90

@@ -5,7 +5,8 @@
 !>
 !> Fortran doesn't have a null value.
 !> As a result, we introduce this derived type
-!> with the convention that a code of 0 indicates no error.
+!> with the convention that a code of `NO_ERROR_CODE` (0)
+!> indicates no error (i.e. is our equivalent of a null value).
 module m_error_v
 
     implicit none

src/example_fgen_basic/error_v/error_v_manager.f90

@@ -68,13 +68,16 @@ subroutine get_available_instance_index(available_instance_index)
 
                 instance_available(i) = .false.
                 available_instance_index = i
+                ! TODO: switch to returning a Result type
+                ! res = ResultInt(data=i)
                 return
 
             end if
 
         end do
 
         ! TODO: switch to returning a Result type with an error set
+        ! res = ResultInt(ErrorV(code=1, message="No available instances"))
         error stop 1
 
     end subroutine get_available_instance_index
@@ -114,17 +117,37 @@ subroutine check_index_claimed(instance_index)
         !! Instance index to check
 
         if (instance_available(instance_index)) then
-            ! TODO: switch to errors here - will require some thinking
+            ! TODO: Switch to using Result here
+            ! Use `ResultNone` which is a Result type
+            ! that doesn't have a `data` attribute
+            ! (i.e. if this succeeds, there is no data to check,
+            ! if it fails, the error_v attribute will be set).
+            ! So the code would be something like
+            ! res = ResultNone(ErrorV(code=1, message="Index ", instance_index, " has not been claimed"))
             print *, "Index ", instance_index, " has not been claimed"
             error stop 1
         end if
 
         if (instance_index < 1) then
-            ! TODO: switch to errors here - will require some thinking
+            ! TODO: Switch to using Result here
+            ! Use `ResultNone` which is a Result type
+            ! that doesn't have a `data` attribute
+            ! (i.e. if this succeeds, there is no data to check,
+            ! if it fails, the error_v attribute will be set).
+            ! So the code would be something like
+            ! res = ResultNone(ErrorV(code=2, message="Requested index is ", instance_index, " which is less than 1"))
             print *, "Requested index is ", instance_index, " which is less than 1"
             error stop 1
         end if
 
+        ! ! Here, result becomes
+        ! ! Now that I've thought about this, it's also clear
+        ! ! that we will only use functions
+        ! ! or subroutines with a result type that has `intent(out)`.
+        ! ! We will no longer have subroutines that return nothing
+        ! ! (like this one currently does).
+        ! res = ResultNone()
+
     end subroutine check_index_claimed
 
     subroutine ensure_instance_array_size_is_at_least(n)

src/example_fgen_basic/result/result.f90

@@ -0,0 +1,96 @@
+!> Result value
+!>
+!> Inspired by the excellent, MIT licensed
+!> https://github.com/samharrison7/fortran-error-handler
+module m_result
+
+    implicit none
+    private
+
+    type, abstract, public :: Result
+    !! Result type
+    !!
+    !! Holds either the result or an error.
+
+        class(*), allocatable :: data(..)
+        !! Data i.e. the result (if no error occurs)
+        !!
+        ! Assumed rank array
+        ! (https://fortran-lang.discourse.group/t/assumed-rank-arrays/1049)
+        ! Technically a Fortran 2018 feature,
+        ! so maybe we need to update our file extensions.
+        ! If we can't use this, just comment this out
+        ! and leave each subclass of Result to set its data type
+        ! (e.g. ResultInteger will have `integer :: data`,
+        ! ResultDP1D will have `real(dp), dimension(:), allocatable :: data`)
+
+        class(ErrorV), allocatable :: error_v
+        !! Error
+
+    contains
+
+        private
+
+        procedure, public:: build, finalise, is_error
+        ! TODO: Think about whether build should be on the abstract class
+        ! or just on each concrete implementation
+
+    end type Result
+
+    interface Result
+    !! Constructor interface - see build (TODO: figure out cross-ref syntax) for details
+        module procedure :: constructor
+    end interface Result
+
+contains
+
+    ! See above about whether we include this here or not
+    ! Build should return a Result with an error if we try to set/allocate both
+    ! data and error
+    ! subroutine build(self, code, message)
+    !     !! Build instance
+    !
+    !     class(ErrorV), intent(inout) :: self
+    !     ! Hopefully can leave without docstring (like Python)
+    !
+    !     integer, intent(in) :: code
+    !     !! Error code
+    !     !!
+    !     !! Use [TODO: figure out xref] `NO_ERROR_CODE` if there is no error
+    !
+    !     character(len=*), optional, intent(in) :: message
+    !     !! Error message
+    !
+    !     self % code = code
+    !     if (present(message)) then
+    !         self % message = message
+    !     end if
+    !
+    ! end subroutine build
+
+    subroutine finalise(self)
+        !! Finalise the instance (i.e. free/deallocate)
+
+        class(Result), intent(inout) :: self
+        ! Hopefully can leave without docstring (like Python)
+
+        deallocate(self % data)
+        deallocate(self % error)
+
+    end subroutine finalise
+
+    pure function is_error(self) result(is_err)
+        !! Determine whether `self` contains an error or not
+
+        class(Result), intent(in) :: self
+        ! Hopefully can leave without docstring (like Python)
+
+        logical :: is_err
+        ! Whether `self` is an error or not
+
+        is_err = self % error_v % is_error()
+        ! TODO: implement is_error on `error_v`
+
+    end function is_error
+
+end module m_result