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 <[email protected]>

---------

Signed-off-by: Joel Dice <[email protected]>
Co-authored-by: Bailey Hayes <[email protected]>

.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/[email protected]</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/[email protected]</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);
 }