Merge of 21071 and unposted c.f. 21735: document return as exit in try block in script.

1 files changed, 103 insertions, 22 deletions

diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo
index 8b25795d0..dd5da93b4 100644
--- a/Doc/Zsh/grammar.yo
+++ b/Doc/Zsh/grammar.yo
@@ -63,18 +63,18 @@ cindex(sublist)
 A em(sublist) is either a single pipeline, or a sequence of two or more
 pipelines separated by `tt(&&)' or `tt(||)'.  If two pipelines are separated
 by `tt(&&)', the second pipeline is executed only if the first succeeds
-(returns a zero value).  If two pipelines are separated by `tt(||)', the
-second is executed only if the first fails (returns a nonzero value).
+(returns a zero status).  If two pipelines are separated by `tt(||)', the
+second is executed only if the first fails (returns a nonzero status).
 Both operators have equal precedence and are left associative.
 The value of the sublist is the value of the last pipeline executed.
 For example,
 
 example(dmesg | grep panic && print yes)
 
-is a sublist consisting of two piplines, the second just a simple command
+is a sublist consisting of two pipelines, the second just a simple command
 which will be executed if and only if the tt(grep) command returns a zero
-value.  If it does not, the value of the sublist is that return value, else
-it is the value returned by the tt(print) (almost certainly zero).
+status.  If it does not, the value of the sublist is that return status, else
+it is the status returned by the tt(print) (almost certainly zero).
 
 cindex(list)
 A em(list) is a sequence of zero or more sublists, in which each sublist
@@ -142,19 +142,29 @@ cindex(if construct)
 item(tt(if) var(list) tt(then) var(list) [ tt(elif) var(list) tt(then) var(list) ] ... [ tt(else) var(list) ] tt(fi))(
 The tt(if) var(list) is executed, and if it returns a zero exit status,
 the tt(then) var(list) is executed.
-Otherwise, the tt(elif) var(list) is executed and if its value is zero,
+Otherwise, the tt(elif) var(list) is executed and if its status is zero,
 the tt(then) var(list) is executed.
-If each tt(elif) var(list) returns nonzero, the tt(else) var(list) is executed.
+If each tt(elif) var(list) returns nonzero status, the tt(else) var(list)
+is executed.
 )
 findex(for)
 cindex(for loops)
 cindex(loops, for)
-item(tt(for) var(name) [ tt(in) var(word) ... var(term) ] tt(do) var(list) tt(done))(
+item(tt(for) var(name) ... [ tt(in) var(word) ... ] var(term) tt(do) var(list) tt(done))(
 where var(term) is at least one newline or tt(;).
 Expand the list of var(word)s, and set the parameter
 var(name) to each of them in turn, executing
 var(list) each time.  If the tt(in) var(word) is omitted,
 use the positional parameters instead of the var(word)s.
+
+More than one parameter var(name) can appear before the list of
+var(word)s.  If var(N) var(name)s are given, then on each execution of the
+loop the next tt(N) var(word)s are assigned to the corresponding
+parameters.  If there are more var(name)s than remaining var(word)s, the
+remaining parameters are each set to the empty string.  Execution of the
+loop ends when there is no remaining var(word) to assign to the first
+var(name).  It is only possible for tt(in) to appear as the first var(name)
+in the list, else it will be treated as marking the end of the list.
 )
 item(tt(for LPAR()LPAR()) [var(expr1)] tt(;) [var(expr2)] tt(;) [var(expr3)] tt(RPAR()RPAR() do) var(list) tt(done))(
 The arithmetic expression var(expr1) is evaluated first (see
@@ -203,6 +213,7 @@ cindex(user selection)
 cindex(selection, user)
 item(tt(select) var(name) [ tt(in) var(word) ... var(term) ] tt(do) var(list) tt(done))(
 where var(term) is one or more newline or tt(;) to terminate the var(word)s.
+vindex(REPLY, use of)
 Print the set of var(word)s, each preceded by a number.
 If the tt(in) var(word) is omitted, use the positional parameters.
 The tt(PROMPT3) prompt is printed and a line is read from the line editor
@@ -216,7 +227,7 @@ The contents of the line read from standard input is saved
 in the parameter tt(REPLY).  var(list) is executed
 for each selection until a break or end-of-file is encountered.
 )
-cindex(subshells)
+cindex(subshell)
 item(tt(LPAR()) var(list) tt(RPAR()))(
 Execute var(list) in a subshell.  Traps set by the tt(trap) builtin
 are reset to their default values while executing var(list).
@@ -224,6 +235,64 @@ are reset to their default values while executing var(list).
 item(tt({) var(list) tt(}))(
 Execute var(list).
 )
+findex(always)
+cindex(always blocks)
+cindex(try blocks)
+item(tt({) var(try-list) tt(} always {) var(always-list) tt(}))(
+First execute var(try-list).  Regardless of errors, or tt(break),
+tt(continue), or tt(return) commands encountered within var(try-list),
+execute var(always-list).  Execution then continues from the
+result of the execution of var(try-list); in other words, any error,
+or tt(break), tt(continue), or tt(return) command is treated in the
+normal way, as if var(always-list) were not present.  The two
+chunks of code are referred to as the `try block' and the `always block'.
+
+Optional newlines or semicolons may appear after the tt(always);
+note, however, that they may em(not) appear between the preceeding
+closing brace and the tt(always).
+
+An `error' in this context is a condition such as a syntax error which
+causes the shell to abort execution of the current function, script, or
+list.  Syntax errors encountered while the shell is parsing the
+code do not cause the var(always-list) to be executed.  For example,
+an erroneously constructed tt(if) block in tt(try-list) would cause the
+shell to abort during parsing, so that tt(always-list) would not be
+executed, while an erroneous substitution such as tt(${*foo*}) would
+cause a run-time error, after which tt(always-list) would be executed.
+
+An error condition can be tested and reset with the special integer
+variable tt(TRY_BLOCK_ERROR).  Outside an tt(always-list) the value is
+irrelevant, but it is initialised to tt(-1).  Inside tt(always-list), the
+value is 1 if an error occurred in the tt(try-list), else 0.  If
+tt(TRY_BLOCK_ERROR) is set to 0 during the tt(always-list), the error
+condition caused by the tt(try-list) is reset, and shell execution
+continues normally after the end of tt(always-list).  Altering the value
+during the tt(try-list) is not useful (unless this forms part of an
+enclosing tt(always) block).
+
+Regardless of tt(TRY_BLOCK_ERROR), after the end of tt(always-list) the
+normal shell status tt($?) is the value returned from tt(always-list).
+This will be non-zero if there was an error, even if tt(TRY_BLOCK_ERROR)
+was set to zero.
+
+The following executes the given code, ignoring any errors it causes.
+This is an alternative to the usual convention of protecting code by
+executing it in a subshell.
+
+example({
+    # code which may cause an error
+  } always {
+    # This code is executed regardless of the error.
+    (( TRY_BLOCK_ERROR = 0 ))
+}
+# The error condition has been reset.)
+
+An tt(exit) command (or a tt(return) command executed at the outermost
+function level of a script) encountered in tt(try-list) does em(not) cause
+the execution of var(always-list).  Instead, the shell exits immediately
+after any tt(EXIT) trap has been executed.
+)
+findex(function)
 xitem(tt(function) var(word) ... [ tt(()) ] [ var(term) ] tt({) var(list) tt(}))
 xitem(var(word) ... tt(()) [ var(term) ] tt({) var(list) tt(}))
 item(var(word) ... tt(()) [ var(term) ] var(command))(
@@ -240,6 +309,7 @@ there is a single var(word);  otherwise, the parentheses will be treated as
 forming a globbing pattern in that case.
 )
 cindex(timing)
+findex(time)
 item(tt(time) [ var(pipeline) ])(
 The var(pipeline) is executed, and timing statistics are
 reported on the standard error in the form specified
@@ -247,7 +317,8 @@ by the tt(TIMEFMT) parameter.
 If var(pipeline) is omitted, print statistics about the
 shell process and its children.
 )
-cindex(testing conditional expression)
+cindex(conditional expression)
+findex([[)
 item(tt([[) var(exp) tt(]]))(
 Evaluates the conditional expression var(exp)
 and return a zero exit status if it is true.
@@ -262,11 +333,16 @@ cindex(commands, alternate forms for complex)
 Many of zsh's complex commands have alternate forms.  These particular
 versions of complex commands should be considered deprecated and may be
 removed in the future.  The versions in the previous section should be
-preferred instead.  The short versions below only work if var(sublist)
-is of the form `tt({) var(list) tt(})' or if the tt(SHORT_LOOPS)
-option is set.  In this case, the test part of the loop must also be
-suitably delimited, such as by `tt([[ ... ]])' or `tt((( ... )))', else
-the end of the test will not be recognized.
+preferred instead.
+
+The short versions below only work if var(sublist) is of the form `tt({)
+var(list) tt(})' or if the tt(SHORT_LOOPS) option is set.  For the tt(if),
+tt(while) and tt(until) commands, in both these cases the test part of the
+loop must also be suitably delimited, such as by `tt([[ ... ]])' or `tt(((
+... )))', else the end of the test will not be recognized.  For the
+tt(for), tt(repeat), tt(case) and tt(select) commands no such special form
+for the arguments is necessary, but the other condition (the special form
+of var(sublist) or use of the tt(SHORT_LOOPS) option) still applies.
 
 startitem()
 item(tt(if) var(list) tt({) var(list) tt(}) [ tt(elif) var(list) tt({) var(list) tt(}) ] ... [ tt(else {) var(list) tt(}) ])(
@@ -286,26 +362,30 @@ example(if true {  # Does not work!
 does em(not), since the test is not suitably delimited.
 )
 item(tt(if) var(list) var(sublist))(
-A short form of the alternate `if'.
+A short form of the alternate `if'.  The same limitations on the form of
+var(list) apply as for the previous form.
 )
-item(tt(for) var(name) tt(LPAR()) var(word) ... tt(RPAR()) var(sublist))(
+item(tt(for) var(name) ... tt(LPAR()) var(word) ... tt(RPAR()) var(sublist))(
 A short form of tt(for).
 )
-item(tt(for) var(name) [ tt(in) var(word) ... var(term) ] var(sublist))(
+item(tt(for) var(name) ... [ tt(in) var(word) ... ] var(term) var(sublist))(
 where var(term) is at least one newline or tt(;).
 Another short form of tt(for).
 )
 item(tt(for LPAR()LPAR()) [var(expr1)] tt(;) [var(expr2)] tt(;) [var(expr3)] tt(RPAR()RPAR()) var(sublist))(
 A short form of the arithmetic tt(for) command.
 )
-item(tt(foreach) var(name) tt(LPAR()) var(word) ... tt(RPAR()) var(list) tt(end))(
+findex(foreach)
+item(tt(foreach) var(name) ... tt(LPAR()) var(word) ... tt(RPAR()) var(list) tt(end))(
 Another form of tt(for).
 )
 item(tt(while) var(list) tt({) var(list) tt(}))(
-An alternative form of tt(while).
+An alternative form of tt(while).  Note the limitations on the form of
+var(list) mentioned above.
 )
 item(tt(until) var(list) tt({) var(list) tt(}))(
-An alternative form of tt(until).
+An alternative form of tt(until).  Note the limitations on the form of
+var(list) mentioned above.
 )
 item(tt(repeat) var(word) var(sublist))(
 This is a short form of tt(repeat).
@@ -376,6 +456,7 @@ tt(print) builtin, and the resulting string is considered to be
 entirely quoted.  A literal `tt(')' character can be included in the
 string by using the `tt(\')' escape.
 
+pindex(RC_QUOTES, use of)
 All characters enclosed between a pair of single quotes (tt('')) that
 is not preceded by a `tt($)' are quoted.  A single quote cannot appear
 within single quotes unless the option tt(RC_QUOTES) is set, in which case
@@ -387,5 +468,5 @@ outputs nothing apart from a newline if tt(RC_QUOTES) is not set, but one
 single quote if it is set.
 
 Inside double quotes (tt("")), parameter and
-command substitution occurs, and `tt(\)' quotes the characters
+command substitution occur, and `tt(\)' quotes the characters
 `tt(\)', `tt(`)', `tt(")', and `tt($)'.