Fix some typos in the documentation.

And some minor clean-ups. There should be no semantic changes to the
documentation in this patch.
This commit is contained in:
Chris Palmer committed 2020-01-03 17:53:58 -08:00
1 parent 6f7e9dfa26
commit e9fdc38300
19 files changed
+39 -41

No files matched your search

+2 -2
View File
@@ -46,7 +46,7 @@ prove that `y` is not zero.
Wuffs is not a general purpose programming language. **It is for writing
libraries, not programs**. The idea isn't to write your whole program in Wuffs,
only the **parts that are both performance-concious and security-concious**.
only the **parts that are both performance-conscious and security-conscious**.
For example, while technically possible, it is unlikely that a Wuffs compiler
would be worth writing entirely in Wuffs.
@@ -221,4 +221,4 @@ owned by Google.
---
Updated on December 2019.
Updated on December 2020.
+1 -1
View File
@@ -1,6 +1,6 @@
# Background
Decoding untrusted data, such as images downloaded from across the web, have a
Decoding untrusted data, such as images downloaded from across the web, has a
long history of security vulnerabilities. As of 2019, libpng is over 20 years
old, and the [PNG specification is dated 2003](https://www.w3.org/TR/PNG/), but
that well examined C library is still getting [CVE's published in
+4 -4
View File
@@ -71,7 +71,7 @@ libpng for PNG, etc.
If your library change is an optimization, run `wuffs bench` or `wuffs bench
-mimic` both before and after your change to quantify the improvement. The
mimic benchmark numbers should't change if you're only changing `.wuffs` code,
but seeing zero change in those numbers is a sanity check on any unrelated
system variance, such as software updates or virus checkers running in the
background.
mimic benchmark numbers shouldn't change if you're only changing `.wuffs`
code, but seeing zero change in those numbers is a sanity check on any
unrelated system variance, such as software updates or virus checkers running
in the background.
+1 -1
View File
@@ -81,7 +81,7 @@ unambiguous (for the computer), equivalent to exactly one of `(a + b) * c` or,
more conventionally, `a + (b * c)`. While good for brevity, Wuffs does not have
operator precedence: the bare `a + b * c` is an invalid Wuffs expression and
the parentheses must be explicit. The ambiguity (for the human) can be a source
of bugs in other [security-concious file format
of bugs in other [security-conscious file format
parsers](https://github.com/jbangert/nail/issues/7).
Some binary operators (`+`, `*`, `&`, `|`, `^`, `and`, `or`) are also
+1 -1
View File
@@ -10,7 +10,7 @@ Similarly, an expression like `x[i]` is invalid unless there is a compile-time
proof that `i` is in-bounds: that `((0 <= i) and (i < x.length()))`. Proofs can
involve natural bounds (e.g. if `i` has type `base.u8` then `(0 <= i)` is
trivially true since a `base.u8` is unsigned),
[refinements](/doc/glossary.md#refinement-type) (e.g. if `i`has type
[refinements](/doc/glossary.md#refinement-type) (e.g. if `i` has type
`base.u32[..= 100]` then 100 is an inclusive upper bound for `i`),
[facts](/doc/note/facts.md) (e.g. an explicit prior check `if i < x.length()`)
and [interval arithmetic](/doc/note/interval-arithmetic.md) (e.g. for an
+1 -1
View File
@@ -11,7 +11,7 @@ Impure functions are marked with a `!` at their definition and at call sites.
Coroutines are similarly marked, with a `?`. Pure functions have no mark.
For those used to C/C++ syntax, in Wuffs, the unary not operator is spelled
`not` instead of `!`, and Wuffs has no ternary operator like C/C++'s `?`.
`not` instead of `!`, and Wuffs has no ternary operator like C/C++'s `?:`.
Sub-expressions in Wuffs must be pure. Only the outermost function call can
have a `!` or `?` mark. You can't write:
+4 -4
View File
@@ -105,7 +105,7 @@ line of code:
arms (e.g. those that end with a `break`, `continue` or `return` statement)
are not considered during reconciliation.
- The start of a while loop can come from not just its preceding line of code,
but also from any explicit `continue`'s inside that loop, and the implicit
but also from any explicit `continue`s inside that loop, and the implicit
`continue` at the closing `}` curly brace.
- Similarly, the line of code immediately after the entire while loop can come
from an explicit `break` or if the while condition fails.
@@ -138,9 +138,9 @@ while n_bits < n_extra_bits,
The `pre`, `post` and `inv` keywords introduce loop pre-conditions,
post-conditions and invariants (things that are both). The snippet above means
that the Wuffs compiler has to verify all three conditions at every place this
loop exits: at the implicit `break` if the `n_Bits < n_extra_bits` evaluates
false (which in this case trivially proves the third condition), but also at
every explicit `break` for that loop within its body.
loop exits: at the implicit `break` if the expression `n_bits < n_extra_bits`
evaluates to false (which in this case trivially proves the third condition),
but also at every explicit `break` for that loop within its body.
Similarly, it has to verify only the first two conditions at every place this
loop repeats (at its initial execution, at every explicit `continue` and at the
+1 -1
View File
@@ -5,7 +5,7 @@ Outside of the Wuffs base package, every Wuffs struct has an implicit
Wuffs' C language form, the `initialize` function for the `foo` package's `bar`
struct is called `wuffs_foo__bar__initialize`. The function takes four
arguments (or, in C++, the `initialize` method takes three arguments, with the
implicit `this` pointer argument);
implicit `this` pointer argument):
- A pointer to the `wuffs_foo__bar` object: the `this` pointer.
- The size (in bytes) of that object. Conceptually, this is
+4 -5
View File
@@ -48,11 +48,10 @@ etcetera
i = i + 1
```
fails the compile-time bounds / overflow checker, because the assignment's
RHS's (Right Hand Side's) range, `[1 ..= 11]`, is not wholly contained by the
LHS (Left Hand Side) variable's range: `i` has range `[0 ..= 10]`. If `i` had
an unrefined type, such as `base.u32`, then this is essentially an overflow
check.
fails the compile-time bounds/overflow checker, because the assignment's RHS's
(Right Hand Side's) range, `[1 ..= 11]`, is not wholly contained by the LHS
(Left Hand Side) variable's range: `i` has range `[0 ..= 10]`. If `i` had an
unrefined type, such as `base.u32`, then this is essentially an overflow check.
## Masking Array Indexes
+8 -9
View File
@@ -8,7 +8,7 @@ prove that you can't misuse a capability, even when given malicious input.
Instead, the code that calls into Wuffs libraries is responsible for
interfacing with e.g. the file system or the network system. An `io_buffer` is
the mechanism for transferring data into and out of Wuffs libraries. For
example, when decompressing gzip, there are two `io_buffer`'s: the caller fills
example, when decompressing gzip, there are two `io_buffer`s: the caller fills
a source buffer with e.g. the compressed file's contents and the callee (the
Wuffs library) reads compressed bytes from that source buffer and writes
decompressed bytes to a destination buffer.
@@ -35,19 +35,18 @@ Reading from an `io_buffer`, e.g. copying from a buffer to a file, increments
An invariant condition is that `((0 <= ri) and (ri <= wi) and (wi <= len))`.
Having separate read and write indexes simplifies connecting a sequence of
filters or processors with `io_buffer`'s, similar to connecting Unix processes
filters or processors with `io_buffer`s, similar to connecting Unix processes
with pipes. Each filter reads from the previous buffer and writes to the next
buffer. Each buffer is written to by the previous filter and is read from by
the next filter. There's no need to flip a buffer between reading and writing
modes. Nonetheless, `io_buffer`'s are generally not thread-safe.
modes. Nonetheless, `io_buffer`s are generally not thread-safe.
Continuing the "decompressing gzip" example, the application would write to the
source buffer by copying from e.g. `/dev/stdin`. The Wuffs library would read
Continuing the "decompressing gzip" example, the application would write to
the source buffer by copying from e.g. `stdin`. The Wuffs library would read
from the source buffer and write to the destination buffer. The application
would read from the destination buffer by copying to e.g. `stdout`. Buffer
space can be re-used, via compaction (see below), so that neither the source
(`/dev/stdin`) or destination (`/dev/stdout`) data needs to be entirely in
memory at any point.
or destination data needs to be entirely in memory at any point.
For example, an `io_buffer` of length 8 could have 4 bytes available to read
and 1 byte available to write. If 1 byte was written, there would then be 5
@@ -100,9 +99,9 @@ at the time of the call. When considering a function as a 'black box', the two
indexes can only travel forward, and it is up to the application code (not
Wuffs library) code to rewind the indexes (e.g. by compaction).
Even though `ri` can not drop below its initial value, Wuffs code can still
Even though `ri` cannot drop below its initial value, Wuffs code can still
read the contents of the slice before `ri` (in sub-slice notation,
`data[0 .. ri]`) and it should still contain the `(pos + 0)`th, `(pos + 1)`th,
`data[0 .. ri]`) and it should still contain the `(pos + 0)`th, `(pos + 1)`th,
etc. byte of the stream.
The contents of the slice after `wi` (in sub-slice notation, `data[wi .. len]`)
+2 -2
View File
@@ -1,7 +1,7 @@
# Iterate Loops
Iterate loops are syntactic sugar for partitioning a variable sized input slice
into fixed sized chunk slices (with possible smaller-sized remainders).
Iterate loops are syntactic sugar for partitioning a variable-sized input slice
into fixed-sized chunk slices (with possible smaller-sized remainders).
Individual chunks' fixed sizes are typically easier for
[bounds-checking](/doc/note/bounds-checking.md).
+1 -1
View File
@@ -118,6 +118,6 @@ Guide](https://afrantzis.github.io/pixel-format-guide/).
## API Stability
The `wuffs_base__pixel_format` bit packing is documented for explanation and to
assist in debugging (e.g. `printf`'ing the bits in `%x` format). However, do
assist in debugging (e.g. `printf`ing the bits in `%x` format). However, do
not manipulate its bits directly; they are private implementation details. Use
functions such as `wuffs_base__pixel_format__num_planes` instead.
+1 -1
View File
@@ -124,6 +124,6 @@ Cb, Cr) and a `denominator_y` of 1, 1 and 1. The `uint32_t` encoding is
## API Stability
The `wuffs_base__pixel_subsampling` bit packing is documented for explanation
and to assist in debugging (e.g. `printf`'ing the bits in `%x` format).
and to assist in debugging (e.g. `printf`ing the bits in `%x` format).
However, do not manipulate its bits directly; they are private implementation
details. Use functions such as `wuffs_base__pixel_subsampling__bias_x` instead.
+1 -1
View File
@@ -15,7 +15,7 @@ entire image, and different implementations choose a different default color
for the outside pixels: opaque black, transparent black, or something else.
Wuffs, out of the box, makes particular choices (typically mimicking the de
facto canonical implementation), but enabling various quirks result in
facto canonical implementation), but enabling various quirks results in
different choices. In particular, quirks are useful in regression testing that
Wuffs and another implementation produce the same output for the same input,
even for malformed input.
+1 -1
View File
@@ -1,7 +1,7 @@
# Ranges and Rects
Ranges are finite numerical intervals, e.g. "all integers `i` such that `(m <=
i)` and `(i < n)`. The high end bound is sometimes exclusive, `(i < n)`, and
i)` and `(i < n)`". The high end bound is sometimes exclusive, `(i < n)`, and
sometimes inclusive, `(i <= n)`.
In Wuffs syntax, similar to Rust syntax, the exclusive range is `m .. n` and
+2 -2
View File
@@ -17,8 +17,8 @@ copy the elements. It has O(1) algorithmic complexity. Assigning to an
array-typed variable copies the elements. It has O(length) algorithmic
complexity.
Both `s[i .. j]` and `a[i .. j]` refer to slices, ranging from the `i`'th
element (inclusive) to the `j`'th element (exclusive). `i` can be omitted,
Both `s[i .. j]` and `a[i .. j]` refer to slices, ranging from the `i`th
element (inclusive) to the `j`th element (exclusive). `i` can be omitted,
implicitly equalling zero. `j` can be omitted, implicitly equalling the length.
For example, `s[.. 5]` contains the first five elements of `s`.
+1 -1
View File
@@ -69,7 +69,7 @@ receiver"` is an error and `"$short read"` is a suspension:
In terms of C implementation, a status value is just its string message: a
`const char *`, with `ok` being the null pointer. That C string is statically
allocated and should never be `free`'d. Status values can be compared by the
allocated and should never be `free`d. Status values can be compared by the
`==` operator and not just by `strcmp`.
The C string's contents has the Wuffs package name inserted by the Wuffs
+2 -2
View File
@@ -47,7 +47,7 @@ domain-specific programming language.
Extended Static Checker for Java (ESC/Java) and its successor
[OpenJML](http://www.openjml.org/), which obviously target the Java programming
language, similarly has to analyze a language that is more complicated that
language, similarly has to analyze a language that is more complicated than
Wuffs. Java is also not commonly used for writing e.g. low level image codecs,
as the language lacks unsigned integer types, it is garbage collected and
idiomatic code often allocates.
@@ -211,7 +211,7 @@ limited to that part of a file format that is easily expressible as a formal
grammar. In particular, it also handles entropy encodings such as LZW (for
GIF), ZLIB (for PNG) and Huffman (for JPEG, TODO). Wuffs differs from nom
combined with other Rust code (e.g. a Rust LZW implementation) in that bounds
and overflow checks not just ubiquitous but also completely eliminated at
and overflow checks are not just ubiquitous but also completely eliminated at
compile time.
[Kaitai Struct](http://kaitai.io/) is in a similar space, generating safe
+1 -1
View File
@@ -19,7 +19,7 @@ also checked into the repository. Using the standard library's C form would be
like using any other third party C library. It's just not hand-written C.
To do so, you need to download only one file, from the
[`/release/c`](/release/c) directory. Wuffs the Library' C form ships as a
[`/release/c`](/release/c) directory. Wuffs the Library's C form ships as a
[single file C
library](https://github.com/nothings/stb/blob/master/docs/stb_howto.txt),
targeting the C99 standard. That file acts as either a traditional `.c` or `.h`