Wuffs' important functions - ones that do a significant amount of work, often involving I/O - return a status value. There are four categories:
When a method returns an error, it is permanent. Calling that method (or any other status-returning method), on the same receiver, will return a
"#disabled by previous error" error.
When a method returns a suspension, the suspended coroutine can be resumed by calling that method again. However, calling any other public coroutine method, while already suspended, will lead to an
"#interleaved coroutine calls" error.
Otherwise, the call was complete. ‘Unsuccessful’ (i.e. a note) doesn‘t necessarily mean ‘bad’ or something to avoid, only that something occurred other than the typical outcome. For example, when decoding an animated image, without knowing the number of frames beforehand, a call to “decode the next frame” could return OK, if there was a next frame, or an
"@end of data" note, if there wasn’t.
There is only one value in the OK category. In Wuffs code, this is a built-in literal value called
" quote marks. For example:
The other categories can contain multiple values, each with an ASCII string message. In Wuffs code, a string literal is synonymous with a status value, as Wuffs otherwise doesn't use string-typed values, only byte slices, arrays and buffers:
// Return an error status, defined in this package. return "#bad Huffman code"
That status value may be package-qualified. For example, a coroutine could refer to a status defined in another package,
// Yield a suspension status, defined in the base package. yield? base."$short read"
That string message is human-readable, for programmers, but it is not for end users. It is not localized, and does not contain additional contextual information such as a source filename.
The first byte of the string message gives the category. For example,
"#bad receiver" is an error and
"$short read" is a suspension:
'@'means a note.
'$'means a suspension.
'#'means an error.
In terms of C implementation, a status'
repr (representation) is just its string message: a
const char *, with
ok being the null pointer. That C string is statically allocated and should never be
reprs can be compared by the
== operator and not just by
The C string's contents has the Wuffs package name inserted by the Wuffs compiler, just after that first byte. For example, the
std/deflate package has this line of Wuffs code, defining an error status:
pub status "#bad Huffman code"
When that Wuffs code is compiled to C, it produces:
const char* wuffs_deflate__error__bad_huffman_code = "#deflate: bad Huffman code";
When printing a status message, the
wuffs_base__status__message function will advance a (non null) pointer by 1 byte, skipping that leading