Merge pull request #84 from BerkeleyLab/wrap-assert-assert

Add specific procedure for call_julienne_assert_ generic interface

Author: rouson

README.md

@@ -156,22 +156,33 @@ Getting Started
 ---------------
 ### Writing Assertions
 To write a Julienne assertion, insert a function-like preprocessor macro
-`call_julienne_assert` on a single line as in the following program:
+`call_julienne_assert` on a single line as in each of the two macro
+invocations below:
 ```fortran
 #include "julienne-assertion-macros.h"
 program main
   use, julienne_m, only : call_julienne_assert_
   implicit none
   real, parameter :: x=1., y=2., tolerance=3.
   call_julienne_assert(x .approximates. y .within. tolerance)
+  call_julienne_assert(abs(x-y) < tolerance)
 end program
 ```
-where inserting `-DASSERTIONS` in a compile command will expand the macro to
+where inserting `-DASSERTIONS` in a compile command will expand the macros to
 ```fortran
-  call call_julienne_assert_(x .approximates. y .within. tolerance)
+  call call_julienne_assert_(x .approximates. y .within. tolerance, __FILE__, __LINE__)
+  call call_julienne_assert_(allocated(a), __FILE__, __LINE__)
 ```
-and where dots (`.`) delimit Julienne operators and the parenthetical expression
-evaluates to a Julienne `test_diagnosis_t` object.
+and where dots (`.`) delimit Julienne operators.  The above expression containing
+Julienne operators evaluates to a Julienne `test_diagnosis_t` object, whereas
+expression `allocated(a)` on the subsequent line evaluates to a `logical` value.
+If an assertion containing a Julienne expression fails, Julienne inserts diagnostic
+information into the stop code in an ultimate `error stop`.  If an expression
+evaluates to a `logical` value of `false.`, the error stop code will contain a
+literal copy of the expression (e.g., `allocated(a)`).  In either case, Julienne
+also inserts the file and line number into the stop code using via the `__FILE__`
+and `__LINE__` macros, respectively.  Most compilers write the resulting stop code
+to `error_unit`.
 
 ### Writing Unit Tests
 Writing tests using Julienne involves constructing a test-description array,

fpm.toml

@@ -1,7 +1,7 @@
 name = "julienne"
 
 [dependencies]
-assert = {git = "https://github.com/berkeleylab/assert", tag = "3.0.0"}
+assert = {git = "https://github.com/berkeleylab/assert", tag = "3.0.2"}
 
 [install]
 library = true

src/julienne/julienne_assert_m.f90

@@ -0,0 +1,53 @@
+! Copyright (c) 2024-2025, The Regents of the University of California and Sourcery Institute
+! Terms of use are as specified in LICENSE.txt
+
+module julienne_assert_m
+  !! Define interfaces for writing assertions
+  use julienne_test_diagnosis_m, only : test_diagnosis_t
+  implicit none
+
+  private
+  public :: call_julienne_assert_
+  public :: julienne_assert
+
+  interface call_julienne_assert_
+
+    pure module subroutine julienne_assert(test_diagnosis, file, line)
+      !! This subroutine wraps the Assert library's `assert` subroutine.
+      !!
+      !! Use Cases
+      !! ---------
+      !!   1. Invoke julienne_assert via the generic interface `call_julienne_assert` to
+      !!      facilitate complete removal when compiling without the flag `-DASSERTIONS`.
+      !!   2. Invoke julienne_assert via direct procedure call to guarantee execution.
+      !!
+      !! Usage
+      !! -----
+      !! Make the only actual argument an expression containing `test_diagnosis_t` defined
+      !! operations, such as `x .approximates. y .within. tolerance`.  The expression
+      !! result will be a `test_diagnosis_t` object on which `julienne_assert` will invoke
+      !! the `diagnostics_string()` type-bound procedure, the result of which julienne_assert
+      !! will include in the stop code of an `error stop` if the expresssion is untrue.
+      !! The resulting stop code will contain such information as the operand values and
+      !! roles (expected value, actual value, tolerance value).  In use case 1, compiling
+      !! with `-DASSERTIONS` will cause the preprocessor to insert the corresponding
+      !! invocations's line number and the encompassing file's name as the `file` and `line`
+      !! arguments, respectively, which `julienne_assert` will include in the stop code.
+      !! Most compilers will write the stop code to `error_unit`.
+      !!
+      !! If a literal reproduction of the test expression suffices, such as when the
+      !! expression is `allocated(a)`, then instead invoke the Assert library's `assert`
+      !! subroutine by that library's `call_assert` macro or by direct call.
+      !! When invoking via the macro, make the only actual argument, `assertion`, a
+      !! `logical` expression.  Then if compiling with `-DASSERTIONS` and if the assertion
+      !! evaluates to `.false.`, the stop code will include the text of the expression
+      !! argument, the file name, and the line number of the `call_assert` macro invocation.
+      implicit none
+      type(test_diagnosis_t), intent(in) :: test_diagnosis
+      character(len=*), intent(in), optional :: file
+      integer, intent(in), optional :: line
+    end subroutine
+
+  end interface
+
+end module julienne_assert_m

src/julienne/julienne_assert_s.f90

@@ -0,0 +1,19 @@
+! Copyright (c) 2024-2025, The Regents of the University of California and Sourcery Institute
+! Terms of use are as specified in LICENSE.txt
+
+submodule(julienne_assert_m) julienne_assert_s
+  use assert_m, only : assert_always
+  use julienne_m, only : string_t
+  implicit none
+
+contains
+
+  module procedure julienne_assert
+    character(len=:), allocatable :: diagnostics_string
+    diagnostics_string =  test_diagnosis%diagnostics_string()
+    if (present(file)) diagnostics_string = diagnostics_string // " in file " // file
+    if (present(line)) diagnostics_string = diagnostics_string // " at line " // string_t(line)
+    call assert_always(test_diagnosis%test_passed(), diagnostics_string)
+  end procedure
+
+end submodule julienne_assert_s

src/julienne/julienne_bin_s.F90

@@ -1,17 +1,17 @@
 ! Copyright (c) 2024-2025, The Regents of the University of California and Sourcery Institute
 ! Terms of use are as specified in LICENSE.txt
 
-#include "assert_macros.h"
+#include "julienne-assert-macros.h"
 
 submodule(julienne_bin_m) julienne_bin_s
-  use assert_m
+  use julienne_m, only : call_julienne_assert_, operator(.isAtLeast.)
   implicit none
 
 contains
 
   module procedure construct
 
-      call_assert(num_items>=num_bins)
+      call_julienne_assert(num_items .isAtLeast. num_bins)
 
       associate( remainder => mod(num_items, num_bins), items_per_bin => num_items/num_bins)
 

src/julienne/julienne_command_line_m.f90

@@ -1,5 +1,6 @@
 ! Copyright (c) 2024-2025, The Regents of the University of California and Sourcery Institute
 ! Terms of use are as specified in LICENSE.txt
+
 module julienne_command_line_m
   !! return command line argument information
   implicit none

src/julienne/julienne_command_line_s.f90

@@ -1,5 +1,6 @@
 ! Copyright (c) 2024-2025, The Regents of the University of California and Sourcery Institute
 ! Terms of use are as specified in LICENSE.txt
+
 submodule(julienne_command_line_m) julienne_command_line_s
   implicit none
 

src/julienne/julienne_file_m.f90

@@ -1,5 +1,6 @@
 ! Copyright (c) 2024-2025, The Regents of the University of California and Sourcery Institute
 ! Terms of use are as specified in LICENSE.txt
+
 module julienne_file_m
   !! A representation of a file as an object
   use julienne_string_m, only : string_t

src/julienne/julienne_formats_m.F90

@@ -1,5 +1,6 @@
 ! Copyright (c) 2024-2025, The Regents of the University of California and Sourcery Institute
 ! Terms of use are as specified in LICENSE.txt
+
 module julienne_formats_m
   !! Useful strings for formatting `print` and `write` statements
   implicit none

src/julienne/julienne_formats_s.F90

@@ -1,5 +1,6 @@
 ! Copyright (c) 2024-2025, The Regents of the University of California and Sourcery Institute
 ! Terms of use are as specified in LICENSE.txt
+
 submodule(julienne_formats_m) julienne_formats_s
   !! Construct separated-value formats 
   implicit none