Add a new API @quote

Author: chaifeng

README-cn.md

@@ -753,6 +753,20 @@ Bach 测试框架中提供的 API 都是以 `@` 开头的。
 
 用于在标准控制台输出内容，每个参数输出一行。
 
+### @quote
+
+用于在标准控制台输出经过 shell 转义的内容，每个参数输出一行。当需要将包含空格或特殊字符的参数传递给 `xargs` 等命令时非常有用。
+
+例子：
+
+    @quote "hello world" "foo bar"
+    # 输出：
+    # hello\ world
+    # foo\ bar
+
+    # 与 xargs 配合使用
+    @quote "file with spaces.txt" "another file.txt" | xargs -I{} -- rm {}
+
 ### @trap
 
 执行真正的内置 `trap` 命令。

README.md

@@ -714,6 +714,20 @@ Output content to the stderr console, one line per parameter.
 
 Output content to the stdout console, one line per parameter.
 
+### @quote
+
+Output shell-quoted content to the stdout console, one line per parameter. This is useful when passing arguments that may contain spaces or special characters to commands like `xargs`.
+
+Example:
+
+    @quote "hello world" "foo bar"
+    # Output:
+    # hello\ world
+    # foo\ bar
+
+    # Using with xargs
+    @quote "file with spaces.txt" "another file.txt" | xargs -I{} -- rm {}
+
 ## Learn Bash Programming with Bach
 
     test-learn-bash-no-double-quote-star() {

bach.sh

@@ -682,6 +682,11 @@ function @stdout() {
 }
 builtin export -f @stdout
 
+function @quote() {
+    builtin printf '%q\n' "$@"
+}
+builtin export -f @quote
+
 function @load_function() {
     local file="${1:?script filename}"
     local func="${2:?function name}"

tests/bach-testing-framework.test.sh

@@ -154,6 +154,34 @@ test-mock-@stdout-include-space-assert() {
 }
 
 
+test-@quote-typical() {
+    @quote abc 123
+}
+test-@quote-typical-assert() {
+    @echo abc
+    @echo 123
+}
+
+
+test-@quote-include-space() {
+    @quote "abc 123" "def 456"
+}
+test-@quote-include-space-assert() {
+    @echo 'abc\ 123'
+    @echo 'def\ 456'
+}
+
+
+test-@quote-with-special-characters() {
+    @quote "it's" 'say "hello"' '$HOME'
+}
+test-@quote-with-special-characters-assert() {
+    @echo "it\\'s"
+    @echo 'say\ \"hello\"'
+    @echo '\$HOME'
+}
+
+
 test-run-a-script() {
     @mock load-script === @echo "for param; do @echo \"script.sh - \$param\"; done"