lib/format: Add array_printf for Bash < 4.1

Turns out Bash versions earlier than 4.1 can't use `printf -v` to print
to a subscripted array variable.

Author: mbland

lib/format

@@ -3,6 +3,8 @@
 # Text formatting utilities
 #
 # Exports:
+#   @go.array_printf
+#     Assigns `printf` transformations of its arguments to an array
 #
 #   @go.pad_items
 #     Pads each string in an array to match the length of the longest element
@@ -13,53 +15,82 @@
 #   @go.strip_formatting_codes
 #     Strips ANSI escape codes of the form `\e[...(;...)m` from a string
 
-. "$_GO_USE_MODULES" 'validation'
+. "$_GO_USE_MODULES" 'strings' 'validation'
 
-# Pads each string in an array to match the length of the longest element
+# Assigns `printf` transformations of its arguments to an array
+#
+# Since `printf -v` can't print to an array subscript prior to Bash 4.1, this
+# provides a portable means of printing to an array variable while avoiding the
+# use of `eval`.
+#
+# NOTE: By default, this function relies on the ASCII Record Separator character
+# ($'\x1f') to delimit generated strings before splitting them into the result
+# array. If you have strings containing this character, you can set a new
+# delimiter via `_GO_ARRAY_PRINTF_DELIMITER`.
+#
+# Globals:
+#   _GO_ARRAY_PRINTF_DELIMITER:
+#     If set, used to separate generated strings prior to array assignment
+#
+# Arguments:
+#   result:  Name of the caller-declared output array
+#   format:  `printf`-style format specification
+#   ...:     Items to pass to `printf` and store in `result`
+@go.array_printf() {
+  @go.validate_identifier_or_die 'Result array name' "$1"
+  local __go_array_printf_delim="${_GO_ARRAY_PRINTF_DELIMITER:-$'\x1f'}"
+  local __tmp_go_array_printf
+  printf -v __tmp_go_array_printf -- "${2}${__go_array_printf_delim}" "${@:3}"
+  @go.split "$__go_array_printf_delim" "$__tmp_go_array_printf" "$1"
+}
+
+# Right-pads each string in an array to match the length of the longest element
+#
+# Globals:
+#   _GO_ARRAY_PRINTF_DELIMITER:  See the comments for `@go.array_printf`
 #
 # Arguments:
 #   items:   Name of the input array in the caller's scope
 #   result:  Name of the caller-declared output array
 @go.pad_items() {
-  @go.validate_identifier_or_die 'Result variable name' "$2"
+  @go.validate_identifier_or_die 'Result array name' "$2"
   local items_reference="${1}[@]"
   local item
   local padding_size=0
-  local pad_format=''
-  local item_index=0
 
   for item in "${!items_reference}"; do
     while [[ "$padding_size" -lt "${#item}" ]]; do
       padding_size="${#item}"
     done
   done
-  pad_format="%-${padding_size}s"
-
-  for item in "${!items_reference}"; do
-    printf -v "$2[$((item_index++))]" -- "$pad_format" "$item"
-  done
+  @go.array_printf "$2" "%-${padding_size}s" "${!items_reference}"
 }
 
 # Concatenates parallel elements from each input array
 #
 # Will produce a number of results matching that of the left-hand input array.
 #
+# Globals:
+#   _GO_ARRAY_PRINTF_DELIMITER:  See the comments for `@go.array_printf`
+#
 # Arguments:
 #   lhs:     Name of the left-hand input array in the caller's scope
 #   rhs:     Name of the right-hand input array in the caller's scope
 #   delim:   String used as a delimiter between elements (default: two spaces)
 #   result:  Name of the caller-declared output array
 @go.zip_items() {
-  @go.validate_identifier_or_die 'Result variable name' "$4"
+  @go.validate_identifier_or_die 'Result array name' "$4"
   local lhs_array_reference="${1}[@]"
   local rhs_item_ref
   local item
   local i=0
+  local __tmp_go_zip_items_result=()
 
   for item in "${!lhs_array_reference}"; do
-    rhs_item_ref="${2}[$i]"
-    printf -v "$4[$((i++))]" -- '%s' "${item}${3}${!rhs_item_ref}"
+    rhs_item_ref="${2}[$((i++))]"
+    __tmp_go_zip_items_result+=("${item}${3}${!rhs_item_ref}")
   done
+  @go.array_printf "$4" '%s' "${__tmp_go_zip_items_result[@]}"
 }
 
 # Strips ANSI escape codes from a string

tests/format.bats

@@ -14,6 +14,15 @@ create_go_format_script() {
   create_test_go_script '. "$_GO_USE_MODULES" format' "$@"
 }
 
+run_array_printf_script() {
+  create_go_format_script \
+    'declare result=()' \
+    '@go.array_printf result "%s" "$@"' \
+    'IFS="|"' \
+    'printf "%s\n" "${result[*]}"'
+  run "$TEST_GO_SCRIPT" "$@"
+}
+
 run_pad_items_script() {
   create_go_format_script \
     'declare items=("$@")' \
@@ -42,51 +51,78 @@ run_strip_formatting_codes_script() {
   run "$TEST_GO_SCRIPT" "$@"
 }
 
-@test "$SUITE: pad items validates result variable name" {
+@test "$SUITE: array_printf validates result array name" {
+  create_test_go_script '. "$_GO_USE_MODULES" format' \
+    '@go.array_printf "3foobar"'
+  run "$TEST_GO_SCRIPT"
+
+  local err_msg='Result array name "3foobar" for @go.array_printf '
+  err_msg+='must not start with a number at:'
+  assert_failure "$err_msg" \
+    "  $TEST_GO_SCRIPT:4 main"
+}
+
+@test "$SUITE: array_printf does nothing for empty argv" {
+  run_array_printf_script
+  assert_success ''
+}
+
+@test "$SUITE: array_printf prints argv items" {
+  run_array_printf_script 'foo' 'bar' 'baz' 'xyzzy' 'quux'
+  assert_success 'foo|bar|baz|xyzzy|quux'
+}
+
+@test "$SUITE: array_printf prints argv items with different delimiter" {
+  _GO_ARRAY_PRINTF_DELIMITER=$'\x1e' run_array_printf_script \
+    $'foo\x1f' $'bar\x1f' $'baz\x1f' $'xyzzy\x1f' $'quux\x1f'
+  assert_success $'foo\x1f|bar\x1f|baz\x1f|xyzzy\x1f|quux\x1f'
+}
+
+@test "$SUITE: pad_items validates result array name" {
   create_test_go_script '. "$_GO_USE_MODULES" format' \
     '@go.pad_items items "3foobar"'
   run "$TEST_GO_SCRIPT"
 
-  local err_msg='Result variable name "3foobar" for @go.pad_items '
+  local err_msg='Result array name "3foobar" for @go.pad_items '
   err_msg+='must not start with a number at:'
   assert_failure "$err_msg" \
     "  $TEST_GO_SCRIPT:4 main"
 }
 
-@test "$SUITE: pad items does nothing for empty argv" {
+@test "$SUITE: pad_items does nothing for empty argv" {
   run_pad_items_script
   assert_success ''
 }
 
-@test "$SUITE: pad items pads argv items" {
+@test "$SUITE: pad_items pads argv items" {
   run_pad_items_script 'foo' 'bar' 'baz' 'xyzzy' 'quux'
   assert_success 'foo  |bar  |baz  |xyzzy|quux '
 }
 
-@test "$SUITE: zip items validates result variable name" {
+@test "$SUITE: zip_items validates result array name" {
   create_test_go_script '. "$_GO_USE_MODULES" format' \
     '@go.zip_items lhs rhs = "3foobar"'
   run "$TEST_GO_SCRIPT"
 
-  local err_msg='Result variable name "3foobar" for @go.zip_items '
+  local err_msg='Result array name "3foobar" for @go.zip_items '
   err_msg+='must not start with a number at:'
   assert_failure "$err_msg" \
     "  $TEST_GO_SCRIPT:4 main"
 }
 
-@test "$SUITE: zip items does nothing for empty argv" {
+@test "$SUITE: zip_items does nothing for empty argv" {
   run_zip_items_script
   assert_success ''
 }
 
-@test "$SUITE: zip items zips matching items with supplied delimiter" {
+@test "$SUITE: zip_items zips matching items with supplied delimiter" {
   local lhs=('foo' 'xyzzy' 'quux')
   local rhs=('bar' 'baz' 'plugh')
   run_zip_items_script "${lhs[*]}" "${rhs[*]}" '='
   assert_success 'foo=bar' 'xyzzy=baz' 'quux=plugh'
 }
 
-@test "$SUITE: strip formatting codes validates result variable name" {
+@test "$SUITE: strip_formatting_codes validates result array name" {
   create_test_go_script '. "$_GO_USE_MODULES" format' \
     '@go.strip_formatting_codes "foobar" "3foobar"'
   run "$TEST_GO_SCRIPT"
@@ -97,27 +133,27 @@ run_strip_formatting_codes_script() {
     "  $TEST_GO_SCRIPT:4 main"
 }
 
-@test "$SUITE: strip formatting codes from empty string" {
+@test "$SUITE: strip_formatting_codes from empty string" {
   run_strip_formatting_codes_script ''
   assert_success ''
 }
 
-@test "$SUITE: strip formatting codes from string with no codes" {
+@test "$SUITE: strip_formatting_codes from string with no codes" {
   run_strip_formatting_codes_script 'foobar'
   assert_success 'foobar'
 }
 
-@test "$SUITE: strip formatting codes from string with one code" {
+@test "$SUITE: strip_formatting_codes from string with one code" {
   run_strip_formatting_codes_script 'foobar\e[0m'
   assert_success 'foobar'
 }
 
-@test "$SUITE: strip formatting codes from string with multiple codes" {
+@test "$SUITE: strip_formatting_codes from string with multiple codes" {
   run_strip_formatting_codes_script '\e[1mf\e[30;47mo\e[0;111mo\e[32mbar\e[0m'
   assert_success 'foobar'
 }
 
-@test "$SUITE: strip formatting codes from string with expanded codes" {
+@test "$SUITE: strip_formatting_codes from string with expanded codes" {
   local orig_value
   printf -v orig_value '%b' '\e[1mf\e[30;47mo\e[0;111mo\e[32mbar\e[0m'
   run_strip_formatting_codes_script "$orig_value"

tests/strings/split.bats

@@ -42,6 +42,14 @@ teardown() {
   assert_success 'foo bar baz'
 }
 
+@test "$SUITE: multiple items using ASCII unit separator" {
+  create_strings_test_script 'declare result=()' \
+    "@go.split \$'\x1f' $'foo\x1fbar\x1fbaz' result" \
+    'echo "${result[@]}"'
+  run "$TEST_GO_SCRIPT"
+  assert_success 'foo bar baz'
+}
+
 @test "$SUITE: split items into same variable" {
   create_strings_test_script 'declare items="foo,bar,baz"' \
     '@go.split "," "$items" "items"' \