Documentation
πŸ“¦ Libraries
πŸ“‚ interactive

πŸ“‚ interactive

interactive::askForConfirmation

Ask the user to press the button to continue.

  • $1: prompt as string: the prompt to display

Returns:

  • $?:
    • 0 if the user pressed enter
    • 1 otherwise
interactive::askForConfirmation "Press enter to continue."

interactive::askForConfirmationRaw

Ask the user to press the button to continue.

This raw version does not display the prompt or the answer.

Returns:

  • $?:
    • 0 if the user pressed enter
    • 1 otherwise
interactive::askForConfirmationRaw

interactive::clearKeyPressed

This function reads all the inputs from the user, effectively discarding them.

interactive::clearKeyPressed

interactive::createSpace

This function creates some new lines after the current cursor position. Then it moves back to its original position. This effectively creates a space in the terminal (scroll up if we are at the bottom). It does not create more space than the number of lines in the terminal.

  • $1: number of lines as int: the number of lines to create
interactive::createSpace 5

interactive::displayAnswer

Displays an answer to a previous question.

The text is wrapped and put inside a box like so:

    β”Œβ”€β”€β”€β”€β”€β”
    β”‚ No. β”œβ”€β”€β–‘
    β””β”€β”€β”€β”€β”€β”˜
  • $1: answer as string: the answer to display
  • $2: max width as int: (optional) the maximum width of the text in the dialog box (defaults to GLOBAL_COLUMNS)
interactive::displayAnswer "My answer."

interactive::displayDialogBox

Displays a dialog box with a speaker and a text.

  • $1: speaker as string: the speaker (system or user)
  • $2: text as string: the text to display
  • $3: max width as int: (optional) the maximum width of the text in the dialog box (defaults to GLOBAL_COLUMNS)
interactive::displayDialogBox "system" "This is a system message."

interactive::displayQuestion

Displays a question to the user.

The text is wrapped and put inside a box like so:

   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
░─── Is this an important question? β”‚
   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  • $1: prompt as string: the prompt to display
  • $2: max width as int: (optional) the maximum width of text in the dialog box (defaults to GLOBAL_COLUMNS)
interactive::displayPrompt "Do you want to continue?"

interactive::getCursorPosition

Get the current cursor position.

Returns:

  • CURSOR_LINE: the line number
  • CURSOR_COLUMN: the column number
interactive::getCursorPosition

interactive::promptYesNo

Ask the user to yes or no.

  • The user can switch between the two options with the arrow keys or space.

  • The user can validate the choice with the enter key.

  • The user can also validate immediately with the y or n key.

  • $1: prompt as string: the prompt to display

  • $2: default as bool: (optional) the default value to select (defaults to true)

Returns:

  • $?:
    • 0 if the user answered yes
    • 1 otherwise
  • RETURNED_VALUE: true or false.
if interactive::promptYesNo "Do you want to continue?"; then echo "Yes."; else echo "No."; fi

interactive::promptYesNoRaw

Ask the user to yes or no.

  • The user can switch between the two options with the arrow keys or space.
  • The user can validate the choice with the enter key.
  • The user can also validate immediately with the y or n key.

This raw version does not display the prompt or the answer.

  • $1: default as bool: (optional) the default value to select (defaults to true)

Returns:

  • $?:
    • 0 if the user answered yes
    • 1 otherwise
  • RETURNED_VALUE: true or false.
interactive::promptYesNoRaw "Do you want to continue?" && local answer="${RETURNED_VALUE}"

interactive::rebindKeymap

Rebinds all special keys to call a callback function interactiveOnKeyBindingPress.

This allows to use the -e option with the read command and receive events for special key press.

Key binding is a mess because binding is based on the sequence of characters that gets generated by the terminal when a key is pressed and this is not standard across all terminals. We do our best here to cover most cases but it is by no mean perfect. A good base documentation was https://en.wikipedia.org/wiki/ANSI_escape_code#Terminal_input_sequences.

Users of this function can completely change the bindings afterward by implementing the interactiveRebindOverride function.

This function should be called before using interactive::waitForKeyPress.

interactive::rebindKeymap

We do not bother to have a restore function because valet should not be sourced and thus, modifications to the keymap are local to this script. showkey -a is a good program to see the sequence of characters sent by the terminal.

interactive::startProgress

Shows a spinner / progress animation with configurable output including a progress bar.

The animation will be displayed until interactive::stopProgress is called or if the max number of frames is reached.

Outputs to stderr. This will run in the background and will not block the main thread. The main thread can continue to output logs while this animation is running.

  • $1: output template as string: (optional) the template to display (defaults to VALET_CONFIG_PROGRESS_BAR_TEMPLATE="#spinner #percent β–‘#barβ–‘ #message")
  • $2: max width as int: (optional) the maximum width of the progress bar (defaults to VALET_CONFIG_PROGRESS_BAR_SIZE=20)
  • $3: frame delay as float: (optional) the time in seconds between each frame of the spinner (defaults to VALET_CONFIG_PROGRESS_ANIMATION_DELAY=0.1)
  • $4: refresh every x frames as int: (optional) the number of frames of the spinner to wait before refreshing the progress bar (defaults to VALET_CONFIG_PROGRESS_BAR_UPDATE_INTERVAL=3)
  • $5: max frames as int: (optional) the maximum number of frames to display (defaults to 9223372036854775807)
  • $6: spinner as string: (optional) the spinner to display (each character is a frame) (defaults to VALET_CONFIG_SPINNER_CHARACTERS=“⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏”) Examples: - ◐◓◑◒ - β––β–˜β–β–— - ⣾⣽⣻Ⓙ⑿⣟⣯⣷ - β’„β’‚β’β‘β‘ˆβ‘β‘  - β—‘βŠ™β—  - β–Œβ–€β–β–„ - β „β †β ‡β ‹β ™β Έβ °β  β °β Έβ ™β ‹β ‡β †
interactive::startProgress "#spinner" "" 0.05 "" "" "β’„β’‚β’β‘β‘ˆβ‘β‘ "
wait 4
interactive::stopProgress

interactive::startProgress "#spinner #percent β–‘#barβ–‘ #message" 30 0.05 1
IDX=0
while [[ ${IDX} -le 50 ]]; do
  interactive::updateProgress $((IDX * 2)) "Doing something ${IDX}/50..."
  IDX=$((IDX + 1))
  sleep 0.1
done

interactive::stopProgress

Stop the progress bar.

interactive::stopProgress

interactive::sttyInit

Disable the echo of the tty. Will no longer display the characters typed by the user.

interactive::sttyInit

interactive::sttyRestore

Enable the echo of the tty. Will display the characters typed by the user.

  • $1: force as bool: (optional) force the restoration of the stty configuration stty state will not be restored if (defaults to false)
interactive::sttyRestore

shellcheck disable=SC2120

interactive::switchBackFromFullScreen

Call this function to switch back from the full screen mode.

  • This function will restore the terminal state and show the cursor.
  • It will also restore the key echoing.
  • If there were error messages during the interactive session, they will be displayed at the end.
interactive::switchBackFromFullScreen

interactive::switchToFullScreen

Call this function to start an interactive session in full screen mode. This function will switch to the alternate screen, hide the cursor and clear the screen. It will also disable echoing when we type something.

You should call interactive::switchBackFromFullScreen at the end of the interactive session.

In the alternate screen, we don’t see the error messages so we capture them somewhere else.

interactive::switchToFullScreen

interactive::testWaitForChar

Wait for the user to send a character to stdin (i.e. wait for a key press) and prints the character that bash reads.

Useful to test the interactive::waitForChar function and see the char sequence we get when pressing a key in a given terminal.

See @interactive::waitForChar for more information.

interactive::testWaitForChar

interactive::testWaitForKeyPress

Wait for the user to press a key and prints it to the screen. This function is used to test the interactive::waitForKeyPress function.

See @interactive::waitForKeyPress for more information.

interactive::testWaitForKeyPress

interactive::updateProgress

Update the progress bar with a new percentage and message.

The animation can be started with interactive::startProgress for more options. The animation will stop if the updated percentage is 100.

  • $1: percent as int: the percentage of the progress bar (0 to 100)
  • $2: message as string: (optional) the message to display
interactive::updateProgress 50 "Doing something..."

interactive::waitForChar

Wait for a user input (single char). You can pass additional parameters to the read command (e.g. to wait for a set amount of time).

It uses the read builtin command. This will not detect all key combinations. The output will depend on the terminal used and the character sequences it sends on each key press.

For more advanced use cases, you can use interactive::waitForKeyPress. This simple implementation does not rely on GNU readline and does not require stty to be initialized.

Some special keys are translated into more readable strings: UP, DOWN, RIGHT, LEFT, BACKSPACE, DEL, PAGE_UP, PAGE_DOWN, HOME, END, ESC, F1-F12, ALT+…

  • $@: read parameters as any: additional parameters to pass to the read command

Returns:

  • $?:
    • 0 if a char was retrieved
    • 1 otherwise
  • LAST_KEY_PRESSED: the last char (key) retrieved.
interactive::waitForChar
interactive::waitForChar -t 0.1

https://en.wikipedia.org/wiki/ANSI_escape_code#Terminal_input_sequences

interactive::waitForKeyPress

Wait for a key press (single key). You can pass additional parameters to the read command (e.g. to wait for a set amount of time).

It uses the read builtin command with the option -e to use readline behind the scene. This means we can detect more key combinations but all keys needs to be binded first… Special keys (CTRL+, ALT+, F1-F12, arrows, etc.) are intercepted using binding.

You must call interactive::rebindKeymap and interactive::sttyInit before using this function. You must also redefine the function interactiveOnKeyBindingPress to react to a binded key press. See @interactive::testWaitForKeyPress for an implementation example.

  • $@: read parameters as any: additional parameters to pass to the read command

Returns:

  • $?:
    • 0 if a key was pressed
    • 1 otherwise
  • LAST_KEY_PRESSED: the key pressed.
interactive::waitForKeyPress
interactive::waitForKeyPress -t 0.1

Due to a bug in bash, if the cursor is at the end of the screen, it will make the screen scroll even when nothing is read… Make sure to not position the cursor at the end of the screen.

Documentation generated for the version 0.26.6 (2024-11-24).

πŸ“‚ fsfsπŸ“‚ io