mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-17 16:32:11 +01:00
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:
1 parent
6f7e9dfa26
commit
e9fdc38300
19 files changed
+39
-41
No files matched your search
@@ -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
@@ -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
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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
@@ -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
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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,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]`)
|
||||
|
||||
@@ -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).
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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
@@ -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,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
|
||||
|
||||
@@ -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`.
|
||||
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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`
|
||||
|
||||
Reference in new issue
Block a user