Merge pull request #92 from BerkeleyLab/auto-generate-driver

Automatically generate demo test suite from JSON file

Author: rouson

README.md

@@ -31,22 +31,21 @@ Example expressions                               | Operand types
 `s .isAfter. t`                                   | `character`
 `.expect. command_line%argument_present("--help")`| `logical`
 
+where 
+* `.isAtLeast.` and `.isAtMost.` can alternatively be spelled `.greaterThanOrEqualTo.` and `.lessThanOrEqualTo.`, respectively;
+* `.equalsExpected.` uses `==`, which implies that trailing blank spaces are ignored in character operands;  
+* `.isBefore.` and `.isAfter.` verify alphabetical and reverse-alphabetical  order, respectively; 
+* `.all.` aggregates arrays of expression results, reports a consensus result, passes, and shows diagnostics only for failing tests, if any; and
+* `.equalsExpected.` generates asymmetric diagnostic output for failures, denoting the left- and right-hand sides as the actual value and expected values, respectively.
 
-where `.isAtLeast.` and `.isAtMost.` can alternatively be spelled
-`.greaterThanOrEqualTo.` and `.lessThanOrEqualTo.`, respectively;
-`.equalsExpected.` uses `==`, which implies that trailing blank spaces
-are ignored in character operands; and `.isBefore.` and `.isAfter.`
-verify alphabetical and reverse-alphabetical order, respectively.
-The new `.all.` operator is synonymous with the `.and.` defined operation
-but avoids confusion with the intrinsic `.and.` operator.
 
 Expressive idioms 
 -----------------
 ### Assertions
-Any of the above tabulated expressions can be the actual argument in an
-invocation of Julienne's `call_assert` function-line preprocessor macro:
-```
-call_assert(x .lessThan. y)
+Any of the above expressions can be the actual argument in an invocation
+of Julienne's `call_julienne_assert` function-line preprocessor macro:
+```fortran
+call_julienne_assert(x .lessThan. y)
 ```
 which a preprocessor will replace with a call to Julienne's assertion subroutine
 when compiling with `-DASSERTIONS`.  Otherwise, the preprocessor will remove the
@@ -103,7 +102,7 @@ Example expression                               | Result
 
 One can use such expressions to craft a diagnostic message when constructing
 a custom test function result:
-```
+```fortran
 type(test_diagnosis_t) test_diagnosis
 test_diagnosis = test_diagnosis_t( &
   test_passed = i==j, &
@@ -122,7 +121,7 @@ or two procedures.  The resulting `file_t` object can be manipulated elsewhere
 without incurring the costs associated with file I/O.  For example, the following
 line reads a file named `data.txt` into a `file_t` object and associates the name
 `file` with the resulting object.
-```
+```fortran
 type(file_t) file
 associate(file => file_t("data.txt"))
 end associate
@@ -155,6 +154,10 @@ diagnostic messages during error termination.
 
 Getting Started
 ---------------
+### Writing Unit Tests
+Please see [demo/README.md](./demo/README.md) for a detailed demonstration of
+test setup.  
+
 ### Writing Assertions
 To write a Julienne assertion, insert a function-like preprocessor macro
 `call_julienne_assert` on a single line as in each of the two macro
@@ -185,46 +188,6 @@ 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,
-in which each element is a `test_description_t` constructor function invocation
-with two arguments: a `character` string describing what the test does and the
-name of a function that performs the test.  An example follows:
-```fortran
-  type(test_description_t), allocatable ::test_descriptions(:)
-  test_descriptions = [ &
-     test_description_t("checking something", check_something) &
-    ,test_description_t("checking something else", check_something_else) &
-  ]
-```
-Execute the tests by calling the `test_description_t` type-bound `run` procedure
-on the `test_descriptions` array.
-
-Define each test function to produce a `test_diagnosis_t` object result
-encapsulating the two components enumerated in the [Assertions] section.
-Use one of Julienne's expression idioms to construct the function result
-automatically:
-```fortran
-  function check_something() result(test_diagnosis)
-    type(test_diagnosis_t) test_diagnosis
-    integer, parameter :: i=1, j=1
-    test_diagnosis = i .equalsExpected. j
-  end function
-```
-where the `.equalsExpected.` operator is named to imply an asymmetry with
-respect to the arguments `i` and `j`.  If the condition `i==j` evaluates to
-`.false.`, Julienne constructs a diagnostic message reflecting the implied
-asymmetry, i.e., indicating that `i` is the actual value, whereas `j` is the
-expected value.
-
-### A demonstration test suite
-Please see the demonstration test suite in [demo README.md](./demo/README.md)
-for detailed instructions on setting up a new test suite.  The demonstration
-test suite's main program also shows how to use Julienne's `command_line_t` type
-to access arguments that users pass to program via a command line or shell
-script.  Julienne also offers useful input/output format strings and
-format-generating functions in the `julienne_formats_m` module.
-
 An Origin Story
 ---------------
 Julienne's name derives from the term for vegetables sliced into thin strings:
@@ -269,7 +232,7 @@ fpm test --compiler flang-new
 ##### `flang-new` version 19
 Add the following command before the `fpm` command recommended above for
 LLVM 20 or later:
-```
+```bash
 export FPM_FFLAGS="-mmlir -allow-assumed-rank"
 ```
 where this `FPM_FFLAGS` setting turns on the support for Fortran's assumed-rank

app/scaffold.F90

@@ -0,0 +1,68 @@
+! Copyright (c) 2024-2025, The Regents of the University of California and Sourcery Institute
+! Terms of use are as specified in LICENSE.txt
+
+program scaffold
+  use julienne_m, only : command_line_t, file_t, test_suite_t
+  implicit none
+  type(command_line_t) command_line
+  integer i
+
+  if (help_requested()) call print_usage_info_and_stop
+
+#ifndef __GNUC__
+  associate(subjects_file_name => command_line%flag_value("--json-file"))
+    if (len(subjects_file_name) == 0) call print_usage_info_and_stop
+    print '(*(a))', "Reading test subject information from " // subjects_file_name
+    associate(test_suite => test_suite_t(file_t(subjects_file_name)))
+      associate(path => command_line%flag_value("--suite-path"))
+        print '(*(a))', "Writing test-suite scaffolding in " // path
+        if (len(path) == 0) call print_usage_info_and_stop
+        associate(driver => test_suite%driver_file())
+          call driver%write_lines(path // "/driver.f90")
+        end associate
+        associate(subjects => test_suite%test_subjects(), modules => test_suite%test_modules())
+          do i = 1, size(subjects)
+            associate(stub => test_suite%stub_file(subjects(i)))
+              call stub%write_lines(path // "/" // modules(i) // ".f90")
+            end associate
+          end do
+        end associate
+      end associate
+    end associate
+  end associate
+#else
+  block
+    character(len=:), allocatable ::  path, subjects_file_name
+    type(file_t) driver
+    subjects_file_name = command_line%flag_value("--json-file")
+    if (len(subjects_file_name) == 0) call print_usage_info_and_stop
+    print '(*(a))', "Reading test subject information from " // subjects_file_name
+    associate(test_suite => test_suite_t(file_t(subjects_file_name)))
+      path = command_line%flag_value("--suite-path")
+      if (len(path) == 0) call print_usage_info_and_stop
+      print '(*(a))', "Writing test-suite scaffolding in " // path
+      call test_suite%write_driver(path // "/driver.f90")
+    end associate
+  end block
+#endif
+
+contains
+
+    logical function help_requested()
+      character(len=:), allocatable :: file_name
+      type(command_line_t) command_line
+      help_requested = command_line%argument_present([character(len=len("--help"))::"--help","-h"])
+    end function
+
+    subroutine print_usage_info_and_stop
+      character(len=*), parameter :: usage = &
+        new_line('') // new_line('') //      &
+        'Usage: fpm run scaffold -- [--json-file <string> --suite-path <string>] | [--help] | -h]' // &
+        new_line('') // new_line('') //      &
+        'where square brackets ([]) denote optional arguments, a pipe (|) separates alternative arguments,' // new_line('') // &
+        'angular brackets (<>) denote a user-provided value, the --subjects string names a JSON file,'      // new_line('') // &
+        'and the --path string names a directory for the new test-suite scaffold.'                          // new_line('')
+      stop usage
+    end subroutine
+
+end program scaffold

app/test-suite.json

@@ -0,0 +1,6 @@
+{
+    "test suite": {
+        "modules" : ["assert_test_m","bin_test_m","command_line_test_m","formats_test_m","string_test_m","test_description_test_m","test_diagnosis_test_m","test_result_test_m"],
+          "types" : ["assert_test_t","bin_test_t","command_line_test_t","formats_test_t","string_test_t","test_description_test_t","test_diagnosis_test_t","test_result_test_t"]
+    }
+}