feat: rm diagnostic_data arg & related types

This commit
1. Removes the diagnostic_data argument from the assert subroutine
2. Removes the types that existed solely to support that argument:
   a. characterizable_t
   b. intrinsic_array_t
3. Edits or deletes examples that referenced the removed entities
4. Edits or deletes documentation that referenced removed entities

Author: rouson

.github/workflows/deploy-docs.yml

@@ -24,7 +24,7 @@ jobs:
 
     - name: Build Developer Documentation
       run: |
-        ford -I include doc-generator.md > ford_output.txt
+        ford -I include ford.md > ford_output.txt
         # Turn warnings into errors
         cat ford_output.txt; if grep -q -i Warning ford_output.txt; then exit 1; fi
         cp ./README.md ./doc/html

README.md

@@ -19,7 +19,6 @@ This assertion utility contains four public entities:
 
 The `assert` subroutine
 * Error-terminates with a variable stop code when a caller-provided logical assertion fails,
-* Includes user-supplied diagnostic data in the output if provided by the calling procedure,
 * Is callable inside `pure` procedures, and
 * Can be eliminated at compile-time, as controlled by the `ASSERTIONS` preprocessor define.
 
@@ -42,10 +41,6 @@ If instead `fpm install` is used, then either the user must copy `include/assert
 the user must invoke `assert` directly (via `call assert(...)`).
 In the latter approach when the assertions are disabled, the `assert` procedure will start and end with `if (.false.) then ... end if`, which might facilitate automatic removal of `assert` during the dead-code removal phase of optimizing compilers.
 
-The `characterizable_t` type defines an `as_character()` deferred binding that produces `character` strings for use as diagnostic output from a user-defined derived type that extends  `characterizable_t` and implements the deferred binding.
-
-The `intrinsic_array_t` type that extends `characterizable_t` provides a convenient mechanism for producing diagnostic output from arrays of intrinsic type `complex`, `integer`, `logical`, or `real`.
-
 Use Cases
 ---------
 Two common use cases include
@@ -208,19 +203,19 @@ character for line-breaks in a macro invocation:
 
 ```fortran
 ! OK for flang-new and gfortran
-call_assert_diagnose( computed_checksum == expected_checksum, \
-                      "Checksum mismatch failure!", \
-                      expected_checksum )                  
+call_assert_describe( computed_checksum == expected_checksum, \
+                      "Checksum mismatch failure!" \
+                    )                  
 ```
 
 Whereas Cray Fortran wants `&` line continuation characters, even inside
 a macro invocation:
 
 ```fortran
 ! OK for Cray Fortran
-call_assert_diagnose( computed_checksum == expected_checksum, &
-                      "Checksum mismatch failure!", &
-                      expected_checksum )                  
+call_assert_describe( computed_checksum == expected_checksum, &
+                      "Checksum mismatch failure!" &
+                    )                  
 ```
 
 There appears to be no syntax acceptable to all compilers, so when writing
@@ -237,29 +232,29 @@ after macro expansion (on gfortran and flang-new):
 
 ```fortran
 ! INCORRECT: cannot use Fortran comments inside macro invocation
-call_assert_diagnose( computed_checksum == expected_checksum, ! ensured since version 3.14
-                      "Checksum mismatch failure!",           ! TODO: write a better message here
-                      computed_checksum )             
+call_assert_describe( computed_checksum == expected_checksum, ! ensured since version 3.14
+                      "Checksum mismatch failure!"            ! TODO: write a better message here
+                    )             
 ```
 
 Depending on your compiler it *might* be possible to use a C-style block
 comment (because they are often removed by the preprocessor), for example with
 gfortran one can instead write the following:
 
 ```fortran
-call_assert_diagnose( computed_checksum == expected_checksum, /* ensured since version 3.14 */ \
-                      "Checksum mismatch failure!",           /* TODO: write a better message here */ \
-                      computed_checksum )
+call_assert_describe( computed_checksum == expected_checksum, /* ensured since version 3.14 */ \
+                      "Checksum mismatch failure!"            /* TODO: write a better message here */ \
+                    )
 ```
 
 However that capability might not be portable to other Fortran compilers. 
 When in doubt, one can always move the comment outside the macro invocation:
 
 ```fortran
 ! assert a property ensured since version 3.14
-call_assert_diagnose( computed_checksum == expected_checksum, \
-                      "Checksum mismatch failure!",           \
-                      computed_checksum ) ! TODO: write a better message above
+call_assert_describe( computed_checksum == expected_checksum, \
+                      "Checksum mismatch failure!"            \
+                    ) ! TODO: write a better message above
 ```                      
 
 Legal Information

doc/assert_class_diagram.puml

@@ -10,82 +10,34 @@ The [simple_assertions.f90] example demonstrates a precondition and a
 postcondition, each with an assertion that checks the truth of a logical
 expression based on scalar, real values.
 
-Derived type diagnostic data
-----------------------------
-
-See [derived_type_diagnostic.f90].  For reasons related to runtime performance,
-it is desirable to ensure that any computation required to extract diagnostic
-data from an object only take place if the assertion fails.  This is one of the
-main motivations for allowing objects to be passed to the `diagnostic_data`
-argument of `assert`.  The generic programming facilities planned for
-"Fortran 202y" (two standards after Fortran 2018) will ultimately provide the
-best way to facilitate the extraction of diagnostic data from objects by
-empowering developers to express requirements on types such as that the types
-must support a specific procedure binding that can be used to extract output
-in character form, the form that `assert` uses for its error stop code.  For
-now, we impose such a requirement through an `as_character` deferred binding
-on the provided `characterizable_t` abstract type.
-
-Because it might prove problematic to require that a user type to extend the
-`characterizable_t` abstract type, the [derived_type_diagnostic.f90] example
-shows a workaround based on the class hierarchy described in the figure below.
-The figure shows a Unified Modeling Language ([UML]) class diagram with the
-`characterizable_t` abstract class, an example user's `stuff_t` class, and a
-`characterizable_stuff_t` class.  The pattern expressed in the workaround
-aggregates the example user type, `stuff_t`, as a component inside the
-encapsulating `characterizable_stuff_t` type defined to extend `characterizable_t`
-for purposes of implementing `characterizable_t` parent type's deferred
-`as_character()` binding.
-
-The figure below also shows two constraints written in UML's Object Constraint
-Language ([OCL]).  The constraints describe the precondition and postcondition
-checked in [derived_type_diagnostic.f90] and the context for those constraints.
-
-The UML diagram below was generated in the [Atom] editor [PlantUML] package
-from the PlantUML script in this repository's [doc] folder.
-
-![Classes involved in Derived-Type Diagnostic Example](https://user-images.githubusercontent.com/13108868/130385757-6b79e5f1-5dec-440c-98f5-0f659c538754.png)
-
 Running the examples
 --------------------
 
 ### Single-image execution
 ```
 fpm run --example simple_assertions
-fpm run --example derived_type_diagnostic
 ```
 where `fpm run` automatically invokes `fpm build` if necessary, .e.g., if the package's source code
-has changed since the most recent build.  If `assert` is working correctly, the first `fpm run` above
-will error-terminate with the character stop code
-```
-Assertion "reciprocal: abs(error) < tolerance" failed on image 1 with diagnostic data "-1.00000000"
+has changed since the most recent build.  If `assert` is working correctly, the `fpm run` above
+will error-terminate with the character stop code similar to the following
 ```
-and the second `fpm run` above will error-terminate with the character stop code
-```
-Assertion "stuff_t%z(): self%defined()" failed on image 1 with diagnostic data "(none provided)"
+Assertion failure on image 1: reciprocal: abs(error) < tolerance
 ```
 
 ### Multi-image execution with `gfortran` and OpenCoarrays
 ```
 git clone git@github.com/sourceryinstitute/assert
 cd assert
 fpm run --compiler caf --runner "cafrun -n 2" --example simple_assertions
-fpm run --compiler caf --runner "cafrun -n 2" --example derived_type_diagnostic
 ```
 Replace either instance of `2` above with the desired number of images to run for parallel execution.
 If `assert` is working correctly, both of the latter `fpm run` commands will error-terminate with one
 or more images providing stop codes analogous to those quoted in the [Single-image execution] section.
 
-## Derived-type diagnostic data output
-To demonstrate the derived-type diagnostic data output capability, try replacing the
-`i%defined()` assertion in the [derived_type_diagnostic.f90](./derived_type_diagnostic.f90)
-with `.false.`.
-
 [Hyperlinks]:#
 [OpenCoarrays]: https://github.com/sourceryinstitute/opencoarrays
 [Enforcing programming contracts]: #enforcing-programming-contracts
 [Single-image execution]: #single-image-execution
-[derived_type_diagnostic.f90]: ./derived_type_diagnostic.f90
 [simple_assertions.f90]: ./simple_assertions.f90
 [UML]: https://en.wikipedia.org/wiki/Unified_Modeling_Language
 [OCL]: https://en.wikipedia.org/wiki/Object_Constraint_Language