add unstable exit-with-code function (#44)

* add unstable `exit-with-code` function

Whereas the existing `exit` function only accepts a `result` parameter
(i.e. binary success or failure), this function allows the instance to report
any status code from 0 to 255 to the host, with 0 usually meaning "success" and
other values having their own meaning depending on the context.

Fixes #11

Signed-off-by: Joel Dice <joel.dice@fermyon.com>

---------

Signed-off-by: Joel Dice <joel.dice@fermyon.com>
Co-authored-by: Bailey Hayes <behayes2@gmail.com>

.github/workflows/main.yml

@@ -20,4 +20,6 @@ jobs:
  git diff --exit-code
  - uses: WebAssembly/wit-abi-up-to-date@v21
  with:
- worlds: "command imports"
+ wit-bindgen: '0.28.0'
+ worlds: 'command imports'
+ features: 'cli-exit-with-code'

command.md

@@ -73,6 +73,17 @@ directory, interpreting <code>.</code> as shorthand for this.</p>
 <ul>
 <li><a name="exit.status"></a><code>status</code>: result</li>
 </ul>
+<h4><a name="exit_with_code"></a><code>exit-with-code: func</code></h4>
+<p>Exit the current instance and any linked instances, reporting the
+specified status code to the host.</p>
+<p>The meaning of the code depends on the context, with 0 usually meaning
+&quot;success&quot;, and other values indicating various types of failure.</p>
+<p>This function does not return; the effect is analogous to a trap, but
+without the connotation that something bad has happened.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="exit_with_code.status_code"></a><code>status-code</code>: <code>u8</code></li>
+</ul>
 <h2><a name="wasi_io_error_0_2_0"></a>Import interface wasi:io/error@0.2.0</h2>
 <hr />
 <h3>Types</h3>

imports.md

@@ -68,6 +68,17 @@ directory, interpreting <code>.</code> as shorthand for this.</p>
 <ul>
 <li><a name="exit.status"></a><code>status</code>: result</li>
 </ul>
+<h4><a name="exit_with_code"></a><code>exit-with-code: func</code></h4>
+<p>Exit the current instance and any linked instances, reporting the
+specified status code to the host.</p>
+<p>The meaning of the code depends on the context, with 0 usually meaning
+&quot;success&quot;, and other values indicating various types of failure.</p>
+<p>This function does not return; the effect is analogous to a trap, but
+without the connotation that something bad has happened.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="exit_with_code.status_code"></a><code>status-code</code>: <code>u8</code></li>
+</ul>
 <h2><a name="wasi_io_error_0_2_0"></a>Import interface wasi:io/error@0.2.0</h2>
 <hr />
 <h3>Types</h3>

wit/exit.wit

@@ -3,4 +3,15 @@ interface exit {
  /// Exit the current instance and any linked instances.
  @since(version = 0.2.0)
  exit: func(status: result);
+
+ /// Exit the current instance and any linked instances, reporting the
+ /// specified status code to the host.
+ ///
+ /// The meaning of the code depends on the context, with 0 usually meaning
+ /// "success", and other values indicating various types of failure.
+ ///
+ /// This function does not return; the effect is analogous to a trap, but
+ /// without the connotation that something bad has happened.
+ @unstable(feature = cli-exit-with-code)
+ exit-with-code: func(status-code: u8);
 }