core: Add @go.select_option function and demo

go-core.bash

@@ -215,6 +215,43 @@ declare _GO_INJECT_MODULE_PATH="$_GO_INJECT_MODULE_PATH"
   return "$result"
 }
 
+# Prompts the user to select one item from a list of options.
+#
+# This is a thin wrapper around the `select` builtin command for
+# straightforward, single-option user prompts. If you need to do anything more
+# complex, use the `select` builtin command directly.
+#
+# This will prompt the user for a single input, returned in the caller-declared
+# variable identified by `result_var`. If the user enters an invalid option,
+# this will notify the user and prompt again. If the user terminates input (via
+# EOF, i.e. Ctrl-D), `result_var` will remain unchanged and the function will
+# return nonzero.
+#
+# Globals:
+#   PS3  environment variable defining the selection prompt
+#
+# Arguments:
+#   result_var:  Name of the caller-declared variable used to store the option
+#   ...:         Strings representing options available for the user to select
+#
+# Returns:
+#   zero if `result_var` contains the user's selection, nonzero otherwise
+@go.select_option() {
+  local __go_selected_option
+  select __go_selected_option in "${@:2}"; do
+    case "$__go_selected_option" in
+    '')
+      @go.printf '"%s" is not a valid option.\n' "$REPLY" >&2
+      ;;
+    *)
+      printf -v "$1" -- '%s' "$__go_selected_option"
+      break
+      ;;
+    esac
+  done
+  [[ -n "$__go_selected_option" ]]
+}
+
 # Searches through plugin directories using a helper function
 #
 # The search will begin in `_GO_SCRIPTS_DIR/plugins`. As long as `search_func`

libexec/demo-core.d/select-option

@@ -0,0 +1,49 @@
+#! /usr/bin/env bash
+#
+# Demonstration of the `@go.select_option` function
+#
+# Usage:
+#   [PS3=<VALUE>] {{go}} {{cmd}} [option...]
+#
+# Where:
+#   PS3        environment variable defining the selection prompt
+#   option...  (Optional) list of user-selectable options, overriding defaults
+#
+# Use this program to get a feel for the core `@go.select_option` function, and
+# for an example of how to use it in your own scripts.
+
+select_option_demo() {
+  local options=("$@")
+  local selected
+  local finish
+
+  if [[ "${#options[@]}" -eq '0' ]]; then
+    options=('Hello, World!' 'Goodbye, World!')
+  fi
+
+  while [[ -z "$finish" ]]; do
+    @go.printf 'Please select one of the following options:\n'
+
+    if @go.select_option 'selected' "${options[@]}"; then
+      @go.printf 'You selected: "%s"\n\n' "$selected"
+    else
+      @go.printf 'You declined to select an option.\n\n'
+    fi
+
+    @go.printf 'Would you like to select another option?\n'
+
+    if @go.select_option 'selected' 'Yes' 'No'; then
+      if  [[ "$selected" == 'No' ]]; then
+        @go.printf 'Exiting...\n'
+        finish='true'
+      else
+        printf '\n'
+      fi
+    else
+      @go.printf 'You declined to select an option. Exiting...\n'
+      finish='true'
+    fi
+  done
+}
+
+select_option_demo "$@"

tests/core/select-option.bats

@@ -0,0 +1,59 @@
+#! /usr/bin/env bats
+
+load ../environment
+
+setup() {
+  test_filter
+  @go.create_test_go_script 'declare selection' \
+    'if @go.select_option "selection" "$@"; then' \
+    '  printf "\nSelection: \"%s\"\n" "$selection"' \
+    'else' \
+    '  exit 1' \
+    'fi'
+  export PS3='Selection> '
+}
+
+teardown() {
+  @go.remove_test_go_rootdir
+}
+
+@test "$SUITE: no options exits instantly" {
+  run "$TEST_GO_SCRIPT"
+  assert_failure ''
+}
+
+@test "$SUITE: single option selection" {
+  run "$TEST_GO_SCRIPT" 'foo' <<<"1"
+  assert_success '1) foo' \
+  "$PS3" \
+  'Selection: "foo"'
+}
+
+@test "$SUITE: multiple option selection" {
+  run "$TEST_GO_SCRIPT" 'foo' 'bar' 'baz' <<<"2"
+  assert_success '1) foo' \
+  '2) bar' \
+  '3) baz' \
+  "$PS3" \
+  'Selection: "bar"'
+}
+
+@test "$SUITE: select valid option after invalid option" {
+  run "$TEST_GO_SCRIPT" 'foo' 'bar' 'baz' <<<$'0\n3'
+  assert_success '1) foo' \
+  '2) bar' \
+  '3) baz' \
+  "$PS3\"0\" is not a valid option." \
+  "$PS3" \
+  'Selection: "baz"'
+}
+
+@test "$SUITE: no selection with invalid option followed by end-of-file" {
+  printf '4\n' >"$TEST_GO_ROOTDIR/input.txt"
+  run "$TEST_GO_SCRIPT" 'foo' 'bar' 'baz' <"$TEST_GO_ROOTDIR/input.txt"
+  assert_failure '1) foo' \
+  '2) bar' \
+  '3) baz' \
+  "$PS3\"4\" is not a valid option." \
+  "$PS3"
+}

tests/demo-core/select-option.bats

@@ -0,0 +1,74 @@
+#! /usr/bin/env bats
+
+load ../environment
+
+setup() {
+  test_filter
+  export PS3='Selection> '
+}
+
+teardown() {
+  @go.remove_test_go_rootdir
+}
+
+@test "$SUITE: use default selection options" {
+  run "$_GO_SCRIPT" demo-core select-option <<<$'1\n1\n2\n2\n'
+  assert_success
+  split_bats_output_into_lines
+  assert_lines_equal 'Please select one of the following options:' \
+    '1) Hello, World!' \
+    '2) Goodbye, World!' \
+    "${PS3}You selected: \"Hello, World!\"" \
+    '' \
+    'Would you like to select another option?' \
+    '1) Yes' \
+    '2) No' \
+    "${PS3}" \
+    'Please select one of the following options:' \
+    '1) Hello, World!' \
+    '2) Goodbye, World!' \
+    "${PS3}You selected: \"Goodbye, World!\"" \
+    '' \
+    'Would you like to select another option?' \
+    '1) Yes' \
+    '2) No' \
+    "${PS3}Exiting..."
+}
+
+@test "$SUITE: use user-provided selection options" {
+  run "$_GO_SCRIPT" demo-core select-option foo bar baz <<<$'2\n2\n'
+  assert_success
+  split_bats_output_into_lines
+  assert_lines_equal 'Please select one of the following options:' \
+    '1) foo' \
+    '2) bar' \
+    '3) baz' \
+    "${PS3}You selected: \"bar\"" \
+    '' \
+    'Would you like to select another option?' \
+    '1) Yes' \
+    '2) No' \
+    "${PS3}Exiting..."
+}
+
+@test "$SUITE: exit both prompts on empty input" {
+  mkdir "$TEST_GO_ROOTDIR"
+  printf '' >"$TEST_GO_ROOTDIR/input.txt"
+  run "$_GO_SCRIPT" demo-core select-option foo bar baz \
+    <"$TEST_GO_ROOTDIR/input.txt"
+
+  assert_success
+  split_bats_output_into_lines
+  assert_lines_equal 'Please select one of the following options:' \
+    '1) foo' \
+    '2) bar' \
+    '3) baz' \
+    "${PS3}" \
+    'You declined to select an option.' \
+    '' \
+    'Would you like to select another option?' \
+    '1) Yes' \
+    '2) No' \
+    "${PS3}" \
+    'You declined to select an option. Exiting...'
+}