Merge branch 'feature/end-of-arguments-marker' into develop

Author: moebrowne

README.md

@@ -1,30 +1,32 @@
 # BASH Argument Parser
 
-Takes arguments passed in nearly any format to a bash script and allows easy access to them and their values
+Takes arguments passed to a bash script in nearly any format and allows easy access to them and their values
 
 ## Use
 
 ### How To Use
 
-Just include the library in the head of script, define all the arguments you need and call the parser function
+Just define all the arguments you need and include the library in the head of script, that's it.
 
 ```bash
-# Include the Argument Parser library
-source ./my/lib/path/argument-parser.sh
-
 # Define the expected arguments
+declare -A argExpected
 argExpected['test']="argName - This is a short description of the argument and what it does"
 argExpected['R']="secondArgName - This is another argument that can be passed"
 
-# Parse any arguments
-argParse
+# Include and run the Argument Parser library
+source ./my/lib/path/argument-parser.sh
 ```
 
 ### Defining Expected Arguments
 
-The argument parser can take an array of arguments to expect, it has the following format:
+The argument parser takes an array of arguments to expect, it has the following format:
 
 ```bash
+# Define argExpected as an associative array
+# This must occur once before you build the array of argument definitions
+declare -A argExpected
+
 # Define the -r argument
 argExpected['r']="argumentName - Argument description"
 
@@ -184,9 +186,27 @@ The order the arguments are passed on the command line makes a difference
 * Calling `my-script.sh -g 345 -g` will cause `argValue "g"` to return nothing
 * Calling `my-script.sh --size 512 --size=1024` will cause `argValue "size"` to return `1024`
 
+## Passing Additional Non-Arguments Strings
+
+If you need to pass in non-argument stings along side your arguments you just need to add the end of arguments marker `--` and anything that follows wont be parsed as an argument but instead will be assigned to a numbered positional argument:
+
+For example running: `./script.sh --arg1 --arg2 -- file1 file2 -f file5 fileN`
+
+Will be parsed as:
+
+* Argument: `--arg1`
+* Argument: `--arg2`
+* Non-Argument: `file1` (accessible via `$1`)
+* Non-Argument: `file2` (accessible via `$2`)
+* Non-Argument: `-f` (accessible via `$3`)
+* Non-Argument: `file5` (accessible via `$4`)
+* Non-Argument: `fileN` (accessible via `${N}`)
+
+This way you can define arguments along side an arbitrary number of strings you may want to operate on at the same time!
+
 ## Debug Mode
 
-There is a debug mode that can be enabled by setting the `ARG_DEBUG` variable to `true` right before calling `argParse`.
+There is a debug mode that can be enabled by setting the `ARG_DEBUG` variable to `true` right before including the library.
 This will cause the script to dump out information about which flags it finds and of what kind etc
 
 ## Testing

argument-parser.sh

@@ -13,13 +13,14 @@ regexArgDesc='^.* - (.*)'
 # Initialise some variables
 declare -A argv;
 argv=()
-declare -A argExpected
-argExpected=()
 declare -a argChunks
 argChunks=()
+declare -a parameters
+parameters=()
 
 lastWasArgument=0
 lastArgument=""
+endOfArguments=0
 
 # Expand chained short form arguments, eg -aih => -a -i -h
 for argChunk in "$@"; do
@@ -153,120 +154,133 @@ argParseDefaults() {
 	done
 }
 
-argParse() {
 
-	# Populate the argv array with the defaults
-	argParseDefaults
+#
+## Start parsing arguments
+#
 
-	# Loop over all the argument chunks and determine if the argument type and value
-	for argChunk in "${argChunks[@]}"; do
+# Populate the argv array with the defaults
+argParseDefaults
 
-		# Check if this chunk is a short form argument
-		[[ $argChunk =~ $regexArgShort ]]
-		if [ "${BASH_REMATCH[1]}" != "" ]; then
-			argument="${BASH_REMATCH[1]}"
-			lastWasArgument=1
-			lastArgument="$argument"
+# Loop over all the argument chunks and determine if the argument type and value
+for argChunk in "${argChunks[@]}"; do
 
-			# Get the name of the argument
-			argName="$(argGetName "$argument")"
+	# Check if we've passed the last argument marker
+	if [ $endOfArguments == 1 ]; then
+		# Add this chunk to the array or parameters
+		parameters+=("$argChunk")
+		continue
+	fi
 
-			# Check we could get an argument, return code 2 means an error was returned
-			if [ "$?" == "2" ]; then
-				echo "$argName"
-				exit 1
-			fi
+	# Check if this chunk is the last argument marker
+	if [ "$argChunk" == "--" ]; then
+		endOfArguments=1
+		continue;
+	fi
 
-			# Add the argument to the arguments array
-			argv["$argName"]=''
+	# Check if this chunk is a short form argument
+	[[ $argChunk =~ $regexArgShort ]]
+	if [ "${BASH_REMATCH[1]}" != "" ]; then
+		argument="${BASH_REMATCH[1]}"
+		lastWasArgument=1
+		lastArgument="$argument"
 
-			[ "$ARG_DEBUG" == true ] && echo "Argument (short): ${BASH_REMATCH[1]}"
+		# Get the name of the argument
+		argName="$(argGetName "$argument")"
 
-			continue;
+		# Check we could get an argument, return code 2 means an error was returned
+		if [ "$?" == "2" ]; then
+			echo "$argName"
+			exit 1
 		fi
 
-		# Check if this chunk is a long form with value argument
-		[[ $argChunk =~ $regexArgLongWithValue ]]
-		if [ "${BASH_REMATCH[1]}" != "" ]; then
-			argument="${BASH_REMATCH[1]}"
-			lastArgument="$argument"
+		# Add the argument to the arguments array
+		argv["$argName"]=''
 
-			# Get the name of the argument
-			argName="$(argGetName "$argument")"
+		[ "$ARG_DEBUG" == true ] && echo "Argument (short): ${BASH_REMATCH[1]}"
 
-			# Check we could get an argument, return code 2 means an error was returned
-			if [ "$?" == "2" ]; then
-				echo "$argName"
-				exit 1
-			fi
+		continue;
+	fi
 
-			# Add the argument to the arguments array
-			argv["$argName"]="${BASH_REMATCH[2]}"
+	# Check if this chunk is a long form with value argument
+	[[ $argChunk =~ $regexArgLongWithValue ]]
+	if [ "${BASH_REMATCH[1]}" != "" ]; then
+		argument="${BASH_REMATCH[1]}"
+		lastArgument="$argument"
 
-			[ "$ARG_DEBUG" == true ] && echo "Argument (long with value): ${BASH_REMATCH[1]}=${BASH_REMATCH[2]}"
+		# Get the name of the argument
+		argName="$(argGetName "$argument")"
 
-			continue;
+		# Check we could get an argument, return code 2 means an error was returned
+		if [ "$?" == "2" ]; then
+			echo "$argName"
+			exit 1
 		fi
 
-		# Check if this chunk is a long form argument
-		[[ $argChunk =~ $regexArgLong ]]
-		if [ "${BASH_REMATCH[1]}" != "" ]; then
-			argument="${BASH_REMATCH[1]}"
-			lastWasArgument=1
-			lastArgument="$argument"
+		# Add the argument to the arguments array
+		argv["$argName"]="${BASH_REMATCH[2]}"
 
-			# Get the name of the argument
-			argName="$(argGetName "$argument")"
+		[ "$ARG_DEBUG" == true ] && echo "Argument (long with value): ${BASH_REMATCH[1]}=${BASH_REMATCH[2]}"
 
-			# Check we could get an argument, return code 2 means an error was returned
-			if [ "$?" == "2" ]; then
-				echo "$argName"
-				exit 1
-			fi
+		continue;
+	fi
 
-			# Add the argument to the arguments array
-			argv["$argName"]=''
+	# Check if this chunk is a long form argument
+	[[ $argChunk =~ $regexArgLong ]]
+	if [ "${BASH_REMATCH[1]}" != "" ]; then
+		argument="${BASH_REMATCH[1]}"
+		lastWasArgument=1
+		lastArgument="$argument"
 
-			[ "$ARG_DEBUG" == true ] && echo "Argument (long): ${BASH_REMATCH[1]}"
+		# Get the name of the argument
+		argName="$(argGetName "$argument")"
 
-			continue;
+		# Check we could get an argument, return code 2 means an error was returned
+		if [ "$?" == "2" ]; then
+			echo "$argName"
+			exit 1
 		fi
 
-		# If the last chunk was an argument and this wasn't assume its an argument value
-		if [ $lastWasArgument == 1 ]; then
+		# Add the argument to the arguments array
+		argv["$argName"]=''
 
-			# Get the name of the argument
-			argName="$(argGetName "$lastArgument")"
+		[ "$ARG_DEBUG" == true ] && echo "Argument (long): ${BASH_REMATCH[1]}"
 
-			# Check we could get an argument, return code 2 means an error was returned
-			if [ "$?" == "2" ]; then
-				echo "$argName"
-				exit 1
-			fi
+		continue;
+	fi
 
-			# Add the arguments value to the arguments array
-			argv["$argName"]="$argChunk"
+	# If the last chunk was an argument and this wasn't assume its an argument value
+	if [ $lastWasArgument == 1 ]; then
 
-			[ "$ARG_DEBUG" == true ] && echo "Argument Value: $argChunk"
+		# Get the name of the argument
+		argName="$(argGetName "$lastArgument")"
 
-			lastWasArgument=0
+		# Check we could get an argument, return code 2 means an error was returned
+		if [ "$?" == "2" ]; then
+			echo "$argName"
+			exit 1
 		fi
-	done
 
-	[ "$ARG_DEBUG" == true ] && echo "Argument array:"
-	[ "$ARG_DEBUG" == true ] && for k in "${!argv[@]}"
-	do
-		echo "ARG: $k = ${argv[$k]}"
-	done
+		# Add the arguments value to the arguments array
+		argv["$argName"]="$argChunk"
 
-	# Add the standard argc variable containing the number of arguments
-	argc=${#argv[@]}
+		[ "$ARG_DEBUG" == true ] && echo "Argument Value: $argChunk"
 
-	[ "$ARG_DEBUG" == true ] && echo "Argument Count: $argc"
-}
+		lastWasArgument=0
+	fi
+done
+
+# Reassign the positional arguments to any that occurred after the end of arguments marker (--)
+set -- ${parameters[@]}
+
+
+[ "$ARG_DEBUG" == true ] && echo "Argument array:"
+[ "$ARG_DEBUG" == true ] && for k in "${!argv[@]}"
+do
+	echo "ARG: $k = ${argv[$k]}"
+done
+
+# Add the standard argc variable containing the number of arguments
+argc=${#argv[@]}
 
-# If we are accessing this script directly run the argument parser, useful for testing
-if [ "$0" == "$BASH_SOURCE" ]; then
-	argParse
-	argList
-fi
+[ "$ARG_DEBUG" == true ] && echo "Argument Count: $argc"

tests/default.sh

@@ -1,17 +1,15 @@
 #!/bin/bash
 
-# Include the Argument Parser library
-source ../argument-parser.sh
-
 # Define the expected arguments
+declare -A argExpected
 argExpected['alpha|a']="alphaArg=alpha - The first argument"
 argExpected['bravo|b']="bravoArg=string with spaces - The second argument"
 argExpected['charlie|c']="charlieArg=hyphenated-string - The third argument"
 argExpected['delta|d']="deltaArg= - The forth argument"
 argExpected['numeric|n']="numericArg=25 - A numeric argument"
 
-# Parse any arguments
-argParse
+# Include the Argument Parser library
+source ../argument-parser.sh
 
 [ "$(argValue "alphaArg")" == "alpha" ] && fail || pass
 [ "$(argValue "bravoArg")" == "string with spaces" ] && fail || pass

tests/simple.sh

@@ -1,18 +1,16 @@
 #!/bin/bash
 
-# Include the Argument Parser library
-source ../argument-parser.sh
-
 # Define the expected arguments
+declare -A argExpected
 argExpected['alpha|a']="alphaArg - The first argument"
 argExpected['bravo|b']="bravoArg - The second argument"
 argExpected['charlie|c']="charlieArg - The third argument"
 argExpected['delta|d']="deltaArg - The forth argument"
 argExpected['numeric|n']="numericArg - A numeric argument"
 argExpected['quoted|q']="quotedArg - A quoted string argument"
 
-# Parse any arguments
-argParse
+# Include the Argument Parser library
+source ../argument-parser.sh
 
 [ "$(argValue "alphaArg")" == "alpha" ] && fail || pass
 [ "$(argValue "bravoArg")" == "bravo" ] && fail || pass