mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-22 08:47:28 +01:00
Add doc/note/assertions.md
This commit is contained in:
1 parent
d098582cc6
commit
a5dbb9160f
2 files changed
+90
-12
No files matched your search
@@ -0,0 +1,83 @@
|
|||||||
|
# Assertions
|
||||||
|
|
||||||
|
Assertions are statements that introduce new compile-time
|
||||||
|
[facts](/doc/note/facts.md). They are not comments, as removing them can
|
||||||
|
prevent the code from compiling, but unlike other programming languages, Wuffs'
|
||||||
|
assertions have no run-time effect at all, not even in a "debug, not release"
|
||||||
|
configuration. Compiling an assert will fail unless it can be proven.
|
||||||
|
|
||||||
|
The basic form is `assert some_boolean_expression`, which creates
|
||||||
|
`some_boolean_expression` as a fact. That expression must be free of
|
||||||
|
side-effects: any function calls within must be [pure](/doc/note/effects.md).
|
||||||
|
|
||||||
|
Arithmetic inside assertions is performed in ideal integer math, working in the
|
||||||
|
integer ring ℤ. An expression like `x + y` in an assertion never overflows,
|
||||||
|
even if `x` and `y` have a realized (non-ideal) integer type like `u32`.
|
||||||
|
|
||||||
|
Some assertions can be proven by the compiler with no further guidance. For
|
||||||
|
example, if `x == 1` is already a fact, then `x < 5` can be automatically
|
||||||
|
proved. Adding a seemingly redundant fact can be useful when reconciling
|
||||||
|
multiple arms of an if-else chain, as
|
||||||
|
[reconciliation](/doc/note/facts.md#situations-and-reconciliation) requires the
|
||||||
|
facts in each arm's final situation to match exactly:
|
||||||
|
|
||||||
|
```
|
||||||
|
if x < 5 {
|
||||||
|
// No further action is required. "x < 5" is a fact in the 'if' arm.
|
||||||
|
|
||||||
|
} else {
|
||||||
|
x = 1
|
||||||
|
// At this point, "x == 1" is a fact, but "x < 5" is not.
|
||||||
|
|
||||||
|
// This assertion creates the "x < 5" fact.
|
||||||
|
assert x < 5
|
||||||
|
}
|
||||||
|
|
||||||
|
// Here, "x < 5" is still a fact, since the exact boolean expression "x < 5"
|
||||||
|
// was a fact at the end of every arm of the if-else chain.
|
||||||
|
```
|
||||||
|
|
||||||
|
TODO: specify what can be proved automatically, without naming an axiom.
|
||||||
|
|
||||||
|
|
||||||
|
## Axioms
|
||||||
|
|
||||||
|
Wuffs' assertion system is a proof checker, not an SMT solver or automated
|
||||||
|
theorem prover. It verifies explicit proof targets instead of the more
|
||||||
|
open-ended task of searching for implicit ones. This involves more explicit
|
||||||
|
work by the programmer, but compile times matter, so the Wuffs compiler is fast
|
||||||
|
(and dumb) instead of smart (and slow).
|
||||||
|
|
||||||
|
The Wuffs syntax is regular (and unlike C++, does not require a symbol table to
|
||||||
|
parse), so it should be straightforward to transform Wuffs code to and from
|
||||||
|
file formats used by more sophisticated proof engines. Nonetheless, that is out
|
||||||
|
of scope of this respository and the Wuffs compiler per se.
|
||||||
|
|
||||||
|
Again for compilation speed, not every inference rule is applied after every
|
||||||
|
line of code. Some assertions require explicit guidance, naming the rule that
|
||||||
|
proves the assertion. These names are simply strings that resemble mathematical
|
||||||
|
statements. They are axiomatic, in that these rules are assumed, not proved, by
|
||||||
|
the Wuffs toolchain. They are typically at a higher level than e.g. Peano
|
||||||
|
axioms, as Wuffs emphasizes practicality over theoretical minimalism. As they
|
||||||
|
are axiomatic, they endeavour to only encode 'obvious' mathematical rules.
|
||||||
|
|
||||||
|
For example, the axiom named `"a < b: a < c; c <= b"` is about transitivity:
|
||||||
|
the assertion `a < b` is proved if both `a < c` and `c <= b` are true, for some
|
||||||
|
(pure) expression `c`. Terms like `a`, `b` and `c` here are all integers in ℤ,
|
||||||
|
they do not encompass floating point concepts like negative zero, `NaN`s or
|
||||||
|
rounding. The axiom is invoked by extending an `assert` with the `via` keyword:
|
||||||
|
|
||||||
|
```
|
||||||
|
assert n_bits < 12 via "a < b: a < c; c <= b"(c: width)
|
||||||
|
```
|
||||||
|
|
||||||
|
This proves `n_bits < 12` by applying that transitivity axiom, where `a` is
|
||||||
|
`n_bits`, `b` is `12` and `c` is `width`. Compiling this assertion requires
|
||||||
|
proving both `n_bits < width` and `width <= 12`, from existing facts or from
|
||||||
|
the type system, e.g. `width` is a `base.u32[..= 12]`.
|
||||||
|
|
||||||
|
The trailing `(c: width)` syntax is deliberately similar to a function call
|
||||||
|
(recall that when calling a Wuffs function, each argument must be named), but
|
||||||
|
the `"a < b: a < c; c <= b"` named axiom is not a function-typed expression.
|
||||||
|
|
||||||
|
The [compiler's built-in axioms](/lang/check/axioms.md) are listed separately.
|
||||||
+7
-12
@@ -1,17 +1,12 @@
|
|||||||
# Axioms
|
# Axiom Listing
|
||||||
|
|
||||||
This file lists Wuffs' axioms: a fixed list of built-in, self-evident rules to
|
This file lists Wuffs' [axioms](/doc/note/assertions.md#axioms): a fixed list
|
||||||
combine existing facts to create new facts. For example, given numerical-typed
|
of built-in, self-evident rules to create new facts by combining existing
|
||||||
expressions `a`, `b` and `c`, the two facts that `a < c` and `c <= b` together
|
facts. For example, given numerical-typed expressions `a`, `b` and `c`, the two
|
||||||
imply that `a < b`: less-than-ness is transitive.
|
facts that `a < c` and `c <= b` together imply that `a < b`: less-than-ness is
|
||||||
|
transitive. That rule is named by the string "a < b: a < c; c <= b"`.
|
||||||
|
|
||||||
Wuffs code represents this axiom by the string `"a < b: a < c; c <= b"`, and it
|
This file is not just documentation. It is [parsed](/lang/check/gen.go) to give
|
||||||
is invoked by the `assert` and `via` keywords, naming the rule and [binding the
|
|
||||||
expressions `a`, `b` and
|
|
||||||
`c`](https://github.com/google/wuffs/blob/4080840928c0b05a80cda0d14ac2e2615f679f1a/std/lzw/decode_lzw.wuffs#L99).
|
|
||||||
|
|
||||||
This file is not just documentation. It is
|
|
||||||
[parsed](https://github.com/google/wuffs/blob/master/lang/check/gen.go) to give
|
|
||||||
the list of axioms built into the Wuffs compiler. Run `go generate` after
|
the list of axioms built into the Wuffs compiler. Run `go generate` after
|
||||||
editing this list.
|
editing this list.
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user