From cb558e4bd2b817bc72275c2bbd90dfe9fe380af9 Mon Sep 17 00:00:00 2001
From: Karen Arutyunov <karen@codesynthesis.com>
Date: Tue, 8 Dec 2020 22:40:54 +0300
Subject: Add export script pseudo-builtin

---
 doc/testscript.cli | 46 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 40 insertions(+), 6 deletions(-)

(limited to 'doc')

diff --git a/doc/testscript.cli b/doc/testscript.cli
index badbe97..4721a88 100644
--- a/doc/testscript.cli
+++ b/doc/testscript.cli
@@ -2461,12 +2461,14 @@ env - --unset=FOO -- $*
 \li|\n\c{-t|--timeout <sec>}
 
   Terminate the command if it fails to complete within the specified number
-  of seconds. See also \l{#builtins-timeout \c{timeout}} builtin.|
+  of seconds. See also the \l{#builtins-timeout \c{timeout}} builtin.|
 
 \li|\n\c{-u|--unset <name>}
 
   Remove the specified variable from the environment.||
 
+See also the \l{#builtins-export \c{export}} builtin.
+
 
 \h#builtins-exit|\c{exit}|
 
@@ -2488,6 +2490,38 @@ the outer scopes unsuccessfully, as if the \c{exit} command failed. In this
 case the argument must be the diagnostics string describing the error.
 
 
+\h#builtins-export|\c{export}|
+
+\
+export [-c <name>]... [-u <name>]... [<name>=<value>]...
+\
+
+Add/remove the variables to/from the current scope commands execution
+environment and/or clear the previous additions/removals.
+
+Note that \c{export} is a \i{pseudo-builtin}. In particular, it must be the
+only command in the pipe expression, it either succeeds or terminates
+abnormally, and its standard streams cannot be redirected.
+
+The environment variables can be added and removed on multiple levels: with
+the \c{export} builtin in the nested test group scopes and the test scope and
+with the \l{#builtins-env \c{env}} builtin for individual commands. Before
+executing a command, all the variable additions and removals from its
+environment hierarchy are merged so that those specified in the inner levels
+override those specified in the outer levels.
+
+\dl|
+
+\li|\n\c{-c|--clear <name>}
+
+  Clear the previous variable addition/removal to/from the environment, if
+  exists.|
+
+\li|\n\c{-u|--unset <name>}
+
+  Remove the specified variable from the environment.||
+
+
 \h#builtins-false|\c{false}|
 
 \
@@ -2866,11 +2900,11 @@ The timeouts can be set on multiple levels: via the \c{config.test.timeout}
 variable on the (potentially nested) project root scopes (see
 \l{build2#module-test \c{test}} module for details), with the \c{timeout}
 builtin in the nested test group scopes and the test scope, and with the
-\c{env} builtin for individual commands. Each command must complete before the
-nearest timeout from its timeout hierarchy. Failed that, a command is
-terminated forcibly causing the entire \c{test} operation to fail unless the
-expired timeout was specified with the \c{--success} option, in which case the
-timed out command is assumed to have succeeded.
+\l{#builtins-env \c{env}} builtin for individual commands. Each command must
+complete before the nearest timeout from its timeout hierarchy. Failed that, a
+command is terminated forcibly causing the entire \c{test} operation to fail
+unless the expired timeout was specified with the \c{--success} option, in
+which case the timed out command is assumed to have succeeded.
 
 \dl|
 
-- 
cgit v1.1