Merge pull request #23 from mbland/version

Introduce _GO_CORE_VERSION

README.md

@@ -342,14 +342,46 @@ your scripts directory. Run `./go help plugins` for more information.
 
 You can import optional Bash library code from the core framework, third-party
 plugins, or your own project's scripts directory by sourcing the
-`$_GO_USE_MODULES` script. For example, to import the core logging utilities:
+`_GO_USE_MODULES` script. For example, to import the core logging utilities:
 
 ```bash
-. $_GO_USE_MODULES 'log'
+. "$_GO_USE_MODULES" 'log'
 ```
 
 Run `./go help modules` and `./go modules --help` for more information.
 
+#### Logging
+
+The core library `log` module provides functions for standard logging
+facilities. For example:
+
+```bash
+@go.log INFO Hello, World!
+@go.log ERROR Goodbye, World!
+```
+
+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` and `lib/bats/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.)
+
+Read the comments from each file for more information.
+
+#### `kcov-ubuntu` module for test coverage on Linux
+
+The `kcov-ubuntu` module provides the `run_kcov` function that will download and
+compile [kcov](https://github.com/SimonKagstrom/kcov), then run `kcov` with the
+original `./go` command line arguments to collect test coverage. Only available
+on Ubuntu Linux for now, hence the name. Run `./go modules --help kcov-ubuntu`
+for more information and see `scripts/test` for an example of how it may be
+used.
+
 ### Feedback and contributions
 
 Feel free to [comment on or file a new GitHub

go-core.bash

@@ -2,9 +2,6 @@
 #
 # Framework for writing "./go" scripts in Bash.
 #
-# Version: v1.0.0
-# URL: https://github.com/mbland/go-script-bash
-#
 # To use this framework, create a bash script in the root directory of your
 # project to act as the main './go' script. This script need not be named 'go',
 # but it must contain the following as the first and last executable lines,
@@ -35,19 +32,25 @@ if [[ "${BASH_VERSINFO[0]}" -lt '3' || "${BASH_VERSINFO[1]}" -lt '2' ]]; then
   exit 1
 fi
 
+# The version of the framework
+#
+# NOTE:
+# ----
+# This and other variables are exported, so that command scripts written in
+# languages other than Bash (and hence run in new processes) can access them.
+# See `./go vars` and `./go help vars`.
+declare -r -x _GO_CORE_VERSION='v1.0.0'
+
+# The URL of the framework's original source repository
+declare -r -x _GO_CORE_URL='https://github.com/mbland/go-script-bash'
+
 declare __go_orig_dir="$PWD"
 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.
-#
-# NOTE:
-# ----
-# This and other variables are exported, so that command scripts written in
-# languages other than Bash (and hence run in new processes) can access them.
-# See `./go vars` and `./go help vars`.
 declare -r -x _GO_ROOTDIR="$PWD"
 
 if [[ "${BASH_SOURCE[0]:0:1}" != '/' ]]; then
@@ -104,9 +107,6 @@ declare -x _GO_CMD_NAME=
 # string with the arguments delimited by the ASCII NUL character ($'\0').
 declare -x _GO_CMD_ARGV=
 
-# The URL of the framework's original source repository.
-declare -r -x _GO_CORE_URL='https://github.com/mbland/go-script-bash'
-
 # The directory in which plugins are installed.
 declare _GO_PLUGINS_DIR=
 

lib/bats/assertions

@@ -24,17 +24,23 @@
 #     fail "output should not match: '$pattern'"
 #   fi
 #
-# Alternatively, write your own assertion functions starting with:
+# Alternatively, write your own assertion function with the following as the
+# first line:
 #
 #   set +o functrace
 #
-# and then make sure every return path calls:
+# and then make sure every return path ends with the following (possibly
+# followed by a `return` statement, if not at the end of the function):
 #
 #   return_from_bats_assertion "$return_status" "$BASH_SOURCE"
 #
 # You may wish to wrap `return_from_bats_assertion` in a local helper function
 # to avoid having to specify `$BASH_SOURCE` everywhere.
 #
+# Also note that if your assertion function calls other assertion functions, you
+# should call `set +o functrace` after every one of them. See the implementation
+# of `assert_lines_equal` for an example.
+#
 # The assertions borrow inspiration from rbenv/test/test_helper.bash.
 
 # Unconditionally returns a failing status

lib/log

@@ -21,7 +21,25 @@
 #   @go.setup_project
 #     Runs the project's 'setup' script and logs the result
 #
-# See the function comments for each of the above for further information.
+# The log level labels are formatted when output to a terminal, and formatting
+# can be forced when writing to a pipe or file by setting `_GO_LOG_FORMATTING`.
+#
+# `@go.log ERROR` will return an error code, so you may use it in conditional
+# statements. `@go.log FATAL` will exit the process.
+#
+# You can pass entire commands to the `@go.log_command` function, which will
+# provide log messages upon startup and completion. Upon error, it will log the
+# status and return an error code, so you may use it in conditional statements.
+# Wrapping blocks of `@go.log_command` invocations in
+# `@go.critical_section_begin` and `@go.critical_section_end` will cause any
+# errors to log `FATAL`. Setting `_GO_DRY_RUN` will log the commands without
+# executing them.
+#
+# The `@go.setup_project` function provides a convenient wrapper for running
+# first-time project setup scripts. It logs the start and finish of the setup
+# script, and provides helpful hints on running the `./go` script upon success.
+#
+# See the function and variable comments from this file for further information.
 
 # Set this if you want to force terminal-formatted output from @go.log.
 #
@@ -229,6 +247,10 @@ declare __GO_CRITICAL_SECTION=0
 # the critical section flag will be shared between parent and child Bash
 # scripts.
 #
+# Globals:
+#   _GO_DRY_RUN:           Will log commands without running them
+#   __GO_CRITICAL_SECTION: Will log FATAL on error
+#
 # Arguments:
 #   $@: The command and its arguments to log and execute
 @go.log_command() {

tests/vars.bats

@@ -35,6 +35,7 @@ quotify_expected() {
     'declare -ax _GO_CMD_NAME=([0]="vars")'
     "declare -rx _GO_CORE_DIR=\"$_GO_CORE_DIR\""
     "declare -rx _GO_CORE_URL=\"$_GO_CORE_URL\""
+    "declare -rx _GO_CORE_VERSION=\"$_GO_CORE_VERSION\""
     'declare -a _GO_IMPORTED_MODULES=()'
     'declare -- _GO_PLUGINS_DIR=""'
     'declare -a _GO_PLUGINS_PATHS=()'
@@ -77,6 +78,7 @@ quotify_expected() {
     'declare -ax _GO_CMD_NAME=([0]="test-command" [1]="test-subcommand")'
     "declare -rx _GO_CORE_DIR=\"$_GO_CORE_DIR\""
     "declare -rx _GO_CORE_URL=\"$_GO_CORE_URL\""
+    "declare -rx _GO_CORE_VERSION=\"$_GO_CORE_VERSION\""
     'declare -a _GO_IMPORTED_MODULES=([0]="complete" [1]="format")'
     "declare -- _GO_PLUGINS_DIR=\"$TEST_GO_PLUGINS_DIR\""
     "declare -a _GO_PLUGINS_PATHS=(${plugins_paths[*]})"
@@ -112,6 +114,7 @@ quotify_expected() {
     "_GO_CMD_NAME: test-command"$'\0'"test-subcommand" \
     "_GO_CORE_DIR: $_GO_CORE_DIR" \
     "_GO_CORE_URL: $_GO_CORE_URL" \
+    "_GO_CORE_VERSION: $_GO_CORE_VERSION" \
     "_GO_ROOTDIR: $TEST_GO_ROOTDIR" \
     "_GO_SCRIPT: $TEST_GO_SCRIPT"
 }