terminal.lua

• Index

Contents

• Functions
• Tables
• Methods

Classes

• Canvas
• EditLine
• Sequence
• canvas.TimeSeriesGraph
• canvas.Viewport
• cli.Confirm
• cli.MultiSelect
• cli.Prompt
• cli.Select
• progress.Bar
• ui.Panel
• ui.panel.Bar
• ui.panel.KeyBar
• ui.panel.Screen
• ui.panel.Set
• ui.panel.TabStrip
• ui.panel.Text

Modules

• spec.helpers
• terminal
• terminal.clear
• terminal.cursor
• terminal.cursor.position
• terminal.cursor.shape
• terminal.cursor.visible
• terminal.draw
• terminal.draw.line
• terminal.input
• terminal.input.keymap
• terminal.output
• terminal.progress
• terminal.scroll
• terminal.text
• terminal.text.color
• terminal.text.width
• terminal.utils

Topics

• 1. Introduction
• 2. Terminal handling
• 3. Text handling
• 4. Canvas (braille pixel graphics)
• CHANGELOG
• CONTRIBUTING
• MIT License

Examples

• async.lua
• canvas.lua
• car_race.lua
• colors.lua
• confirm.lua
• cow.lua
• graph.lua
• headers.lua
• keymap.lua
• multiselect.lua
• panel.lua
• progress.lua
• progressbar.lua
• prompt-copas.lua
• prompt.lua
• screen.lua
• select.lua
• sequence.lua
• tabstrip.lua
• testscreen.lua
• text_panel.lua

Class cli.Confirm

A confirmation widget for CLI tools.

Displays a prompt with a list of labelled responses styled as a cli.Select menu. The user navigates with arrow keys or typing, and confirms with Enter. Optionally the widget can be cancelled with <esc> or <ctrl+c>.

Each response entry is a table { label = string, value = any, cancel = bool? }. When value is omitted it defaults to label. Marking an entry with cancel = true means pressing Escape selects that entry instead of returning nil, "cancelled".

NOTE: you MUST call terminal.initialize before calling this widget's :run() method.

Example using a pre-defined set of responses:

local Confirm = require("terminal.cli.confirm")

local widget = Confirm{
  prompt = "Delete this file?",
  responses = Confirm.sets.yes_no_cancel,
  default = Confirm.ids.no,
}

local result = widget()   -- invokes the 'run' method
if result == Confirm.ids.yes then
  -- proceed
end

Example using a custom set of responses:

local Confirm = require("terminal.cli.confirm")

local widget = Confirm{
  prompt = "Choose an option:",
  responses = {
    { label = "Option 1", value = "opt1" },
    { label = "Option 2", value = "opt2", cancel = true },
  },
  default = "opt2",
}

local result, err = widget:run()

Functions

cli.Confirm (opts)

Create a new Confirm instance.

Tables

cli.confirm.ids	Response ID constants.
cli.confirm.sets	Preset response sets.

Methods

cli.confirm:height ()	Returns the display height in rows.
cli.confirm:print_selection ()	Prints a one-line summary of the prompt and selected response.
cli.confirm:run ()	Executes the widget.

Functions

cli.Confirm (opts)

Create a new Confirm instance.

Parameters:

• opts Options for the Confirm widget.
  • prompt string The question to display.
  • responses table List of response entry tables. Each entry must have a label (string) and may have a value (any; defaults to label) and cancel (bool; marks the entry selected when Escape is pressed). Defaults to Confirm.sets.ok. (optional)
  • default any The value of the response to pre-select. Defaults to the value of the first entry. (optional)
  • cancellable boolean Whether the widget can be cancelled by pressing <esc> or <ctrl+c>. Defaults to true when a response has cancel = true, false otherwise. (optional)
  • clear boolean When false (default), replaces the widget with a one-line summary on completion. When true, clears everything. (default false)

Returns:

Confirm A new Confirm instance.

Tables

cli.confirm.ids

Response ID constants. Plain strings used as value fields in the preset sets. Useful for comparing the return value of run() without hardcoding strings.

Fields:

• ok "ok"
• cancel "cancel"
• abort "abort"
• retry "retry"
• ignore "ignore"
• yes "yes"
• no "no"
• try_again "try_again"
• continue "continue"

cli.confirm.sets

Preset response sets. Each is an array, where the values are has tables; {label, value, cancel?}. These are ready to pass as opts.responses, as the most common confirmations.

Fields:

• ok Single OK response.
• ok_cancel OK and Cancel responses.
• abort_retry_ignore Abort (cancel), Retry, and Ignore responses.
• yes_no_cancel Yes, No, and Cancel responses.
• yes_no Yes and No responses.
• retry_cancel Retry and Cancel responses.
• cancel_try_continue Cancel, Try Again, and Continue responses.

Methods

cli.confirm:height ()

Returns the display height in rows.

Returns:

number The height of the widget in rows.

cli.confirm:print_selection ()

Prints a one-line summary of the prompt and selected response.

cli.confirm:run ()

Executes the widget. Initializes the terminal if necessary, and handles cleanup after the widget closes. On completion, replaces the interactive widget with a one-line summary unless clear was set.

Returns:

any The value of the selected response entry (defaults to its label when unset).

Or

1. nil On error.
2. string "cancelled" if cancelled and no response has cancel = true.