From bd81c7fa04ccf0cb6353733b3f64863bc56892dc Mon Sep 17 00:00:00 2001 From: Damian Rouson Date: Thu, 17 Jul 2025 16:52:10 -0700 Subject: [PATCH 1/4] doc(README): rm ford, update intro --- README.md | 21 ++++++++------------- 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 9503f8e..c15cd5a 100644 --- a/README.md +++ b/README.md @@ -12,15 +12,15 @@ Overview -------- This assertion utility contains four public entities: -1. An `assert` subroutine, -2. A `characterizable_t` abstract type supporting `assert`, and -3. An `intrinsic_array_t` non-abstract type extending `characterizable_t`. -4. An `assert_macros.h` header file containing C-preprocessor macros. +1. An `assert_macros.h` file defining the recommended preprocessor macros for writing assertion: + a. `call_assert(assertion)`, + b. `call_assert_describe(assertion, description)`, and +2. An `assert` subroutine. The `assert` subroutine * Error-terminates with a variable stop code when a caller-provided logical assertion fails, * Is callable inside `pure` procedures, and -* Can be eliminated at compile-time, as controlled by the `ASSERTIONS` preprocessor define. +* Can be eliminated by not defining the `ASSERTIONS` preprocessor macro. Assertion enforcement is controlled via the `ASSERTIONS` preprocessor macro, which can be defined to non-zero or zero at compilation time to @@ -164,9 +164,7 @@ fpm test --compiler nagfor --flag -fpp Documentation ------------- -See [Assert's GitHub Pages site] for HTML documentation generated with [`ford`]. - -For further documentation, please see [example/README.md] and the [tests]. Also, the code in [src] has comments formatted for generating HTML documentation using [FORD]. +Please see [example/README.md] and the [tests] for examples of how to use Assert. ### Potential pitfalls of `call_assert` macros: @@ -178,7 +176,7 @@ of aggressively asserting invariants throughout their code, without needing to balance any potential performance cost associated with such assertions when the code runs in production. -Unfortunately, C-preprocessor macros do not integrate cleanly with some aspects +Unfortunately, preprocessor macros do not integrate cleanly with some aspects of the Fortran language. As such, you might encounter one or more of the following pitfalls when using these macros. @@ -212,7 +210,7 @@ In the case of gfortran, this appears to have been resolved by default starting #### Line breaks in macro invocations The preprocessor is not currently specified by any Fortran standard, and -as of 2024 its operation differs in subtle ways between compilers. +as of 2025 its operation differs in subtle ways between compilers. One way in which compilers differ is how macro invocations can safely be broken across multiple lines. @@ -286,9 +284,6 @@ See the [LICENSE](LICENSE) file for copyright and licensing information. [example/README.md]: ./example/README.md [tests]: ./tests [src]: ./src -[FORD]: https://github.com/Fortran-FOSS-Programmers/ford [Fortran Package Manager]: https://github.com/fortran-lang/fpm [OCL]: https://en.wikipedia.org/wiki/Object_Constraint_Language -[Assert's GitHub Pages site]: https://berkeleylab.github.io/assert/ -[`ford`]: https://github.com/Fortran-FOSS-Programmers/ford [example/invoke-via-macro.F90]: ./example/invoke-via-macro.F90 From 3c78cda93b7ddea156877d547cd5c3096a725126 Mon Sep 17 00:00:00 2001 From: Damian Rouson Date: Thu, 17 Jul 2025 17:01:49 -0700 Subject: [PATCH 2/4] doc(example/README): describe invoke-via-macro --- example/README.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/example/README.md b/example/README.md index 8891d9a..c4c9508 100644 --- a/example/README.md +++ b/example/README.md @@ -1,7 +1,24 @@ Examples ======== -This directory contains two example programs. +This directory contains several example programs. + +Example of recommended use +-------------------------- +The [invoke-via-macro.F90] example demonstrates the recommended ways +to write assertions in code. These leverage the function-like macros +`call_assert` and `call_assert_describe`. The primary advantage of +using these macros is that they are completely eliminated when a file +is compiled with the `ASSERTIONS` macro undefined or defined as `0`. +To run this example with assertions off, use the command +``` +fpm run --example invoke-via-macro +``` +To run the example with assertions on, use either of the following +commands: +``` +fpm run --example invoke-via-macro --flag "-DASSERTIONS" +``` Simple examples --------------- @@ -39,6 +56,7 @@ or more images providing stop codes analogous to those quoted in the [Single-ima [Enforcing programming contracts]: #enforcing-programming-contracts [Single-image execution]: #single-image-execution [simple_assertions.f90]: ./simple_assertions.f90 +[invoke-via-macro.F90]: ./invoke-via-macro.F90 [UML]: https://en.wikipedia.org/wiki/Unified_Modeling_Language [OCL]: https://en.wikipedia.org/wiki/Object_Constraint_Language [Atom]: https://atom.io From d479fbea7e7b834200aace2ef4694bfdddda9410 Mon Sep 17 00:00:00 2001 From: Damian Rouson Date: Thu, 17 Jul 2025 17:05:07 -0700 Subject: [PATCH 3/4] fix(README.md): edit sublist --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index c15cd5a..bb41859 100644 --- a/README.md +++ b/README.md @@ -12,10 +12,10 @@ Overview -------- This assertion utility contains four public entities: -1. An `assert_macros.h` file defining the recommended preprocessor macros for writing assertion: - a. `call_assert(assertion)`, - b. `call_assert_describe(assertion, description)`, and -2. An `assert` subroutine. +* An `assert_macros.h` file defining the recommended preprocessor macros for writing assertion: + - `call_assert(assertion)` + - `call_assert_describe(assertion, description)` +* An `assert` subroutine The `assert` subroutine * Error-terminates with a variable stop code when a caller-provided logical assertion fails, From b6f4e1fd55d4ad3ebf0ab70ec61e50abc2c1a30a Mon Sep 17 00:00:00 2001 From: Dan Bonachea Date: Thu, 17 Jul 2025 20:13:23 -0400 Subject: [PATCH 4/4] README.md: fix a typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bb41859..0ee77c7 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Overview -------- This assertion utility contains four public entities: -* An `assert_macros.h` file defining the recommended preprocessor macros for writing assertion: +* An `assert_macros.h` file defining the recommended preprocessor macros for writing assertions: - `call_assert(assertion)` - `call_assert_describe(assertion, description)` * An `assert` subroutine