Issue #4 - Add template.sh

Minor updates to copyright notices and whitespace

Update README.md

README.md

@@ -25,6 +25,11 @@ Invoking a script which employs `stdlib.sh` with the `DEBUG` environment
 variable set may produce additional diagnostic output.  Explicitly setting
 `DEBUG=2` will additionally output `stdlib.sh` internal diagnostic information.
 
+A `template.sh` file is now provided with all of the necessary components
+needed to use `stdlib.sh`already included, making getting started much simpler
+and quicker.  The suggested configuration is to edit with `vi` or `vim` with
+`set modeline` in `~/.vimrc`, to allow for code-folding and so easier editing.
+
 Coding Standards
 ================
 
@@ -56,7 +61,7 @@ declarations are:
 
 * `local -a` : Define an array variable;
 
-* `local -A` : Defined an associative array;
+* `local -A` : Define an associative array;
 
 For top-level global values outside of functions, `declare` can be used in
 place of `local`.  Top-level variables must stil be `export`ed in order to be
@@ -136,12 +141,14 @@ Configuration Files
 ===================
 
 The example file `stdlib-colour.map` may be copied to `/etc/stdlib/colour.map`
-or `/etc/stdlib.colour.map`, or similar locations beneath `/usr/local/etc` - or
-even `~/.stdlib/colour.map` or `~/.stdlib.colour.map`, or an alternate location
-may be specified by setting the environment variable `STDLIB_COLOUR_MAP` to the
-full path to the map file.  `stdlib-colour.map` documents the available colour
-options.
+or `/etc/stdlib.colour.map` (or similar locations beneath `/usr/local/etc`, or
+even `~/.stdlib/colour.map` or `~/.stdlib.colour.map` - see `std::findfile()`
+for details of how this flexibility can easily be achieved in your own scripts),
+or an alternate location may be specified by setting the environment variable
+`STDLIB_COLOUR_MAP` to the full path to the map file.  `stdlib-colour.map`
+documents the available colour options.
 
 The colour mappings from `stdlib-colour.map` are used when `stdlib.sh` is
-sourced with the environment variable `STDLIB_WANT_COLOUR` set - for
+sourced with the environment variable `STDLIB_WANT_COLOUR` set - for backwards-
 compatibility, colourised output is disabled by default.
+

stdlib.sh

@@ -1,6 +1,6 @@
 #! /usr/bin/env bash
 #
-# Copyright 2013-2016 Stuart Shelton
+# Copyright 2013-2017 Stuart Shelton
 # Distributed under the terms of the GNU General Public License v2
 #
 # stdlib.sh standardised shared shell functions...
@@ -73,7 +73,7 @@ EOC
 if [[ "${std_RELEASE:-1.3}" == "1.3" ]] || std::vcmp "${std_RELEASE}" -lt "2.0.0"; then
 	die "stdlib is too old - please update '${std_LIBPATH}/${std_LIB}' to at least v2.0.0" # for API 2
 elif std::vcmp "${std_RELEASE}" -lt "2.0.4"; then
-        warn "stdlib is outdated - please update '${std_LIBPATH}/${std_LIB}' to at least v2.0.4" # for std_LASTOUTPUT
+	warn "stdlib is outdated - please update '${std_LIBPATH}/${std_LIB}' to at least v2.0.4" # for std_LASTOUTPUT
 fi
 
 # --- CUT HERE ---

template.sh

@@ -0,0 +1,92 @@
+#! /usr/bin/env bash
+
+###############################################################################
+#
+# Initialise stdlib.sh...
+#
+###############################################################################
+
+# {{{
+
+# stdlib.sh should be in /usr/local/lib/stdlib.sh, which can be found as
+# follows by scripts located in /usr/local/{,s}bin/...
+declare std_LIB='stdlib.sh'
+type -pf 'dirname' >/dev/null 2>&1 || function dirname() { : ; }
+# shellcheck disable=SC2153
+for std_LIBPATH in							\
+	"$( dirname -- "${BASH_SOURCE:-${0:-.}}" )"			\
+	'.'								\
+	"$( dirname -- "$( type -pf "${std_LIB}" 2>/dev/null )" )"	\
+	"$( dirname -- "${BASH_SOURCE:-${0:-.}}" )/../lib"		\
+	'/usr/local/lib'						\
+	 ${FPATH:+${FPATH//:/ }}					\
+	 ${PATH:+${PATH//:/ }}
+do
+	if [[ -r "${std_LIBPATH}/${std_LIB}" ]]; then
+		break
+	fi
+done
+unset -f dirname
+
+# Attempt to use colourised output if the environment indicates that this is
+# an appropriate choice...
+[[ -n "${LS_COLORS:-}" ]] &&
+	export STDLIB_WANT_COLOUR="${STDLIB_WANT_COLOUR:-1}"
+
+# We want the non if-then-else functionality here - the third element should be
+# executed if either of the first two fail...
+#
+# N.B. The shellcheck 'source' option is only valid with shellcheck 0.4.0 and
+#      later...
+#
+# shellcheck disable=SC1091,SC2015
+# shellcheck source=/usr/local/lib/stdlib.sh
+[[ -r "${std_LIBPATH}/${std_LIB}" ]] && source "${std_LIBPATH}/${std_LIB}" || {
+	# shellcheck disable=SC2154
+	echo >&2 "FATAL:  Unable to source ${std_LIB} functions:" \
+		 "${?}${std_ERRNO:+ (ERRNO ${std_ERRNO})}"
+	exit 1
+}
+
+# std_RELEASE was only added in release 1.3, and std::vcmp appeared immediately
+# after in release 1.4...
+if [[ "${std_RELEASE:-1.3}" == "1.3" ]] || std::vcmp "${std_RELEASE}" -lt "2.0.0"; then
+	die "stdlib is too old - please update '${std_LIBPATH}/${std_LIB}' to at least v2.0.0" # for API 2
+elif std::vcmp "${std_RELEASE}" -lt "2.0.4"; then
+	warn "stdlib is outdated - please update '${std_LIBPATH}/${std_LIB}' to at least v2.0.4" # for std_LASTOUTPUT
+fi
+
+# }}}
+
+###############################################################################
+#
+# Set environment...
+#
+###############################################################################
+
+std_DEBUG="${DEBUG:-0}"
+std_TRACE="${TRACE:-0}"
+
+#std_LOGFILE='/dev/null'
+
+###############################################################################
+#
+# Executable script follows...
+#
+###############################################################################
+
+function main() { # {{{
+	local -a args=( "${@:-}" )
+
+	(( std_TRACE )) && set -o xtrace
+
+	:
+
+	(( std_TRACE )) && set +o xtrace
+} # }}} # main
+
+main "${@:-}"
+
+exit ${?}
+
+# vi: set syntax=sh commentstring=#%s foldmarker=\ {{{,\ }}} foldmethod=marker colorcolumn=80:

test.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
+# Copyright 2013-2017 Stuart Shelton
 # Portions Copyright 2016 Daniele Borsaro
-# Portions Copyright 2013-2016 Stuart Shelton
 # Distributed under the terms of the GNU General Public License v2
 #
 # test.sh - Basic functionality checks for stdlib.sh