metis.input.readline

An extension of CC's builtin read function (and io.read), and utilities to work with it.

Usage

• Prompt a user for a password. The typed input will be written with *s instead.

  local readline = require "metis.input.readline"
  io.write("Enter password> ")
  local pw = readline.read { replace_char = "*" }
  print("Entered " .. pw)

• A basic REPL with history, which just prints the output.

  local readline = require "metis.input.readline"
  local history = {}
  while true do
    io.write("> ")
    local line = readline.read { history = history }
    if line == nil then break end
    readline.insert_history(history, line)
    print(line)
  end

• Reads a string, completing to a list of foods.

  local readline = require "metis.input.readline"
  local completion = require "cc.completion"
  local choices = { "pizza", "calzone", "pasta" }
  readline.read {
    complete = function(line) return completion.choice(line, choices) end,
  }

• Highlights the word "foo".

  local readline = require "metis.input.readline"
  readline.read {
    highlight = function(line, pos)
      local next, fin = line:find("foo", pos)
      if not next then return #line, colours.white -- No more "foo"s
      elseif next == pos then return fin, colours.yellow -- Highlight this "foo"
      else return next - 1, colours.white -- Highlight until the next "foo"
      end
    end
  }

read(opts)Source

The main prompt function. Instead of accepting multiple arguments, read accepts an options table, with the following fields:

• default: The text that this prompt will start with.
• replace_char: A character that will be written in place of each typed character. This may be used to mask the user's input, such as when writing passwords.
• forever: Whether this prompt will run forever, meaning RET and C-d have no effect. This should be used along with the changed function.
• changed: A function called whenever the input is changed. This may be useful if you want to dynamically update your UI whenever text is written (for instance, if writing a search box).
• history: A list of previous strings entered at this prompt. Items may be added to this list manually, or using insert_history.
• complete: A completion function. This accepts the current input string, and returns a list of suffixes that will be provided as completion candidates. The cc.complete module provides some utilities for working with these.
• complete_fg: The foreground colour that completions will be written with. Defaults to light gray, and can be set to transparent by passing to -1.
• complete_bg: The background colour that completions will be written with. Defaults to transparent.
• highlight: A function to highlight the current input line. This will be given the current input line, and a position to start highlighting from. It must the end position of the token and its colour.

See the example below for more details.

Parameters

1. opts { default? = string, replace_char? = string, forever? = boolean, changed? = function(value: string), history? = { string... }, complete? = function(line: string):{ string... }, complete_fg? = number, complete_bg? = number, highlight = function(line: string, pos: string):number } The options table, as documented above.

Returns

1. string | nil The entered text, or nil if the prompt was closed with C-d.

insert_history(history, str)Source

Insert a string into the history table.

This is recommended over a simple table.insert, as it ensures that duplicate or blank strings are not added.

Parameters

1. history { string... } The history of previous inputs.
2. str string The new input to add.

Returns

1. boolean If the history table was changed.