Skip to content

Commit

Permalink
Iterate on wording.
Browse files Browse the repository at this point in the history 
Escape sequences are now "recognized" rather than being "defined for the
appropriate mode", output terminals are now more completely described,
and various sentences are tidied up.
  • Loading branch information
@sunfishcode
sunfishcode committed Feb 10, 2025
1 parent ffe05de commit 37388d6
Showing 1 changed file with 72 additions and 52 deletions.
124 changes: 72 additions & 52 deletions wit-0.3.0-draft/terminal.wit
View file
Original file line number Diff line number Diff line change
@@ -1,40 +1,34 @@
/// Support for terminal input.
///
/// This defines APIs for controlling "termios" attributes affecting input,
/// as well as control codes and "ANSI"-style escape sequences for terminal
/// input streams.
/// as well as control codes and "ANSI"-style escape sequences identifying
/// key-presses and other input events.
///
/// This specification requires implementations to parse the output bytestreams
/// This specification requires implementations to parse the input bytestreams
/// and translate escape sequences and control codes to ensure consistent
/// behavior. Implementations shall not permit arbitrary escape sequences to be
/// communicated between applications and virtual terminals.
///
/// All terminal input and output is encoded in UTF-8. No 8-bit
/// "extended ASCII" control code encodings are recognized. On input to
/// applications, any bytes which are not valid UTF-8 are replaced with the
/// UTF-8 encoding of U+FFFD (REPLACEMENT CHARACTER), following the
/// [UTF-8 decoder] algorithm in the [WHATWG Encoding spec], with an
/// [error mode] of "replacement". On output from applications, any bytes which
/// are not valid UTF-8 evoke a trap, following the [UTF-8 decoder] algorithm
/// in the [WHATWG Encoding spec], with an [error mode] of "fatal".
/// All terminal input streams are encoded in UTF-8. No 8-bit "extended ASCII"
/// control code encodings are recognized. Any bytes which are not valid UTF-8
/// are replaced with the UTF-8 encoding of U+FFFD (REPLACEMENT CHARACTER),
/// following the [UTF-8 decoder] algorithm in the [WHATWG Encoding spec], with
/// an [error mode] of "replacement".
///
/// Any UTF-8 encoding of a Unicode control code other than U+1B (ESC) that is
/// not defined below for terminal input in the active mode shall be replaced
/// by the UTF-8 encoding of U+FFFD (REPLACEMENT CHARACTER).
/// Also, any UTF-8 encoding of a Unicode control code other than U+1B (ESC)
/// that is not recognized shall also be replaced by the UTF-8 encoding of
/// U+FFFD (REPLACEMENT CHARACTER).
///
/// Any sequence beginning with the UTF-8 encoding of U+1B (ESC) and matching
/// the UTF-8 encoding of any of the following regular expressions shall be
/// silently removed from the stream:
/// To reserve space for future escape sequences, any sequence that is not
/// recognized, and that matches the UTF-8 encoding of any of the following
/// regular expressions, shall be silently removed from the stream:
///
/// * `U+1B U+5B [U+20–U+3F]* U+6D`
/// * `[U+1B]+ U+5B U+5B [U+–U+7F]?`
/// * `[U+1B]+ U+5B [U+20–U+3F]* [U+40–U+7E]?`
/// * `[U+1B]+ U+5D [^U+7,U+18,U+1B]* [U+7,U+18]?`
/// * `[U+1B]+ [U+40–U+7E]?`
///
/// This is intended to carve out a space for possible escape sequences so that
/// new sequences may be defined without breaking backwards compatibility.
///
/// In the tables below, "terminfo" refers to the long form of the equivalent
/// terminfo capability, "ti" refers to the short form of the equivalent
/// terminfo capability, and "tc" refers to the equivalent termcap name.
Expand All @@ -50,22 +44,23 @@ interface terminal-input {
/// Implementations must reset terminals to default settings when terminal
/// resources are created and dropped.
///
/// In non-immediate mode, a user Ctrl-M keypress is sent to the
/// Except when in immediate mode, a user Ctrl-M keypress is sent to the
/// application as U+A instead of U+D (`stty icrnl -inlcr`).
///
/// Terminals may also assign other meanings to other control codes and
/// apply other input translations; non-immediate mode is recommended to
/// use line buffering (`stty icanon`), support UTF-8 input
/// (`stty iutf8 -istrip cs8`), support uppercase (`stty -iuclc` if
/// applicable), and support common signal behavior (`stty isig`).
/// apply other input translations; when not in immediate mode,
/// implementations are recommended to use line buffering (`stty icanon`),
/// support UTF-8 input (`stty iutf8 -istrip cs8`), support uppercase
/// (`stty -iuclc` if applicable), and support common signal behavior
/// (`stty isig`).
///
/// By default, terminal input is in echo mode (`stty echo -echonl`) and
/// not in immediate mode (`stty icanon`).
///
/// # Control codes and escape sequences
///
/// The following control codes and escape sequences are defined for
/// terminal input in all modes.
/// The following control codes and escape sequences are recognized in all
/// modes.
///
/// ## Control codes
///
Expand All @@ -77,8 +72,8 @@ interface terminal-input {
/// | U+7F | Backspace; this is the backspace key | key_backspace | kbs | kb |
///
/// Additionally, all other C0 control codes except U+D that are not
/// otherwise defined are defined for terminal input with their ASCII
/// control-key meaning (eg. Ctrl-A).
/// otherwise recognized are recognized with their ASCII control-key
/// meaning (eg. Ctrl-A).
///
/// ## Escape sequences
///
Expand Down Expand Up @@ -137,7 +132,7 @@ interface terminal-input {
/// # Control codes and escape sequences
///
/// In immediate mode, the following additional control codes are
/// defined for input.
/// recognized.
///
/// ## Control codes
///
Expand Down Expand Up @@ -170,13 +165,40 @@ interface terminal-input {
/// Support for terminal output.
///
/// This defines APIs for controlling "termios" attributes affecting output,
/// as well as control codes and "ANSI"-style escape sequences for terminal
/// output streams.
/// as well as control codes and "ANSI"-style escape sequences for controlling
/// the cursor, changing the appearance of text, and other output controls.
///
/// This specification requires implementations to parse the output bytestreams
/// and translate escape sequences and control codes to ensure consistent
/// behavior. Implementations shall not permit arbitrary escape sequences to be
/// communicated between applications and virtual terminals.
///
/// All terminal output streams are encoded in UTF-8. No 8-bit "extended ASCII"
/// control code encodings are recognized. Any bytes which are not valid UTF-8
/// evoke a trap, following the [UTF-8 decoder] algorithm in the
/// [WHATWG Encoding spec], with an [error mode] of "fatal".
///
/// Also, any UTF-8 encoding of a Unicode control code other than U+1B (ESC)
/// that is not recognized shall also evoke a trap.
///
/// To reserve space for future escape sequences, any sequence that is not
/// recognized, and that matches the UTF-8 encoding of any of the following
/// regular expressions, shall be silently removed from the stream:
///
/// * `U+1B U+5B [U+20–U+3F]* U+6D`
/// * `[U+1B]+ U+5B U+5B [U+–U+7F]?`
/// * `[U+1B]+ U+5B [U+20–U+3F]* [U+40–U+7E]?`
/// * `[U+1B]+ U+5D [^U+7,U+18,U+1B]* [U+7,U+18]?`
/// * `[U+1B]+ [U+40–U+7E]?`
///
/// In the tables below, "terminfo" refers to the long form of the equivalent
/// terminfo capability, "ti" refers to the short form of the equivalent
/// terminfo capability, and "tc" refers to the equivalent termcap name.
/// A "\*" indicates that there is no simple equivalent.
///
/// As with `terminal-input`, implementations are required to parse the
/// bytestreams, the bytestreams are encoded in UTF-8, control codes other
/// than U+1B (ESC) are replaced with U+FFFD, and undefined escape sequences
/// are silently removed.
/// [UTF-8 decoder]: https://encoding.spec.whatwg.org/#utf-8-decoder
/// [WHATWG Encoding algorithm]: https://encoding.spec.whatwg.org/
/// [error mode]: https://encoding.spec.whatwg.org/#error-mode
@since(version = 0.3.0)
interface terminal-output {
/// The output side of a terminal.
Expand All @@ -196,8 +218,8 @@ interface terminal-output {
///
/// # Control codes and escape sequences
///
/// The following control codes and escape sequences are defined for
/// terminal output in all modes.
/// The following control codes and escape sequences are recognized in all
/// modes.
///
/// ## Control codes
///
Expand Down Expand Up @@ -233,8 +255,8 @@ interface terminal-output {
/// An empty list also resets all attributes to default settings. This
/// includes reseting the colors to defaults, if colors are supported.
///
/// (Additional attributes for color are defined in the documentation for the `color`
/// function.)
/// (Additional attributes for color are defined in the documentation for
/// the `color` function.)
///
/// By default, terminals are not in full-screen mode or bracketed paste
/// mode, the cursor is visible, and all attributes are set to defaults.
Expand Down Expand Up @@ -266,13 +288,13 @@ interface terminal-output {

/// What kinds of colors are supported, and preferred?
///
/// This returns a set of flags indicating which families of
/// escape sequences for displaying color are supported. The "OSC 4"
/// method of detecting color is not supported.
/// This returns a set of flags indicating which families of escape
/// sequences for displaying color are supported. The "OSC 4" method of
/// detecting color is not supported.
///
/// # Control codes and escape sequences
///
/// The following additional escape sequences are defined in
/// The following additional escape sequences are recognized in
/// implementations which declare `ansi` color support.
///
/// ## Escape sequences
Expand Down Expand Up @@ -309,7 +331,7 @@ interface terminal-output {
///
/// # Control codes and escape sequences
///
/// The following additional escape sequences are defined in
/// The following additional escape sequences are recognized in
/// implementations which declare `truecolor` color support.
///
/// ## Escape sequences
Expand All @@ -327,15 +349,13 @@ interface terminal-output {
/// Does this terminal support line-editing features?
///
/// These include the control codes and escape sequences for moving
/// the cursor around the current line, clearing all or part of the
/// current line, as well as the "alert" code (U+7) which should
/// produce an acoustic or visual notification. This reflects the
/// functionality commonly used for command-line prompts.
/// the cursor around the current line and clearing all or part of the
/// current line.
///
/// # Control codes and escape sequences
///
/// The following additional control codes and escape sequences are
/// defined in implementations which declare line-editing support.
/// recognized in implementations which declare line-editing support.
///
/// ## Control codes
///
Expand Down Expand Up @@ -367,7 +387,7 @@ interface terminal-output {
/// # Control codes and escape sequences
///
/// The following additional control codes and escape sequences are
/// defined in implementations which declare full-screen support.
/// recognized in implementations which declare full-screen support.
///
/// ## Escape sequences
///
Expand All @@ -378,7 +398,7 @@ interface terminal-output {
/// # Control codes and escape sequences
///
/// The following additional control codes and escape sequences are
/// defined when full-screen mode has been entered.
/// recognized when full-screen mode has been entered.
///
/// ## Escape sequences
///
Expand Down

0 comments on commit 37388d6

Please sign in to comment.