Skip to content

doc(README): rm ford, update intro #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bonachea merged 4 commits into from
Jul 18, 2025
Merged

doc(README): rm ford, update intro #65

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bd81c7f
doc(README): rm ford, update intro
rouson Jul 17, 2025
3c78cda
doc(example/README): describe invoke-via-macro
rouson Jul 18, 2025
d479fbe
fix(README.md): edit sublist
rouson Jul 18, 2025
b6f4e1f
README.md: fix a typo
bonachea Jul 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 8 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
* An `assert_macros.h` file defining the recommended preprocessor macros for writing assertions:
- `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,
* 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
Expand Down Expand Up @@ -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:

Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
20 changes: 19 additions & 1 deletion example/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
---------------
Expand Down Expand Up @@ -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
Expand Down