NAME:
	get_options.sh
 PURPOSE:
	Parses command line options for a bash script
 CATEGORY:
	general/bash
 CALLING SEQUENCE:
	get_options $*
 INPUTS:
	$*			all cmd line arguments
 OUTPUTS:
	One variable for each of the options defined in array __OPTION__.
	Variable __ARGV__ contains everything that was not interpreted
	as an option. The same list of arguments is stored in array
	__ARGS__, but to be available to caller it must be declared
	explicitly with 'declare -A ___ARGS__'
 EXAMPLE:
	. get_options.sh
	__MESSAGE__="Version 2.11 --- Paul Hick (UCSD/CAIDA; pphick@caida.org) --- 16-Jul-2012"
	__OPTION__=(	\
		[--dummy]=bool-DUMMY	\
	)
	__DESCRIPTION__=( \
		[--dummy]="dummy description"	\
	)
   __USAGE_MESSAGE__=(
      "Usage: `basename $0` [options] <args>"         \
        "FILESET is fileset name"                     \
        "'`basename $0` --options ' list of options"  \
        "'`basename $0` --help ' displays help"       \
   )
	get_options $*
	unset get_options

	Variables set by user prior to calling get_options:
	__CMD_LINE_LOG__
					if set to a valid filename than a single line is added
					containing a timestamp and the full cmd line.
	__DEPTH_CHARGE__		see PROCEDURE
	__NO_ABBREVIATIONS__	see PROCEDURE

	Variables set by get_options:
	__NARGS__		number of non-key arguments (i.e. ${#__ARGS__[@]})
	__ARGS__		array with non-key arguments
	__ARGV__		all non-key arguments as single string (seperated by space)
	__NKEYS__		number of keys set on the command line

	Access individual arguments of __ARGS__ with:
		ARGV1="${__ARGS__[0]}"
		ARGV2="${__ARGS__[1]}"

 PROCEDURE:
	Short and long options can be combined as

		[-X,--word-x --word-y]=type-VAR_NAME_X:DEFAULT::RESTRICTIONS

	The short option is optional. There must be at least one long
	option present. Although not strictly necessary, it is
	recommended to use only one short option, and put it at the
	start of the definition as shown above] (this will ensure an
	orderly display of options with the --options keyword).

	The entry between brackets (-X,--letter-x) and the name following the
	equal sign (VAR_NAME_X or bool-VAR_NAME_X) are mandatory. The components
	following the single colon (DEFAULT) and double colon (RESTRICTIONS)
	are optional.

	The entry between brackets is the cmd line option as specified
	when calling the command (for one-letter options it is permitted
	to concatenate, i.e. '-xyz' is the same as '-x -y -z').

	The entry VAR_NAME_X is the name of a bash variable that will be set.

	The "type" prefix can be set to 'bool', 'integer', 'array', 'string'
	or can be left undefined. An undefined type is the same as 'string'.

	'bool' indicates a boolean option (i.e. an option that is 'off' by default,
	and 'on' only if specified on the cmd line. Boolean options cannot be given
	an explicit value through the cmd line: the bash variable will always
	exist and will be set to 0 (not set, 'off') or 1 (set, 'on').

	'integer' indicates an integer option. In this case the input value will be
	explicitly tested to be a numerical value. The DEFAULT and RESTRICTIONS
	(if specified) must also be integer.

	'array' indicates an array variable, and is set using a list of key, value
	pairs for an associative array, or (TODO) as a list of values only for
	a regular array.

	The entry DEFAULT is an optional default value for VAR_NAME_X if it is not
	specified. For boolean options the default is ignored.
	If the default specification is omitted then VAR_NAME_X will not be touched 
	if the corresponding option is not present on the cmd line. This means that
	another way to set a default is to set VAR_NAME_X before calling get_options.

	The entry RESTRICTIONS represents a restriction on the allowed value of the
	key. This can be an integer range specified as a pair of integers separated
	by a colon, e.g. '1:5'. The lower limit can be set to -Inf to indicate that
	no limit exists (e.g. -Inf:-5); similarly the upper limit can be set to +Inf
	(e.g. 5:+Inf). Note that -Inf:+Inf is the same as not specifying a range.

	Instead of a colon, a dash will also work if both upper and lower limit
	are positive definite. -Inf and +Inf are not allowed if a dash is used
	(this in only supported for backward compatibility, and should not be used).

	Alternatively, it can be a set of strings specified
	as a comma-separated list, e.g. 'one,two,three'. An 'exit 1' is executed
	if the input value does not match the restriction.

	In addition to VAR_NAME the variable var_name (lowercase) is set to the
	string used on the cmd line to invoke the option, e.g. if --help is used
	the the bash variable help="--help" is set.

	Two types of options are common:
	'-x', '--letter-x'
		boolean on/off switches get an implicit ON value of 1, and must
		be defined as [-X]=bool-VAR_NAME_X.
		VAR_NAME_X will be 1 (on) if -x is set, or 0 (off) if not

	'-x value', '-x=value', '--letter-x value', '--letter-x=value'
		Usually defined as [-X]=VAR_NAME_X
		VAR_NAME_X is set to the string 'value'. If the option is not used,
		then VAR_NAME_X will be undefined.

	Array variables are specified as:
	'--array key1:value1,key2:value2,key3:value3'
		Defined as [--array]=array-VAR_NAME_X
		VAR_NAME_X is set using the specified key,value pairs
			VAR_NAME_X[key1]=value1   , etc.
		Note that the array needs to be declared explicitly using
			declare -A VAR_NAME_X
		(this is due to a limitation in scope for bash arrays, I think)

	Putting -- (double-dash, followed by a space) on the cmd line will
	terminate the search for options. Everything after the double-dash
	ends up in __ARGV__

	There are five 'reserved' options which are always available:
	-o,--options    prints a list of available options.
                   Sets variable __OPTIONS__
	-h,--help       print the documentation header (everything between
	                lines "#+" and "#-").
	                Sets variable __HELP__
	-n,--dry-run    can be used to define a 'dry run'
	                Sets variable DRYRUN
	   --debug <n>  verbose output
	                Sets variable DEBUG
	-v,--verbose    verbose output; same as --debug 1
	                Sets variable VERBOSE
	-V,--version    prints the version message in __MESSAGE__
	                Sets variable __VERSION__
	--timetag <s>   sets time format for "tiny message" functions
			Sets variable __TIME_TAG__

	--debug is an integer option; the other four are boolean.

	By default, unrecognized options results in an abort, with an error
	message pointing out the error.

	Instead of aborting it is possible to collect these unrecognized
	options in a single variable. To activate this option set
		__DEPTH_CHARGE__=1
	prior to calling get_options. The unrecognized variables are then
	collected in __depth_charge__. In theory this could be passed as
	argument to a called script.
	This is still experimental, so use at your own risk !!

	By default cmd-line keywords can be abbreviated, as long as the
	abbreviations identifies a unique keyword. To override, and force
	that keywords must be completely specified set:
		__NO_ABBREVIATIONS__=1

 MODIFICATION HISTORY:
	JUL-2011, Paul Hick (UCSD/CAIDA)
	AUG-2011, Paul Hick (UCSD/CAIDA)
		Added -v (--verbose) as "reserved" option.
		Substantial rewrite to remove restriction on providing defaults
		for non-boolean options.
		Added test for presence of reserved options
	JUN-2012, Paul Hick (UCSD/CAIDA)
		Added array __ARGS__ for easier access to remaining
		(unprocessed) cmd line arguments.
		--options now prints a list of options sorted alphabetically
	SEP-2012, Paul Hick (UCSD/CAIDA)
		Added capability to limit input values for keys to a specific
		set of strings, or range of integers.
	OCT-2012, Paul Hick (UCSD/CAIDA)
		Added __DEPTH_CHARGE__ option to capture unrecognized options
		into the variable __depth_charge__
	JAN-2013, Paul Hick (UCSD/CAIDA)
		Added code to options_set_key to allow for abbreviation
		of cmd line arguments. __NO_ABBREVIATIONS__ can be set to suppress
		this (in which case keywords must match exactly).
		Added reserved option DEBUG
		Added tiny_* echo routines.
		Fair amount of changes to handle number of patological inputs.
		Long options are now mandatory; a single short option can
		be used alongside a long option.
	JAN-2014, Paul Hick (UCSD/CAIDA)
		Generalized specification of range for integer key to allow
		negative values, and non-existing lower (-Inf) and upper
		limits (+Inf).
	MAY-2013, Paul Hick (UCSD/CAIDA)
		Some clean up by unsetting some unused variables at the end of
		get_options.
		Finally found a solution to consistenly pick up quoted,
		multiword command line arguments (see __CMD_LINE_PIECES__)
	MAY-2014,  Paul Hick (UCSD/CAIDA)
		Improved processing of array keywords.
	APR-2015,  Paul Hick (UCSD/CAIDA)
		Expanded initialiation (with . get_options). Renamed a number
		of global variables.
	AUG-2018,  Paul Hick (UCSD/CAIDA)
		Bug fix: failed to process null-string cmd line args correctly.
	SEP-2018, Paul Hick (UCSD/CAIDA; pphick@caida.org)
		Added check for already existing control variables as set by caller.

 NAME:
	goto
 PURPOSE:
	Mounting/unmounting of removable disks (floppy,cdrom,zip)
 CALLING SEQUENCE
	goto 'drive'
 RESTRICTIONS:
	'drive' must be listed in /etc/fstab
 PROCEDURE:
 >	After checking /etc/fstab, the mount command is piped
	through grep searching for 'drive'. If present the
	drive is mounted.
 >	When bash is the default shell aliases can be defined as:
		alias floppy=". goto floppy"
		alias cdrom=". goto cdrom"
		alias zip=". goto zip"
	(i.e. the script is sourced)
	In other shells (e.g. csh) the aliases need to be defined as
		alias floppy "$COM/goto floppy"
 >	If 'drive' is not mounted yet then it is mounted, and
	a 'cd' is made to the root directory 'drive'
 >	If 'drive' is mounted, then it is umounted. If the
	current directory is on 'drive' then a 'cd' is made
	to the previous working directory $OLDPWD. If this fails
	then a 'cd' to the user home directory follows.
 MODIFICATION HISTORY:
	FEB-2001, Paul Hick (UCSD/CASS)
	FEB-2003, Paul Hick (UCSD/CASS)
		Fixed problem detecting non-existing mount points
	FEB-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Instead of testing for "drive" test for "drive ".
		The added space should avoid problems when e.g.
		cdrom and cdrom1 exist.