Merge pull request #54 from BerkeleyLab/chores

Chores and minor new feature

Author: rouson

README.md

@@ -1,40 +1,37 @@
+<p align="center">
+  <img width="250" height="250" src="https://github.com/user-attachments/assets/1a1c4f1a-f229-4d6d-bcaa-d5d9826ee639">
+</p>
+
 Julienne
 ========
-```
-     _       _ _                       
-    | |_   _| (_) ___ _ __  _ __   ___ 
- _  | | | | | | |/ _ \ '_ \| '_ \ / _ \
-| |_| | |_| | | |  __/ | | | | | |  __/
- \___/ \__,_|_|_|\___|_| |_|_| |_|\___|
- ```
-Julienne is a modern Fortran unit-testing framework that includes utilities for manipulating strings 
+Julienne is a modern Fortran unit-testing framework that includes utilities for manipulating strings
 via Julienne's `string_t` derived type.  The target strings include command-line arguments accessed
 via Julienne's `command_line_t` type  and format strings generated by functions in Julienne's `formats_m` module.
 
 Users construct tests by
 1. Extending Julienne's `test_t` abstract derived type,
 2. Defining a `subject()` function that returns a description of the entity being tested,
 3. Defining a `results()` function that
-    - Constructs an array of `test_description_t` objects, each of which encapsulates
+    - Defines a result comprised of an array of `test_result_t` objects.
+    - Defines a local array of `test_description_t` objects, each of which encapsulates
         * A string describing a function that produces one or more `test_diagnosis_t` result objects, each of which encapsulates
             * A `logical` indicator of whether the test passed and
             * A `character` or `string_t` diagnostics string.
-        * The corresponding function name and
-    - Produces an array of `test_result_t` objects.
+        * The corresponding function name.
 
 Julienne empowers users to customize the diagnostic information that prints when tests fail.
 For this purpose, Julienne's `string_t` constructors convert various data types, kinds, and ranks to character data.
 Julienne also provides `string_t` operators supporting concatenation and delimited lists such as comma-separated value lists.
 
 Julienne's name derives from the term for vegetables sliced into thin strings: julienned vegetables.
 The [Veggies] unit-testing framework inspired the structure of Julienne's tests and output.
-Julienne aims to be a more lightweight alternative that is more portable across compilers and compiler versions.
+Julienne aims to be a more lightweight alternative that is more portable across compilers.
 
 Getting Started
 ---------------
 Please see the [example-test-suite README.md](./example/example-test-suite/README.md).
 
-Supported Compilers 
+Supported Compilers
 -------------------
 
 Compiler         | Version(s) Tested        | Known Issues
@@ -104,5 +101,5 @@ See our online [documentation] or build the documentation locally by installing
 [Veggies]: https://gitlab.com/everythingfunctional/veggies
 [here]: https://github.com/rouson/handy-dandy/blob/7caaa4dc3d6e5331914a3025f0cb1db5ac1a886f/src/fresh-llvm-build.sh
 [documentation]: https:///berkeleylab.github.io/julienne/
-[FORD]: https://github.com/Fortran-FOSS-Programmers/ford 
+[FORD]: https://github.com/Fortran-FOSS-Programmers/ford
 [handy-dandy]: https://github.com/rouson/handy-dandy/blob/7caaa4dc3d6e5331914a3025f0cb1db5ac1a886f/src/fresh-llvm-build.sh

example/check-command-line-argument.f90

@@ -1,14 +1,14 @@
-! Copyright (c) 2024, The Regents of the University of California and Sourcery Institute
+! Copyright (c) 2024-2025, The Regents of the University of California and Sourcery Institute
 ! Terms of use are as specified in LICENSE.txt
 program check_command_line_argument
-  !! This program serves the dual purposes of 
+  !! This program serves the dual purposes of
   !! 1. Showing how to use the command_line_t derived type to check whether a
   !!    command-line argument is present and
   !! 2. Supporting the test suite verification of this same behavior.
   !!
   !! Running this program as follows with the command
   !!
-  !! fpm run --example check-command-line-argument -- --some-argument 
+  !! fpm run --example check-command-line-argument -- --some-argument
   !!
   !! should result in normal termination.
   use assert_m, only : assert

example/example-test-suite/README.md

@@ -10,18 +10,18 @@ Likely the fastest way to get started with Julienne is to copy the source code i
 3. Similarly replace occurrences of `specimen` in the resulting`test/main.F90` file.
 4. Modify the `test_descriptions_t` array constructor in your new `*_test_m.F90` file, adding elements for each test to be performed:
 ```fortran
-  test_descriptions = [ & 
+  test_descriptions = [ &
     test_description_t("the type-bound function zero() producing a result of 0", check_zero) &
-  ]  
+  ]
 ```
 5. Replace the above string (`"the type-bound..."`) with a description of your intended test.  The test output will read most naturally if your description contains a gerund: a verb ending in "ing" and used as a noun, such as `producing` above.
-6. Replace the `check_zero` function name with the name of a function that will perform your test. 
+6. Replace the `check_zero` function name 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. An example result might be the following:
 ```fortran
   test_diagnosis = test_diagnosis_t( &
      test_passed = actual_value == expected_value &
     ,diagnostics_string = "expected value " // string_t(expected_value) //", actual value " // string_t(actual_value) &
-  )   
+  )
 ```
 The above `test_diagnosis_t` constructor function invocation demonstrates the recommended pattern for writing tests with Julienne:
 
@@ -54,7 +54,7 @@ and the following corresponding test:
 ```
 If the `counting_numbers` result contains all zeros, the test report would include the following text:
 ```
-FAILS  on returning the counting numbers up to 3 
+FAILS  on returning the counting numbers up to 3
       diagnostics: expected 1,2,3; actual 0,0,0
 ```
 To support a common array notation, Julienne also supports bracketing strings.
@@ -82,7 +82,7 @@ test_t --> specimen_test_t : report() invokes subject() and results()
 
 class specimen_test_t{
     subject() character(len=:)
-    results() test_result_t[0..*]  
+    results() test_result_t[0..*]
 }
 specimen_test_t --|> test_t : extends and implements
 specimen_test_t --> test_description_t : results() constructs local array of
@@ -138,7 +138,7 @@ One might accomplish this with the compiler's predefined preprocessor macro:
 #ifndef __GFORTRAN__
       ,test_description_t('constructing bracketed strings', brackets_strings_ptr) &
 #else
-      ,test_description_t('constructing bracketed strings'                      ) &  
+      ,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.

example/example-test-suite/main.F90

@@ -1,4 +1,4 @@
-! Copyright (c) 2024, The Regents of the University of California and Sourcery Institute
+! 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"
@@ -29,7 +29,7 @@ subroutine print_usage_and_stop_if_help_requested
       print '(a)', 'the tests with test subjects or test descriptions containing the user-specified substring.'
       stop
     else
-      print * 
+      print *
       print "(a)", "Append '-- --help' or '-- -h' to your `fpm test` command to display usage information."
     end if
   end subroutine

example/example-test-suite/scalar_and_vector_test_description_m.f90

@@ -1,4 +1,4 @@
-! Copyright (c) 2024, The Regents of the University of California and Sourcery Institute
+! 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"
@@ -29,7 +29,7 @@ module scalar_and_vector_test_description_test_m
 
   pure function subject() result(specimen)
     character(len=:), allocatable :: specimen
-    specimen = "The test_description_t type" 
+    specimen = "The test_description_t type"
   end function
 
   function results() result(test_results)
@@ -60,11 +60,11 @@ function results() result(test_results)
            string_t(    "finding a substring in a test description") &
           ,string_t("not finding a missing substring in a test description") &
         ], check_substring_search &
-      )]) 
+      )])
         associate(num_vector_tests => size(vector_test_descriptions))
           block
             integer i
-           
+
             if (substring_in_subject) then
               vector_test_results = [(vector_test_descriptions(i)%run(), i=1,num_vector_tests)]
             else

example/example-test-suite/specimen_m.F90

@@ -1,4 +1,4 @@
-! Copyright (c) 2024, The Regents of the University of California and Sourcery Institute
+! Copyright (c) 2024-2025, The Regents of the University of California and Sourcery Institute
 ! Terms of use are as specified in LICENSE.txt
 module specimen_m
   !! Example test specimen corresponding to the test defined in specimen_test_m.F90

example/example-test-suite/specimen_test_m.F90

@@ -1,4 +1,4 @@
-! Copyright (c) 2024, The Regents of the University of California and Sourcery Institute
+! 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"
@@ -16,7 +16,7 @@ module specimen_test_m
 #if ! HAVE_PROCEDURE_ACTUAL_FOR_POINTER_DUMMY
   use julienne_m, only : diagnosis_function_i ! work around gfortran's missing Fortran 2008 feature
 #endif
-    
+
   implicit none
 
   private
@@ -32,32 +32,32 @@ module specimen_test_m
 
   pure function subject() result(specimen_description)
     character(len=:), allocatable :: specimen_description
-    specimen_description = "A specimen_t object" 
+    specimen_description = "A specimen_t object"
   end function
 
   function results() result(test_results)
     type(test_result_t), allocatable :: test_results(:)
     type(test_description_t), allocatable :: test_descriptions(:)
 
 #if HAVE_PROCEDURE_ACTUAL_FOR_POINTER_DUMMY
-    test_descriptions = [ & 
+    test_descriptions = [ &
       test_description_t("the type-bound function zero() producing a result of 0", check_zero) &
-    ]   
-#else 
+    ]
+#else
     ! work around gfortran's missing Fortran 2008 feature
     procedure(diagnosis_function_i), pointer :: check_zero_ptr
     check_zero_ptr => check_zero
 
-    test_descriptions = [ & 
+    test_descriptions = [ &
       test_description_t("the type-bound function zero() producing a result of 0", check_zero_ptr) &
-    ]   
+    ]
 #endif
 #ifndef __GFORTRAN__
     associate(test_subset => pack(test_descriptions, test_descriptions%contains_text(test_description_substring) .or. index(subject(), test_description_substring)/=0))
       test_results = test_subset%run()
     end associate
-#else 
-    
+#else
+
     test_descriptions = pack(test_descriptions, test_descriptions%contains_text(test_description_substring) .or. index(subject(), test_description_substring)/=0)
     test_results = test_descriptions%run()
 #endif

example/get-flag-value.f90

@@ -1,7 +1,7 @@
-! Copyright (c) 2024, The Regents of the University of California and Sourcery Institute
+! Copyright (c) 2024-2025, The Regents of the University of California and Sourcery Institute
 ! Terms of use are as specified in LICENSE.txt
 program get_flag_value
-  !! Demonstrate how to find the value of a command-line flag 
+  !! Demonstrate how to find the value of a command-line flag
   !! Running this program as follows with the command
   !!
   !! fpm run --example get-flag-value -- --input-file foo

example/handle-missing-flag.f90

@@ -1,4 +1,4 @@
-! Copyright (c) 2024, The Regents of the University of California and Sourcery Institute
+! Copyright (c) 2024-2025, The Regents of the University of California and Sourcery Institute
 ! Terms of use are as specified in LICENSE.txt
 program handle_missing_flag
   !! This program serves the dual purposes of

fpm.toml

@@ -1,9 +1,9 @@
 name = "julienne"
-version = "1.8.4"
+version = "2.0.1"
 license = "license"
 author = "Damian Rouson, Brad Richardson, Patrick Raynaud, Katherine Rasmussen"
 maintainer = "rouson@lbl.gov"
-copyright = "Copyright 2024, Sourcery Institute and Berkeley Lab"
+copyright = "Copyright 2024-2025, Sourcery Institute and Berkeley Lab"
 
 [dependencies]
 assert = {git = "https://github.com/berkeleylab/assert", tag = "2.1.0"}