diff --git a/wit-0.3.0-draft/stdio.wit b/wit-0.3.0-draft/stdio.wit index 6a1208f..505eb9a 100644 --- a/wit-0.3.0-draft/stdio.wit +++ b/wit-0.3.0-draft/stdio.wit @@ -1,17 +1,74 @@ @since(version = 0.3.0) interface stdin { - @since(version = 0.3.0) - get-stdin: func() -> stream; + use stdio.{error}; + + /// Reads data from a “standard input”. + /// + /// This function reads at most `amount` bytes from a + /// “standard input” source. + @since(version = 0.3.0) + read: func(amount: u32) -> result, error>; } @since(version = 0.3.0) interface stdout { - @since(version = 0.3.0) - set-stdout: func(data: stream); + use stdio.{error}; + + /// Writes data to a “standard output”. + /// + /// This function writes the bytes of `data` to a “standard output” + /// destination. + /// + /// The data may be either text or binary; if it is text, it is recommended + /// to be encoded as UTF-8, to allow terminal implementations on non-UTF-8 + /// host environments to transcode it into their native text encoding. + @since(version = 0.3.0) + write: func(data: list) -> result<_, error>; } @since(version = 0.3.0) interface stderr { - @since(version = 0.3.0) - set-stderr: func(data: stream); + use stdio.{error}; + + /// Writes data to a “standard error”. + /// + /// This function writes the bytes of `data` to a “standard error” + /// destination. + /// + /// As with `stdout.write`, the data may be tierh text or binary, and + /// if it is text, it is recommended to be encoded as UTF-8. + @since(version = 0.3.0) + write: func(data: list) -> result<_, error>; +} + +/// Types common to the stdio interfaces. +@since(version = 0.3.0) +interface stdio { + /// An error code for stdio functions. + @since(version = 0.3.0) + enum error { + /// An I/O error occurred and the operation not completed successfully. + /// + /// After a `read` or `write` function has returned `io`, it thereafter + /// always returns `io`. + io, + + /// The other end was dropped and so this end must now be dropped. + /// + /// For `read`, this means the end of the stream has been reached. + /// + /// For `write`, this means that the consumer has no need for further + /// data from this stream. This doesn't signify an error; it just + /// instructs the producer to stop sending data. + /// + /// After a `read` or `write` function has returned `dropped`, it + /// thereafter always returns `dropped`. + dropped, + } } + +// FIXME: Provide a way to keep reading after a `dropped`, for the `tail -f` idiom? + +// FIXME: Should write return the number of bytes written? + +// FIXME: How can we avoid the whole situation that caused wasip2 to have `check-write`?