Merge pull request #155 from mbland/template

Add go-template for bootstrapping ./go scripts

Author: mbland

README.md

@@ -206,12 +206,29 @@ If you do not see this, follow the instructions in the [Installing
 Bash](#installing-bash) section later in this document.
 
 __Note: While Bash is required to run this framework, your individual command
-scripts can be in any other interpreted language.__
+scripts can be in any other interpreted language installed on the host system.__
 
 ### How to use this framework
 
 First you'll need a copy of this framework available in your project sources.
-Archives are available at:
+The most expedient way to bootstrap your program is to use the [`go-template`
+file](https://github.com/mbland/go-script-bash/blob/master/go-template) as a
+starting point (replacing `curl` with `wget`, `fetch`, or whichever tool you
+prefer):
+
+```bash
+$ curl https://raw.githubusercontent.com/mbland/go-script-bash/master/go-template >./go
+$ chmod ugo+rx ./go
+```
+
+You may rename this file whatever you wish (i.e. it doesn't have to be named
+`./go`), update its documentation and variables to fit your project, and check
+it into your project repository. See the `go-template` comments for details.
+
+If you'd prefer to download a copy of the framework and check it into your
+sources, versioned archives are available from the [go-script-bash Releases
+page](https://github.com/mbland/go-script-bash/releases). The archives for the
+current release are:
 
 - https://github.com/mbland/go-script-bash/archive/v1.3.0.tar.gz
 - https://github.com/mbland/go-script-bash/archive/v1.3.0.zip
@@ -228,21 +245,24 @@ $ git submodule update --init
 where `<target-dir>` is any point inside your project directory structure that
 you prefer.
 
-Then 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, respectively:
+If you're not using `go-template`, 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 lines, with `@go "$@"` as the last line
+of the script:
 
 ```bash
 . "${0%/*}/go-core.bash" "scripts"
 @go "$@"
 ```
 
 where:
-- `"${0%/*}"` produces the path to the project's root directory
-- `go-core.bash` is the path to the file of the same name imported from this
-repository
+- `${0%/*}` produces the path to the project's root directory based on the path
+  to the `./go` script
+- `${0%/*}/go-core.bash` produces the path to the framework's `go-core.bash`
+  file within your project's copy of the framework (adjusted to reflect where
+  your copy of `go-script-bash` actually resides)
 - `scripts` is the path to the directory holding your project's command scripts
-  relative to the project root
+  relative to the project root (it can be any name you like)
 
 #### Directory structure
 
@@ -489,8 +509,8 @@ need the following utilities installed:
 - `tput` (ncurses) on Linux, OS X, UNIX
 - `mode.com` should be present on Windows
 
-To use the `get` builtin, the `curl`, `wget`, and `git` programs must be
-installed on your system.
+To use the `get file` builtin, either `curl`, `wget`, or `fetch` must be
+installed on your system. `get git-repo` requires `git`, naturally.
 
 ### Open Source License
 

go-template

@@ -0,0 +1,55 @@
+#! /usr/bin/env bash
+#
+# Template for a Bash program based on the go-script-bash framework
+#
+# You should replace this comment with your own program's high-level
+# description. You may remove any other comments from this template as well.
+#
+# This template automatically checks for the presence of the go-script-bash
+# sources and makes a shallow clone of the the go-script-bash repository if
+# necessary before dispatching commands. (If you prefer, you can change the
+# logic to create a regular clone instead.) This allows users to set up the
+# framework without taking any extra steps when running the command for the
+# first time, without the need to commit the framework to your repository.
+#
+# Alternatively, you can make the `GO_SCRIPT_BASH_REPO_URL` a Git submodule of
+# your project or check in a versioned copy of the sources. See the "How to use
+# this framework" section of `README.md` for details.
+#
+# Make sure the `_GO_STANDALONE`, `SCRIPTS_DIR`, and `GO_SCRIPT_BASH_VERSION`
+# variables within this script are configured as necessary for your program.
+# You can also add any other initialization or configuration logic between:
+#
+#   . "$_GO_SCRIPT_BASH_CORE" "${SCRIPTS_DIR##*/}"`
+#   `@go "$@"`
+
+# Set `_GO_STANDALONE='true'` if your program isn't a project-specific script.
+readonly _GO_STANDALONE=
+
+# Set SCRIPTS_DIR to the path where your command scripts reside.
+#
+# For `_GO_STANDALONE` programs and plugins containing command scripts, you may
+# wish to set SCRIPTS_DIR to end with `bin` and have a separate `./go` script to
+# manage project tasks that finds its command scripts in `scripts`.
+readonly SCRIPTS_DIR="${0%/*}/scripts"
+
+# Set this to the `GO_SCRIPT_BASH_REPO_URL` tag or branch you wish to use.
+readonly GO_SCRIPT_BASH_VERSION='v1.3.0'
+
+readonly GO_SCRIPT_BASH_CORE="$SCRIPTS_DIR/go-script-bash/go-core.bash"
+readonly GO_SCRIPT_BASH_REPO_URL='https://github.com/mbland/go-script-bash.git'
+
+if [[ ! -e "$GO_SCRIPT_BASH_CORE" ]]; then
+  printf "Cloning framework from '%s'...\n" "$GO_SCRIPT_BASH_REPO_URL"
+  if ! git clone --depth 1 -c advice.detachedHead=false \
+      -b "$GO_SCRIPT_BASH_VERSION" "$GO_SCRIPT_BASH_REPO_URL" \
+      "${GO_SCRIPT_BASH_CORE%/*}"; then
+    printf "Failed to clone '%s'; aborting.\n" "$GO_SCRIPT_BASH_REPO_URL" >&2
+    exit 1
+  fi
+  printf "Clone of '%s' successful.\n\n" "$GO_SCRIPT_BASH_REPO_URL"
+fi
+
+. "$GO_SCRIPT_BASH_CORE" "${SCRIPTS_DIR##*/}"
+# Add any other configuration or initialization steps here.
+@go "$@"

tests/template.bats

@@ -0,0 +1,84 @@
+#! /usr/bin/env bats
+
+load environment
+
+# By default, the test will try to clone its own repo to avoid flakiness due to
+# an external dependency. However, doing so causes a failure on Travis, since it
+# uses shallow clones to produce test runs, resulting in the error:
+#
+#   fatal: attempt to fetch/clone from a shallow repository
+#
+# However, since Travis already depends on having a good connection to GitHub,
+# we'll use the real URL. Alternatively, `git` could be stubbed out via
+# `stub_program_in_path` from `_GO_CORE_DIR/lib/bats/helpers`, but the potential
+# for neither flakiness nor complexity seems that great, and this approach
+# provides extra confidence that the mechanism works as advertised.
+#
+# A developer can also run the test locally against the real URL by setting
+# `TEST_USE_REAL_URL` on the command line. The value of `GO_CORE_URL` is
+# subsequently displayed in the name of the test case to validate which repo is
+# being used during the test run.
+TEST_USE_REAL_URL="${TEST_USE_REAL_URL:-$TRAVIS}"
+GO_CORE_URL="${TEST_USE_REAL_URL:+$_GO_CORE_URL}"
+GO_CORE_URL="${GO_CORE_URL:-$_GO_CORE_DIR}"
+
+setup() {
+  test_filter
+  mkdir "$TEST_GO_ROOTDIR"
+
+  if [[ -e "$GO_CORE_URL/.git/shallow" ]]; then
+    skip "Can't clone shallow repositories"
+  fi
+}
+
+teardown() {
+  @go.remove_test_go_rootdir
+}
+
+create_template_script() {
+  local repo_url="$1"
+  local version="$2"
+  local template="$(< "$_GO_CORE_DIR/go-template")"
+  local replacement
+
+  if [[ "$template" =~ GO_SCRIPT_BASH_REPO_URL=[^$'\n']+ ]]; then
+    replacement="GO_SCRIPT_BASH_REPO_URL='$repo_url'"
+    template="${template/${BASH_REMATCH[0]}/$replacement}"
+  fi
+  if [[ "$template" =~ GO_SCRIPT_BASH_VERSION=[^$'\n']+ ]]; then
+    replacement="GO_SCRIPT_BASH_VERSION='$version'"
+    template="${template/${BASH_REMATCH[0]}/$replacement}"
+  fi
+  printf '%s\n' "$template" > "$TEST_GO_ROOTDIR/go-template"
+  chmod 700 "$TEST_GO_ROOTDIR/go-template"
+}
+
+@test "$SUITE: clone the go-script-bash repository from $GO_CORE_URL" {
+  create_template_script "$GO_CORE_URL" "$_GO_CORE_VERSION"
+  run "$TEST_GO_ROOTDIR/go-template"
+
+  # Without a command argument, the script will print the top-level help and
+  # return an error, but the core repo should exist as expected.
+  assert_failure
+  assert_output_matches "Cloning framework from '$GO_CORE_URL'\.\.\."
+
+  # Use `.*/scripts/go-script-bash` to account for the fact that `git clone` on
+  # MSYS2 will output `C:/Users/<user>/AppData/Local/Temp/` in place of `/tmp`.
+  assert_output_matches "Cloning into '.*/scripts/go-script-bash'\.\.\."
+  assert_output_matches "Clone of '$GO_CORE_URL' successful\."$'\n\n'
+  assert_output_matches "Usage: $TEST_GO_ROOTDIR/go-template <command>"
+  [[ -f "$TEST_GO_ROOTDIR/scripts/go-script-bash/go-core.bash" ]]
+
+  cd "$TEST_GO_ROOTDIR/scripts/go-script-bash"
+  run git log --oneline -n 1
+  assert_success
+  assert_output_matches "go-script-bash $_GO_CORE_VERSION"
+}
+
+@test "$SUITE: fail to clone a nonexistent repo" {
+  create_template_script 'bogus-repo-that-does-not-exist'
+  run "$TEST_GO_ROOTDIR/go-template"
+  assert_failure "Cloning framework from 'bogus-repo-that-does-not-exist'..." \
+    "fatal: repository 'bogus-repo-that-does-not-exist' does not exist" \
+    "Failed to clone 'bogus-repo-that-does-not-exist'; aborting."
+}