mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-17 16:32:11 +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
|
||||
combine existing facts to create new facts. For example, given numerical-typed
|
||||
expressions `a`, `b` and `c`, the two facts that `a < c` and `c <= b` together
|
||||
imply that `a < b`: less-than-ness is transitive.
|
||||
This file lists Wuffs' [axioms](/doc/note/assertions.md#axioms): a fixed list
|
||||
of built-in, self-evident rules to create new facts by combining existing
|
||||
facts. For example, given numerical-typed expressions `a`, `b` and `c`, the two
|
||||
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
|
||||
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
|
||||
This file is not just documentation. It is [parsed](/lang/check/gen.go) to give
|
||||
the list of axioms built into the Wuffs compiler. Run `go generate` after
|
||||
editing this list.
|
||||
|
||||
|
||||
Reference in new issue
Block a user