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, id = any, cancel = bool? }. When id 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", id = "opt1" },
    { label = "Option 2", id = "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 an id (any; defaults to label) and cancel (bool; marks the entry selected when Escape is pressed). Defaults to Confirm.sets.ok. (optional)
    • default any The id of the response to pre-select. Defaults to the id 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 id 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, id, 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. On completion, replaces the interactive widget with a one-line summary unless clear was set.

Returns:

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

Or

  1. nil On success.
  2. string Error string "cancelled" if cancelled and no response has cancel = true.
generated by LDoc 1.5.0