aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2020-06-09 08:42:15 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2020-06-09 08:42:15 +0200
commitb256e5ce05c045e6d536c728776342a5c45c5995 (patch)
tree22e55585a202bb50bbdf1614aa7e31edbf8de460
parent23cbbc7f7cdcb7721d8d1cf4e70ae58184f8cc7e (diff)
Update Testscript manual with notes on redirect aliases
-rw-r--r--doc/testscript.cli52
1 files changed, 40 insertions, 12 deletions
diff --git a/doc/testscript.cli b/doc/testscript.cli
index 4c78e18..65f455f 100644
--- a/doc/testscript.cli
+++ b/doc/testscript.cli
@@ -1536,9 +1536,9 @@ stderr: '2'(out-redirect)
in-redirect: '<-'|\
'<|'|\
- ('<='|'<<<') <file>|\
- ('<<='|'<<'){':'?'/'?} <here-end>|\
- ('<<<='|'<'){':'?'/'?} <text>
+ ('<<<'|'<=') <file>|\
+ ('<<'|'<<='){':'?'/'?} <here-end>|\
+ ('<'|'<<<='){':'?'/'?} <text>
out-redirect: '>-'|\
'>|'|\
@@ -1546,9 +1546,9 @@ out-redirect: '>-'|\
'>=' <file>|\
'>+' <file>|\
'>&' ('1'|'2')|\
- ('>?'|'>>>') <file>|\
- ('>>?'|'>>'){':'?'/'?}'~'? <here-end>|\
- ('>>>?'|'>'){':'?'/'?}'~'? <text>
+ ('>>>'|'>?') <file>|\
+ ('>>'|'>>?'){':'?'/'?}'~'? <here-end>|\
+ ('>'|'>>>?'){':'?'/'?}'~'? <text>
here-document:
*<text>
@@ -1866,9 +1866,9 @@ $* a1>-
\
in-redirect: '<-'|\
'<|'|\
- ('<='|'<<<') <file>|\
- ('<<='|'<<'){':'?'/'?} <here-end>|\
- ('<<<='|'<'){':'?'/'?} <text>
+ ('<<<'|'<=') <file>|\
+ ('<<'|'<<='){':'?'/'?} <here-end>|\
+ ('<'|'<<<='){':'?'/'?} <text>
\
The \c{stdin} data can come from a pipe, here-string (\c{<}), here-document
@@ -1879,6 +1879,20 @@ failed (unexpected input). However, whether this is detected and diagnosed is
implementation-defined. To allow reading from the default \c{stdin} (for
instance, if the test is really an example), the \c{<|} redirect is used.
+\N|The \c{<=}, \c{<<=}, and \c{<<<=} redirects are a stable syntax across
+various \c{build2} scripting language flavors (Testscript, Buildscript,
+etc). While the \c{<}, \c{<<}, and \c{<<<} redirects are their Testscript
+aliases with the mapping chosen to be more convenient for this flavor of the
+scripting language. This mapping is as follows:
+
+\
+< <<<= here-string
+<< <<= here-document
+<<< <= file
+\
+
+|
+
Here-string and here-document redirects may specify the following redirect
modifiers:
@@ -1905,9 +1919,9 @@ out-redirect: '>-'|\
'>=' <file>|\
'>+' <file>|\
'>&' ('1'|'2')|\
- ('>?'|'>>>') <file>|\
- ('>>?'|'>>'){':'?'/'?}'~'? <here-end>|\
- ('>>>?'|'>'){':'?'/'?}'~'? <text>
+ ('>>>'|'>?') <file>|\
+ ('>>'|'>>?'){':'?'/'?}'~'? <here-end>|\
+ ('>'|'>>>?'){':'?'/'?}'~'? <text>
\
The \c{stdout} and \c{stderr} data can go to a pipe (\c{stdout} only), file
@@ -1919,6 +1933,20 @@ stream (either \c{stdout} or \c{stderr}) is considered to have failed
(unexpected output). To allow writing to the default \c{stdout} or \c{stderr}
(for instance, if the test is really an example), the \c{>|} redirect is used.
+\N|The \c{>?}, \c{>>?}, and \c{>>>?} redirects are a stable syntax across
+various \c{build2} scripting language flavors (Testscript, Buildscript,
+etc). While the \c{>}, \c{>>}, and \c{>>>} redirects are their Testscript
+aliases with the mapping chosen to be more convenient for this flavor of the
+scripting language. This mapping is as follows:
+
+\
+> >>>? here-string comparison
+>> >>? here-document comparison
+>>> >? file contents comparison
+\
+
+|
+
The \c{>!} redirect acts like \c{>-} if the build system verbosity level is
below 2 and as \c{>|} otherwise. It is normally used to ignore diagnostics (as
opposed to data) during normal operation but to still be able to examine it,