diff --git a/hello-wuffs-c/README.md b/hello-wuffs-c/README.md index d07bfd3d..8e853515 100644 --- a/hello-wuffs-c/README.md +++ b/hello-wuffs-c/README.md @@ -20,7 +20,7 @@ pointer. Anyway, here's what the output should look like: ``` $ ./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 afa0b51d..d4ef4303 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 #include #include -// 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 a184739c..d2b205ca 100644 --- a/hello-wuffs-c/naive-parse.c +++ b/hello-wuffs-c/naive-parse.c @@ -1,5 +1,19 @@ -#include +// 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 +#include 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 a2eb53c7..86de7024 100755 --- a/hello-wuffs-c/run.sh +++ b/hello-wuffs-c/run.sh @@ -22,10 +22,10 @@ CC=${CC:-gcc} # 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 d66cac25..b19e5889 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 // 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); }