package notty

A selection of extra keys on the keyboard.

Mouse buttons.

Modifier state.

Keypress event.

Mouse event.

Paste event.

Things that terminals say to applications.

• `Key (k, mods) is keyboard input.

  k is a key, one of:

  • `ASCII c where c is a char in the ASCII range;
  • `Uchar u where u is any other unicode character; or
  • a special key.

  `ASCII and `Uchar together represent the textual part of the input. These characters are guaranteed not to be control characters, and are safe to use when constructing images. ASCII is separated from the rest of Unicode for convenient pattern-matching.

  mods are the extra modifier keys.

• `Mouse (event, (x, y), mods) is mouse input.

  event is the actual mouse event: button press, release, or motion of the mouse with buttons depressed.

  (x, y) are column and row position of the mouse. The origin is (0,0), the upper-left corner.

  Note Every `Press (`Left|`Middle|`Right) generates a corresponding `Release, but there is no portable way to detect which button was released. `Scroll (`Up|`Down) presses are not followed by releases.

• `Paste (`Start|`End) are bracketed paste events, signalling the beginning and end of a sequence of events pasted into the terminal.

  Note This mechanism is useful, but not reliable. The pasted text could contain spurious start-of-paste or end-of-paste markers, or they could be entered by hand.

Terminal input protocols are historical cruft, and heavily overload the ASCII range. For instance:

• It is impossible to distinguish lower- and upper-case ASCII characters if Ctrl is pressed;
• several combinations of key-presses are aliased as special keys; and
• in a UTF-8 encoded stream, there is no representation for non-ASCII characters with modifier keys.

This means that many values that inhabit the event type are impossible, while some reflect multiple different user actions. Limitations include:

• `Shift is reported only with special keys, and not all of them.
• `Meta and `Control are reported with mouse events, key events with special keys, and key events with values in the ranges 0x40-0x5f (@ to _) and 0x60-0x7e (` to ~). If Ctrl is pressed, the higher range is mapped into the lower range.
• Terminals will variously under-report modifier key state.

Perform own experiments before relying on elaborate key combinations.

uchar x is the Uchar.t corresponding to x. This operations merges the ASCII and Unicode variants of key.

Input decoding filter.

The filter should be fed strings, which it first decodes from UTF-8, and then extracts the input events.

Malformed UTF-8 input bytes and unrecognized escape sequences are silently discarded.

create () is a new, empty filter.

input t buffer i len feeds len bytes of string into t, starting from position len.

len = 0 signals the end of input.

buffer is immediately processed and can be reused after the call returns.

next t is the next event in the filter's input stream:

• #event, an input event.
• `Await if the filter needs more input.
• `End if the input had ended.

pending t is true if a call to next, without any intervening input, would not return `Await.

decode us are the events encoded by us.

us are assumed to have been generated in a burst, and the end of the list is taken to mean a pause. Therefore, decode us1 @ decode us2 <> decode (us1 @ us2) if us1 ends with a partial escape sequence, including a lone \x1b.

Unsupported escape sequences are silently discarded.