Merge pull request #151 from mbland/standalone

core: Implement `_GO_STANDALONE` mode

Author: mbland

README.md

@@ -160,6 +160,22 @@ under Bash 3.2, 4.2, 4.3, and 4.4 across OS X, Ubuntu Linux, Arch Linux, Alpine
 Linux, FreeBSD 9.3, FreeBSD 10.3, and Windows 10 (using all the environments
 described in the "Will this work on Windows?" section above).
 
+#### Can I use it to write standalone programs that aren't project scripts?
+
+Actually, yes. See the [Standalone mode](#standalone-mode) section below.
+
+Also see the following question...
+
+#### Can I have more than one ./go script in the same project source tree?
+
+Yes. You can share one copy of the go-bash-framework sources, and even have
+common code in the `lib/` directory, but set each script to use its own command
+scripts dir.
+
+This may be especially useful if you're writing a [standalone](#standalone-mode)
+program, in which one script provides the actual program interface, and the
+other provides the development-only interface.
+
 #### How is it tested?
 
 The project's own `./go test` command does it all. Combined with automatic
@@ -298,6 +314,20 @@ To learn the API for adding tab completion to your own command scripts, run
 `./go help complete`. You can also learn by reading the scripts for the builtin
 commands.
 
+#### Standalone mode
+
+If you wish to use the framework to write a standalone program, rather than a
+project-specific development script, set `_GO_STANDALONE` in your top-level
+script to prevent alias commands, builtin commands, and plugin commands from
+showing up in `help` output or from being offered as tab completions. (`help`
+will still appear as a top-level tab completion.) All of these commands will
+still be available, but users won't be presented with them directly.
+
+`_GO_STANDALONE` also prevents the script from setting `PWD` to `_GO_ROOTDIR`,
+enabling the script to process relative file path arguments anywhere in the file
+system. Note that then you'll have to add `_GO_ROOTDIR` manually to any
+`_GO_ROOTDIR`-relative paths in your own scripts.
+
 #### Including common code
 
 There are a number of possible methods available for sharing code between

go-core.bash

@@ -50,19 +50,28 @@ cd "${0%/*}" || exit 1
 # Path to the project's root directory
 #
 # This is directory containing the main ./go script. All functions, commands,
-# and scripts are invoked relative to this directory.
+# and scripts are invoked relative to this directory (unless `_GO_STANDALONE`
+# is set).
 declare -x _GO_ROOTDIR="$PWD"
 
 if [[ "${BASH_SOURCE[0]:0:1}" != '/' ]]; then
   cd "$__go_orig_dir/${BASH_SOURCE[0]%/*}" || exit 1
 else
   cd "${BASH_SOURCE[0]%/*}" || exit 1
 fi
-unset __go_orig_dir
 
 # Path to the ./go script framework's directory
 declare -r -x _GO_CORE_DIR="$PWD"
-cd "$_GO_ROOTDIR" || exit 1
+
+# Set _GO_STANDALONE if your script is a standalone program.
+#
+# See the "Standalone mode" section of README.md for more information.
+if [[ -z "$_GO_STANDALONE" ]]; then
+  cd "$_GO_ROOTDIR" || exit 1
+else
+  cd "$__go_orig_dir" || exit 1
+fi
+unset __go_orig_dir
 
 # Path to the script used to import optional library modules.
 #

lib/internal/commands

@@ -56,11 +56,15 @@ _@go.find_commands() {
         scripts+=("$script")
       fi
     done
-    _@go.merge_scripts_into_list "${scripts[@]#$_GO_ROOTDIR/}"
+    _@go.merge_scripts_into_list "${scripts[@]}"
   done
 
   if [[ "${#__go_command_scripts[@]}" -eq '0' ]]; then
     return 1
+  elif [[ -z "$_GO_STANDALONE" ]]; then
+    __go_command_scripts=("${__go_command_scripts[@]#$_GO_ROOTDIR/}")
+  else
+    __go_command_scripts=("${__go_command_scripts[@]#$PWD/}")
   fi
 
   __go_command_names=("${__go_command_scripts[@]##*/}")

lib/internal/complete

@@ -1,8 +1,13 @@
 #! /bin/bash
 
 _@go.complete_top_level_commands() {
-  _@go.source_builtin 'aliases'
-  _@go.source_builtin 'commands'
+  if [[ -z "$_GO_STANDALONE" ]]; then
+    _@go.source_builtin 'aliases'
+    _@go.source_builtin 'commands'
+  else
+    printf 'help\n'
+    _@go.source_builtin 'commands' "$_GO_SCRIPTS_DIR"
+  fi
 }
 
 # A successful return status from this function is a signal that __go_cmd_path

libexec/complete

@@ -15,8 +15,9 @@
 #   <command>     is the command supporting argument completion
 #
 # Aliases and some builtin commands will complete file and directory paths
-# relative to {{root}}. Other commands may implement their own specific
-# completion schemes.
+# relative to {{root}} (unless `_GO_STANDALONE` is set, in which case they'll be
+# relative to the caller's `PWD`). Other commands may implement their own
+# specific completion schemes.
 #
 # This behavior is normally accessible by using `{{go}} env` to set up your
 # shell environment for argument completion. Running `{{go}} {{cmd}}` or `{{go}}

libexec/help

@@ -55,10 +55,14 @@
 # enforced.
 
 _@go.usage() {
-  local cmd_paths=("${_GO_PLUGINS_PATHS[@]}" "$_GO_SCRIPTS_DIR")
+  local cmd_paths=("$_GO_SCRIPTS_DIR")
   local summaries
   local summaries_status=0
 
+  if [[ -z "$_GO_STANDALONE" ]]; then
+    cmd_paths+=("${_GO_PLUGINS_PATHS[@]}")
+  fi
+
   . "$_GO_USE_MODULES" 'strings'
   @go.join ':' 'cmd_paths' "${cmd_paths[@]}"
   summaries="$(_@go.source_builtin 'commands' --summaries "$cmd_paths")"
@@ -69,14 +73,18 @@ _@go.usage() {
     summaries_status=1
   fi
 
-  @go.printf "%s\n\n%s\n\n%s\n\n%s %s\n\n%s %s\n\n" \
+  @go.printf "%s\n\n%s\n\n%s\n\n%s %s\n\n" \
     "Usage: $_GO_CMD <command> [arguments...]" \
     "Where <command> is one of:" \
     "$summaries" \
     "Use \"$_GO_CMD help <command>\" for more information about that command," \
-    "if available." \
-    "Use \"$_GO_CMD help builtins\" for help on builtin commands," \
-    "and \"$_GO_CMD help aliases\" for information on shell alias commands."
+    "if available."
+
+  if [[ -z "$_GO_STANDALONE" ]]; then
+    @go.printf '%s %s\n\n' \
+      "Use \"$_GO_CMD help builtins\" for help on builtin commands," \
+      "and \"$_GO_CMD help aliases\" for information on shell alias commands."
+  fi
   [[ "$?" -eq '0' && "$summaries_status" -eq '0' ]]
 }
 

tests/commands/find.bats

@@ -27,7 +27,7 @@ teardown() {
 assert_command_scripts_equal() {
   set "$BATS_ASSERTION_DISABLE_SHELL_OPTIONS"
   unset 'lines[0]' 'lines[1]'
-  lines=("${lines[@]#$_GO_ROOTDIR/}")
+  lines=("${lines[@]}")
   assert_lines_equal "$@"
   return_from_bats_assertion "$?"
 }
@@ -73,7 +73,7 @@ assert_command_scripts_equal() {
 
   assert_line_equals 0 "LONGEST NAME LEN: ${#longest_name}"
   assert_line_equals 1 "COMMAND_NAMES: ${__all_scripts[*]##*/}"
-  assert_command_scripts_equal "${__all_scripts[@]}"
+  assert_command_scripts_equal "${__all_scripts[@]#$TEST_GO_ROOTDIR/}"
 }
 
 @test "$SUITE: return builtins, plugins, and user scripts" {
@@ -91,7 +91,28 @@ assert_command_scripts_equal() {
 
   assert_line_equals 0 "LONGEST NAME LEN: ${#longest_name}"
   assert_line_equals 1 "COMMAND_NAMES: ${__all_scripts[*]##*/}"
-  assert_command_scripts_equal "${__all_scripts[@]}"
+  assert_command_scripts_equal "${__all_scripts[@]#$TEST_GO_ROOTDIR/}"
+}
+
+@test "$SUITE: return paths relative to PWD when _GO_STANDALONE is set" {
+  local longest_name="super-extra-long-name-that-no-one-would-use"
+  local __all_scripts=("${BUILTIN_SCRIPTS[@]}")
+
+  # Command script and plugin script names must remain hand-sorted.
+  add_scripts 'bar' 'baz' 'foo' \
+    'plugins/plugh/bin/plugh' \
+    'plugins/quux/bin/quux' \
+    "plugins/$longest_name/bin/$longest_name" \
+    'plugins/xyzzy/bin/xyzzy'
+  cd "$HOME"
+  _GO_STANDALONE='true' run "$TEST_GO_SCRIPT"
+  assert_success
+
+  test_printf 'SCRIPT: %s\n' "${__all_scripts[@]}"
+
+  assert_line_equals 0 "LONGEST NAME LEN: ${#longest_name}"
+  assert_line_equals 1 "COMMAND_NAMES: ${__all_scripts[*]##*/}"
+  assert_command_scripts_equal "${__all_scripts[@]#$HOME/}"
 }
 
 @test "$SUITE: commands from earlier paths precede duplicates in later paths" {

tests/commands/helpers.bash

@@ -10,7 +10,7 @@ find_builtins() {
   local cmd_script
   local cmd_name
 
-  for cmd_script in "$_GO_ROOTDIR"/libexec/*; do
+  for cmd_script in "$_GO_CORE_DIR"/libexec/*; do
     if [[ ! (-f "$cmd_script" && -x "$cmd_script") ]]; then
       continue
     fi
@@ -22,9 +22,6 @@ find_builtins() {
       LONGEST_BUILTIN_NAME="$cmd_name"
     fi
   done
-
-  # Strip the rootdir to make output less noisy.
-  BUILTIN_SCRIPTS=("${BUILTIN_SCRIPTS[@]#$_GO_ROOTDIR/}")
 }
 
 merge_scripts() {
@@ -58,9 +55,9 @@ merge_scripts() {
 add_scripts() {
   local script_names=("$@")
 
-  merge_scripts "${script_names[@]/#/$TEST_GO_SCRIPTS_RELATIVE_DIR/}"
+  merge_scripts "${script_names[@]/#/$TEST_GO_SCRIPTS_DIR/}"
 
   for script_path in "${script_names[@]}"; do
-    @go.create_test_command_script "$script_path"
+    @go.create_test_command_script "${script_path#$TEST_GO_ROOTDIR/}"
   done
 }

tests/commands/main.bats

@@ -7,12 +7,6 @@ setup() {
   test_filter
   @go.create_test_go_script '@go "$@"'
   find_builtins
-
-  # We have to add back the _GO_ROOTDIR that was stripped from the beginning of
-  # each element of BUILTIN_SCRIPTS, because it will be different from the
-  # _GO_ROOTDIR of the generated test script. Thus, `$TEST_GO_SCRIPT commands`
-  # will report builtin command paths as absolute.
-  BUILTIN_SCRIPTS=("${BUILTIN_SCRIPTS[@]/#/$_GO_ROOTDIR/}")
 }
 
 teardown() {
@@ -183,9 +177,7 @@ generate_expected_paths() {
   done
 }
 
-@test "$SUITE: command paths" {
-  local user_commands=('bar' 'baz' 'foo')
-  local plugin_commands=('plugh' 'quux' 'xyzzy')
+@test "$SUITE: command paths are relative to _GO_ROOTDIR by default" {
   local __all_scripts=("${BUILTIN_SCRIPTS[@]}")
 
   # Command script and plugin script names must remain hand-sorted.
@@ -195,12 +187,31 @@ generate_expected_paths() {
     'plugins/xyzzy/bin/xyzzy'
 
   local __expected_paths=()
+  __all_scripts=("${__all_scripts[@]#$TEST_GO_ROOTDIR/}")
   generate_expected_paths
 
   run "$TEST_GO_SCRIPT" commands --paths
   assert_success "${__expected_paths[@]}"
 }
 
+@test "$SUITE: command paths are relative to PWD when _GO_STANDALONE is set" {
+  local __all_scripts=("${BUILTIN_SCRIPTS[@]}")
+
+  # Command script and plugin script names must remain hand-sorted.
+  add_scripts 'bar' 'baz' 'foo' \
+    'plugins/plugh/bin/plugh' \
+    'plugins/quux/bin/quux' \
+    'plugins/xyzzy/bin/xyzzy'
+
+  local __expected_paths=()
+  __all_scripts=("${__all_scripts[@]#$HOME/}")
+  generate_expected_paths
+
+  cd "$HOME"
+  _GO_STANDALONE='true' run "$TEST_GO_SCRIPT" commands --paths
+  assert_success "${__expected_paths[@]}"
+}
+
 create_script_with_description() {
   local script_path="$1"
   local cmd_name="${script_path##*/}"

tests/complete.bats

@@ -4,6 +4,7 @@ load environment
 load commands/helpers
 
 setup() {
+  test_filter
   @go.create_test_go_script '@go "$@"'
   find_builtins
   . "$_GO_USE_MODULES" 'complete'
@@ -28,11 +29,14 @@ teardown() {
 }
 
 @test "$SUITE: all top-level commands for zeroth or first argument" {
-  # Aliases will get printed before all other commands.
-  local __all_commands=("$(./go 'aliases')" "${BUILTIN_CMDS[@]}")
+  local __all_scripts=("${BUILTIN_CMDS[@]}")
+
+  # The script name arguments must remain alphabetically sorted by basename.
+  add_scripts 'bar' 'plugins/baz/bin/baz' 'foo'
 
+  # Aliases will get printed before all other commands.
   run "$TEST_GO_SCRIPT" complete 0
-  assert_success "${__all_commands[@]}"
+  assert_success $(./go 'aliases') "${__all_scripts[@]##*/}"
 
   run "$TEST_GO_SCRIPT" complete 0 complete
   assert_success 'complete '
@@ -41,6 +45,15 @@ teardown() {
   assert_failure ''
 }
 
+@test "$SUITE: _GO_STANDALONE only completes 'help' and project scripts" {
+  @go.create_test_command_script 'foo'
+  @go.create_test_command_script 'bar'
+  @go.create_test_command_script 'plugins/baz/bin/baz'
+
+  _GO_STANDALONE='true' run "$TEST_GO_SCRIPT" complete 0
+  assert_success 'help' 'bar' 'foo'
+}
+
 @test "$SUITE: cd and pushd complete directories" {
   local subdirs=('bar' 'baz' 'foo')
   local files=('plugh' 'quux' 'xyzzy')