Add more hello-wuffs-c commentary
diff --git a/hello-wuffs-c/README.md b/hello-wuffs-c/README.md
index d07bfd3..8e85351 100644
--- a/hello-wuffs-c/README.md
+++ b/hello-wuffs-c/README.md
@@ -20,7 +20,7 @@
```
$ ./run.sh
---- C Implementation prints ---
+--- C Implementation Prints ---
0
12
56789
diff --git a/hello-wuffs-c/main.c b/hello-wuffs-c/main.c
index afa0b51..d4ef430 100644
--- a/hello-wuffs-c/main.c
+++ b/hello-wuffs-c/main.c
@@ -12,14 +12,12 @@
// See the License for the specific language governing permissions and
// limitations under the License.
-// ----------------
-
#include <inttypes.h>
#include <stdio.h>
#include <string.h>
-// See naive-parse.c and wuffs-parse.c for implementations of this function
-uint32_t parse(char *, size_t);
+// See naive-parse.c and wuffs-parse.c for implementations of this function.
+uint32_t parse(char*, size_t);
void run(char* p) {
size_t n = strlen(p) + 1; // +1 for the trailing NUL that ends a C string.
diff --git a/hello-wuffs-c/naive-parse.c b/hello-wuffs-c/naive-parse.c
index a184739..d2b205c 100644
--- a/hello-wuffs-c/naive-parse.c
+++ b/hello-wuffs-c/naive-parse.c
@@ -1,5 +1,19 @@
-#include <stdlib.h>
+// 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 <stdlib.h>
uint32_t parse(char* p, size_t n) {
uint32_t ret = 0;
diff --git a/hello-wuffs-c/run.sh b/hello-wuffs-c/run.sh
index a2eb53c..86de702 100755
--- a/hello-wuffs-c/run.sh
+++ b/hello-wuffs-c/run.sh
@@ -22,10 +22,10 @@
# beforehand, to install the wuffs-c compiler.
wuffs-c gen -package_name demo < parse.wuffs > parse.c
-echo --- C Implementation prints ---
-$CC main.c naive-parse.c
-./a.out
+echo --- C Implementation Prints ---
+$CC main.c naive-parse.c -o n.out
+./n.out
echo ------ Wuffs Impl Prints ------
-$CC main.c wuffs-parse.c
-./a.out
+$CC main.c wuffs-parse.c -o w.out
+./w.out
diff --git a/hello-wuffs-c/wuffs-parse.c b/hello-wuffs-c/wuffs-parse.c
index d66cac2..b19e588 100644
--- a/hello-wuffs-c/wuffs-parse.c
+++ b/hello-wuffs-c/wuffs-parse.c
@@ -1,3 +1,17 @@
+// 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 <stdio.h>
// TODO: this 'rough edge' shouldn't be necessary. See
@@ -9,33 +23,65 @@
uint32_t parse(char* p, size_t n) {
wuffs_base__status status;
- // If you want this on the heap instead, use
- // wuffs_demo__parser *parser = wuffs_demo__parser__alloc();
- // and don't run __initialize();
+
+ // This next line of code allocates a wuffs_demo__parser on the stack. Stack
+ // allocation in C means uninitialized memory, so we need to call
+ // wuffs_demo__parser__initialize afterwards.
+ //
+ // An alternative, allocating on the heap and initializing in a single
+ // function call, is to say:
+ //
+ // wuffs_demo__parser* parser = wuffs_demo__parser__alloc();
+ // if (!parser) {
+ // // Out of memory.
+ // return 0;
+ // }
+ // // No need to call wuffs_demo__parser__initialize, but don't forget to
+ // // free(parser) before this function returns, taking extra care if this
+ // // function has multiple return points. Wuffs has no destructor functions
+ // // and Wuffs types never hold or own any resources in the RAII sense.
+ // // Just free the memory.
+ //
+ // For stack allocation, the C compiler needs to know
+ // sizeof(wuffs_demo__parser), but that compile-time value isn't guaranteed
+ // to be stable across Wuffs versions. Stack allocation is therefore only
+ // valid when the C file also #define's WUFFS_IMPLEMENTATION. When linking
+ // against a separately built Wuffs library (and the Wuffs types in this
+ // compilation are incomplete types), you'll have to use heap allocation.
wuffs_demo__parser parser;
+
+ // Initialize (and check status). An error here means that bad arguments were
+ // passed to wuffs_demo__parser__initialize.
+ //
+ // There are two other categories of not-OK status values, notes and
+ // suspensions, but they won't be encountered in this example.
status = wuffs_demo__parser__initialize(&parser, sizeof__wuffs_demo__parser(),
WUFFS_VERSION, 0);
- // This happens when bad arguments are passed to __initialize()
if (!wuffs_base__status__is_ok(&status)) {
printf("initialize: %s\n", wuffs_base__status__message(&status));
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;
+ // True means that the wuffs_base__io_buffer is closed - we are at the end of
+ // the input. False would mean that there might be additional data in the
+ // byte stream (that this buffer is not large enough to hold all at once).
+ //
+ // In general, Wuffs' coroutine and suspension status mechanisms let it parse
+ // arbitrarily large data streams using fixed sized buffers, but that won't
+ // be encountered in this example.
+ wuffs_base__io_buffer iobuf =
+ wuffs_base__ptr_u8__reader((uint8_t*)p, n, true);
- // This happens when wuffs code returns "# Some status"
+ // Parse (and check status). An error here means that we had invalid input
+ // (i.e. "#not a digit" or "#too large").
+ //
+ // There are two other categories of not-OK status values, notes and
+ // suspensions, but they won't be encountered in this example.
status = wuffs_demo__parser__parse(&parser, &iobuf);
if (!wuffs_base__status__is_ok(&status)) {
printf("parse: %s\n", wuffs_base__status__message(&status));
return 0;
}
- uint32_t ret = wuffs_demo__parser__value(&parser);
- return ret;
+ return wuffs_demo__parser__value(&parser);
}
