From fac9d5174786a6d849f0f713a6c244d4313bf37c Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Tue, 17 Jan 2017 10:36:49 +0200
Subject: Specify testscript sed builtin

---
 doc/testscript.cli | 102 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 91 insertions(+), 11 deletions(-)

(limited to 'doc')

diff --git a/doc/testscript.cli b/doc/testscript.cli
index 9423ca3..4fe6d72 100644
--- a/doc/testscript.cli
+++ b/doc/testscript.cli
@@ -462,7 +462,6 @@ the above as a single test with some branching and without using the
 \
 : config-empty
 :
-@@ Why no +?
 if ($cxx.target.class != windows)
   conf = /dev/null
 else
@@ -853,7 +852,7 @@ buildfile as described in \l{#integration Build System Integration}.
 
 A scope also establishes a cleanup context. All cleanups (\l{syntax-cleanup
 Cleanup}) registered in a scope are performed at the end of that scope's
-execution.
+execution in the reverse order of their registration.
 
 Prior to executing a scope, a nested temporary directory is created with the
 scope id as its name. This directory then becomes the scope's working
@@ -1322,7 +1321,7 @@ and ones that start on the same line describes the syntax inside the line. If
 a rule contains multiple lines, then each line matches a separate line in the
 input.
 
-If a multiplier appears in from of a line then it specifies the number of
+If a multiplier appears in front of a line then it specifies the number of
 repetitions of the entire line. For example, from the following three rules,
 the first describes a single line of multiple literals, the second \- multiple
 lines of a single literal, and the third \- multiple lines of multiple
@@ -1427,7 +1426,7 @@ variable-like:
   variable-line|variable-if
 
 variable-line:
-  <variable-name> ('='|'+='|'=+') value-attributes? <value>
+  <variable-name> ('='|'+='|'=+') value-attributes? <value> ';'?
 
 value-attributes: '[' <key-value-pairs> ']'
 
@@ -1646,7 +1645,7 @@ variable-like:
   variable-line|variable-if
 
 variable-line:
-  <variable-name> ('='|'+='|'=+') value-attributes? <value>
+  <variable-name> ('='|'+='|'=+') value-attributes? <value> ';'?
 
 value-attributes: '[' <key-value-pairs> ']'
 \
@@ -1659,6 +1658,9 @@ args = [strings] foo   bar 'fox   baz'
 echo $args # foo bar fox   baz
 \
 
+The value can only be followed by \c{;} inside a test to signal the test
+continuation.
+
 \h#syntax-variable-if|Variable-If|
 
 \
@@ -1965,9 +1967,11 @@ continuations.
 
 \h#syntax-regex|Output Regex|
 
-The expected result in output here-strings and here-documents can be specified
-as a regular expression instead of literal text. To signal the use of regular
-expressions the redirect must end with the \c{~} modifier, for example:
+Instead of literal text the expected result in output here-strings and
+here-documents can be specified as ECMAScript regular expressions (more
+specifically, ECMA-262-based C++11 regular expressions). To signal the use of
+regular expressions the redirect must end with the \c{~} modifier, for
+example:
 
 \
 $* >~'/fo+/' 2>>~/EOE/
@@ -2186,8 +2190,10 @@ Compare the contents of \i{file1} and \i{file2}.
 
 The \c{diff} utility is not a builtin. Instead, the test platform is expected
 to provide a (reasonably) POSIX-compatible implementation. It should at least
-supports the \c{-u} and \c{-U} options. On Windows GNU \c{diff} can be
-assumed (provided as part of the \c{build2} toolchain).
+supports the \c{-u} (unified output format) and \c{-U} (unified output format
+with \i{num} lines of context) options and recognize the \c{-} file name as
+an instruction to read from \c{stdin}. On Windows, GNU \c{diff} can be assumed
+(provided as part of the \c{build2} toolchain).
 
 
 \h#builtins-echo|\c{echo}|
@@ -2276,6 +2282,80 @@ working directory unless the \c{-f} option is specified.
   is outside the script working directory.||
 
 
+\h#builtins-sed|\c{sed}|
+
+\
+sed [-n] -e <script> [<file>]
+\
+
+Read text from \i{file}, make editing changes according to \i{script}, and
+write the result to \c{stdout}. If \i{file} is not specified or is \c{-}, read
+from \c{stdin}.
+
+Note that this builtin implementation deviates significantly from POSIX
+\c{sed} (as described next). Most significantly, the regular expression flavor
+is ECMAScript (more specifically, ECMA-262-based C++11 regular expressions).
+
+\dl|
+
+\li|\n\c{-n}
+
+  Suppress automatic printing of the pattern space at the end of the script.|
+
+\li|\n\c{-e <script>}\n
+
+  Editing commands to be executed (required).||
+
+To perform the transformation \c{sed} reads each line of input (without the
+newline) into the pattern space. It then executes the script commands on
+the pattern space. At the end of the script, unless the \c{-n} option is
+specified, \c{sed} writes the pattern space to \c{stdout} followed by a
+newline.
+
+Currently, only single-command scripts using the following editing commands
+are supported.
+
+\dl|
+
+\li|\n\c{s/<regex>/<replacement>/<flags>}\n
+
+  Match \i{regex} against the pattern space. If successful, replace the part
+  of the pattern space that matched with \i{replacement}. If the \c{g} flag is
+  present in \i{flags} then continue substituting subsequent matches of
+  \i{regex} in the same pattern space. If the \c{p} flag is present in
+  \i{flags} and the replacement has been made, then write the pattern space to
+  \c{stdout}. If both \c{g} and \c{p} were specified, then write the pattern
+  space out only after the last substitution.
+
+  Any character other than \c{\\} (backslash) or newline can be used instead
+  of \c{/} (slash) to delimit \i{regex}, \i{replacement}, and \i{flags}. Note
+  that no escaping of the delimiter character is supported.
+
+  If \i{regex} starts with \c{^}, then it only matches at the beginning of the
+  pattern space. Similarly, if it ends with \c{$}, then it only matches at the
+  end of the pattern space. If the \c{i} flag is present in \i{flags}, then
+  the match is performed in a case-insensitive manner.
+
+  In \i{replacement}, besides the standard ECMAScript escape sequences
+  (\c{$1}, \c{$2}, \c{$&}, etc), the following additional sequences are
+  recognized:
+
+  \
+    \N - Nth capture, where N is in the 1-9 range.
+
+    \u - Convert next character to the upper case.
+    \l - Convert next character to the lower case.
+
+    \U - Convert next characters until \E to the upper case.
+    \L - Convert next characters until \E to the lower case.
+
+    \\ - Literal backslash.
+  \
+
+  Note that unlike POSIX semantics, just \c{&} does not have a special meaning
+  in \i{replacement}.||
+
+
 \h#builtins-test|\c{test}|
 
 \
@@ -2295,7 +2375,7 @@ Test the specified \i{path} according to one of the following options. Succeed
 
   Path exists and is to a directory.||
 
-Note that all tests dereference symbolic links.
+Note that tests dereference symbolic links.
 
 
 \h#builtins-touch|\c{touch}|
-- 
cgit v1.1