Skip to content

Interactive Functions

🛠️ Tools · ⬅ Top

File pipelines

interactiveManager

Run checks interactively until errors are all fixed.

Usage

interactiveManager loopCallable [ --exec binary ] [ --delay delaySeconds ] [ fileToCheck ... ]

Run checks interactively until errors are all fixed. Not ready for prime time yet - written not tested.

Arguments

  • loopCallable - Required. Callable. Call this on each file and a zero result code means passed and non-zero means fails.
  • --exec binary - Optional. Callable. Run binary with files as an argument for any failed files. Only works if you pass in item names.
  • --delay delaySeconds - Optional. Integer. Delay in seconds between checks in interactive mode.
  • fileToCheck ... - Optional. File. Shell file to validate. May also supply file names via stdin.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Interactive utilities

loopExecute

Run checks interactively until errors are all fixed.

Usage

loopExecute loopCallable arguments ...

Run checks interactively until errors are all fixed.

Arguments

  • loopCallable - Required. Callable. Call this on each file and a zero result code means passed and non-zero means fails.
  • --delay delaySeconds - Optional. Integer. Delay in seconds between checks in interactive mode.
  • --until exitCode - Optional. Integer. Check until exit code matches this.
  • --title title - Optional. String. Display this title instead of the command.
  • arguments ... - Optional. Arguments to loopCallable

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

interactiveCountdown

Display a message and count down display

Usage

interactiveCountdown [ --help ] [ --badge text ] [ --prefix prefix ] counter binary [ ... ]

Display a message and count down display

Arguments

  • --help - Optional. Flag. Display this help.
  • --badge text - String. Display this text as bigTextAt
  • --prefix prefix - String.
  • counter - Integer. Required. Count down from.
  • binary - Callable. Required. Run this with any additional arguments when the countdown is completed.
  • ... - Arguments. Optional. Passed to binary.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

confirmYesNo

Read user input and return success on yes

Usage

confirmYesNo [ --default defaultValue ] [ --attempts attempts ] [ --timeout seconds ] [ --info ] [ --yes ] [ --no ] [ --help ] [ --handler handler ] [ message ... ]

Read user input and return 0 if the user says yes, or non-zero if they say no Return Code: 0 - Yes Return Code: 1 - No Example: Will time out after 10 seconds, regardless (user must make valid input in that time): Example: Example:

Arguments

  • --default defaultValue - Boolean. Optional. Value to return if no value given by user
  • --attempts attempts - PositiveInteger. Optional. User can give us a bad response this many times before we return the default.
  • --timeout seconds - PositiveInteger. Optional. Wait this long before choosing the default. If no default, default is --no.
  • --info - Flag. Optional. Add Type Y or N as instructions to the user.
  • --yes - Flag. Optional. Short for --default yes
  • --no - Flag. Optional. Short for --default no
  • --help - Optional. Flag. Display this help.
  • --handler handler - Optional. Function. Use this error handler instead of the default error handler.
  • message ... - String. Any additional arguments are considered part of the message.

Examples

confirmYesNo --timeout 10 "Stop the timer!"

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

confirmMenu

Ask the user for a menu of options

Usage

confirmMenu --choice choiceCharacter [ --default default ] --result resultFile [ --attempts attemptCount ] [ --timeout timeoutSeconds ] [ --prompt promptString ] [ message ]

Ask the user for a menu of options

Return Code: interrupt - Attempts exceeded Return Code: timeout - Timeout

Arguments

  • --choice choiceCharacter - Required. String. Character to accept.
  • --default default - Optional. String. Character to choose when there is a timeout or other failure.
  • --result resultFile - Required. File. File to write the result to.
  • --attempts attemptCount - Optional. PositiveInteger. Number of attempts to try and get valid unput from the user.
  • --timeout timeoutSeconds - Optional. PositiveInteger. Number of seconds to wait for user input before stopping.
  • --prompt promptString - Optional. String. String to suffix the prompt with (usually tells the user what to do)
  • message - Optional. String. Display this message as the confirmation menu.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

pause

Pause for user input

Usage

pause [ --help ] [ -- ] [ message ... ]

Pause for user input

Arguments

  • --help - Optional. Flag. Display this help.
  • -- - Optional. Flag. Stops command processing to enable arbitrary text to be passed as additional arguments without special meaning.
  • message ... - Display this message while pausing

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

notify

Notify after running a binary. Uses the notify hook with

Usage

notify [ --help ] [ --handler handler ] [ --verbose ] [ --title title ] [ --message message ] [ --fail failMessage ] [ --sound soundName ] [ --fail-title title ] [ --fail-sound soundName ]

Notify after running a binary. Uses the notify hook with some handy parameters which are inherited between "success" and "failure":

  • Upon success uses: --message --title --sound
  • Upon failure uses: --fail-message --fail-title --fail-sound

If a value is not specified for failure, it will use the success value.

Arguments

  • --help - Optional. Flag. Display this help.
  • --handler handler - Optional. Function. Use this error handler instead of the default error handler.
  • --verbose - Flag. Optional. Be verbose.
  • --title title - String. Optional. Sets the title for the notification.
  • --message message - String. Optional. Display this message (alias is -m)
  • --fail failMessage - String. Optional. Display this message in console and dialog upon failure.
  • --sound soundName - String. Optional. Sets the sound played for the notification.
  • --fail-title title - String. Optional. Sets the title for the notification if the binary fails.
  • --fail-sound soundName - String. Optional. Sets the sound played for the notification if the binary fails.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Copy files

fileCopyWouldChange

Check whether copying a file would change it

Usage

fileCopyWouldChange [ --map ] source destination

Check whether copying a file would change it This function does not modify the source or destination. Return Code: 0 - Something would change Return Code: 1 - Nothing would change

Arguments

  • --map - Flag. Optional. Map environment values into file before copying.
  • source - File. Required. Source path
  • destination - File. Required. Destination path

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

fileCopy

Copy file from source to destination

Usage

fileCopy [ --map ] [ --escalate ] source destination

Copy file from source to destination

Supports mapping the file using the current environment, or escalated privileges. Return Code: 0 - Success Return Code: 1 - Failed

Arguments

  • --map - Flag. Optional. Map environment values into file before copying.
  • --escalate - Flag. Optional. The file is a privilege escalation and needs visual confirmation. Requires root privileges.
  • source - File. Required. Source path
  • destination - File. Required. Destination path

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Approve

approvedSources

List approved Bash script sources which can be loaded automatically

Usage

approvedSources [ --debug ] [ --no-delete ] [ --delete ]

List approved Bash script sources which can be loaded automatically by project hooks.

Approved sources are stored in a cache structure at $XDG_STATE_HOME/.interactiveApproved. Stale files are ones which no longer are associated with a file's current fingerprint.

Arguments

  • --debug - Flag. Optional. Show a lot of information about the approved cache.
  • --no-delete - Flag. Optional. Do not delete stale approval files.
  • --delete - Flag. Optional. Delete stale approval files.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • XDG_STATE_HOME - Directory. Base directory for user-specific state files to be stored

See Also

  • XDG_STATE_HOME - Directory. Base directory for user-specific state files to be stored

Examples

Example:

args=(--map configure/sshd_config /etc/ssh/sshd_config)
if fileCopyWouldChange "${args[@]}"; then
    catchEnvironment "$handler" fileCopy "${args[@]}" || return $?
    catchEnvironment "$handler" service ssh restart || return $?
fi