Module terminal.input

Module for getting keyboard input.

Also enables querying the terminal. When inmplementing any other queries, check out preread and read_query_answer documentation.

Usage:

    local terminal = require "terminal"
terminal.initialize()

local char, typ, sequence = terminal.input.readansi(1)

Functions

preread () Preread stdin buffer into internal buffer.
push_input (seq, typ, part) Pushes input into the buffer.
query (query, answer_pattern) Query the terminal.
read_query_answer (answer_pattern[, count=1]) Reads the answer to a query from the terminal.
readansi (timeout[, fsleep]) Same as sys.readansi, but works with the internal buffer required by terminal.lua.
sys_readansi () The original readansi function from LuaSystem.


Functions

preread ()

Preread stdin buffer into internal buffer. This function will read from stdin and store the input in the internal buffer. This is required because querying the terminal (e.g. getting cursor position) might read data from the keyboard buffer, which would be lost if not buffered. Hence this function should be called before querying the terminal.

Typical query flow;

  1. call preread to empty stdin buffer into internal buffer.
  2. query terminal by writing the required ANSI escape sequences.
  3. call flush to ensure the ANSI sequences are sent to the terminal.
  4. call read_query_answer to read the terminal responses.

Returns:

    true if successful, nil and an error message if reading failed
push_input (seq, typ, part)
Pushes input into the buffer. The input will be appended to the current buffer contents. This means the data being pushed ends up after the current buffer contents, but before the next data read from stdin. The input parameters are the same as those returned by readansi.

Parameters:

  • seq the sequence of input
  • typ the type of input
  • part the partial of the input

Returns:

    true
query (query, answer_pattern)
Query the terminal. This is a wrapper around preread and read_query_answer. It sends a single query and reads the answer in one go. It is a convenience function for simple queries. It is limited to only a single query/answer pair.

Parameters:

  • query string the ANSI sequence to be written to query the terminal
  • answer_pattern string a pattern that matches the expected ANSI response sequence, and captures the data needed.

Returns:

    table an array with the captures from the answer pattern.
read_query_answer (answer_pattern[, count=1])
Reads the answer to a query from the terminal.

Parameters:

  • answer_pattern string a pattern that matches the expected ANSI response sequence, and captures the data needed.
  • count number the number of responses to read (in case multiple queries were sent) (default 1)

Returns:

    table an array with count entries. Each entry is another array with the captures from the answer pattern.
readansi (timeout[, fsleep])
Same as sys.readansi, but works with the internal buffer required by terminal.lua. This function will read from the internal buffer first, before calling sys.readansi. This is required because querying the terminal (e.g. getting cursor position) might read data from the keyboard buffer, which would be lost if not buffered. Hence this function must be used instead of sys.readansi, to ensure the previously read buffer is consumed first.

Parameters:

  • timeout number the timeout in seconds
  • fsleep function the sleep function to use (default: the sleep function set by initialize) (optional)
sys_readansi ()
The original readansi function from LuaSystem.
generated by LDoc 1.5.0