Vtex (Vtex v0.1.0)

Vtex — a streaming VT/ANSI escape-sequence library for Elixir.

Vtex handles terminal I/O in both directions: it turns a raw byte stream (from an SSH/Telnet/TCP transport) into typed tokens and semantic input events, and it builds the control sequences you write back to draw the screen. It is intended for SSH/Telnet game servers, BBS engines and MUD frameworks.

The library is transport-agnostic and does no IO of its own: input functions take bytes you've read, output functions return bytes for you to write.

Input pipeline

raw bytes
  -> Vtex.Input.Stream    # stateful: buffers partial sequences, caps memory
  -> Vtex.Input.Tokenizer # pure: bytes -> tokens
  -> Vtex.Input     # pure: tokens -> semantic events
  -> your game / app logic

stream = Vtex.Input.Stream.new()

{tokens, _stream} = Vtex.Input.Stream.feed(stream, <<0x1B, ?[, ?A, ?h, ?i>>)
#=> {[{:csi, "", "", ?A}, {:text, "hi"}], %Vtex.Input.Stream{}}

Vtex.Input.interpret(tokens)
#=> [:arrow_up, {:char, ?h}, {:char, ?i}]

Output

Vtex.Output.ANSI is a drop-in superset of IO.ANSI (verified byte-for-byte) with 24-bit truecolor on top. Output functions return iodata to write:

transport_write([
  Vtex.Output.Screen.clear(),
  Vtex.Output.ANSI.cursor(1, 1),
  Vtex.Output.ANSI.format([:bright, Vtex.Output.ANSI.true_color(255, 128, 0), "Hello"])
])

Modules

Input: Vtex.Input.Stream, Vtex.Input.Tokenizer, Vtex.Input. Output: Vtex.Output.ANSI (IO.ANSI-compatible colour/style/cursor + truecolor), Vtex.Output.Cursor, Vtex.Output.Screen, Vtex.Output.OSC (title, hyperlinks), Vtex.SGR (encode/1). Both: Vtex.SGR (parse + encode), and the mode toggles Vtex.Mouse, Vtex.Paste, Vtex.Focus (whose events also feed Vtex.Input).