feat: Remove '--as' and '--by' in favor of just writing --ref or --value

Author: hyperupcall

README.md

@@ -1,6 +1,6 @@
 # bash-object
 
-The _first_ Bash library for imperatively constructing heterogenously hierarchical data structures
+The _first_ Bash library for imperatively constructing heterogeneously hierarchical data structures
 
 This is meant to be a low level API providing primitives for other libraries.
 
@@ -27,21 +27,21 @@ declare -A yankee_object=()
 declare -A xray_object=([whiskey]=victor)
 declare -a foxtrot_array=(omicron pi rho sigma)
 
-bobject set-object --by-ref root_object '.zulu' zulu_object
-bobject set-object --by-ref root_object '.zulu.yankee' yankee_object
-bobject set-object --by-ref root_object '.zulu.yankee.xray' xray_object
-bobject set-array --by-ref root_object '.zulu.yankee.xray.foxtrot' foxtrot_array
+bobject set-object --ref root_object '.zulu' zulu_object
+bobject set-object --ref root_object '.zulu.yankee' yankee_object
+bobject set-object --ref root_object '.zulu.yankee.xray' xray_object
+bobject set-array --ref root_object '.zulu.yankee.xray.foxtrot' foxtrot_array
 
-bobject get-object --as-value root_object '.zulu.yankee.xray'
+bobject get-object --value root_object '.zulu.yankee.xray'
 assert [ "${REPLY[whiskey]}" = victor ]
 
-bobject get-string --as-value root_object '.zulu.yankee.xray.whiskey'
+bobject get-string --value root_object '.zulu.yankee.xray.whiskey'
 assert [ "$REPLY" = victor ]
 
-bobject get-array --as-value root_object '.zulu.yankee.xray.foxtrot'
+bobject get-array --value root_object '.zulu.yankee.xray.foxtrot'
 assert [ ${#REPLY[@]} -eq 4 ]
 
-bobject get-string --as-value root_object '.["zulu"].["yankee"].["xray"].["foxtrot"].[2]'
+bobject get-string --value root_object '.["zulu"].["yankee"].["xray"].["foxtrot"].[2]'
 assert [ "$REPLY" = rho ]
 ```
 
@@ -55,7 +55,5 @@ bpm install
 ```
 
 ## TODO
-- error on invalid references (`type=object` in virtual object metadata, when it is referencing an array)
 - ensure error (for set primarily) if the virtual object references a variable that does not exist
-- use ${param@A} on newer bash instead of declare -p
 - error if set in array out of bounds?

docs/unmarshaling.md

@@ -66,7 +66,7 @@ declare -A OBJECT=([xray]=$'\x1C\x1Dtype=object;&unique_global_variable_xray')
 You can retrieve the data with
 
 ```sh
-bobject get-object --as-value 'OBJECT' 'xray'
+bobject get-object --value 'OBJECT' 'xray'
 assert [ "${REPLY[yankee]}" = zulu ]
 ```
 

pkg/lib/traverse-get.sh

@@ -12,16 +12,16 @@ bash_object.traverse-get() {
 	local -a args=()
 
 	for arg; do case "$arg" in
-	--as-ref)
+	--ref)
 		if [ -n "$flag_as_what" ]; then
-			bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "Flags '--as-ref' and '--as-value' are mutually exclusive"
+			bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "Flags '--ref' and '--value' are mutually exclusive"
 			return
 		fi
 		flag_as_what='as-ref'
 		;;
-	--as-value)
+	--value)
 		if [ -n "$flag_as_what" ]; then
-			bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "Flags '--as-ref' and '--as-value' are mutually exclusive"
+			bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "Flags '--ref' and '--value' are mutually exclusive"
 			return
 		fi
 		flag_as_what='as-value'
@@ -35,12 +35,12 @@ bash_object.traverse-get() {
 	esac done
 
 	if [ -z "$flag_as_what" ]; then
-		bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "Must pass either the '--as-ref' or '--as-value' flag"
+		bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "Must pass either the '--ref' or '--value' flag"
 		return
 	fi
 
 	if [ "$flag_as_what" = 'as-ref' ]; then
-		bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "--as-ref not implemented"
+		bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "--ref not implemented"
 	fi
 
 	# Ensure correct number of arguments have been passed

pkg/lib/traverse-set.sh

@@ -10,16 +10,16 @@ bash_object.traverse-set() {
 	local -a args=()
 
 	for arg; do case "$arg" in
-	--by-ref)
+	--ref)
 		if [ -n "$flag_pass_by_what" ]; then
-			bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "Flags '--by-ref' and '--by-value' are mutually exclusive"
+			bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "Flags '--ref' and '--value' are mutually exclusive"
 			return
 		fi
 		flag_pass_by_what='by-ref'
 		;;
-	--by-value)
+	--value)
 		if [ -n "$flag_pass_by_what" ]; then
-			bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "Flags '--by-ref' and '--by-value' are mutually exclusive"
+			bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "Flags '--ref' and '--value' are mutually exclusive"
 			return
 		fi
 		flag_pass_by_what='by-value'
@@ -33,12 +33,12 @@ bash_object.traverse-set() {
 	esac done
 
 	if [ -z "$flag_pass_by_what" ]; then
-		bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "Must pass either the '--by-ref' or '--by-value' flag"
+		bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "Must pass either the '--ref' or '--value' flag"
 		return
 	fi
 
 	if [ "$flag_pass_by_what" = 'by-value' ]; then
-		bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "--by-value not implemented"
+		bash_object.util.die 'ERROR_ARGUMENTS_INVALID' "--value not implemented"
 	fi
 
 	local final_value_type root_object_name filter final_value

pkg/lib/util/util.sh

@@ -62,7 +62,7 @@ bash_object.util.generate_vobject_name() {
 # stack. This is used when generating objects to prevent
 # conflicts
 bash_object.util.generate_filter_stack_string() {
-	unset REPLY
+	unset REPLY; REPLY=
 
 	local oldIFS="$IFS"
 	IFS='_'

tests/e2e.bats

@@ -8,7 +8,7 @@ load './util/init.sh'
 	for subcmd in "${subcmds[@]}"; do
 		declare -A OBJECT=()
 
-		run bobject "$subcmd" --as-value 'OBJECT' '.zulu.yankee' 'invalid'
+		run bobject "$subcmd" --value 'OBJECT' '.zulu.yankee' 'invalid'
 
 		assert_failure
 		assert_line -p "Expected '3' arguments, but received '4'"
@@ -21,7 +21,7 @@ load './util/init.sh'
 	for subcmd in "${subcmds[@]}"; do
 		declare -A OBJECT=()
 
-		run bobject "$subcmd" --as-value 'invalid'
+		run bobject "$subcmd" --value 'invalid'
 
 		assert_failure
 		assert_failure
@@ -35,7 +35,7 @@ load './util/init.sh'
 	for subcmd in "${subcmds[@]}"; do
 		declare -A OBJECT=()
 
-		run bobject "$subcmd" --by-ref 'OBJECT' '.zulu.yankee' 'xray' 'invalid'
+		run bobject "$subcmd" --ref 'OBJECT' '.zulu.yankee' 'xray' 'invalid'
 
 		assert_failure
 		assert_line -p "Expected '4' arguments, but received '5'"
@@ -48,7 +48,7 @@ load './util/init.sh'
 	for subcmd in "${subcmds[@]}"; do
 		declare -A OBJECT=()
 
-		run bobject "$subcmd" --by-ref 'OBJECT' '.zulu'
+		run bobject "$subcmd" --ref 'OBJECT' '.zulu'
 
 		assert_failure
 		assert_line -p "Expected '4' arguments, but received '3'"
@@ -60,9 +60,9 @@ load './util/init.sh'
 	declare -A subobj=()
 	str='MEOW'
 
-	bobject set-object --by-ref 'OBJECT' '.zulu' subobj
-	bobject set-string --by-ref 'OBJECT' '.zulu.yankee' str
-	bobject get-string --as-value 'OBJECT' '.zulu.yankee'
+	bobject set-object --ref 'OBJECT' '.zulu' subobj
+	bobject set-string --ref 'OBJECT' '.zulu.yankee' str
+	bobject get-string --value 'OBJECT' '.zulu.yankee'
 
 	assert [ "$REPLY" = 'MEOW' ]
 }
@@ -72,9 +72,9 @@ load './util/init.sh'
 	declare -A subobj=()
 	str='MEOW'
 
-	bobject set-object --by-ref 'OBJECT' '.zulu' subobj
-	bobject set-string --by-ref 'OBJECT' '.["zulu"].["yankee"]' str
-	bobject get-string --as-value 'OBJECT' '.["zulu"].["yankee"]'
+	bobject set-object --ref 'OBJECT' '.zulu' subobj
+	bobject set-string --ref 'OBJECT' '.["zulu"].["yankee"]' str
+	bobject get-string --value 'OBJECT' '.["zulu"].["yankee"]'
 
 	assert [ "$REPLY" = 'MEOW' ]
 }
@@ -86,20 +86,20 @@ load './util/init.sh'
 	declare -A xray_object=([whiskey]=victor)
 	declare -a foxtrot_array=(omicron pi rho sigma)
 
-	bobject set-object --by-ref root_object '.zulu' zulu_object
-	bobject set-object --by-ref root_object '.zulu.yankee' yankee_object
-	bobject set-object --by-ref root_object '.zulu.yankee.xray' xray_object
-	bobject set-array --by-ref root_object '.zulu.yankee.xray.foxtrot' foxtrot_array
+	bobject set-object --ref root_object '.zulu' zulu_object
+	bobject set-object --ref root_object '.zulu.yankee' yankee_object
+	bobject set-object --ref root_object '.zulu.yankee.xray' xray_object
+	bobject set-array --ref root_object '.zulu.yankee.xray.foxtrot' foxtrot_array
 
-	bobject get-object --as-value root_object '.zulu.yankee.xray'
+	bobject get-object --value root_object '.zulu.yankee.xray'
 	assert [ "${REPLY[whiskey]}" = victor ]
 
-	bobject get-string --as-value root_object '.zulu.yankee.xray.whiskey'
+	bobject get-string --value root_object '.zulu.yankee.xray.whiskey'
 	assert [ "$REPLY" = victor ]
 
-	bobject get-array --as-value root_object '.zulu.yankee.xray.foxtrot'
+	bobject get-array --value root_object '.zulu.yankee.xray.foxtrot'
 	assert [ ${#REPLY[@]} -eq 4 ]
 
-	bobject get-string --as-value root_object '.["zulu"].["yankee"].["xray"].["foxtrot"].[2]'
+	bobject get-string --value root_object '.["zulu"].["yankee"].["xray"].["foxtrot"].[2]'
 	assert [ "$REPLY" = rho ]
 }

tests/errors-circular-reference.bats

@@ -7,7 +7,7 @@ load './util/init.sh'
 	declare -A SUB_OBJECT=([nested]=$'\x1C\x1Dtype=object;&SUB_OBJECT')
 	declare -A OBJECT=([my_key]=$'\x1C\x1Dtype=object;&SUB_OBJECT')
 
-	run bobject get-object --as-value OBJECT '.my_key.nested'
+	run bobject get-object --value OBJECT '.my_key.nested'
 
 	assert_failure
 	assert_line -p "ERROR_SELF_REFERENCE"
@@ -18,7 +18,7 @@ load './util/init.sh'
 	declare -A SUB_OBJECT=([nested]=$'\x1C\x1Dtype=object;&SUB_OBJECT')
 	declare -A OBJECT=([my_key]=$'\x1C\x1Dtype=object;&SUB_OBJECT')
 
-	run bobject get-object --as-value OBJECT '.my_key.nested.nested'
+	run bobject get-object --value OBJECT '.my_key.nested.nested'
 
 	assert_failure
 	assert_line -p "ERROR_SELF_REFERENCE"
@@ -29,7 +29,7 @@ load './util/init.sh'
 	declare -a SUB_ARRAY=([nested]=$'\x1C\x1Dtype=array;&SUB_ARRAY')
 	declare -A OBJECT=([my_key]=$'\x1C\x1Dtype=array;&SUB_ARRAY')
 
-	run bobject get-array --as-value OBJECT '.my_key.nested'
+	run bobject get-array --value OBJECT '.my_key.nested'
 
 	assert_failure
 	assert_line -p "ERROR_SELF_REFERENCE"
@@ -40,7 +40,7 @@ load './util/init.sh'
 	declare -a SUB_ARRAY=([nested]=$'\x1C\x1Dtype=array;&SUB_ARRAY')
 	declare -A OBJECT=([my_key]=$'\x1C\x1Dtype=array;&SUB_ARRAY')
 
-	run bobject get-array --as-value OBJECT '.my_key.nested.nested'
+	run bobject get-array --value OBJECT '.my_key.nested.nested'
 
 	assert_failure
 	assert_line -p "ERROR_SELF_REFERENCE"
@@ -53,7 +53,7 @@ load './util/init.sh'
 	declare -A OBJECT=([my_key]=$'\x1C\x1Dtype=object;&SUB_OBJECT')
 	declare -A obj=()
 
-	run bobject set-object OBJECT --by-ref '.my_key.nested' obj
+	run bobject set-object OBJECT --ref '.my_key.nested' obj
 
 	assert_failure
 	assert_line -p "ERROR_SELF_REFERENCE"
@@ -65,7 +65,7 @@ load './util/init.sh'
 	declare -A OBJECT=([my_key]=$'\x1C\x1Dtype=object;&SUB_OBJECT')
 	declare -A obj=()
 
-	run bobject set-object OBJECT --by-ref '.my_key.nested.gone' obj
+	run bobject set-object OBJECT --ref '.my_key.nested.gone' obj
 
 	assert_failure
 	assert_line -p "ERROR_SELF_REFERENCE"
@@ -77,7 +77,7 @@ load './util/init.sh'
 	declare -A OBJECT=([my_key]=$'\x1C\x1Dtype=array;&SUB_ARRAY')
 	declare -a arr=()
 
-	run bobject set-array OBJECT --by-ref '.my_key.nested' arr
+	run bobject set-array OBJECT --ref '.my_key.nested' arr
 
 	assert_failure
 	assert_line -p "ERROR_SELF_REFERENCE"
@@ -89,7 +89,7 @@ load './util/init.sh'
 	declare -A OBJECT=([my_key]=$'\x1C\x1Dtype=array;&SUB_ARRAY')
 	declare -a arr=()
 
-	run bobject set-array OBJECT --by-ref '.my_key.nested.gone' arr
+	run bobject set-array OBJECT --ref '.my_key.nested.gone' arr
 
 	assert_failure
 	assert_line -p "ERROR_SELF_REFERENCE"

tests/errors-required-flags.bats

@@ -8,23 +8,23 @@ load './util/init.sh'
 
 	assert_failure
 	assert_line -p 'ERROR_ARGUMENTS_INVALID'
-	assert_line -p "Must pass either the '--as-ref' or '--as-value' flag"
+	assert_line -p "Must pass either the '--ref' or '--value' flag"
 }
 
 @test "get errors on combining mutually exclusive flags" {
-	run bobject get-string --as-value --as-ref
+	run bobject get-string --value --ref
 
 	assert_failure
 	assert_line -p 'ERROR_ARGUMENTS_INVALID'
-	assert_line -p "Flags '--as-ref' and '--as-value' are mutually exclusive"
+	assert_line -p "Flags '--ref' and '--value' are mutually exclusive"
 }
 
-@test "error on unimplemented --as-ref" {
-	run bobject get-string --as-ref
+@test "error on unimplemented --ref" {
+	run bobject get-string --ref
 
 	assert_failure
 	assert_line -p 'ERROR_ARGUMENTS_INVALID'
-	assert_line -p "--as-ref not implemented"
+	assert_line -p "--ref not implemented"
 }
 
 # set
@@ -33,21 +33,21 @@ load './util/init.sh'
 
 	assert_failure
 	assert_line -p 'ERROR_ARGUMENTS_INVALID'
-	assert_line -p "Must pass either the '--by-ref' or '--by-value' flag"
+	assert_line -p "Must pass either the '--ref' or '--value' flag"
 }
 
 @test "set errors on combining mutually exclusive flags" {
-	run bobject set-string --by-value --by-ref
+	run bobject set-string --value --ref
 
 	assert_failure
 	assert_line -p 'ERROR_ARGUMENTS_INVALID'
-	assert_line -p "Flags '--by-ref' and '--by-value' are mutually exclusive"
+	assert_line -p "Flags '--ref' and '--value' are mutually exclusive"
 }
 
-@test "error on unimplemented --by-value" {
-	run bobject set-string --by-value
+@test "error on unimplemented --value" {
+	run bobject set-string --value
 
 	assert_failure
 	assert_line -p 'ERROR_ARGUMENTS_INVALID'
-	assert_line -p "--by-value not implemented"
+	assert_line -p "--value not implemented"
 }