README,commands,plugins,use: Update search docs

Closes #137. These updates explain the updates to command script,
library module, and plugin search precedence. It could probably be
improved, but at least the basic information is now present and
discoverable.

Author: mbland

README.md

@@ -274,17 +274,18 @@ interpreted as relative to the project root.
 Your project structure may look something like this:
 
 ```
-project/
+project-root/
   go - main ./go script
-  scripts/ - project ./go command scripts
+  lib/ - publicly-exported modules (if the project is a go-bash-script plugin)
+  scripts/ (or bin/) - project (or plugin) ./go command scripts
     lib/ - project-specific Bash library modules (see "Modules" section)
     plugins/ - (optional) third-party command scripts (see `./go help plugins`)
       .../
         bin/ - plugin ./go command scripts
-        lib/ - optional Bash library modules (see "Modules" section)
+        lib/ - publicly-exported Bash library modules (see "Modules" section)
     go-script-bash/
       go-core.bash - top-level functions
-      lib/ - optional Bash library modules (see "Modules" section)
+      lib/ - publicly-exported Bash library modules (see "Modules" section)
       libexec/ - builtin ./go command scripts
 ```
 
@@ -293,11 +294,20 @@ This structure implies that the first line of your `./go` script will be:
 . "${0%/*}/scripts/go-script-bash/go-core.bash" "scripts"
 ```
 
-The precedence for discovering commands is:
+#### Variables and plugin scoping
 
-- aliases/builtins (provided by this framework)
-- plugins (in `scripts/plugins` above)
-- project scripts (in `scripts` above)
+The following variables are set by the framework based on the above example
+(note there are many other variables set in `go-core.bash` and elsewhere; see
+`./go help vars`):
+
+* `_GO_ROOTDIR`: `/absolute/path/to/project-root`
+* `_GO_CORE_DIR`: `/absolute/path/to/project-root/scripts/go-script-bash`
+* `_GO_SCRIPTS_DIR`: `$_GO_ROOTDIR/scripts`
+* `_GO_PLUGINS_DIR`: `/absolute/path/to/project-root/plugins`
+
+For plugins, `_GO_ROOTDIR` and `_GO_SCRIPTS_DIR` will be scoped to the root
+directory of the plugin installation; the other variables will remain the same.
+See `./go help plugins` for more details.
 
 #### Command scripts
 
@@ -316,6 +326,9 @@ need not be written in Bash.__ Bash scripts will be sourced (i.e. imported into
 the same process running the `./go` script itself). Other languages will use the
 `PATH` environment variable to discover the interpreter for the script.
 
+See `./go help commands` for details on the algorithm used to discover command
+scripts for execution.
+
 #### Command summaries and help text
 
 The builtin `./go help` command will parse command script summaries and help
@@ -417,14 +430,15 @@ For more information, run `./go modules --help log`.
 #### Bats test assertions and helpers
 
 The assertions and helpers from the test suite have been extracted into the
-`lib/bats/assertions`, `lib/bats/helpers`, and `lib/bats/assertion-test-helpers`
-libraries. While these are not modules you can import with `_GO_USE_MODULES`,
-they are completely independent of the rest of the core framework and you may
-source them in your own Bats tests. (Whether or not these will ever become a
-separate library remains an open question.)
+`lib/bats` libraries. While these are not modules you can import with
+`_GO_USE_MODULES`, they are completely independent of the rest of the core
+framework and you may source them in your own Bats tests. (Whether or not these
+will ever become a separate library remains an open question.)
 
 Variables, helper functions, and assertions for testing features based on the
-core framework are available in the `lib/testing` directory.
+core framework are available in the `lib/testing` directory. The `lib/bats-main`
+library makes it easy to write a `./go test` command script with the same
+interface and features as the core framework's `./go test` command.
 
 Read the comments from each file for more information.
 

go-core.bash

@@ -291,6 +291,11 @@ declare _GO_INJECT_MODULE_PATH="$_GO_INJECT_MODULE_PATH"
 #   fi
 # }
 #
+# Note that this algorithm is modeled after the `node_modules` search algorithm
+# used by `npm`. See:
+#
+#   https://docs.npmjs.com/files/folders#cycles-conflicts-and-folder-parsimony
+#
 # Arguments:
 #   search_func:  Helper function implementing the search operation
 #

lib/internal/use

@@ -5,10 +5,9 @@
 # Usage:
 #   .  "$_GO_USE_MODULES" <module> [<module>...]
 #
-#   NOTE: It's important to wrap `$_GO_USE_MODULES` in double-quotes to ensure
-#   the statement is portable to environments in which the file paths may
-#   contain spaces. It's good practice to wrap each `<module>` in
-#   single-quotes as well.
+# NOTE: It's important to wrap `$_GO_USE_MODULES` in double-quotes to ensure the
+# statement is portable to environments in which the file paths may contain
+# spaces. It's good practice to wrap each `<module>` in single-quotes as well.
 #
 # Where:
 #   <module>  The name of an optional Bash library module
@@ -40,17 +39,20 @@
 # require the functionality can use `_GO_CORE_MODULES` on an as-needed basis,
 # rather than using it in the top-level `./go` script.
 #
-# The precedence for discovering modules is (with examples from the "Directory
-# structure" example from README.md):
+# The precedence for discovering modules is similar to that for discovering
+# command scripts:
 #
-#   - the `_GO_INJECT_MODULE_PATH` directory
-#   - the `lib/` directory of the framework (`scripts/go-script-bash/lib`)
-#   - the `lib/` directory in your project scripts directory (`scripts/lib`)
-#   - the `lib/` directory of `_GO_ROOTDIR` (i.e. exported scripts)
-#   - the `lib/` directory of installed plugins (`scripts/plugins/*/lib`)
+#   - `_GO_INJECT_MODULE_PATH` for module stubs injected during testing;
+#     see `lib/testing/stubbing`
+#   - `_GO_CORE_DIR/lib/` for core library modules
+#   - `_GO_SCRIPTS_DIR/lib` for project-internal modules
+#   - `_GO_ROOTDIR/lib` for publicly-exported modules (`./go` script plugins)
+#   - `_GO_SCRIPTS_DIR/plugins/*/lib` for installed plugin modules
+#   - Parent plugin dirs up to `_GO_PLUGINS_DIR/*/lib` for plugin modules
+#     installed in parent directories
 #
-# For modules contained in plugin directories, you must specify the path as
-# `<plugin-name>/<module-name>`. There is no need to include the `lib/`
+# To import a module exported from an installed plugin, you must specify the
+# path as `<plugin-name>/<module-name>`. There is no need to include the `lib/`
 # component.  For example, if you have a plugin called `foo` and it contains a
 # module file `lib/bar` (installed as `scripts/plugins/foo/lib/bar` in your
 # project repository), you could import the module via:
@@ -59,11 +61,15 @@
 #
 # Note that if there is a module with the relative path `foo/bar` in one of the
 # other directories, such as `_GO_ROOTDIR/lib/foo/bar`, it will take precedence
-# over the plugin `scripts/plugins/foo/lib/bar`.
+# over the plugin `scripts/plugins/foo/lib/bar`. See `{{go}} help plugins` for
+# more information on plugins and their operating constraints.
 #
 # Module loading is idempotent, as the names of imported modules are added to
 # the `_GO_IMPORTED_MODULES` array and are not sourced again if their names are
-# already in the array.
+# already in the array. If a potential collision between installed module names
+# is detected (possible with installed plugins), a verbose warning pinpointing
+# the collision points will be printed to standard error, but execution will
+# continue.
 #
 # To see what modules are currently imported and their corresponding files, use:
 #

libexec/commands

@@ -9,10 +9,21 @@
 #   --paths      List the path of each command script
 #   --summaries  List the summary of each command script
 #
+# The precedence for discovering commands executed via `@go` is:
+#
+#   - Command aliases; see `{{go}} help aliases`
+#   - `_GO_INJECT_SEARCH_PATH` for command script stubs injected during testing;
+#     see `lib/testing/stubbing`
+#   - `_GO_CORE_DIR/libexec` for core library command scripts
+#   - `_GO_SCRIPTS_DIR` for project command scripts
+#   - `_GO_SCRIPTS_DIR/plugins/*/bin` for installed plugin command scripts
+#   - Parent plugin dirs up to `_GO_PLUGINS_DIR/*/bin` for plugin command
+#     scripts
+#
 # If no <command-name> or <script-path> is given, lists all top-level builtins,
-# plugins, and user-defined commands. If <command-name> is given, lists the
-# subcommands for that command. If <script-paths> is given, lists top-level
-# commands within those directories.
+# plugins, and user-defined commands discovered via the above algorithm. If
+# <command-name> is given, lists the subcommands for that command. If
+# <script-paths> is given, lists top-level commands within those directories.
 #
 # Only one of <command-name> or <script-paths> may be specified. <command-name>
 # can be a multiple-word subcommand name, in which case its subcommands, if any,
@@ -21,6 +32,10 @@
 #
 # NOTE: This command will not return the names of shell aliases; use `{{go}}
 # aliases` for those.
+#
+# While executing a plugin command script, `_GO_ROOTDIR` and `_GO_SCRIPTS_DIR`
+# are scoped to the top-level directory of the plugin. See `{{go}} help plugins`
+# for more information on plugins and their operating constraints.
 
 _@go.summarize_commands() {
   . "$_GO_CORE_DIR/lib/internal/command_descriptions"

libexec/plugins

@@ -9,13 +9,38 @@
 #   --summaries  List all plugin command summaries
 #
 # To install plugins, first create a subdirectory of your scripts directory
-# called "plugins". Then add any third-party scripts to this new directory.
+# called "plugins". Then copy, clone, or add submodules for `./go` script
+# plugins inside this new directory. The `./go get git-repo` command may be used
+# for this purpose.
 #
-# As with your project-specific scripts, any scripts in this directory must be
-# executable and the first line must be of the form: '#!/path/to/interpreter'
+# A plugin must have a top-level `bin/` directory for its exported command
+# scripts, a top-level `lib/` directory for its exported library modules, or
+# both.
 #
-# Plugins that are installed as directories (possibly as git submodules) should
-# contain a `bin/` subdirectory containing its command scripts.
+# `_GO_ROOTDIR` and `_GO_SCRIPTS_DIR` are scoped to each installed plugin's
+# top-level directory during both command script execution and library module
+# importation. This enables a plugin's code to refer to its own relative paths
+# and to give its own command scripts and library modules priority in these
+# contexts.
+#
+# Note that plugin module code that isn't executed during importation WILL NOT
+# have these variables scoped to its installation directory. If a library module
+# needs to refer to its own relative paths when executed outside of these
+# contexts, it should calculate them based on the `BASH_SOURCE` variable.
+# Alternatively, it might capture them during importation using its own
+# uniquely-named variables, possibly with safety checks to ensure the variables
+# are not yet defined.
+#
+# Also, if a plugin is intended to operate on the files and directories of a
+# project that's installed it, the plugin must provide an interface to receive
+# file paths from the project.
+#
+# See `{{go}} help commands` for more information on command script execution,
+# and `{{go}} modules -h` for more information on library module importation.
+# See the comments for `@go.search_plugins` from `go-core.bash` for details on
+# the plugin search algorithm used by command script execution and library
+# module importation, which is modeled after the `node_modules` search algorithm
+# used by `npm`.
 
 _@go.plugins_pathspec() {
   local IFS=':'