Merge branch 'master' into rasa/add_hd

add namerefs to avoid command substitution subproc for function output assignment

CONTRIBUTING.md

@@ -5,7 +5,7 @@
 * [Adding Code to the Bible.](#adding-code-to-the-bible)
 * [Special meanings for code blocks.](#special-meanings-for-code-blocks)
 * [Writing tests](#writing-tests)
-* [Running tests](#running-the-tests)
+* [Running tests](#running-tests)
 
 <!-- vim-markdown-toc -->
 
@@ -65,7 +65,7 @@ Steps:
 2. The test script will automatically execute it. :+1:
 
 
-## Running the tests
+## Running tests
 
 Running `test.sh` also runs `shellcheck` on the code.
 

README.md

@@ -161,8 +161,8 @@ See something incorrectly described, buggy or outright wrong? Open an issue or s
     * [Bypass shell aliases](#bypass-shell-aliases)
     * [Bypass shell functions](#bypass-shell-functions)
     * [Run a command in the background](#run-a-command-in-the-background)
+    * [Capture function return without command substitution](#capture-the-return-value-of-a-function-without-command-substitution)
     * [Display a hexidecimal dump](#Display-a-hexidecimal-dump)
-
 * [AFTERWORD](#afterword)
 
 <!-- vim-markdown-toc -->
@@ -2221,6 +2221,23 @@ $ hd test_file
 00000000  1b 5b 35 6d 48 65 6c 6c  6f 2c 09 57 6f 72 6c 64  |.[5mHello,.World|
 00000010  1b 5b 6d 00 0a                                    |.[m..|
 00000015
+
+## Capture the return value of a function without command substitution
+
+**CAVEAT:** Requires `bash` 4+
+
+This uses local namerefs to avoid using `var=$(some_func)` style command substitution for function output capture.
+
+```sh
+to_upper() {
+  local -n ptr=${1}
+
+  ptr=${ptr^^}
+}
+
+foo="bar"
+to_upper foo
+printf "%s\n" "${foo}" # BAR
 ```
 
 <!-- CHAPTER END -->

manuscript/chapter19.txt

@@ -237,13 +237,13 @@ hd() {
   fi
   local IFS='' # disables interpretation of \t, \n and space
   local LANG=C # allows characters > 0x7F
-  local bytes=0 char chars=''
-  declare -i bytes
+  local char chars=''
+  declare -i bytes=0
   printf '%08x  ' 0
   while read -s -d '' -r -n 1 char; do  # -d '' allows newlines, -r allows \
     printf '%02x ' "'$char" # see https://pubs.opengroup.org/onlinepubs/009695399/utilities/printf.html
     [[ "$char" =~ [[:print:]] ]] || char='.' # display non-printables as a dot
-    chars+=$char
+    chars+="$char"
     ((++bytes % 8)) && continue
     printf ' '
     ((bytes % 16)) && continue
@@ -275,5 +275,23 @@ $ hd test_file
 00000015
 ```
 
+## Capture the return value of a function without command substitution
+
+**CAVEAT:** Requires `bash` 4+
+
+This uses local namerefs to avoid using `var=$(some_func)` style command substitution for function output capture.
+
+```sh
+to_upper() {
+  local -n ptr=${1}
+
+  ptr=${ptr^^}
+}
+
+foo="bar"
+to_upper foo
+printf "%s\n" "${foo}" # BAR
+```
+
 <!-- CHAPTER END -->