Skip to content

Commit

Permalink
generate markdown
Browse files Browse the repository at this point in the history
  • Loading branch information
Pat Hickey committed Jan 24, 2024
1 parent bb517a0 commit 174dbd7
Showing 1 changed file with 60 additions and 21 deletions.
81 changes: 60 additions & 21 deletions imports.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,34 @@
<ul>
<li>Imports:
<ul>
<li>interface <a href="#wasi:io_error_0.2.0_rc_2023_11_10"><code>wasi:io/[email protected]-rc-2023-11-10</code></a></li>
<li>interface <a href="#wasi:io_poll_0.2.0_rc_2023_11_10"><code>wasi:io/[email protected]-rc-2023-11-10</code></a></li>
<li>interface <a href="#wasi:io_streams_0.2.0_rc_2023_11_10"><code>wasi:io/[email protected]-rc-2023-11-10</code></a></li>
<li>interface <a href="#wasi:clocks_wall_clock_0.2.0_rc_2023_11_10"><code>wasi:clocks/[email protected]-rc-2023-11-10</code></a></li>
<li>interface <a href="#wasi:filesystem_types_0.2.0_rc_2023_11_10"><code>wasi:filesystem/[email protected]-rc-2023-11-10</code></a></li>
<li>interface <a href="#wasi:filesystem_preopens_0.2.0_rc_2023_11_10"><code>wasi:filesystem/[email protected]-rc-2023-11-10</code></a></li>
<li>interface <a href="#wasi:io_error_0.2.0"><code>wasi:io/[email protected]</code></a></li>
<li>interface <a href="#wasi:io_poll_0.2.0"><code>wasi:io/[email protected]</code></a></li>
<li>interface <a href="#wasi:io_streams_0.2.0"><code>wasi:io/[email protected]</code></a></li>
<li>interface <a href="#wasi:clocks_wall_clock_0.2.0"><code>wasi:clocks/[email protected]</code></a></li>
<li>interface <a href="#wasi:filesystem_types_0.2.0"><code>wasi:filesystem/[email protected]</code></a></li>
<li>interface <a href="#wasi:filesystem_preopens_0.2.0"><code>wasi:filesystem/[email protected]</code></a></li>
</ul>
</li>
</ul>
<h2><a name="wasi:io_error_0.2.0_rc_2023_11_10">Import interface wasi:io/[email protected]-rc-2023-11-10</a></h2>
<h2><a name="wasi:io_error_0.2.0">Import interface wasi:io/[email protected]</a></h2>
<hr />
<h3>Types</h3>
<h4><a name="error"><code>resource error</code></a></h4>
<hr />
<p>A resource which represents some error information.</p>
<p>The only method provided by this resource is <code>to-debug-string</code>,
which provides some human-readable information about the error.</p>
<p>In the <code>wasi:io</code> package, this resource is returned through the
<code>wasi:io/streams/stream-error</code> type.</p>
<p>To provide more specific error information, other interfaces may
provide functions to further &quot;downcast&quot; this error into more specific
error information. For example, <a href="#error"><code>error</code></a>s returned in streams derived
from filesystem types to be described using the filesystem's own
error-code type, using the function
<code>wasi:filesystem/types/filesystem-error-code</code>, which takes a parameter
<code>borrow&lt;error&gt;</code> and returns
<code>option&lt;wasi:filesystem/types/error-code&gt;</code>.</p>
<h2>The set of functions which can &quot;downcast&quot; an <a href="#error"><code>error</code></a> into a more
concrete type is open.</h2>
<h3>Functions</h3>
<h4><a name="method_error.to_debug_string"><code>[method]error.to-debug-string: func</code></a></h4>
<p>Returns a string that is suitable to assist humans in debugging
Expand All @@ -32,13 +46,13 @@ hazard.</p>
<ul>
<li><a name="method_error.to_debug_string.0"></a> <code>string</code></li>
</ul>
<h2><a name="wasi:io_poll_0.2.0_rc_2023_11_10">Import interface wasi:io/[email protected]-rc-2023-11-10</a></h2>
<h2><a name="wasi:io_poll_0.2.0">Import interface wasi:io/[email protected]</a></h2>
<p>A poll API intended to let users wait for I/O events on multiple handles
at once.</p>
<hr />
<h3>Types</h3>
<h4><a name="pollable"><code>resource pollable</code></a></h4>
<hr />
<h2><a href="#pollable"><code>pollable</code></a> represents a single I/O event which may be ready, or not.</h2>
<h3>Functions</h3>
<h4><a name="method_pollable.ready"><code>[method]pollable.ready: func</code></a></h4>
<p>Return the readiness of a pollable. This function never blocks.</p>
Expand Down Expand Up @@ -82,7 +96,7 @@ being reaedy for I/O.</p>
<ul>
<li><a name="poll.0"></a> list&lt;<code>u32</code>&gt;</li>
</ul>
<h2><a name="wasi:io_streams_0.2.0_rc_2023_11_10">Import interface wasi:io/[email protected]-rc-2023-11-10</a></h2>
<h2><a name="wasi:io_streams_0.2.0">Import interface wasi:io/[email protected]</a></h2>
<p>WASI I/O is an I/O abstraction API which is currently focused on providing
stream types.</p>
<p>In the future, the component model is expected to add built-in stream types;
Expand Down Expand Up @@ -112,11 +126,28 @@ future operations.
</li>
</ul>
<h4><a name="input_stream"><code>resource input-stream</code></a></h4>
<p>An input bytestream.</p>
<p><a href="#input_stream"><code>input-stream</code></a>s are <em>non-blocking</em> to the extent practical on underlying
platforms. I/O operations always return promptly; if fewer bytes are
promptly available than requested, they return the number of bytes promptly
available, which could even be zero. To wait for data to be available,
use the <code>subscribe</code> function to obtain a <a href="#pollable"><code>pollable</code></a> which can be polled
for using <code>wasi:io/poll</code>.</p>
<h4><a name="output_stream"><code>resource output-stream</code></a></h4>
<hr />
<p>An output bytestream.</p>
<h2><a href="#output_stream"><code>output-stream</code></a>s are <em>non-blocking</em> to the extent practical on
underlying platforms. Except where specified otherwise, I/O operations also
always return promptly, after the number of bytes that can be written
promptly, which could even be zero. To wait for the stream to be ready to
accept data, the <code>subscribe</code> function to obtain a <a href="#pollable"><code>pollable</code></a> which can be
polled for using <code>wasi:io/poll</code>.</h2>
<h3>Functions</h3>
<h4><a name="method_input_stream.read"><code>[method]input-stream.read: func</code></a></h4>
<p>Perform a non-blocking read from the stream.</p>
<p>When the source of a <code>read</code> is binary data, the bytes from the source
are returned verbatim. When the source of a <code>read</code> is known to the
implementation to be text, bytes containing the UTF-8 encoding of the
text are returned.</p>
<p>This function returns a list of bytes containing the read data,
when successful. The returned list will contain up to <code>len</code> bytes;
it may return fewer than requested, but not more. The list is
Expand Down Expand Up @@ -212,6 +243,11 @@ error.</p>
</ul>
<h4><a name="method_output_stream.write"><code>[method]output-stream.write: func</code></a></h4>
<p>Perform a write. This function never blocks.</p>
<p>When the destination of a <code>write</code> is binary data, the bytes from
<code>contents</code> are written verbatim. When the destination of a <code>write</code> is
known to the implementation to be text, the bytes of <code>contents</code> are
transcoded from UTF-8 into the encoding of the destination and then
written.</p>
<p>Precondition: check-write gave permit of Ok(n) and contents has a
length of less than or equal to n. Otherwise, this function will trap.</p>
<p>returns Err(closed) without writing if the stream has closed since
Expand All @@ -234,7 +270,7 @@ following pseudo-code:</p>
<pre><code class="language-text">let pollable = this.subscribe();
while !contents.is_empty() {
// Wait for the stream to become writable
poll-one(pollable);
pollable.block();
let Ok(n) = this.check-write(); // eliding error handling
let len = min(n, contents.len());
let (chunk, rest) = contents.split_at(len);
Expand All @@ -243,7 +279,7 @@ while !contents.is_empty() {
}
this.flush();
// Wait for completion of `flush`
poll-one(pollable);
pollable.block();
// Check for any errors that arose during `flush`
let _ = this.check-write(); // eliding error handling
</code></pre>
Expand Down Expand Up @@ -303,7 +339,7 @@ all derived <a href="#pollable"><code>pollable</code></a>s created with this fun
</ul>
<h4><a name="method_output_stream.write_zeroes"><code>[method]output-stream.write-zeroes: func</code></a></h4>
<p>Write zeroes to a stream.</p>
<p>this should be used precisely like <code>write</code> with the exact same
<p>This should be used precisely like <code>write</code> with the exact same
preconditions (must use check-write first), but instead of
passing a list of bytes, you simply pass the number of zero-bytes
that should be written.</p>
Expand All @@ -326,15 +362,15 @@ the following pseudo-code:</p>
<pre><code class="language-text">let pollable = this.subscribe();
while num_zeroes != 0 {
// Wait for the stream to become writable
poll-one(pollable);
pollable.block();
let Ok(n) = this.check-write(); // eliding error handling
let len = min(n, num_zeroes);
this.write-zeroes(len); // eliding error handling
num_zeroes -= len;
}
this.flush();
// Wait for completion of `flush`
poll-one(pollable);
pollable.block();
// Check for any errors that arose during `flush`
let _ = this.check-write(); // eliding error handling
</code></pre>
Expand Down Expand Up @@ -385,7 +421,7 @@ is ready for reading, before performing the <code>splice</code>.</p>
<ul>
<li><a name="method_output_stream.blocking_splice.0"></a> result&lt;<code>u64</code>, <a href="#stream_error"><a href="#stream_error"><code>stream-error</code></a></a>&gt;</li>
</ul>
<h2><a name="wasi:clocks_wall_clock_0.2.0_rc_2023_11_10">Import interface wasi:clocks/[email protected]-rc-2023-11-10</a></h2>
<h2><a name="wasi:clocks_wall_clock_0.2.0">Import interface wasi:clocks/[email protected]</a></h2>
<p>WASI Wall Clock is a clock API intended to let users query the current
time. The name &quot;wall&quot; makes an analogy to a &quot;clock on the wall&quot;, which
is not necessarily monotonic as it may be reset.</p>
Expand Down Expand Up @@ -426,7 +462,7 @@ also known as <a href="https://en.wikipedia.org/wiki/Unix_time">Unix Time</a>.</
<ul>
<li><a name="resolution.0"></a> <a href="#datetime"><a href="#datetime"><code>datetime</code></a></a></li>
</ul>
<h2><a name="wasi:filesystem_types_0.2.0_rc_2023_11_10">Import interface wasi:filesystem/[email protected]-rc-2023-11-10</a></h2>
<h2><a name="wasi:filesystem_types_0.2.0">Import interface wasi:filesystem/[email protected]</a></h2>
<p>WASI filesystem is a filesystem API primarily intended to let users run WASI
programs that access their files on their existing filesystems, without
significant overhead.</p>
Expand Down Expand Up @@ -856,8 +892,11 @@ not reuse it thereafter.
</li>
</ul>
<h4><a name="descriptor"><code>resource descriptor</code></a></h4>
<p>A descriptor is a reference to a filesystem object, which may be a file,
directory, named pipe, special file, or other object on which filesystem
calls may be made.</p>
<h4><a name="directory_entry_stream"><code>resource directory-entry-stream</code></a></h4>
<hr />
<h2>A stream of directory entries.</h2>
<h3>Functions</h3>
<h4><a name="method_descriptor.read_via_stream"><code>[method]descriptor.read-via-stream: func</code></a></h4>
<p>Return a stream for reading from a file, if available.</p>
Expand Down Expand Up @@ -1303,7 +1342,7 @@ errors are filesystem-related errors.</p>
<ul>
<li><a name="filesystem_error_code.0"></a> option&lt;<a href="#error_code"><a href="#error_code"><code>error-code</code></a></a>&gt;</li>
</ul>
<h2><a name="wasi:filesystem_preopens_0.2.0_rc_2023_11_10">Import interface wasi:filesystem/[email protected]-rc-2023-11-10</a></h2>
<h2><a name="wasi:filesystem_preopens_0.2.0">Import interface wasi:filesystem/[email protected]</a></h2>
<hr />
<h3>Types</h3>
<h4><a name="descriptor"><code>type descriptor</code></a></h4>
Expand Down

0 comments on commit 174dbd7

Please sign in to comment.