aboutsummaryrefslogtreecommitdiff
path: root/doc/testscript.cli
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2022-04-26 10:39:03 +0200
committerKaren Arutyunov <karen@codesynthesis.com>2022-07-07 18:08:25 +0300
commita473abe80f4c42a366f0573bbbc762fa440b7fe6 (patch)
tree6214c1d25162c2e614ed91e163011ac13091e7e3 /doc/testscript.cli
parent900436dd83787f2cd47e7fc37f0530fc581a3e3b (diff)
Use new cmdline type for canned command lines in {Build,Test}script
Diffstat (limited to 'doc/testscript.cli')
-rw-r--r--doc/testscript.cli53
1 files changed, 24 insertions, 29 deletions
diff --git a/doc/testscript.cli b/doc/testscript.cli
index 1395363..817837b 100644
--- a/doc/testscript.cli
+++ b/doc/testscript.cli
@@ -741,6 +741,9 @@ Note also that these \c{test.*} variables only establish a convention. You
could also put everything into, say \c{test.arguments}, and it will still work
as expected.
+\N|The \c{test.redirects}, \c{test.cleanups}, and \c{$*} variables are of the
+special \c{cmdline} type, see \l{#lexical Lexical Structure} for details.|
+
Another pre-defined variable is \c{test.target}. It is used to specify the
test target platform when cross-testing (for example, when running Windows
test on Linux under Wine). Normally, you would set it in your
@@ -1285,62 +1288,54 @@ here-document single-quoted here_line_single
here-document double-quoted here_line_double expansions
\
-Finally, unquoted expansions in command lines (test, setup, and teardown) are
-re-lexed in the \c{command_expansion} mode in order to recognize command line
-syntax tokens (redirects, pipes, etc). To illustrate why this re-lexing is
-necessary, consider the following example of a \"canned\" command line:
+Finally, unquoted expansions in command lines (test, setup, and teardown) of
+the special \c{cmdline} type are re-lexed in the \c{command_expansion} mode in
+order to recognize command line syntax tokens (redirects, pipes, etc). To
+illustrate this mechanism, consider the following example of a \"canned\"
+command line:
\
-x = echo >-
-$x foo
+cmd = [cmdline] echo >-
+$cmd foo
\
-The test command line token sequence will be \c{$}, \c{x}, \c{foo}. After the
-expansion we have \c{echo}, \c{>-}, \c{foo}, however, the second element
-(\c{>-}) is not (yet) recognized as a redirect. To recognize it we re-lex
-the result of the expansion.
+The test command line token sequence will be \c{$}, \c{cmd}, \c{foo}. After
+the expansion we have \c{echo}, \c{>-}, \c{foo}, however, the second element
+(\c{>-}) is not (yet) recognized as a redirect. To recognize it, the result of
+the expansion is re-lexed.
Note that besides the few command line syntax characters, re-lexing will also
\"consume\" quotes and escapes, for example:
\
-args = \"'foo'\" # 'foo'
-echo $args # echo foo
+cmd = [cmdline] echo \"'foo'\" # echo 'foo'
+$cmd # echo foo
\
To preserve quotes in this context we need to escape them:
\
-args = \"\\\\'foo\\\\'\" # \'foo\'
-echo $args # echo 'foo'
-\
-
-Alternatively, for a single value, we could quote the expansion (in order
-to suppress re-lexing; note, however, that quoting will also inhibit
-word-splitting):
-
-\
-arg = \"'foo'\" # 'foo'
-echo \"$arg\" # echo 'foo'
+cmd = [cmdline] echo \"\\\\'foo\\\\'\" # echo \'foo\'
+$cmd # echo 'foo'
\
To minimize unhelpful consumption of escape sequences (for example, in Windows
paths), re-lexing only performs the \i{effective escaping} for the \c{'\"\\}
characters. All other escape sequences are passed through uninterpreted. Note
-that this means there is no way to escape command line syntax characters. The
-recommendation is to use quoting except for passing literal quotes, for
-example:
+that this means there is no way to escape command line syntax characters in
+canned commands. The recommendation is to use quoting except for passing
+literal quotes, for example:
\
-args = \'&foo\' # '&foo'
-echo $args # echo &foo
+cmd = [cmdline] echo \'&foo\' # echo '&foo'
+$cmd # echo &foo
\
To make sure that a string is passed as is through both expansions use the
\i{doubled single-quoting} idiom, for example:
\
-filter = sed -e \''s/foo (bar|baz)/$&/'\'
+filter = [cmdline] sed -e \''s/foo (bar|baz)/$&/'\'
$* <<EOI | $filter >>EOO
...
EOI