diff --git a/docs/function-calling/BASH-PROMPT-HELPERS.md b/docs/function-calling/BASH-PROMPT-HELPERS.md new file mode 100644 index 0000000..92f22f8 --- /dev/null +++ b/docs/function-calling/BASH-PROMPT-HELPERS.md @@ -0,0 +1,275 @@ +# Bash Prompt Helpers + +When creating bash based tools, it's often helpful to prompt the user for input or confirmation. + +Loki comes pre-packaged with a handful of prompt helpers for your bash-based tools. These helpers +can be used to prompt the user for various types of input, such as yes/no confirmations, +text input, and selections from a list. + +The utility script is located at `functions/utils/prompt-utils.sh` within your Loki `functions` directory. + +The Loki `functions` directory varies between machines, so you can find its location on your system by running the following command in your terminal: + +```shell +loki --info | grep functions_dir | awk '{print $2}' +``` + +## Quick Links + +- [Import The Prompt Utils Into Your Tools Script](#import-the-prompt-utils-into-your-tools-script) +- [Included Utility Functions](#included-utility-functions) + - [input](#input) + - [confirm](#confirm) + - [list](#list) + - [checkbox](#checkbox) + - [password](#password) + - [editor](#editor) + - [with_validate](#with_validate) + - [validate_present](#validate_present) + - [detect_os](#detect_os) + - [get_opener](#get_opener) + - [open_link](#open_link) + - [guard_operation](#guard_operation) + - [guard_path](#guard_path) + - [patch_file](#patch_file) + - [error](#error) + - [warn](#warn) + - [info](#info) + - [debug](#debug) + - [trace](#trace) + - [Colored Output](#colored-output) + + +--- + +## Import The Prompt Utils Into Your Tools Script +In order to use the bash prompt helpers in your bash scripts, you need to source the provided `prompt-utils.sh` script. +This script is pre-packaged with Loki and is located [here](../../assets/functions/utils/prompt-utils.sh). + +When sourcing the file in your bash script, you use the `LLM_PROMPT_UTILS_FILE` environment variable that automatically +populates the `functions/utils/prompt-utils.sh` path for you. + +Thus, to properly source and enable all the bash prompt helpers in your Bash tools, add the following prelude to your +scripts: + +```bash +source "$LLM_PROMPT_UTILS_FILE" +``` + +## Included Utility Functions +Below are the built-in bash prompt helpers that can be used to enhance user interaction with your tool scripts. + +### input +Prompt for text input + +![Prompt Utils Input](../images/tools/prompt-utils-input.png) + +**Example With Validation:** +```bash +text=$(with_validation 'input "Please enter something:"' validate_present) +``` + +**Example Without Validation:** +```bash +text=$(input "Please enter something:") +``` + +### confirm +Show a confirm dialog with options for yes/no + +![Prompt Utils Confirm](../images/tools/prompt-utils-confirm.png) + +**Example:** +```bash +confirmed=$(confirm "Do the thing?") +if [[ $confirmed == "0" ]]; then echo "No"; else echo "Yes"; fi +``` + +### list +Renders a text based list of options that can be selected by the user using up, down, and enter +keys that then returns the chosen option. + +![Prompt Utils List](../images/tools/prompt-utils-list.png) + +**Example:** +```bash +options=("one" "two" "three" "four") +choice=$(list "Select an item" "${options[@]}") +echo "Your choice: ${options[$choice]}" +``` + +### checkbox +Render a text based list of options, where multiple options can be selected by the user using down, up, +and enter keys that then returns the chosen options. + +![Prompt Utils Checkbox](../images/tools/prompt-utils-checkbox.png) + +**Example:** +```bash +options=("one" "two" "three" "four") +checked=$(checkbox "Select one or more items" "${options[@]}") +echo "Your choices: ${checked}" +``` + +### password +Show a password prompt displaying stars for each character typed. + +![Prompt Utils Password](../images/tools/prompt-utils-password.png) + +**Example With Validation:** +```bash +validate_password() { + if [[ ${#1} -lt 10 ]]; then + echo "Password must be at least 10 characters" + exit 1 + fi +} +pass=$(with_validate 'password "Enter your password"' validate_password) +``` + +**Example Without Validation:** +```bash +pass="$(password "Enter your password:")" +``` + +### editor +Open the default editor (`$EDITOR`); if none is set, default back to `vi` + +**Example:** +```bash +text=$(editor "Please enter something in the editor") +echo -e "You wrote:\n${text}" +``` + +### with_validate +Evaluate the given prompt command with validation. This prompts the user for input until the +validation functions returns 0. + +![Prompt Utils With-validate](../images/tools/prompt-utils-with-validate.png) + +**Example:** +```bash +# Using the built-in 'validate_present' validator +text=$(with_validate 'input "Please enter something and confirm with enter"' validate_present) + +# Using a custom validator; e.g. for password +validate_password() { + if [[ ${#1} -lt 10 ]]; then + echo "Password needs to be at least 10 characters" + exit 1 + fi +} +pass=$(with_validate 'password "Enter random password"' validate_password) +``` + +### validate_present +Validate that the prompt returned a value. + +![Prompt Utils Validate-Present](../images/tools/prompt-utils-validate-present.png) + +**Example:** +```bash +text=$(with_validate 'input "Please enter something and confirm with enter"' validate_present) +``` + +### detect_os +Detect the current OS. + +Returns one of the following: + +* `solaris` +* `macos` +* `linux` +* `bsd` +* `windows` +* `unknown` + +**Example:** +```bash +detect_os +``` + +### get_opener +Determines the Os-specific file opening command (i.e. the command to open anything) + +**Example:** +```bash +# Returns 'xdg-open' +get_opener +``` + +### open_link +Opens the given link in the default browser + +**Example:** +```bash +open_link https://www.google.com +``` + +### guard_operation +Prompt for permission to run an operation + +**Example:** +```bash +guard_operation "Execute SQL?" +_run_sql +``` + +### guard_path +Prompt for permission to perform path operations + +**Example:*** +```bash +guard_path "$target_path" "Remove '$target_path'?" +rm -rf "$target_path" +``` + +### patch_file +Patch a file and show a diff using the default diff viewer. Uses git diff syntax. + +**Example:** +```bash +new_contents="$(patch_file "$path" file.patch)" +``` + +### error +Log an error + +![Prompt Utils Error](../images/tools/prompt-utils-error.png) + +### warn +Log a warning + +![Prompt Utils Warning](../images/tools/prompt-utils-warning.png) + +### info +Log info + +![Prompt Utils Info](../images/tools/prompt-utils-info.png) + +### debug +Log a debug message + +![Prompt Utils Debug](../images/tools/prompt-utils-debug.png) + +### trace +Log a trace message + +![Prompt Utils Trace](../images/tools/prompt-utils-trace.png) + +### Colored Output +The following commands allow users to output text in specific colors. + +* `red` +* `green` +* `gold` +* `blue` +* `magenta` +* `cyan` +* `white` + +**Example:** +```bash +red "This will be red" +yellow "This will be yellow" +``` diff --git a/docs/images/tools/prompt-utils-checkbox.png b/docs/images/tools/prompt-utils-checkbox.png new file mode 100644 index 0000000..f557f4a Binary files /dev/null and b/docs/images/tools/prompt-utils-checkbox.png differ diff --git a/docs/images/tools/prompt-utils-confirm.png b/docs/images/tools/prompt-utils-confirm.png new file mode 100644 index 0000000..cc18a8b Binary files /dev/null and b/docs/images/tools/prompt-utils-confirm.png differ diff --git a/docs/images/tools/prompt-utils-debug.png b/docs/images/tools/prompt-utils-debug.png new file mode 100644 index 0000000..2eed9bb Binary files /dev/null and b/docs/images/tools/prompt-utils-debug.png differ diff --git a/docs/images/tools/prompt-utils-error.png b/docs/images/tools/prompt-utils-error.png new file mode 100644 index 0000000..3f3e733 Binary files /dev/null and b/docs/images/tools/prompt-utils-error.png differ diff --git a/docs/images/tools/prompt-utils-info.png b/docs/images/tools/prompt-utils-info.png new file mode 100644 index 0000000..221f0e8 Binary files /dev/null and b/docs/images/tools/prompt-utils-info.png differ diff --git a/docs/images/tools/prompt-utils-input.png b/docs/images/tools/prompt-utils-input.png new file mode 100644 index 0000000..513e567 Binary files /dev/null and b/docs/images/tools/prompt-utils-input.png differ diff --git a/docs/images/tools/prompt-utils-list.png b/docs/images/tools/prompt-utils-list.png new file mode 100644 index 0000000..604d146 Binary files /dev/null and b/docs/images/tools/prompt-utils-list.png differ diff --git a/docs/images/tools/prompt-utils-password.png b/docs/images/tools/prompt-utils-password.png new file mode 100644 index 0000000..2206020 Binary files /dev/null and b/docs/images/tools/prompt-utils-password.png differ diff --git a/docs/images/tools/prompt-utils-trace.png b/docs/images/tools/prompt-utils-trace.png new file mode 100644 index 0000000..f698c2e Binary files /dev/null and b/docs/images/tools/prompt-utils-trace.png differ diff --git a/docs/images/tools/prompt-utils-validate-present.png b/docs/images/tools/prompt-utils-validate-present.png new file mode 100644 index 0000000..bacd958 Binary files /dev/null and b/docs/images/tools/prompt-utils-validate-present.png differ diff --git a/docs/images/tools/prompt-utils-warning.png b/docs/images/tools/prompt-utils-warning.png new file mode 100644 index 0000000..5363986 Binary files /dev/null and b/docs/images/tools/prompt-utils-warning.png differ diff --git a/docs/images/tools/prompt-utils-with-validate.png b/docs/images/tools/prompt-utils-with-validate.png new file mode 100644 index 0000000..4c4dbb8 Binary files /dev/null and b/docs/images/tools/prompt-utils-with-validate.png differ