Add hello-wuffs-c example

Fixes #9
This commit is contained in:
Nigel Tao committed 2019-12-19 21:46:05 +11:00
1 parent aaa30fc5a6
commit 5256cb67d9
7 files changed
+360

No files matched your search

+1
View File
@@ -2,5 +2,6 @@
*.out
*~
/gen
/hello-wuffs-c/parse.c
Cargo.lock
target
+6
View File
@@ -85,3 +85,9 @@ not compile if overflow is possible. Some of these operators have alternative
definition, these never overflow.
The `as` operator, e.g. `x as T`, converts an expression `x` to the type `T`.
## Introductory Example
A simple Wuffs the Language program, unrelated to Wuffs the Library, is
discussed in [/hello-wuffs-c](/hello-wuffs-c).
+161
View File
@@ -0,0 +1,161 @@
# Hello `wuffs-c`
This directory contains a simple example of a C program using a Wuffs library.
It uses the `wuffs-c` command line tool, which transpiles from Wuffs code to
generate C code.
Traditionally, the first program anyone writes in a given programming language
is something that prints "Hello world". This doesn't work for Wuffs, for two
reasons. One is that Wuffs doesn't have a string type per se. Two is that Wuffs
code doesn't even have the capability to write to files directly, such as to
`stdout`. Wuffs is a language for writing libraries, not complete programs, and
the less Wuffs can do, the less Wuffs can do that is surprising (such as upload
your files to the internet), even when processing untrusted input.
Instead, we're going to run some Wuffs code that parses a string (like `"123"`)
and returns an integer (like `123`). It'll be similar to the C `atoi` function,
although our function will return unsigned instead of signed, as it's a simpler
problem. Our function will also take a pointer-length pair, not just a C style
pointer. Anyway, here's what the output should look like:
```
$ ./run.sh
0
12
56789
4294967295
0
3197704724
--------
0
12
56789
4294967295
parse: demo: too large
0
parse: demo: too large
0
```
The [`run.sh`](/hello-wuffs-c/run.sh) script compiles and runs the
[`main.c`](/hello-wuffs-c/main.c) program twice, without and with Wuffs. On
each run, it parses 6 inputs. The first 4 are within the `uint32_t` range and
the last 2 are not. Here's an excerpt of `main.c`:
```
int main(int argc, char* argv) {
run("0");
run("12");
run("56789");
run("4294967295"); // (1<<32) - 1, aka UINT32_MAX.
run("4294967296"); // (1<<32).
run("123456789012");
return 0;
}
```
The first run (without Wuffs) uses a simple C implementation:
```
uint32_t parse(char* p, size_t n) {
uint32_t ret = 0;
for (size_t i = 0; (i < n) && p[i]; i++) {
ret = (10 * ret) + (p[i] - '0');
}
return ret;
}
```
This works for the first 4 inputs, but silently overflows for the last 2. A
subtle point is that, by default, the C compiler accepted this code without any
indication that integer overflow could occur, yet integer overflow can lead to
[serious bugs](https://en.wikipedia.org/wiki/Stagefright_%28bug%29).
Some C compilers, and some compilers for other languages, can optionally insert
run-time checks for integer overflow, but these are typically disabled by
default because of the performance impact. Having these checks enabled for
developer builds are better than nothing, but it still isn't a complete
solution. We don't ship developer builds to our users, and while computer
programmers are better than the average person at e.g. spotting phising
attempts, that also means that they can be less likely than the average person
to 'test' their developer builds on the malicious input that users encounter.
Anyway, in Wuffs, integer overflow is a mandatory concern. Addressing that
concern takes a little more code, this time in Wuffs:
```
pub func parser.parse?(src: base.io_reader) {
var c : base.u8
while true {
c = args.src.read_u8?()
if c == 0 {
return ok
}
if (c < 0x30) or (0x39 < c) { // '0' and '9' are ASCII 0x30 and 0x39.
return "#not a digit"
}
// Rebase from ASCII (0x30 ..= 0x39) to the value (0 ..= 9).
c -= 0x30
if this.val < 429496729 {
this.val = (10 * this.val) + (c as base.u32)
continue
} else if (this.val > 429496729) or (c > 5) {
return "#too large"
}
// Uncomment this assertion to see what facts are known here.
// assert false
this.val = (10 * this.val) + (c as base.u32)
}
}
```
Obviously, we could have written the same careful algorithm in C. The point is
that, unlike C, Wuffs doesn't let you forget to consider integer (or buffer)
overflows. This can certainly be annoying in general, but reassuring whenever
the code has to run in security-concious contexts.
Play with the [parse.wuffs](/hello-wuffs-c/parse.wuffs) code and see what sort
of compiler errors you get:
```diff
diff --git a/hello-wuffs-c/parse.wuffs b/hello-wuffs-c/parse.wuffs
index cb207eec..c38dcf88 100644
--- a/hello-wuffs-c/parse.wuffs
+++ b/hello-wuffs-c/parse.wuffs
@@ -35,7 +35,7 @@ pub func parser.parse?(src: base.io_reader) {
if this.val < 429496729 {
this.val = (10 * this.val) + (c as base.u32)
continue
- } else if (this.val > 429496729) or (c > 5) {
+ } else if (this.val > 429496729) {
return "#too large"
}
// Uncomment this assertion to see what facts are known here.
```
```
$ ./run.sh
check: expression "(10 * this.val) + (c as base.u32)" bounds [4294967290 ..= 4294967299] is not within bounds [0 ..= 4294967295] at stdin:43. Facts:
c <> -48
c >= 0
c <= 9
this.val >= 429496729
this.val <= 429496729
```
Note that the `parser.parse` method is a [coroutine](/doc/note/coroutines.md)
and therefore doesn't return the value directly. Instead, the pattern is that
the `parse` method updates the state and the `value` method returns the state.
For more realistic problem domains, the output often isn't just a single
`uint32_t`, and the pattern for e.g. image decoding in Wuffs is that the
`decode` method takes the destination buffer as an additional argument.
That's the end of this "Hello world"-ish introduction. After that, you can read
more documentation about both [Wuffs the Language](/doc/wuffs-the-language.md)
and [Wuffs the Library](/doc/wuffs-the-library.md).
Finally, there are admittedly a couple of TODOs in this directory, concerning
some rough edges in what should be a simple example. Version 0.2 (December
2019) has prioritized users of Wuffs the Library over users of Wuffs the
Language. A future version should fix that imbalance.
+91
View File
@@ -0,0 +1,91 @@
// Copyright 2019 The Wuffs Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------
#include <inttypes.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#ifndef USE_WUFFS
uint32_t parse(char* p, size_t n) {
uint32_t ret = 0;
for (size_t i = 0; (i < n) && p[i]; i++) {
ret = (10 * ret) + (p[i] - '0');
}
return ret;
}
#else // #ifndef USE_WUFFS
// TODO: this 'rough edge' shouldn't be necessary. See
// https://github.com/google/wuffs/issues/24
#define WUFFS_CONFIG__MODULE__BASE
#define WUFFS_IMPLEMENTATION
#include "./parse.c"
uint32_t parse(char* p, size_t n) {
wuffs_base__status status;
wuffs_demo__parser* parser =
(wuffs_demo__parser*)(malloc(sizeof__wuffs_demo__parser()));
if (!parser) {
printf("malloc failed\n");
return 0;
}
status = wuffs_demo__parser__initialize(parser, sizeof__wuffs_demo__parser(),
WUFFS_VERSION, 0);
if (!wuffs_base__status__is_ok(status)) {
printf("initialize: %s\n", wuffs_base__status__message(status));
free(parser);
return 0;
}
wuffs_base__io_buffer iobuf;
iobuf.data.ptr = (uint8_t*)p;
iobuf.data.len = n;
iobuf.meta.wi = n;
iobuf.meta.ri = 0;
iobuf.meta.pos = 0;
iobuf.meta.closed = true;
status = wuffs_demo__parser__parse(parser, &iobuf);
if (!wuffs_base__status__is_ok(status)) {
printf("parse: %s\n", wuffs_base__status__message(status));
free(parser);
return 0;
}
uint32_t ret = wuffs_demo__parser__value(parser);
free(parser);
return ret;
}
#endif // #ifndef USE_WUFFS
void run(char* p) {
size_t n = strlen(p) + 1; // +1 for the trailing NUL that ends a C string.
uint32_t i = parse(p, n);
printf("%" PRIu32 "\n", i);
}
int main(int argc, char** argv) {
run("0");
run("12");
run("56789");
run("4294967295"); // (1<<32) - 1, aka UINT32_MAX.
run("4294967296"); // (1<<32).
run("123456789012");
return 0;
}
+49
View File
@@ -0,0 +1,49 @@
// Copyright 2019 The Wuffs Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
pri status "#not a digit"
pri status "#too large"
pub struct parser?(
val : base.u32,
)
pub func parser.parse?(src: base.io_reader) {
var c : base.u8
while true {
c = args.src.read_u8?()
if c == 0 {
return ok
}
if (c < 0x30) or (0x39 < c) { // '0' and '9' are ASCII 0x30 and 0x39.
return "#not a digit"
}
// Rebase from ASCII (0x30 ..= 0x39) to the value (0 ..= 9).
c -= 0x30
if this.val < 429496729 {
this.val = (10 * this.val) + (c as base.u32)
continue
} else if (this.val > 429496729) or (c > 5) {
return "#too large"
}
// Uncomment this assertion to see what facts are known here.
// assert false
this.val = (10 * this.val) + (c as base.u32)
}
}
pub func parser.value() base.u32 {
return this.val
}
+33
View File
@@ -0,0 +1,33 @@
#!/bin/bash -eu
# Copyright 2019 The Wuffs Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ----------------
CC=${CC:-gcc}
# You may need to run
# go get github.com/google/wuffs/cmd/wuffs-c
# beforehand, to install the wuffs-c compiler.
wuffs-c gen -package_name demo < parse.wuffs > parse.c
$CC main.c
./a.out
echo --------
$CC main.c -DUSE_WUFFS
./a.out
rm a.out parse.c
+19
View File
@@ -0,0 +1,19 @@
// Copyright 2019 The Wuffs Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------
// TODO: this 'rough edge' shouldn't be necessary. See
// https://github.com/google/wuffs/issues/24
#include "../release/c/wuffs-unsupported-snapshot.c"