b3bp sourced mode (#61)

If main.sh is being sourced instead of being executed it respects the
variables __usage and __helptext being defined beforehand. Its behaviour
will depend on the sourcing script. If __usage is defined but empty no
argument parsing is done. If __helptext is defined but empty no helptext
will be shown.

Logging support still exists as it did before. The environment variables
LOG_LEVEL and NO_COLOR are supported just as they were before.

example.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# This file:
+#
+#  - Demos BASH3 Boilerplate (change this for your script)
+#
+# Usage:
+#
+#  LOG_LEVEL=7 ./example.sh -f /tmp/x -d (change this for your script)
+#
+# Based on a template by BASH3 Boilerplate v2.1.0
+# http://bash3boilerplate.sh/#authors
+#
+# The MIT License (MIT)
+# Copyright (c) 2013 Kevin van Zonneveld and contributors
+# You are not obligated to bundle the LICENSE file with your b3bp projects as long
+# as you leave these references intact in the header comments of your source files.
+
+
+### BASH3 Boilerplate (b3bp) Header
+##############################################################################
+
+# Commandline options. This defines the usage page, and is used to parse cli
+# opts & defaults from. The parsing is unforgiving so be precise in your syntax
+# - A short option must be preset for every long option; but every short option
+#   need not have a long option
+# - `--` is respected as the separator between options and arguments
+# - We do not bash-expand defaults, so setting '~/app' as a default will not resolve to ${HOME}.
+#   you can use bash variables to work around this (so use ${HOME} instead)
+
+read -r -d '' __usage <<-'EOF' || true # exits non-zero when EOF encountered
+  -f --file  [arg] Filename to process. Required.
+  -t --temp  [arg] Location of tempfile. Default="/tmp/bar"
+  -v               Enable verbose mode, print script as it is executed
+  -d --debug       Enables debug mode
+  -h --help        This page
+  -n --no-color    Disable color output
+  -1 --one         Do just one thing
+EOF
+
+read -r -d '' __helptext <<-'EOF' || true # exits non-zero when EOF encountered
+ This is Bash3 Boilerplate's help text. Feel free to add any description of your
+ program or elaborate more on command-line arguments. This section is not
+ parsed and will be added as-is to the help.
+EOF
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/main.sh"
+
+
+### Command-line argument switches (like -d for debugmode, -h for showing helppage)
+##############################################################################
+
+# debug mode
+if [ "${arg_d}" = "1" ]; then
+  set -o xtrace
+  LOG_LEVEL="7"
+fi
+
+# verbose mode
+if [ "${arg_v}" = "1" ]; then
+  set -o verbose
+fi
+
+# no color mode
+if [ "${arg_n}" = "1" ]; then
+  NO_COLOR="true"
+fi
+
+# help mode
+if [ "${arg_h}" = "1" ]; then
+  # Help exists with code 1
+  help "Help using ${0}"
+fi
+
+
+### Validation. Error out if the things required for your script are not present
+##############################################################################
+
+[ -z "${arg_f:-}" ] && help "Setting a filename with -f or --file is required"
+[ -z "${LOG_LEVEL:-}" ] && emergency "Cannot continue without LOG_LEVEL. "
+
+
+### Runtime
+##############################################################################
+
+function cleanup_before_exit () {
+  info "Cleaning up. Done"
+}
+trap cleanup_before_exit EXIT
+
+info "__file: ${__file}"
+info "__dir: ${__dir}"
+info "__base: ${__base}"
+info "OSTYPE: ${OSTYPE}"
+
+info "arg_f: ${arg_f}"
+info "arg_d: ${arg_d}"
+info "arg_v: ${arg_v}"
+info "arg_h: ${arg_h}"
+
+info "$(echo -e "multiple lines example - line #1\nmultiple lines example - line #2\nimagine logging the output of 'ls -al /path/'")"
+
+# All of these go to STDERR, so you can use STDOUT for piping machine readable information to other software
+debug "Info useful to developers for debugging the application, not useful during operations."
+info "Normal operational messages - may be harvested for reporting, measuring throughput, etc. - no action required."
+notice "Events that are unusual but not error conditions - might be summarized in an email to developers or admins to spot potential problems - no immediate action required."
+warning "Warning messages, not an error, but indication that an error will occur if action is not taken, e.g. file system 85% full - each item must be resolved within a given time. This is a debug message"
+error "Non-urgent failures, these should be relayed to developers or admins; each item must be resolved within a given time."
+critical "Should be corrected immediately, but indicates failure in a primary system, an example is a loss of a backup ISP connection."
+alert "Should be corrected immediately, therefore notify staff who can fix the problem. An example would be the loss of a primary ISP connection."
+emergency "A \"panic\" condition usually affecting multiple apps/servers/sites. At this level it would usually notify all tech staff on call."

main.sh

@@ -26,9 +26,19 @@ set -o pipefail
 # Turn on traces, useful while debugging but commented out by default
 # set -o xtrace
 
+if [ "${BASH_SOURCE[0]}" != "${0}" ]; then
+  if [ ! -z ${__usage+x} ]; then
+    __b3bp_external_usage="true"
+    __b3bp_tmp_source_idx=1
+  fi
+else
+  [ ! -z ${__usage+x} ] && unset __usage
+  [ ! -z ${__helptext+x} ] && unset __helptext
+fi
+
 # Set magic variables for current file, directory, os, etc.
-__dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-__file="${__dir}/$(basename "${BASH_SOURCE[0]}")"
+__dir="$(cd "$(dirname "${BASH_SOURCE[${__b3bp_tmp_source_idx:-0}]}")" && pwd)"
+__file="${__dir}/$(basename "${BASH_SOURCE[${__b3bp_tmp_source_idx:-0}]}")"
 __base="$(basename ${__file} .sh)"
 
 # Define the environment variables (and their defaults) that this script depends on
@@ -93,11 +103,6 @@ function help () {
   exit 1
 }
 
-function cleanup_before_exit () {
-  info "Cleaning up. Done"
-}
-trap cleanup_before_exit EXIT
-
 
 ### Parse commandline options
 ##############################################################################
@@ -109,7 +114,7 @@ trap cleanup_before_exit EXIT
 # - `--` is respected as the separator between options and arguments
 # - We do not bash-expand defaults, so setting '~/app' as a default will not resolve to ${HOME}.
 #   you can use bash variables to work around this (so use ${HOME} instead)
-read -r -d '' __usage <<-'EOF' || true # exits non-zero when EOF encountered
+[ -z ${__usage+x} ] && read -r -d '' __usage <<-'EOF' || true # exits non-zero when EOF encountered
   -f --file  [arg] Filename to process. Required.
   -t --temp  [arg] Location of tempfile. Default="/tmp/bar"
   -v               Enable verbose mode, print script as it is executed
@@ -118,7 +123,7 @@ read -r -d '' __usage <<-'EOF' || true # exits non-zero when EOF encountered
   -n --no-color    Disable color output
   -1 --one         Do just one thing
 EOF
-read -r -d '' __helptext <<-'EOF' || true # exits non-zero when EOF encountered
+[ -z ${__helptext+x} ] && read -r -d '' __helptext <<-'EOF' || true # exits non-zero when EOF encountered
  This is Bash3 Boilerplate's help text. Feel free to add any description of your
  program or elaborate more on command-line arguments. This section is not
  parsed and will be added as-is to the help.
@@ -223,6 +228,15 @@ done
 unset __tmp_varname
 
 
+### Externally supplied __usage. Nothing else to do here
+##############################################################################
+
+if [ "${__b3bp_external_usage:-}" = "true" ]; then
+  unset __b3bp_external_usage
+  return
+fi
+
+
 ### Command-line argument switches (like -d for debugmode, -h for showing helppage)
 ##############################################################################
 
@@ -259,6 +273,11 @@ fi
 ### Runtime
 ##############################################################################
 
+function cleanup_before_exit () {
+  info "Cleaning up. Done"
+}
+trap cleanup_before_exit EXIT
+
 info "__file: ${__file}"
 info "__dir: ${__dir}"
 info "__base: ${__base}"

test/fixture/main-help.stdio

@@ -14,4 +14,3 @@ ACCPTST:STDIO_REPLACE_DATETIMES
  program or elaborate more on command-line arguments. This section is not
  parsed and will be added as-is to the help.
 
-{datetime} UTC [     info] Cleaning up. Done