Centralize the test filtering logic to test_description_m

.github/workflows/build-with-flang.yml

@@ -1,4 +1,4 @@
-name: Build with LLVM Flang
+name: Build with LLVM Flang 20
 
 on: [push, pull_request]
 
@@ -28,5 +28,5 @@ jobs:
         fpm --version
         $FC --version
         export FPM_FC=$FC
-        export FPM_FFLAGS="-mmlir -allow-assumed-rank -O3"
+        export FPM_FFLAGS="-O3"
         fpm test

.github/workflows/CI.yml → .github/workflows/build-with-gfortran.yml

@@ -1,4 +1,4 @@
-name: CI
+name: Build with gfortran-14
 
 on: [push, pull_request]
 
@@ -8,6 +8,10 @@ jobs:
     strategy:
       matrix:
         os: [macos-13, ubuntu-24.04]
+      fail-fast: true
+    env:
+      FC: gfortran-14
+      CXX: g++-14
 
     steps:
     - name: Checkout code
@@ -21,8 +25,10 @@ jobs:
       if: contains(matrix.os, 'ubuntu')
       run: |
         sudo apt update
-        sudo apt install -y build-essential gfortran-14 g++-14
+        sudo apt install -y build-essential $FC $CC
 
-    - name: Build and Run unit tests
+    - name: Build and Test with GCC
       run: |
-        fpm test --compiler gfortran-14
+        fpm --version
+        $FC --version
+        fpm test --compiler $FC

README.md

@@ -24,12 +24,13 @@ Example expressions                               | Operand types
 `(i .lessThan. j) .also. (k .equalsExpected. m))` | `integer`, `real`, `double precision`
 `x .lessThan. y`                                  | `integer`, `real`, `double precision`
 `x .greaterThan. y`                               | `integer`, `real`, `double precision`
-`i .greaterThan. j`                               | `integer`, `real`, `double precision`
 `i .equalsExpected. j`                            | `integer`, `character`
 `i .isAtLeast. j`                                 | `integer`, `real`, `double precision`
 `i .isAtMost. j`                                  | `integer`, `real`, `double precision`
 `s .isBefore. t`                                  | `character`
 `s .isAfter. t`                                   | `character`
+`.expect. command_line%argument_present("--help")`| `logical`
+
 
 where `.isAtLeast.` and `.isAtMost.` can alternatively be spelled
 `.greaterThanOrEqualTo.` and `.lessThanOrEqualTo.`, respectively;
@@ -250,12 +251,10 @@ GCC `gfortran`   | 13, 14, 15               | see 1 below
 Intel `ifx`      | 2025.1.1 Build 20250418  | see 2 below
 
 1. `gfortran` issues:
-   - With GCC 14 or earlier, the `test_description_t` constructor's
+   - With GCC 14.2.0 or earlier, the `test_description_t` constructor's
      `diagnosis_function` actual argument must be a procedure pointer conforming
      conforming with the `diagnosis_function_i` abstract interface.
-   - The `string_t` `bracket` type-bound function crashes for GCC 14 or earlier.
-   - _Deprecated feature_: Each element of a [`vector_test_description_t`] array
-     must be defined in a separate statement.
+   - The `string_t` `bracket` type-bound function crashes for GCC 14.2.0 or earlier.
 2. `ifx` issue:
    - Two `string_t` tests fail as described in issue [#51].
 
@@ -316,5 +315,4 @@ See our online [documentation] or build the documentation locally by installing
 [Garden]: https://gitlab.com/everythingfunctional/garden
 [handy-dandy]: https://github.com/rouson/handy-dandy/blob/7caaa4dc3d6e5331914a3025f0cb1db5ac1a886f/src/fresh-llvm-build.sh
 [Sourcery]: https://github.com/sourceryinstitute/sourcery
-[`vector_test_diagnosis_i`]: https://github.com/BerkeleyLab/julienne/blob/37bcc959efa8f9e27ae50fecfd37a6bf52ef0a43/src/julienne/julienne_vector_test_description_m.F90#L18
 [Veggies]: https://gitlab.com/everythingfunctional/veggies

demo/README.md

@@ -1,38 +1,36 @@
 Getting Started
 ===============
 To get started with Julienne, review and test the demonstration project in this directory.
-Then copy the `main.F90` and `specimen_test_m.F90` files to your project's test directory.
+Then copy the `main.f90` and `specimen_test_m.f90` files to your project's test directory.
 Finally, modify the files as described below to adapt them to your project.
 
 Testing the Demonstration Project
 --------------------------------
 This demonstration project defines a trivial library named "specimen" in the `src`
-subdirectory and a test suite the `test` subdirectory.  The test suite includes five tests:
+subdirectory and a test suite in the `test` subdirectory.  The test suite includes five tests:
 
-1. Two tests pass.
+1. Three tests pass.
 2. One test intentionally fails to demonstrate diagnostic output.
 3. One test is skipped to demonstrate the reporting and tallying of skipped tests.
-4. One test passes with three compilers but is skipped with GCC due to a compiler bug.
 
 Test Julienne by setting your present working directory to the `demo/` subdirectory in a
 terminal window and then building and running the demonstration project's test suite using
 the command corresponding to your compiler in the table below.
 
-|Vendor   | Version/Build           | Example shell command                                                              |
-|---------|-------------------------|------------------------------------------------------------------------------------|
-|LLVM     | 20.1.4 (Homebrew)       | `fpm test --compiler flang-new`                                                    |
-|GCC      | 14.2.0_1 (Homebrew)     | `fpm test --compiler gfortran --profile release`                                   |
-|GCC      | 13.3.0_1 (Homebrew)     | `fpm test --compiler gfortran --profile release --flag "-ffree-line-length-0"`     |
-|NAG      | 7.2 Build 7227          | `fpm test --compiler nagfor --flag -fpp`                                           |
-|Intel    | 2025.1.0 Build 20250317 | `fpm test --compiler ifx --flag "-fpp -O3 -coarray"`                               |
+|Vendor   | Version/Build Tested    | Example shell command                                |
+|---------|-------------------------|------------------------------------------------------|
+|LLVM     | 20.1.4                  | `fpm test --compiler flang-new`                      |
+|GCC      | 14.3.0                  | `fpm test --compiler gfortran --profile release`     |
+|NAG      | 7.2 Build 7235          | `fpm test --compiler nagfor --flag -fpp`             |
+|Intel    | 2025.1.0 Build 20250317 | `fpm test --compiler ifx --flag "-fpp -O3 -coarray"` |
 
 Setting Up Your Project's Test Suite
 ------------------------------------
 
-1. If you build your project with the Fortran Package Manager ([`fpm`](https://github.com/fotran-lang/fpm)), then you might copy the `main.F90` and `specimen_test_m.F90` files from this subdirectory to a `test/` subdirectory in the root of your project's source tree.
-2. Rename the `specimen_test_m.F90` file, the `specimen_test_m` module, and the `specimen_test_t` derived type and any references thereto, replacing `specimen` with the name of an entity that you intend to test -- most likely a module containing procedures or derived type with type-bound procedures.
-3. Similarly replace occurrences of `specimen` in the resulting`test/main.F90` file.
-4. In the `results()` function body of your new `*_test_m.F90` file, replace the `test_descriptions_t` array constructor elements with your own test descriptions.  The test output will read most naturally if your description string (the first argument) contains a gerund: a verb ending in "ing" and used as a noun, such as `producing` above 
+1. If you build your project with the Fortran Package Manager ([`fpm`](https://github.com/fotran-lang/fpm)), then you might copy the `main.f90` and `specimen_test_m.f90` files from this subdirectory to a `test/` subdirectory in the root of your project's source tree.
+2. Rename the `specimen_test_m.f90` file, the `specimen_test_m` module, and the `specimen_test_t` derived type and any references thereto, replacing `specimen` with the name of an entity that you intend to test -- most likely a module containing procedures or derived type with type-bound procedures.
+3. Similarly replace occurrences of `specimen` in the resulting`test/main.f90` file.
+4. In the `results()` function body of your new `*_test_m.f90` file, replace the `test_descriptions_t` array constructor elements with your own test descriptions.  The test output will read most naturally if your description string (the first argument) contains a gerund: a verb ending in "ing" and used as a noun, such as `producing` above.
 5. Replace the function name (the second argument) with the name of a function that will perform your test.
 7. Edit the correspondingly-renamed function to perform the test.  The function must take no arguments and define a `test_diagnosis_t` result.
 
@@ -43,7 +41,7 @@ The options include
 2. Invoking the `test_diagnosis_t` constructor and using Julienne's `string_t` constructors to form a diagnostic string.
 
 `String_t` is a generic interface to various specific functions, each of which takes an argument of a different data type, kind, and rank (TKR) and defines a `string_t` result containing a charater representation of the function argument.
-Please see Julienne's online [documentation] for the currently supported TKR.
+Please see Julienne's online [documentation](https://berkeleylab.github.io/julienne) for the currently supported TKR.
 Please submit an issue to request support for additional TKR or submit a pull request to contribute such support.
 
 #### Forming diagnostic strings from array data
@@ -117,7 +115,7 @@ Skipping Tests
 --------------
 When a test is known to cause a compile-time or runtime crash in a specific scenario, e.g., with a specific compiler or compiler version, including that test will prevent the test suite from building or running to completion.
 It can be useful to skip a test with the problematic compiler but to report the test as skipped and account for the skipped tests in the tally of test results.
-For this purpose, the `test_description_t` and `vector_test_description_t` constructor functions have optional second arguments `diagnosis_function` and `vector_diagnosis_function`, respectively.
+For this purpose, the `test_description_t` constructor function has a `diagnosis_function` argument that is optional.
 When these arguments are not `present`, the `test_t`'s `report` procedure will report the test as skipped but will terminate normally as long as the sum of the passing tests and skipped tests equals the total number of tests.
 One might accomplish this with the compiler's predefined preprocessor macro:
 ```
@@ -127,7 +125,7 @@ One might accomplish this with the compiler's predefined preprocessor macro:
       ,test_description_t('constructing bracketed strings'                      ) &
 #endif
 ```
-which presently appears in Julienne `test/string_test_m.F90` test in order to work around a runtime crash known to be caused by a `gfortran` bug.
+which presently appears in Julienne `test/string_test_m.f90` test in order to work around a runtime crash known to be caused by a `gfortran` bug.
 
 String_t Functions
 ------------------
@@ -161,32 +159,3 @@ class string_t{
     base_name(string_t) string_t
 }
 ```
-
-Deprecated: Vector Diagnosis Function
--------------------------------------
-Julienne's `vector_diagnosis_function_i` abstract interface and the corresponding `vector_test_description_t` type were developed before Julienne's `operator(.all.)` and `operator(.and.)`.
-Because the operators replace the interface and type with simpler functionality, it is likely that a future release will remove the `vector_*` entities.
-
-The Unified Modeling Language ([UML]) class diagram below depicts the class relationships involved when test function performs multiple checks and defines a result containing an array of corresponding `test_diagnosis_t` objects:
-```mermaid
- %%{init: { 'theme':'default',  "class" : {"hideEmptyMembersBox": true} } }%%
-classDiagram
-
-class vector_test_description_t{
-    vector_test_description_t(description : string_t[1..*], vector_diagnosis_function : vector_diagnosis_function_i)
-    run() test_result_t[1..*]
-}
-vector_test_description_t --> test_diagnosis_t : run() invokes vector_diagnosis_function to construct array of
-vector_test_description_t --> test_result_t : run() uses test_diagnostics_t array to construct array of
-
-class test_result_t{
-    test_result_t(test_passed : logical, diagnosis : test_diagnosis_t)
-}
-
-class test_diagnosis_t{
-    test_diagnosis_t(test_passed : logical, diagnostics_string : string_t)
-}
-```
-
-[documentation]: https://berkeleylab.github.io/julienne
-[UML]: https://wikipedia.org/Unified_modeling_language

demo/fpm.toml

@@ -1,4 +1,4 @@
 name = "Example-Test-Suite"
 
 [dependencies]
-julienne = {git = "https://github.com/berkeleylab/julienne", tag = "2.1.0-rc5"}
+julienne = {path = "../"}

demo/test/main.f90

@@ -0,0 +1,23 @@
+! Copyright (c) 2024-2025, The Regents of the University of California and Sourcery Institute
+! Terms of use are as specified in LICENSE.txt
+
+program test_suite_driver
+  !! Example test-suite driver
+  use julienne_m      ,only : test_fixture_t, test_harness_t ! Import test infrastructure
+  use specimen_test_m ,only : specimen_test_t  ! Must be a non-abstract child type extending Julienne's test_t type
+  use iso_fortran_env ,only : compiler_version
+  implicit none
+
+  call stop_if_compiler_too_old
+
+  ! Construct a test harness from an array of test fixtures, each of which is
+  ! constructed from a structure constructor for a type that extends test_t.
+  associate(test_harness => test_harness_t( [ test_fixture_t(specimen_test_t()) ] ))
+    call test_harness%report_results
+  end associate
+
+contains
+#if __GNUC__ && ( __GNUC__ < 14 || (__GNUC__ == 14 && __GNUC_MINOR__ < 3) )
+  stop "GFortran " // __VERSION__ // " too old: GCC >= 14.3.0 required"
+#endif
+end program

demo/test/specimen_test_m.F90 → demo/test/specimen_test_m.f90

@@ -1,8 +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
 
-#include "language-support.F90"
-
 module specimen_test_m
   !! Example unit test for the specimen_t test subject
   use specimen_m, only : specimen_t
@@ -17,11 +15,8 @@ module specimen_test_m
     ,operator(.within.) &
     ,operator(.all.) &
     ,operator(.equalsExpected.) &
-    ,operator(.greaterThan.) &
-    ,operator(.lessThan.)
-#if defined(__GFORTRAN__)
-  use julienne_m, only : diagnosis_function_i ! work around gfortran's missing Fortran 2008 feature
-#endif
+    ,operator(.lessThan.) &
+    ,operator(.isAtMost.)
 
   implicit none
 
@@ -41,8 +36,6 @@ pure function subject() result(specimen_description)
     specimen_description = "A specimen_t object"
   end function
 
-#if ! defined(__GFORTRAN__)
-
   function results() result(test_results)
     type(test_result_t), allocatable :: test_results(:)
     type(test_description_t), allocatable :: test_descriptions(:)
@@ -61,35 +54,6 @@ function results() result(test_results)
     test_results = test_descriptions%run()
   end function
 
-#else
-
-  function results() result(test_results)
-    !! work around missing Fortran 2008 feature in gfortran versions earlier than 15
-    type(test_result_t), allocatable :: test_results(:)
-    type(test_description_t), allocatable :: test_descriptions(:)
-    procedure(diagnosis_function_i), pointer :: check_operators_ptr => check_zero_using_operators
-    procedure(diagnosis_function_i), pointer :: check_constructor_ptr => check_zero_using_constructor
-    procedure(diagnosis_function_i), pointer :: check_aggregate_ptr => check_aggregate_diagnosis
-    procedure(diagnosis_function_i), pointer :: check_print_diagnosis_ptr => check_print_diagnosis
-
-    ! Omitting the optional 2nd argument in the 3rd test_description_t constructor below skips the described
-    ! test.  When the test suite runs, it reports the test as skipped and reports a tally of skippped tests.
-
-    test_descriptions = [ &
-       test_description_t("diagnosing the zero function using Julienne operators", check_operators_ptr) &
-      ,test_description_t("diagnosing the zero function using a diagnosis constructor", check_constructor_ptr) &
-      ,test_description_t("aggregating diagnoses of the zero and one functions using operator(.all.)") &
-      ,test_description_t("(intentional failure to demonstrate diagnostic output)", check_print_diagnosis_ptr) &
-      ,test_description_t("skipping a test when no diagnosis function is specified") &
-    ]
-    test_descriptions =  pack( &
-       array = test_descriptions &
-      ,mask = test_descriptions%contains_text(test_description_substring) .or. index(subject(), test_description_substring)/=0 &
-    )
-    test_results = test_descriptions%run()
-  end function
-#endif
-
   function check_zero_using_operators() result(test_diagnosis)
     !! Construct a test diagnosis using Julienne's operator(.approximates.) and operator(.within.)
     type(test_diagnosis_t) test_diagnosis
@@ -123,8 +87,9 @@ function check_aggregate_diagnosis() result(test_diagnosis)
   end function
 
   function check_print_diagnosis() result(test_diagnosis)
+    !! Intentional test failure to demonstrate diagnostic output
     type(test_diagnosis_t) test_diagnosis
-    test_diagnosis = 2 .lessThan. 1 ! intentional test failure
+    test_diagnosis = 2 .isAtMost. 1 
   end function
 
 end module