# `Atui.Key`
[🔗](https://github.com/iboard/atui/blob/v0.3.0/lib/atui/key.ex#L1)

Decodes a raw byte stream from the terminal into key events.

In raw mode the terminal hands us bytes, not keystrokes: arrows arrive as
escape sequences, Ctrl-C as byte 3, and a non-ASCII character as two to four
UTF-8 bytes. `decode/1` turns whatever bytes have arrived so far into keys,
returning any trailing incomplete sequence for the next read.

A lone ESC is indistinguishable from the start of an arrow key until either
more bytes arrive or enough time passes — see `flush/1`.

## Modifiers

A key held with Shift, Alt or Ctrl decodes as `{modifiers, key}`, the
modifiers in a list: `{[:shift], :left}`, `{[:ctrl], "a"}`,
`{[:shift, :ctrl], :up}`. Bare keys stay bare, so `:left` means exactly that.

Terminals report modified arrows as `\e[1;2A` and friends; the rxvt style
(`\e[a`) is not decoded.

# `modifier`

```elixir
@type modifier() :: :shift | :alt | :ctrl
```

# `modifiers`

```elixir
@type modifiers() :: [modifier()]
```

# `t`

```elixir
@type t() ::
  :enter
  | :tab
  | :backspace
  | :esc
  | :up
  | :down
  | :left
  | :right
  | :home
  | :end
  | :delete
  | :page_up
  | :page_down
  | :ctrl_c
  | {:char, String.t()}
  | {modifiers(), t()}
  | {:unknown, binary()}
```

# `decode`

```elixir
@spec decode(binary()) :: {[t()], binary()}
```

Decodes `buffer` into `{keys, rest}`.

`rest` is the tail of an escape or UTF-8 sequence that is not complete yet;
prepend it to the next chunk of bytes.

# `flush`

```elixir
@spec flush(binary()) :: [t()]
```

Decodes a buffer that has stopped growing (an input timeout).

This is where a pending ESC finally becomes the `:esc` key.

---

*Consult [api-reference.md](api-reference.md) for complete listing*