Merge pull request #106 from pipefail/master

add namerefs to avoid command substitution subproc for function output assignment

README.md

@@ -161,6 +161,7 @@ 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)
 * [AFTERWORD](#afterword)
 
 <!-- vim-markdown-toc -->
@@ -2169,6 +2170,24 @@ bkr() {
 bkr ./some_script.sh # some_script.sh is now running in the background
 ```
 
+## 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 -->
 
 # AFTERWORD

manuscript/chapter19.txt

@@ -219,10 +219,26 @@ This will run the given command and keep it running, even after the terminal or
 bkr() {
     (nohup "$@" &>/dev/null &)
 }
+
+bkr ./some_script.sh # some_script.sh is now running in the background
 ```
 
-```shell
-bkr ./some_script.sh # some_script.sh is now running in the background
+## 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 -->