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


read(opts)The main prompt function.
insert_history(history, str)Insert a string into the history table.

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.


  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.


  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.


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


  1. boolean If the history table was changed.