TermUI.Parser (TermUI v1.0.0)

Escape sequence parser for terminal input.

Transforms raw terminal input bytes into structured events (key presses, mouse actions, paste content, focus changes).

This is a standalone compatibility parser that returns structs under TermUI.Parser.Events. TermUI.Runtime does not call it; runtime Raw and TTY input use TermUI.Terminal.EscapeParser and return TermUI.Event structs.

Summary

Types

event()

state()

Functions

flush_escape(state)

Flushes any pending escape sequence as an ESC key event.

new()

Creates a new parser state.

parse(input, state)

Parses input bytes into events.

reset(state)

Resets parser state while preserving configuration.

Types

event()

@type event() ::
  TermUI.Parser.Events.KeyEvent.t()
  | TermUI.Parser.Events.MouseEvent.t()
  | TermUI.Parser.Events.PasteEvent.t()
  | TermUI.Parser.Events.FocusEvent.t()

state()

@type state() :: %{
  mode: atom(),
  buffer: binary(),
  params: [integer()],
  paste_buffer: binary()
}

Functions

flush_escape(state)

@spec flush_escape(state()) :: {[event()], state()}

Flushes any pending escape sequence as an ESC key event.

Call this after a timeout when parser is in :escape state.

new()

@spec new() :: state()

Creates a new parser state.

parse(input, state)

@spec parse(binary(), state()) :: {[event()], binary(), state()}

Parses input bytes into events.

Returns {events, remaining_bytes, new_state} where:

events - List of parsed events
remaining_bytes - Bytes that couldn't be parsed yet (incomplete sequences)
new_state - Parser state for next call

Examples

iex> {events, "", _state} = TermUI.Parser.parse("a", TermUI.Parser.new())
iex> [%TermUI.Parser.Events.KeyEvent{key: "a"}] = events

reset(state)

@spec reset(state()) :: state()

Resets parser state while preserving configuration.