BREAKING CHANGE: Update command name and options usage

Author: hyperupcall

README.md

@@ -14,11 +14,12 @@ A cute little Bash library for blazing fast argument parsing
 STATUS: IN DEVELOPMENT!
 
 ```sh
-# With Basher
-basher install eankeen/args
+# With bpm (recommended)
+bpm install eankeen/args
 
 # With Git
-git clone "https://github.com/eankeen/args" ~/.args
+git clone "https://github.com/eankeen/args" "$HOME/.bash-args"
+export PATH="$HOME/.bash-args/pkg/bin:$PATH"
 ```
 
 ## Usage
@@ -29,7 +30,7 @@ declare -A args=()
 
 # Pass through your command line arguments to 'args'
 # Pass your argument specification through stdin (see more examples below)
-source bash-args parse "$@" <<-"EOF"
+source bash-args parse parse "$@" <<-"EOF"
 @flag [port.p] {3000} - The port to open on
 EOF
 
@@ -49,7 +50,7 @@ echo "argsHelpText: $argsHelpText"
 
 ### Argument Specification
 
-The following are valid lines and their explanations to pass as stdin to `args.parse`
+The following are valid lines and their explanations to pass as stdin to `bash-args`
 
 #### `@flag [verbose] - Enable verbose logging`
 

docs/reference.md

@@ -2,7 +2,7 @@
 
 ## Variables
 
-Available variables after calling `args.parse`. If the values of the variables appear to be blank, you may have to declare the variable before calling `args.parse`
+Available variables after calling `bash-args`. If the values of the variables appear to be blank, you may have to declare the variable before calling `bash-args`
 
 ### `argsPostHyphen`
 
@@ -11,7 +11,7 @@ An array that contains every argument or flag after the first `--`
 ```sh
 declare -a argsPostHyphen=()
 
-source args.parse --port 3005 -- ls -L --color=always /lib <<-'EOF'
+source bash-args parse --port 3005 -- ls -L --color=always /lib <<-'EOF'
 	@flag [port] {3000} - The port to open on
 EOF
 
@@ -21,12 +21,12 @@ echo "${argsPostHyphen[*]}"
 
 ### `argsRawSpec`
 
-A string that is a copy of standard input to `args.parse`
+A string that is a copy of standard input to `bash-args`
 
 ```sh
 declare argsRawSpec=
 
-source args.parse --port 3005 <<-'EOF'
+source bash-args parse --port 3005 <<-'EOF'
 	@flag [port] {3000} - The port to open on
 	@flag [version.v] - Prints program version
 EOF
@@ -43,14 +43,14 @@ An associative array that contains the values of arguments
 ```sh
 declare -A args=()
 
-source args.parse --port 3005 <<-'EOF'
+source bash-args parse --port 3005 <<-'EOF'
 	@flag [port.p] {3000} - The port to open on
 EOF
 
 echo "${args[port]} ${args[p]}"
 # 3005 3005
 
-source args.parse -p 3005 <<-'EOF'
+source bash-args parse -p 3005 <<-'EOF'
 	@flag [port.p] {3000} - The port to open on
 EOF
 
@@ -65,7 +65,7 @@ An array contaning all the commands supplied
 ```sh
 declare -a argsCommands=()
 
-source args.parse --port 3005 serve --user admin now --enable-security <<-'EOF'
+source bash-args parse --port 3005 serve --user admin now --enable-security <<-'EOF'
 	@flag [port.p] {3000} - The port to open on
 EOF
 
@@ -77,4 +77,15 @@ echo "${argsCommands[*]}"
 
 The full generated help text
 
-// TODO
+```sh
+source bash-args parse parse "$@" <<-"EOF"
+@flag [port.p] {3000} - The port to open on
+EOF
+
+echo "$argsHelpText"
+# Usage:
+#   stdin [flags] <arguments>
+
+# Flags:
+#   p, port           (Default: 3000)
+```

docs/troubleshooting.md

@@ -4,7 +4,7 @@ If you are receiving opaque errors, the following may help
 
 ## `bash: /usr/lib/jvm/default/bin: syntax error: operand expected (error token is "/usr/lib/jvm/default/bin")`
 
-Ensure `args` exists as an associate array and NOT an index array. Create it _before_ calling out to `args.parse`
+Ensure `args` exists as an associate array and NOT an index array. Create it _before_ calling out to `bash-args`
 
 
 ```sh
@@ -15,12 +15,24 @@ declare -a args
 declare -A args
 ```
 
-## Not sourcing `args.parse`
+## Not sourcing `bash-args`
 
-// TODO
+If you do not source `bash-args` the variables that it sets will not be available to your current shell execution context
+
+```sh
+# Wrong
+bash-args parse "$@" <<-"EOF"
+@flag [port.p] {3000} - The port to open on
+EOF
+
+# Correct
+source bash-args parse parse "$@" <<-"EOF"
+@flag [port.p] {3000} - The port to open on
+EOF
+```
 
 ## Not declaring variables
 
 TODO: test this
 
-If you wish to use a variable, please declare it before invoking `args.parse`. If your shell context has `set -u` enabled, you may have to declare it for variables that you do not use
+If you wish to use a variable, please declare it before invoking `bash-args`. If your shell context has `set -u` enabled, you may have to declare it for variables that you do not use

examples/bashblog.sh

@@ -2,7 +2,7 @@
 
 # https://github.com/cfenollosa/bashblog
 
-source args.parse <<"EOF"
+source bash-args parse <<"EOF"
 @arg post - insert a new blog post, or the filename of a draft to continue editing it. it tries to use markdown by default, and falls back to HTML if it's not available. use '-html' to override it and edit the post as HTML even when markdown is available
 @arg edit - edit an already published .html or .md file. **NEVER** edit manually a published .html file, always use this function as it keeps internal data and rebuilds the blog. use '-n' to give the file a new name, if title was changed. use '-f' to edit full html file, instead of just text part (also preserves name)
 @arg delete - deletes the post and rebuilds the blog

examples/basher.sh

@@ -2,8 +2,10 @@
 
 # https://github.com/basherpm/basher
 
-source args.parse <<"EOF"
+source bash-args parse parse <<"EOF"
 @arg help - Display help for a command
 @arg commands - List all available basher commands
 @arg init - Configure the shell environment for basher
 EOF
+
+echo "$argsHelpText"

examples/bats.sh

@@ -2,7 +2,7 @@
 
 # https://github.com/bats-core/bats-core
 
-source args.parse -- <<"EOF"
+source bash-args parse -- <<"EOF"
 @flag [count.c] - Count test cases without running any tests
 @flag [filter.f] {} - Only run tests that match the regular expression
 @flag [formatter.F] {pretty} - Swithc between formatters: pretty (default), tap (default w/o term), tap13, junit

examples/json.sh

@@ -2,7 +2,7 @@
 
 # https://github.com/dominictarr/JSON.sh
 
-source args.parse -- <<"EOF"
+source bash-args parse -- <<"EOF"
 @flag [.p] - Prune empty. Exclude fields with empty values.
 @flag [.l] - Leaf only. Only show leaf nodes, which stops data duplication.
 @flag [.b] - Brief. Combines 'Leaf only' and 'Prune empty' options.

pkg/lib/cmd/bash-args.sh

@@ -21,7 +21,7 @@ bash-args() {
 
 		Flags
 		--version
-			Show version of 'args.parse'
+			Show version of 'bash-args'
 
 		--help
 			Show help
@@ -99,12 +99,12 @@ bash-args() {
 
 			# Sanity checks
 			if [ -z "$flagNameOptional" ] && [ -z "$flagNameRequired" ]; then
-				bash_args.util.die 'args.parse: Must specify either an optional or required flag; neither were specified'
+				bash_args.util.die 'bash-args: Must specify either an optional or required flag; neither were specified'
 				return
 			fi
 
 			if [ -n "$flagNameOptional" ] && [ -n "$flagNameRequired" ]; then
-				bash_args.util.die 'args.parse: Must specify either an optional or required flag; both were specified'
+				bash_args.util.die 'bash-args: Must specify either an optional or required flag; both were specified'
 				return
 			fi
 
@@ -205,14 +205,14 @@ bash-args() {
 				# If we did not set flagWasFound=yes, it means it did not find
 				# the flag. So, if the flag is <required>, we fail right away
 				if [ "$flagWasFound" = no ]; then
-					bash_args.util.die "args.parse: You must supply the flag '$currentFlag' with a value"
+					bash_args.util.die "bash-args: You must supply the flag '$currentFlag' with a value"
 					return
 				fi
 
 				# If we were supposed to do an immediate break, but didn't actually
 				# do it, it means we are on the last argument and there is no value
 				if [ "$flagWasFound" = yes ] && [ "$didImmediateBreak" = no ]; then
-					bash_args.util.die "args.parse: No value found for flag '$currentFlag'"
+					bash_args.util.die "bash-args: No value found for flag '$currentFlag'"
 					return
 				fi
 			fi
@@ -245,7 +245,7 @@ bash-args() {
 				case "$flagValueCli" in
 					-*)
 						if [[ -v flagValueDefault ]]; then
-							bash_args.util.die "args.parse: You must supply a value for '$currentFlag'"
+							bash_args.util.die "bash-args: You must supply a value for '$currentFlag'"
 							return
 						fi
 						;;
@@ -329,7 +329,7 @@ bash-args() {
 			printf -v name '%-20s' "  $name"
 			argsHelpArrayArgs+=("${name}${argDescription}"$'\n')
 		else
-			bash_args.util.die "args.parse: Pragma must be either @flag or @arg. Received: '$type'"
+			bash_args.util.die "bash-args: Pragma must be either @flag or @arg. Received: '$type'"
 			return
 		fi
 	done
@@ -384,7 +384,7 @@ bash-args() {
 			done
 
 			if [ "$isValidFlag" = no ]; then
-				bash_args.util.die "args.parse: Flag '$arg' is not accepted"
+				bash_args.util.die "bash-args: Flag '$arg' is not accepted"
 				return
 			fi
 		esac

test/args.bats

@@ -4,7 +4,7 @@ set -Eeuo pipefail
 @test "longOption with value" {
 	declare -A args=()
 
-	source ./bin/args.parse --port 3005 <<-'EOF'
+	source bash-args parse --port 3005 <<-'EOF'
 	@flag [port] {3000} - The port to open on
 	EOF
 
@@ -16,7 +16,7 @@ set -Eeuo pipefail
 @test "shortOption with value" {
 	declare -A args=()
 
-	source ./bin/args.parse -p 3005 <<-'EOF'
+	source bash-args parse -p 3005 <<-'EOF'
 	@flag [.p] {3000} - The port to open on
 	EOF
 
@@ -27,7 +27,7 @@ set -Eeuo pipefail
 @test "longOption and shortOption with longOption value" {
 	declare -A args=()
 
-	source ./bin/args.parse --port 3005 <<-'EOF'
+	source bash-args parse --port 3005 <<-'EOF'
 	@flag [port.p] {3000} - The port to open on
 	EOF
 
@@ -41,7 +41,7 @@ set -Eeuo pipefail
 @test "longOption and shortOption with shortOption value" {
 	declare -A args=()
 
-	source ./bin/args.parse -p 3005 <<-'EOF'
+	source bash-args parse -p 3005 <<-'EOF'
 	@flag [port.p] {3000} - The port to open on
 	EOF
 
@@ -58,7 +58,7 @@ set -Eeuo pipefail
 
 	declare -A args=()
 
-	source ./bin/args.parse --version <<-'EOF'
+	source bash-args parse --version <<-'EOF'
 	@flag [version.v] - The port to open on
 	EOF
 
@@ -69,7 +69,7 @@ set -Eeuo pipefail
 @test "longOption and default" {
 	declare -A args=()
 
-	source ./bin/args.parse <<-'EOF'
+	source bash-args parse <<-'EOF'
 	@flag [port] {3000} - The port to open on
 	EOF
 
@@ -79,7 +79,7 @@ set -Eeuo pipefail
 @test "shortOption and default" {
 	declare -A args=()
 
-	source ./bin/args.parse <<-'EOF'
+	source bash-args parse <<-'EOF'
 	@flag [.p] {3000} - The port to open on
 	EOF
 
@@ -89,7 +89,7 @@ set -Eeuo pipefail
 @test "longOption and shortOption" {
 	declare -A args=()
 
-	source ./bin/args.parse <<-'EOF'
+	source bash-args parse <<-'EOF'
 	@flag [port.p] {3000} - The port to open on
 	EOF
 
@@ -103,7 +103,7 @@ set -Eeuo pipefail
 	declare -A args=()
 
 	! (
-		source ./bin/args.parse --port --something nother <<-'EOF'
+		source bash-args parse --port --something nother <<-'EOF'
 		@flag <port> {} - The port to open on
 		EOF
 	)
@@ -113,7 +113,7 @@ set -Eeuo pipefail
 	declare -A args=()
 
 	(
-		source ./bin/args.parse --port --something nother <<-'EOF'
+		source bash-args parse --port --something nother <<-'EOF'
 		@flag <port> - The port to open on
 		@flag <something> - something
 		EOF
@@ -124,7 +124,7 @@ set -Eeuo pipefail
 	declare -A args=()
 
 	! (
-		source ./bin/args.parse --port - <<-'EOF'
+		source bash-args parse --port - <<-'EOF'
 		@flag [port] {} - The port to open on
 		EOF
 	)
@@ -134,7 +134,7 @@ set -Eeuo pipefail
 	declare -A args=()
 
 	(
-		source ./bin/args.parse --port - <<-'EOF'
+		source bash-args parse --port - <<-'EOF'
 		@flag [port] - The port to open on
 		EOF
 	)
@@ -144,7 +144,7 @@ set -Eeuo pipefail
 	declare -A args=()
 
 	! (
-		source ./bin/args.parse <<-'EOF'
+		source bash-args parse <<-'EOF'
 		@flag <port> The port to open on
 		EOF
 	)

test/argsCommands.bats

@@ -5,7 +5,7 @@ set -Eeuo pipefail
 	declare -A args
 	declare -a argsCommands=()
 
-	source ./bin/args.parse alfa bravo <<-'EOF'
+	source bash-args parse alfa bravo <<-'EOF'
 	@flag [port.p] {3000} - The port to open on
 	EOF
 
@@ -19,7 +19,7 @@ set -Eeuo pipefail
 	declare -A args
 	declare -a argsCommands=()
 
-	source ./bin/args.parse --port 3005 serve --user admin --enable-security now <<-'EOF'
+	source bash-args parse --port 3005 serve --user admin --enable-security now <<-'EOF'
 	@flag [port.p] {3000} - The port to open on
 	@flag [user] {} - User
 	@flag [enable-security] - Enable security
@@ -34,7 +34,7 @@ set -Eeuo pipefail
 	declare -A args
 	declare -a argsCommands=()
 
-	source ./bin/args.parse --port 3005 serve now --enable-security last <<-'EOF'
+	source bash-args parse --port 3005 serve now --enable-security last <<-'EOF'
 	@flag [port.p] {3000} - The port to open on
 	@flag [enable-security] - Whether to enable security
 	EOF