Skip to content

Commit b5022c2

Browse files
rousonrouson
committed
doc(README.md): update/expand tables & discussion
1 parent 2b22aeb commit b5022c2

2 files changed

Lines changed: 56 additions & 23 deletions

File tree

‎README.md‎

Lines changed: 46 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,41 @@ conditions in a common way when writing tests that wrap the tested procedures
1010
or assertions that conditionally execute inside procedures. Julienne's idioms
1111
center around expressions built up from defined operations: a uniquely flexible
1212
Fortran capability that allows developers to define _new_ operators in addition
13-
to overloading the Fortran's intrinsic operators.
13+
to overloading the Fortran's intrinsic operators. The following table provides
14+
some examples of the expressions that can be written in assertions and tests
15+
using Julienne:
16+
17+
Example expressions | Operand types
18+
--------------------------------------------------|--------------------------------------
19+
`x .approximates. y .within. tolerance` | `real`, `double precision`
20+
`x .approximates. y .withinFraction. tolerance` | `real`, `double precision`
21+
`x .approximates. y .withinPercentage. tolerance` | `real`, `double precision`
22+
`.all. ([i,j] .lessThan. k)` | `integer`, `real`, `double precision`
23+
`(i .lessThan. j) .and. (k .equalsExpected. m))` | `integer`, `real`, `double precision`
24+
`x .lessThan. y` | `integer`, `real`, `double precision`
25+
`x .greaterThan. y` | `integer`, `real`, `double precision`
26+
`i .greaterThan. j` | `integer`, `real`, `double precision`
27+
`i .equalsExpected. j` | `integer`
28+
`i .greaterThanOrEqualTo. j` | `integer`
29+
`i .lessThanOrEqualTo. j` | `integer`
30+
31+
The operations and operands have the following properties:
32+
33+
1. The operand type and kind must be uniform throughout the expression.
34+
2. All operations are `elemental`, which implies the operands must be conformable.
35+
Arrays of the same shape are conformable. Scalars are conformable with arrays.
36+
37+
The above expressions produce automated diagnostic messages when an expression
38+
is untrue. Julienne also provides string-handling utilities for user customization
39+
of diagnostic messages. The following table shows some of the string expressions
40+
that Julienne supports:
41+
42+
Example expressions | Result (`character`)
43+
----------------------------------------|---------------------
44+
.csv. [1,2,4] | "1,2,4"
45+
s=string\_t("1,2,4"); s%bracket() | "[1,2,4]"
46+
s=string\_t("1,2,4"); s%bracket("{","}")| "{1,2,4}"
47+
s=string\_t("1,2,4"); s%bracket("|") | "|1,2,4|"
1448

1549
Assertions
1650
----------
@@ -73,7 +107,7 @@ encapsulating the two components enumerated in the [Assertions] section.
73107
Use one of Julienne's expression idioms to construct the function result
74108
automatically:
75109
```fortran
76-
function check_something()
110+
function check_something() result(test_diagnosis)
77111
type(test_diagnosis_t) test_diagnosis
78112
integer, parameter :: i=1, j=1
79113
test_diagnosis = i .equalsExpected. j
@@ -115,22 +149,20 @@ with a partially supported compiler, the Julienne test suite skips some tests
115149
due to compiler bugs. The test output reports which tests are skipped and
116150
thereby details any features Julienne does not supported with a given compiler.
117151

118-
Compiler | Version(s) Tested | Support
119-
-----------------|--------------------------|----------------------
120-
LLVM `flang-new` | 19, 20 | full
121-
NAG `nagfor` | 7.2 Build 7227 | full
122-
GCC `gfortran` | 13.1.0, 14.2.0_1, 15.0.1 | partial (see 1 below)
123-
Intel `ifx` | 2025.4 Build 20241205 | partial (see 2 below)
124-
125-
Compiler bugs related to the following issues have been reported:
152+
Compiler | Version(s) Tested | Known Issues
153+
-----------------|--------------------------|-------------
154+
LLVM `flang-new` | 19, 20 | none
155+
NAG `nagfor` | 7.2 Build 7227 | none
156+
GCC `gfortran` | 13, 14, 15 | see 1 below
157+
Intel `ifx` | 2025.4 Build 20241205 | see 2 below
126158

127159
1. `gfortran` issues:
128-
- The `test_description_t` constructor's [`diagnosis_function`] actual
129-
argument must be a procedure pointer.
160+
- The `test_description_t` constructor's `diagnosis_function` actual argument
161+
must be a procedure pointer conforming to the `diagnosis_function_i`
162+
abstract interface.
163+
- The `string_t` `bracket` type-bound function crashes for GCC versions < 15.
130164
- Each element of a [`vector_test_description_t`] array (a feature to be
131165
deprecated in a future release) must be defined in a separate statement.
132-
- The `string_t` type's `bracket` type-bound procedure causes a program crash.
133-
- The `string_t` type's `.all.` operator causes a program crash.
134166
2. `ifx` issue:
135167
- Two `string_t` tests fail as described in issue [#51].
136168

‎demo/README.md‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,21 +9,22 @@ Testing the Demonstration Project
99
This demonstration project defines a trivial library named "specimen" in the `src`
1010
subdirectory and a test suite the `test` subdirectory. The test suite includes five tests:
1111

12-
1. Two pass.
13-
2. One intentionally fails to demonstrate diagnostic output.
14-
3. One test is skipped to the reporting and tallying of skipped tests.
12+
1. Two tests pass.
13+
2. One test intentionally fails to demonstrate diagnostic output.
14+
3. One test is skipped to demonstrate the reporting and tallying of skipped tests.
1515
4. One test passes with three compilers but is skipped with GCC due to a compiler bug.
1616

1717
Test Julienne by setting your present working directory to the `demo/` subdirectory in a
1818
terminal window and then building and running the demonstration project's test suite using
1919
the command corresponding to your compiler in the table below.
2020

21-
|Vendor | Version/Build | Example shell command |
22-
|---------|-------------------------|------------------------------------------------------|
23-
|LLVM | 20.1.4 (Homebrew) | `fpm test --compiler flang-new` |
24-
|GCC | 14.2.0_1 (Homebrew) | `fpm test --compiler gfortran --profile release` |
25-
|NAG | 7.2 Build 7227 | `fpm test --compiler nagfor --flag -fpp` |
26-
|Intel | 2025.1.0 Build 20250317 | `fpm test --compiler ifx --flag "-fpp -O3 -coarray"` |
21+
|Vendor | Version/Build | Example shell command |
22+
|---------|-------------------------|------------------------------------------------------------------------------------|
23+
|LLVM | 20.1.4 (Homebrew) | `fpm test --compiler flang-new` |
24+
|GCC | 14.2.0_1 (Homebrew) | `fpm test --compiler gfortran --profile release` |
25+
|GCC | 13.3.0_1 (Homebrew) | `fpm test --compiler gfortran --profile release --flag "-ffree-line-length-0"` |
26+
|NAG | 7.2 Build 7227 | `fpm test --compiler nagfor --flag -fpp` |
27+
|Intel | 2025.1.0 Build 20250317 | `fpm test --compiler ifx --flag "-fpp -O3 -coarray"` |
2728

2829
Setting Up Your Project's Test Suite
2930
------------------------------------

0 commit comments

Comments
 (0)